gio/gsocketcontrolmessage.c

   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  * @see_also: #GSocket.
  20  *
  21  * A #GSocketControlMessage is a special-purpose utility message that
  22  * can be sent to or received from a #GSocket. These types of
  23  * messages are often called "ancillary data".
  24  *
  25  * The message can represent some sort of special instruction to or
  26  * information from the socket or can represent a special kind of
  27  * transfer to the peer (for example, sending a file descriptor over
  28  * a UNIX socket).
  29  *
  30  * These messages are sent with g_socket_send_message() and received
  31  * with g_socket_receive_message().
  32  *
  33  * To extend the set of control message that can be sent, subclass this
  34  * class and override the get_size, get_level, get_type and serialize
  35  * methods.
  36  *
  37  * To extend the set of control messages that can be received, subclass
  38  * this class and implement the deserialize method. Also, make sure your
  39  * class is registered with the GType typesystem before calling
  40  * g_socket_receive_message() to read such a message.
  41  *
  42  * Since: 2.22
  43  */
  44
  45 #include "config.h"
  46 #include "gsocketcontrolmessage.h"
  47 #include "gnetworkingprivate.h"
  48 #include "glibintl.h"
  49
  50 #ifndef G_OS_WIN32
  51 #include "gunixcredentialsmessage.h"
  52 #include "gunixfdmessage.h"
  53 #endif
  54
  55
  56 G_DEFINE_ABSTRACT_TYPE (GSocketControlMessage,
  57                         g_socket_control_message,
  58                         G_TYPE_OBJECT);
  59
  60 /**
  61  * g_socket_control_message_get_size:
  62  * @message: a #GSocketControlMessage
  63  *
  64  * Returns the space required for the control message, not including
  65  * headers or alignment.
  66  *
  67  * Returns: The number of bytes required.
  68  *
  69  * Since: 2.22
  70  */
  71 gsize
  72 g_socket_control_message_get_size (GSocketControlMessage *message)
  73 {
  74   g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);
  75
  76   return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_size (message);
  77 }
  78
  79 /**
  80  * g_socket_control_message_get_level:
  81  * @message: a #GSocketControlMessage
  82  *
  83  * Returns the "level" (i.e. the originating protocol) of the control message.
  84  * This is often SOL_SOCKET.
  85  *
  86  * Returns: an integer describing the level
  87  *
  88  * Since: 2.22
  89  */
  90 int
  91 g_socket_control_message_get_level (GSocketControlMessage *message)
  92 {
  93   g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);
  94
  95   return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_level (message);
  96 }
  97
  98 /**
  99  * g_socket_control_message_get_msg_type:
 100  * @message: a #GSocketControlMessage
 101  *
 102  * Returns the protocol specific type of the control message.
 103  * For instance, for UNIX fd passing this would be SCM_RIGHTS.
 104  *
 105  * Returns: an integer describing the type of control message
 106  *
 107  * Since: 2.22
 108  */
 109 int
 110 g_socket_control_message_get_msg_type (GSocketControlMessage *message)
 111 {
 112   g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);
 113
 114   return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_type (message);
 115 }
 116
 117 /**
 118  * g_socket_control_message_serialize:
 119  * @message: a #GSocketControlMessage
 120  * @data: A buffer to write data to
 121  *
 122  * Converts the data in the message to bytes placed in the
 123  * message.
 124  *
 125  * @data is guaranteed to have enough space to fit the size
 126  * returned by g_socket_control_message_get_size() on this
 127  * object.
 128  *
 129  * Since: 2.22
 130  */
 131 void
 132 g_socket_control_message_serialize (GSocketControlMessage *message,
 133                                     gpointer               data)
 134 {
 135   g_return_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message));
 136
 137   G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->serialize (message, data);
 138 }
 139
 140
 141 static void
 142 g_socket_control_message_init (GSocketControlMessage *message)
 143 {
 144 }
 145
 146 static void
 147 g_socket_control_message_class_init (GSocketControlMessageClass *class)
 148 {
 149 }
 150
 151 /**
 152  * g_socket_control_message_deserialize:
 153  * @level: a socket level
 154  * @type: a socket control message type for the given @level
 155  * @size: the size of the data in bytes
 156  * @data: (array length=size) (element-type guint8): pointer to the message data
 157  *
 158  * Tries to deserialize a socket control message of a given
 159  * @level and @type. This will ask all known (to GType) subclasses
 160  * of #GSocketControlMessage if they can understand this kind
 161  * of message and if so deserialize it into a #GSocketControlMessage.
 162  *
 163  * If there is no implementation for this kind of control message, %NULL
 164  * will be returned.
 165  *
 166  * Returns: (transfer full): the deserialized message or %NULL
 167  *
 168  * Since: 2.22
 169  */
 170 GSocketControlMessage *
 171 g_socket_control_message_deserialize (int      level,
 172                                       int      type,
 173                                       gsize    size,
 174                                       gpointer data)
 175 {
 176   GSocketControlMessage *message;
 177   GType *message_types;
 178   guint n_message_types;
 179   int i;
 180
 181   /* Ensure we know about the built in types */
 182 #ifndef G_OS_WIN32
 183   g_type_ensure (G_TYPE_UNIX_CREDENTIALS_MESSAGE);
 184   g_type_ensure (G_TYPE_UNIX_FD_MESSAGE);
 185 #endif
 186
 187   message_types = g_type_children (G_TYPE_SOCKET_CONTROL_MESSAGE, &n_message_types);
 188
 189   message = NULL;
 190   for (i = 0; i < n_message_types; i++)
 191     {
 192       GSocketControlMessageClass *class;
 193
 194       class = g_type_class_ref (message_types[i]);
 195       message = class->deserialize (level, type, size, data);
 196       g_type_class_unref (class);
 197
 198       if (message != NULL)
 199         break;
 200     }
 201
 202   g_free (message_types);
 203
 204   /* It's not a bug if we can't deserialize the control message - for
 205    * example, the control message may be be discarded if it is deemed
 206    * empty, see e.g.
 207    *
 208    *  http://git.gnome.org/browse/glib/commit/?id=ec91ed00f14c70cca9749347b8ebc19d72d9885b
 209    *
 210    * Therefore, it's not appropriate to print a warning about not
 211    * being able to deserialize the message.
 212    */
 213
 214   return message;
 215 }