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 description 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 "gunixfdmessage.h"
  52 #endif
  53
  54
  55 G_DEFINE_ABSTRACT_TYPE (GSocketControlMessage,
  56                         g_socket_control_message,
  57                         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: 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: 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: 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   GSocketControlMessageClass *klass;
 176   GSocketControlMessage *message;
 177   GType *message_types;
 178   guint n_message_types;
 179   int i;
 180 #ifndef G_OS_WIN32
 181   volatile GType a_type;
 182 #endif
 183
 184   /* Ensure we know about the built in types */
 185 #ifndef G_OS_WIN32
 186   a_type = g_unix_fd_message_get_type ();
 187 #endif
 188
 189   message_types = g_type_children (G_TYPE_SOCKET_CONTROL_MESSAGE, &n_message_types);
 190
 191   message = NULL;
 192   for (i = 0; i < n_message_types; i++)
 193     {
 194       klass = (GSocketControlMessageClass *)g_type_class_ref (message_types[i]);
 195
 196       if (klass && klass->deserialize)
 197         {
 198           message = klass->deserialize (level, type, size, data);
 199           g_type_class_unref ((GTypeClass *) klass);
 200         }
 201
 202       if (message != NULL)
 203         break;
 204     }
 205
 206   g_free (message_types);
 207
 208   if (message == NULL)
 209     g_warning ("unknown control message type %d:%d", level, type);
 210
 211   return message;
 212 }