gio/gsocketcontrolmessage.c

   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   int 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_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 (message_types[i]);
 194       message = class->deserialize (level, type, size, data);
 195       g_type_class_unref (class);
 196
 197       if (message != NULL)
 198         break;
 199     }
 200
 201   g_free (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 }