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
57G_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 */
70gsize
71g_socket_control_message_get_size (GSocketControlMessage *message)
72{
73 g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);
74
75 return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_size (message);
76}
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 */
89int
90g_socket_control_message_get_level (GSocketControlMessage *message)
91{
92 g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);
93
94 return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_level (message);
95}
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 */
108int
109g_socket_control_message_get_msg_type (GSocketControlMessage *message)
110{
111 g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);
112
113 return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_type (message);
114}
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 */
130void
131g_socket_control_message_serialize (GSocketControlMessage *message,
132 gpointer data)
133{
134 g_return_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message));
135
136 G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->serialize (message, data);
137}
138
139
140static void
141g_socket_control_message_init (GSocketControlMessage *message)
142{
143}
144
145static void
146g_socket_control_message_class_init (GSocketControlMessageClass *class)
147{
148}
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 */
169GSocketControlMessage *
170g_socket_control_message_deserialize (int level,
171 int type,
172 gsize size,
173 gpointer data)
174{
175 GSocketControlMessage *message;
176 GType *message_types;
177 guint n_message_types;
178 guint i;
179
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
185
186 message_types = g_type_children (G_TYPE_SOCKET_CONTROL_MESSAGE, n_children: &n_message_types);
187
188 message = NULL;
189 for (i = 0; i < n_message_types; i++)
190 {
191 GSocketControlMessageClass *class;
192
193 class = g_type_class_ref (type: message_types[i]);
194 message = class->deserialize (level, type, size, data);
195 g_type_class_unref (g_class: class);
196
197 if (message != NULL)
198 break;
199 }
200
201 g_free (mem: 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 return message;
214}
215

source code of gtk/subprojects/glib/gio/gsocketcontrolmessage.c