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  * @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 }