/src/glib/gio/gsocketcontrolmessage.c

Source (jump to first uncovered line)
/* GIO - GLib Input, Output and Streaming Library
 *
 * Copyright © 2009 Codethink Limited
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * See the included COPYING file for more information.
 *
 * Authors: Ryan Lortie <desrt@desrt.ca>
 */

/**
 * SECTION:gsocketcontrolmessage
 * @title: GSocketControlMessage
 * @short_description: A GSocket control message
 * @include: gio/gio.h
 * @see_also: #GSocket.
 *
 * A #GSocketControlMessage is a special-purpose utility message that
 * can be sent to or received from a #GSocket. These types of
 * messages are often called "ancillary data".
 *
 * The message can represent some sort of special instruction to or
 * information from the socket or can represent a special kind of
 * transfer to the peer (for example, sending a file descriptor over
 * a UNIX socket).
 *
 * These messages are sent with g_socket_send_message() and received
 * with g_socket_receive_message().
 *
 * To extend the set of control message that can be sent, subclass this
 * class and override the get_size, get_level, get_type and serialize
 * methods.
 *
 * To extend the set of control messages that can be received, subclass
 * this class and implement the deserialize method. Also, make sure your
 * class is registered with the GType typesystem before calling
 * g_socket_receive_message() to read such a message.
 *
 * Since: 2.22
 */

#include "config.h"
#include "gsocketcontrolmessage.h"
#include "gnetworkingprivate.h"
#include "glibintl.h"

#ifndef G_OS_WIN32
#include "gunixcredentialsmessage.h"
#include "gunixfdmessage.h"
#endif


G_DEFINE_ABSTRACT_TYPE (GSocketControlMessage, g_socket_control_message, G_TYPE_OBJECT)

/**
 * g_socket_control_message_get_size:
 * @message: a #GSocketControlMessage
 *
 * Returns the space required for the control message, not including
 * headers or alignment.
 *
 * Returns: The number of bytes required.
 *
 * Since: 2.22
 */
gsize
g_socket_control_message_get_size (GSocketControlMessage *message)
{
  g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);

  return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_size (message);
}

/**
 * g_socket_control_message_get_level:
 * @message: a #GSocketControlMessage
 *
 * Returns the "level" (i.e. the originating protocol) of the control message.
 * This is often SOL_SOCKET.
 *
 * Returns: an integer describing the level
 *
 * Since: 2.22
 */
int
g_socket_control_message_get_level (GSocketControlMessage *message)
{
  g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);

  return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_level (message);
}

/**
 * g_socket_control_message_get_msg_type:
 * @message: a #GSocketControlMessage
 *
 * Returns the protocol specific type of the control message.
 * For instance, for UNIX fd passing this would be SCM_RIGHTS.
 *
 * Returns: an integer describing the type of control message
 *
 * Since: 2.22
 */
int
g_socket_control_message_get_msg_type (GSocketControlMessage *message)
{
  g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);

  return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_type (message);
}

/**
 * g_socket_control_message_serialize:
 * @message: a #GSocketControlMessage
 * @data: (not nullable): A buffer to write data to
 *
 * Converts the data in the message to bytes placed in the
 * message.
 *
 * @data is guaranteed to have enough space to fit the size
 * returned by g_socket_control_message_get_size() on this
 * object.
 *
 * Since: 2.22
 */
void
g_socket_control_message_serialize (GSocketControlMessage *message,
            gpointer               data)
{
  g_return_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message));

  G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->serialize (message, data);
}


static void
g_socket_control_message_init (GSocketControlMessage *message)
{
}

static void
g_socket_control_message_class_init (GSocketControlMessageClass *class)
{
}

/**
 * g_socket_control_message_deserialize:
 * @level: a socket level
 * @type: a socket control message type for the given @level
 * @size: the size of the data in bytes
 * @data: (array length=size) (element-type guint8): pointer to the message data
 *
 * Tries to deserialize a socket control message of a given
 * @level and @type. This will ask all known (to GType) subclasses
 * of #GSocketControlMessage if they can understand this kind
 * of message and if so deserialize it into a #GSocketControlMessage.
 *
 * If there is no implementation for this kind of control message, %NULL
 * will be returned.
 *
 * Returns: (transfer full): the deserialized message or %NULL
 *
 * Since: 2.22
 */
GSocketControlMessage *
g_socket_control_message_deserialize (int      level,
              int      type,
              gsize    size,
              gpointer data)
{
  GSocketControlMessage *message;
  GType *message_types;
  guint n_message_types;
  guint i;

  /* Ensure we know about the built in types */
#ifndef G_OS_WIN32
  g_type_ensure (G_TYPE_UNIX_CREDENTIALS_MESSAGE);
  g_type_ensure (G_TYPE_UNIX_FD_MESSAGE);
#endif

  message_types = g_type_children (G_TYPE_SOCKET_CONTROL_MESSAGE, &n_message_types);

  message = NULL;
  for (i = 0; i < n_message_types; i++)
    {
      GSocketControlMessageClass *class;

      class = g_type_class_ref (message_types[i]);
      message = class->deserialize (level, type, size, data);
      g_type_class_unref (class);

      if (message != NULL)
        break;
    }

  g_free (message_types);

  /* It's not a bug if we can't deserialize the control message - for
   * example, the control message may be be discarded if it is deemed
   * empty, see e.g.
   *
   *  http://git.gnome.org/browse/glib/commit/?id=ec91ed00f14c70cca9749347b8ebc19d72d9885b
   *
   * Therefore, it's not appropriate to print a warning about not
   * being able to deserialize the message.
   */

  return message;
}

Coverage Report

Created: 2025-07-01 07:09

Line	Count	Source (jump to first uncovered line)
1		/* GIO - GLib Input, Output and Streaming Library
2		*
3		* Copyright © 2009 Codethink Limited
4		*
5		* This library is free software; you can redistribute it and/or
6		* modify it under the terms of the GNU Lesser General Public
7		* License as published by the Free Software Foundation; either
8		* version 2.1 of the License, or (at your option) any later version.
9		*
10		* See the included COPYING file for more information.
11		*
12		* Authors: Ryan Lortie <desrt@desrt.ca>
13		*/
14
15		/**
16		* SECTION:gsocketcontrolmessage
17		* @title: GSocketControlMessage
18		* @short_description: A GSocket control message
19		* @include: gio/gio.h
20		* @see_also: #GSocket.
21		*
22		* A #GSocketControlMessage is a special-purpose utility message that
23		* can be sent to or received from a #GSocket. These types of
24		* messages are often called "ancillary data".
25		*
26		* The message can represent some sort of special instruction to or
27		* information from the socket or can represent a special kind of
28		* transfer to the peer (for example, sending a file descriptor over
29		* a UNIX socket).
30		*
31		* These messages are sent with g_socket_send_message() and received
32		* with g_socket_receive_message().
33		*
34		* To extend the set of control message that can be sent, subclass this
35		* class and override the get_size, get_level, get_type and serialize
36		* methods.
37		*
38		* To extend the set of control messages that can be received, subclass
39		* this class and implement the deserialize method. Also, make sure your
40		* class is registered with the GType typesystem before calling
41		* g_socket_receive_message() to read such a message.
42		*
43		* Since: 2.22
44		*/
45
46		#include "config.h"
47		#include "gsocketcontrolmessage.h"
48		#include "gnetworkingprivate.h"
49		#include "glibintl.h"
50
51		#ifndef G_OS_WIN32
52		#include "gunixcredentialsmessage.h"
53		#include "gunixfdmessage.h"
54		#endif
55
56
57		G_DEFINE_ABSTRACT_TYPE (GSocketControlMessage, g_socket_control_message, G_TYPE_OBJECT)
58
59		/**
60		* g_socket_control_message_get_size:
61		* @message: a #GSocketControlMessage
62		*
63		* Returns the space required for the control message, not including
64		* headers or alignment.
65		*
66		* Returns: The number of bytes required.
67		*
68		* Since: 2.22
69		*/
70		gsize
71		g_socket_control_message_get_size (GSocketControlMessage *message)
72	0	{
73	0	g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);
74
75	0	return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_size (message);
76	0	}
77
78		/**
79		* g_socket_control_message_get_level:
80		* @message: a #GSocketControlMessage
81		*
82		* Returns the "level" (i.e. the originating protocol) of the control message.
83		* This is often SOL_SOCKET.
84		*
85		* Returns: an integer describing the level
86		*
87		* Since: 2.22
88		*/
89		int
90		g_socket_control_message_get_level (GSocketControlMessage *message)
91	0	{
92	0	g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);
93
94	0	return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_level (message);
95	0	}
96
97		/**
98		* g_socket_control_message_get_msg_type:
99		* @message: a #GSocketControlMessage
100		*
101		* Returns the protocol specific type of the control message.
102		* For instance, for UNIX fd passing this would be SCM_RIGHTS.
103		*
104		* Returns: an integer describing the type of control message
105		*
106		* Since: 2.22
107		*/
108		int
109		g_socket_control_message_get_msg_type (GSocketControlMessage *message)
110	0	{
111	0	g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);
112
113	0	return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_type (message);
114	0	}
115
116		/**
117		* g_socket_control_message_serialize:
118		* @message: a #GSocketControlMessage
119		* @data: (not nullable): A buffer to write data to
120		*
121		* Converts the data in the message to bytes placed in the
122		* message.
123		*
124		* @data is guaranteed to have enough space to fit the size
125		* returned by g_socket_control_message_get_size() on this
126		* object.
127		*
128		* Since: 2.22
129		*/
130		void
131		g_socket_control_message_serialize (GSocketControlMessage *message,
132		gpointer data)
133	0	{
134	0	g_return_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message));
135
136	0	G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->serialize (message, data);
137	0	}
138
139
140		static void
141		g_socket_control_message_init (GSocketControlMessage *message)
142	0	{
143	0	}
144
145		static void
146		g_socket_control_message_class_init (GSocketControlMessageClass *class)
147	0	{
148	0	}
149
150		/**
151		* g_socket_control_message_deserialize:
152		* @level: a socket level
153		* @type: a socket control message type for the given @level
154		* @size: the size of the data in bytes
155		* @data: (array length=size) (element-type guint8): pointer to the message data
156		*
157		* Tries to deserialize a socket control message of a given
158		* @level and @type. This will ask all known (to GType) subclasses
159		* of #GSocketControlMessage if they can understand this kind
160		* of message and if so deserialize it into a #GSocketControlMessage.
161		*
162		* If there is no implementation for this kind of control message, %NULL
163		* will be returned.
164		*
165		* Returns: (transfer full): the deserialized message or %NULL
166		*
167		* Since: 2.22
168		*/
169		GSocketControlMessage *
170		g_socket_control_message_deserialize (int level,
171		int type,
172		gsize size,
173		gpointer data)
174	0	{
175	0	GSocketControlMessage *message;
176	0	GType *message_types;
177	0	guint n_message_types;
178	0	guint i;
179
180		/* Ensure we know about the built in types */
181	0	#ifndef G_OS_WIN32
182	0	g_type_ensure (G_TYPE_UNIX_CREDENTIALS_MESSAGE);
183	0	g_type_ensure (G_TYPE_UNIX_FD_MESSAGE);
184	0	#endif
185
186	0	message_types = g_type_children (G_TYPE_SOCKET_CONTROL_MESSAGE, &n_message_types);
187
188	0	message = NULL;
189	0	for (i = 0; i < n_message_types; i++)
190	0	{
191	0	GSocketControlMessageClass *class;
192
193	0	class = g_type_class_ref (message_types[i]);
194	0	message = class->deserialize (level, type, size, data);
195	0	g_type_class_unref (class);
196
197	0	if (message != NULL)
198	0	break;
199	0	}
200
201	0	g_free (message_types);
202
203		/* It's not a bug if we can't deserialize the control message - for
204		* example, the control message may be be discarded if it is deemed
205		* empty, see e.g.
206		*
207		* http://git.gnome.org/browse/glib/commit/?id=ec91ed00f14c70cca9749347b8ebc19d72d9885b
208		*
209		* Therefore, it's not appropriate to print a warning about not
210		* being able to deserialize the message.
211		*/
212
213	0	return message;
214	0	}