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 "glibintl.h"
  48
  49 #ifndef G_OS_WIN32
  50 #include "gunixfdmessage.h"
  51 #include <sys/socket.h>
  52 #else
  53 # include <winsock2.h>
  54 # include <mswsock.h>
  55 #endif
  56
  57 #include "gioalias.h"
  58
  59 G_DEFINE_ABSTRACT_TYPE (GSocketControlMessage,
  60                         g_socket_control_message,
  61                         G_TYPE_OBJECT);
  62
  63 /**
  64  * g_socket_control_message_get_size:
  65  * @message: a #GSocketControlMessage
  66  *
  67  * Returns the space required for the control message, not including
  68  * headers or alignment.
  69  *
  70  * Returns: The number of bytes required.
  71  *
  72  * Since: 2.22
  73  */
  74 gsize
  75 g_socket_control_message_get_size (GSocketControlMessage *message)
  76 {
  77   g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);
  78
  79   return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_size (message);
  80 }
  81
  82 /**
  83  * g_socket_control_message_get_level:
  84  * @message: a #GSocketControlMessage
  85  *
  86  * Returns the "level" (i.e. the originating protocol) of the control message.
  87  * This is often SOL_SOCKET.
  88  *
  89  * Returns: an integer describing the level
  90  *
  91  * Since: 2.22
  92  */
  93 int
  94 g_socket_control_message_get_level (GSocketControlMessage *message)
  95 {
  96   g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);
  97
  98   return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_level (message);
  99 }
 100
 101 /**
 102  * g_socket_control_message_get_msg_type:
 103  * @message: a #GSocketControlMessage
 104  *
 105  * Returns the protocol specific type of the control message.
 106  * For instance, for UNIX fd passing this would be SCM_RIGHTS.
 107  *
 108  * Returns: an integer describing the type of control message
 109  *
 110  * Since: 2.22
 111  */
 112 int
 113 g_socket_control_message_get_msg_type (GSocketControlMessage *message)
 114 {
 115   g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0);
 116
 117   return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_type (message);
 118 }
 119
 120 /**
 121  * g_socket_control_message_serialize:
 122  * @message: a #GSocketControlMessage
 123  * @data: A buffer to write data to
 124  *
 125  * Converts the data in the message to bytes placed in the
 126  * message.
 127  *
 128  * @data is guaranteed to have enough space to fit the size
 129  * returned by g_socket_control_message_get_size() on this
 130  * object.
 131  *
 132  * Since: 2.22
 133  */
 134 void
 135 g_socket_control_message_serialize (GSocketControlMessage *message,
 136                                     gpointer               data)
 137 {
 138   g_return_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message));
 139
 140   G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->serialize (message, data);
 141 }
 142
 143
 144 static void
 145 g_socket_control_message_init (GSocketControlMessage *message)
 146 {
 147 }
 148
 149 static void
 150 g_socket_control_message_class_init (GSocketControlMessageClass *class)
 151 {
 152 }
 153
 154 /**
 155  * g_socket_control_message_deserialize:
 156  * @level: a socket level
 157  * @type: a socket control message type for the given @level
 158  * @size: the size of the data in bytes
 159  * @data: pointer to the message data
 160  *
 161  * Tries to deserialize a socket control message of a given
 162  * @level and @type. This will ask all known (to GType) subclasses
 163  * of #GSocketControlMessage if they can understand this kind
 164  * of message and if so deserialize it into a #GSocketControlMessage.
 165  *
 166  * If there is no implementation for this kind of control message, %NULL
 167  * will be returned.
 168  *
 169  * Returns: the deserialized message or %NULL
 170  *
 171  * Since: 2.22
 172  */
 173 GSocketControlMessage *
 174 g_socket_control_message_deserialize (int      level,
 175                                       int      type,
 176                                       gsize    size,
 177                                       gpointer data)
 178 {
 179   GSocketControlMessageClass *klass;
 180   GSocketControlMessage *message;
 181   GType *message_types;
 182   guint n_message_types;
 183   int i;
 184 #ifndef G_OS_WIN32
 185   volatile GType a_type;
 186 #endif
 187
 188   /* Ensure we know about the built in types */
 189 #ifndef G_OS_WIN32
 190   a_type = g_unix_fd_message_get_type ();
 191 #endif
 192
 193   message_types = g_type_children (G_TYPE_SOCKET_CONTROL_MESSAGE, &n_message_types);
 194
 195   message = NULL;
 196   for (i = 0; i < n_message_types; i++)
 197     {
 198       klass = (GSocketControlMessageClass *)g_type_class_ref (type);
 199
 200       if (klass && klass->deserialize)
 201         {
 202           message = klass->deserialize (level, type, size, data);
 203           g_type_class_unref ((GTypeClass *) klass);
 204         }
 205
 206       if (message != NULL)
 207         break;
 208     }
 209
 210   g_free (message_types);
 211
 212   if (message == NULL)
 213     g_warning ("unknown control message type %d:%d", level, type);
 214
 215   return message;
 216 }
 217
 218 #define __G_SOCKET_CONTROL_MESSAGE_C__
 219 #include "gioaliasdef.c"