/src/glib/gio/gsocketcontrolmessage.c

Source (jump to first uncovered line)
/* GIO - GLib Input, Output and Streaming Library
 *
 * Copyright © 2009 Codethink Limited
 *
 * SPDX-License-Identifier: LGPL-2.1-or-later
 *
 * 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: (nullable) (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.
   *
   *  https://gitlab.gnome.org/GNOME/glib/commit/ec91ed00f14c70cca9749347b8ebc19d72d9885b
   *
   * Therefore, it's not appropriate to print a warning about not
   * being able to deserialize the message.
   */

  return message;
}

Coverage Report

Created: 2025-06-13 06:55

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