docs: Small improvements to glib-mkenums man page
[glib.git] / gio / gsocketcontrolmessage.c
blob7acf6b3585603e0483d5a43900573302cc7e60f9
1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright © 2009 Codethink Limited
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.
10 * See the included COPYING file for more information.
12 * Authors: Ryan Lortie <desrt@desrt.ca>
15 /**
16 * SECTION:gsocketcontrolmessage
17 * @title: GSocketControlMessage
18 * @short_description: A GSocket control message
19 * @include: gio/gio.h
20 * @see_also: #GSocket.
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".
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).
31 * These messages are sent with g_socket_send_message() and received
32 * with g_socket_receive_message().
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.
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.
43 * Since: 2.22
46 #include "config.h"
47 #include "gsocketcontrolmessage.h"
48 #include "gnetworkingprivate.h"
49 #include "glibintl.h"
51 #ifndef G_OS_WIN32
52 #include "gunixcredentialsmessage.h"
53 #include "gunixfdmessage.h"
54 #endif
57 G_DEFINE_ABSTRACT_TYPE (GSocketControlMessage, g_socket_control_message, G_TYPE_OBJECT)
59 /**
60 * g_socket_control_message_get_size:
61 * @message: a #GSocketControlMessage
63 * Returns the space required for the control message, not including
64 * headers or alignment.
66 * Returns: The number of bytes required.
68 * Since: 2.22
70 gsize
71 g_socket_control_message_get_size (GSocketControlMessage *message)
73 g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);
75 return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_size (message);
78 /**
79 * g_socket_control_message_get_level:
80 * @message: a #GSocketControlMessage
82 * Returns the "level" (i.e. the originating protocol) of the control message.
83 * This is often SOL_SOCKET.
85 * Returns: an integer describing the level
87 * Since: 2.22
89 int
90 g_socket_control_message_get_level (GSocketControlMessage *message)
92 g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);
94 return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_level (message);
97 /**
98 * g_socket_control_message_get_msg_type:
99 * @message: a #GSocketControlMessage
101 * Returns the protocol specific type of the control message.
102 * For instance, for UNIX fd passing this would be SCM_RIGHTS.
104 * Returns: an integer describing the type of control message
106 * Since: 2.22
109 g_socket_control_message_get_msg_type (GSocketControlMessage *message)
111 g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);
113 return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_type (message);
117 * g_socket_control_message_serialize:
118 * @message: a #GSocketControlMessage
119 * @data: (not nullable): A buffer to write data to
121 * Converts the data in the message to bytes placed in the
122 * message.
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.
128 * Since: 2.22
130 void
131 g_socket_control_message_serialize (GSocketControlMessage *message,
132 gpointer data)
134 g_return_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message));
136 G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->serialize (message, data);
140 static void
141 g_socket_control_message_init (GSocketControlMessage *message)
145 static void
146 g_socket_control_message_class_init (GSocketControlMessageClass *class)
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
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.
162 * If there is no implementation for this kind of control message, %NULL
163 * will be returned.
165 * Returns: (transfer full): the deserialized message or %NULL
167 * Since: 2.22
169 GSocketControlMessage *
170 g_socket_control_message_deserialize (int level,
171 int type,
172 gsize size,
173 gpointer data)
175 GSocketControlMessage *message;
176 GType *message_types;
177 guint n_message_types;
178 int i;
180 /* Ensure we know about the built in types */
181 #ifndef G_OS_WIN32
182 g_type_ensure (G_TYPE_UNIX_CREDENTIALS_MESSAGE);
183 g_type_ensure (G_TYPE_UNIX_FD_MESSAGE);
184 #endif
186 message_types = g_type_children (G_TYPE_SOCKET_CONTROL_MESSAGE, &n_message_types);
188 message = NULL;
189 for (i = 0; i < n_message_types; i++)
191 GSocketControlMessageClass *class;
193 class = g_type_class_ref (message_types[i]);
194 message = class->deserialize (level, type, size, data);
195 g_type_class_unref (class);
197 if (message != NULL)
198 break;
201 g_free (message_types);
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.
207 * http://git.gnome.org/browse/glib/commit/?id=ec91ed00f14c70cca9749347b8ebc19d72d9885b
209 * Therefore, it's not appropriate to print a warning about not
210 * being able to deserialize the message.
213 return message;