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 | { |
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 | */ |
89 | int |
90 | g_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 | */ |
108 | int |
109 | g_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 | */ |
130 | void |
131 | g_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 | |
140 | static void |
141 | g_socket_control_message_init (GSocketControlMessage *message) |
142 | { |
143 | } |
144 | |
145 | static void |
146 | g_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 | */ |
169 | GSocketControlMessage * |
170 | g_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 | |