nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 1 /* GIO - GLib Input, Output and Streaming Library
2 *
3 * Copyright © 2009 Codethink Limited
4 *
5 * This program is free software: you can redistribute it and/or modify
6 * it under the terms of the GNU Lesser General Public License as published
7 * by the Free Software Foundation; either version 2 of the licence or (at
8 * 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,
58 g_socket_control_message,
59 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 {
75 g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);
76  
77 return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_size (message);
78 }
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 {
94 g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);
95  
96 return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_level (message);
97 }
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 {
113 g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);
114  
115 return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_type (message);
116 }
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 {
136 g_return_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message));
137  
138 G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->serialize (message, data);
139 }
140  
141  
142 static void
143 g_socket_control_message_init (GSocketControlMessage *message)
144 {
145 }
146  
147 static void
148 g_socket_control_message_class_init (GSocketControlMessageClass *class)
149 {
150 }
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: (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 {
177 GSocketControlMessage *message;
178 GType *message_types;
179 guint n_message_types;
180 int i;
181  
182 /* Ensure we know about the built in types */
183 #ifndef G_OS_WIN32
184 g_type_ensure (G_TYPE_UNIX_CREDENTIALS_MESSAGE);
185 g_type_ensure (G_TYPE_UNIX_FD_MESSAGE);
186 #endif
187  
188 message_types = g_type_children (G_TYPE_SOCKET_CONTROL_MESSAGE, &n_message_types);
189  
190 message = NULL;
191 for (i = 0; i < n_message_types; i++)
192 {
193 GSocketControlMessageClass *class;
194  
195 class = g_type_class_ref (message_types[i]);
196 message = class->deserialize (level, type, size, data);
197 g_type_class_unref (class);
198  
199 if (message != NULL)
200 break;
201 }
202  
203 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 * http://git.gnome.org/browse/glib/commit/?id=ec91ed00f14c70cca9749347b8ebc19d72d9885b
210 *
211 * Therefore, it's not appropriate to print a warning about not
212 * being able to deserialize the message.
213 */
214  
215 return message;
216 }