| /* GIO - GLib Input, Output and Streaming Library |
| * |
| * Copyright © 2009 Codethink Limited |
| * |
| * SPDX-License-Identifier: LGPL-2.1-or-later |
| * |
| * This library is free software; you can redistribute it and/or |
| * modify it under the terms of the GNU Lesser General Public |
| * License as published by the Free Software Foundation; either |
| * version 2.1 of the License, or (at your option) any later version. |
| * |
| * See the included COPYING file for more information. |
| * |
| * Authors: Ryan Lortie <desrt@desrt.ca> |
| */ |
| |
| /** |
| * GSocketControlMessage: |
| * |
| * A `GSocketControlMessage` is a special-purpose utility message that |
| * can be sent to or received from a [class@Gio.Socket]. These types of |
| * messages are often called ‘ancillary data’. |
| * |
| * The message can represent some sort of special instruction to or |
| * information from the socket or can represent a special kind of |
| * transfer to the peer (for example, sending a file descriptor over |
| * a UNIX socket). |
| * |
| * These messages are sent with [method@Gio.Socket.send_message] and received |
| * with [method@Gio.Socket.receive_message]. |
| * |
| * To extend the set of control message that can be sent, subclass this |
| * class and override the `get_size`, `get_level`, `get_type` and `serialize` |
| * methods. |
| * |
| * To extend the set of control messages that can be received, subclass |
| * this class and implement the `deserialize` method. Also, make sure your |
| * class is registered with the [type@GObject.Type] type system before calling |
| * [method@Gio.Socket.receive_message] to read such a message. |
| * |
| * Since: 2.22 |
| */ |
| |
| #include "config.h" |
| #include "gsocketcontrolmessage.h" |
| #include "gnetworkingprivate.h" |
| #include "glibintl.h" |
| |
| #ifndef G_OS_WIN32 |
| #include "gunixcredentialsmessage.h" |
| #include "gunixfdmessage.h" |
| #endif |
| |
| |
| G_DEFINE_ABSTRACT_TYPE (GSocketControlMessage, g_socket_control_message, G_TYPE_OBJECT) |
| |
| /** |
| * g_socket_control_message_get_size: |
| * @message: a #GSocketControlMessage |
| * |
| * Returns the space required for the control message, not including |
| * headers or alignment. |
| * |
| * Returns: The number of bytes required. |
| * |
| * Since: 2.22 |
| */ |
| gsize |
| g_socket_control_message_get_size (GSocketControlMessage *message) |
| { |
| g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0); |
| |
| return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_size (message); |
| } |
| |
| /** |
| * g_socket_control_message_get_level: |
| * @message: a #GSocketControlMessage |
| * |
| * Returns the "level" (i.e. the originating protocol) of the control message. |
| * This is often SOL_SOCKET. |
| * |
| * Returns: an integer describing the level |
| * |
| * Since: 2.22 |
| */ |
| int |
| g_socket_control_message_get_level (GSocketControlMessage *message) |
| { |
| g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0); |
| |
| return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_level (message); |
| } |
| |
| /** |
| * g_socket_control_message_get_msg_type: |
| * @message: a #GSocketControlMessage |
| * |
| * Returns the protocol specific type of the control message. |
| * For instance, for UNIX fd passing this would be SCM_RIGHTS. |
| * |
| * Returns: an integer describing the type of control message |
| * |
| * Since: 2.22 |
| */ |
| int |
| g_socket_control_message_get_msg_type (GSocketControlMessage *message) |
| { |
| g_return_val_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message), 0); |
| |
| return G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->get_type (message); |
| } |
| |
| /** |
| * g_socket_control_message_serialize: |
| * @message: a #GSocketControlMessage |
| * @data: (not nullable): A buffer to write data to |
| * |
| * Converts the data in the message to bytes placed in the |
| * message. |
| * |
| * @data is guaranteed to have enough space to fit the size |
| * returned by g_socket_control_message_get_size() on this |
| * object. |
| * |
| * Since: 2.22 |
| */ |
| void |
| g_socket_control_message_serialize (GSocketControlMessage *message, |
| gpointer data) |
| { |
| g_return_if_fail (G_IS_SOCKET_CONTROL_MESSAGE (message)); |
| |
| G_SOCKET_CONTROL_MESSAGE_GET_CLASS (message)->serialize (message, data); |
| } |
| |
| |
| static void |
| g_socket_control_message_init (GSocketControlMessage *message) |
| { |
| } |
| |
| static void |
| g_socket_control_message_class_init (GSocketControlMessageClass *class) |
| { |
| } |
| |
| /** |
| * g_socket_control_message_deserialize: |
| * @level: a socket level |
| * @type: a socket control message type for the given @level |
| * @size: the size of the data in bytes |
| * @data: (array length=size) (element-type guint8): pointer to the message data |
| * |
| * Tries to deserialize a socket control message of a given |
| * @level and @type. This will ask all known (to GType) subclasses |
| * of #GSocketControlMessage if they can understand this kind |
| * of message and if so deserialize it into a #GSocketControlMessage. |
| * |
| * If there is no implementation for this kind of control message, %NULL |
| * will be returned. |
| * |
| * Returns: (nullable) (transfer full): the deserialized message or %NULL |
| * |
| * Since: 2.22 |
| */ |
| GSocketControlMessage * |
| g_socket_control_message_deserialize (int level, |
| int type, |
| gsize size, |
| gpointer data) |
| { |
| GSocketControlMessage *message; |
| GType *message_types; |
| guint n_message_types; |
| guint i; |
| |
| /* Ensure we know about the built in types */ |
| #ifndef G_OS_WIN32 |
| g_type_ensure (G_TYPE_UNIX_CREDENTIALS_MESSAGE); |
| g_type_ensure (G_TYPE_UNIX_FD_MESSAGE); |
| #endif |
| |
| message_types = g_type_children (G_TYPE_SOCKET_CONTROL_MESSAGE, &n_message_types); |
| |
| message = NULL; |
| for (i = 0; i < n_message_types; i++) |
| { |
| GSocketControlMessageClass *class; |
| |
| class = g_type_class_ref (message_types[i]); |
| message = class->deserialize (level, type, size, data); |
| g_type_class_unref (class); |
| |
| if (message != NULL) |
| break; |
| } |
| |
| g_free (message_types); |
| |
| /* It's not a bug if we can't deserialize the control message - for |
| * example, the control message may be be discarded if it is deemed |
| * empty, see e.g. |
| * |
| * https://gitlab.gnome.org/GNOME/glib/commit/ec91ed00f14c70cca9749347b8ebc19d72d9885b |
| * |
| * Therefore, it's not appropriate to print a warning about not |
| * being able to deserialize the message. |
| */ |
| |
| return message; |
| } |