:right-sidebar: True

SocketControlMessage
===================================================================

.. currentmodule:: gi.repository.Gio


.. versionadded:: 2.22




.. class:: SocketControlMessage(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.GObject.Object`


Subclasses: :class:`~gi.repository.Gio.UnixCredentialsMessage`, :class:`~gi.repository.Gio.UnixFDMessage`




A ``GSocketControlMessage`` is a special-purpose utility message that
can be sent to or received from a :obj:`~gi.repository.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 :obj:`~gi.repository.Gio.Socket.send_message` and received
with :obj:`~gi.repository.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 :obj:`~gi.repository.GObject.Type` type system before calling
:obj:`~gi.repository.Gio.Socket.receive_message` to read such a message.




Methods
-------

.. rst-class:: interim-class

.. class:: SocketControlMessage
   :no-index:


   .. classmethod:: deserialize(type: int, data: list[int]) -> ~gi.repository.Gio.SocketControlMessage | None

      Tries to deserialize a socket control message of a given
      ``level`` and ``type``\. This will ask all known (to GType) subclasses
      of :obj:`~gi.repository.Gio.SocketControlMessage` if they can understand this kind
      of message and if so deserialize it into a :obj:`~gi.repository.Gio.SocketControlMessage`\.

      If there is no implementation for this kind of control message, :const:`None`
      will be returned.


      .. versionadded:: 2.22





      :param type: a socket control message type for the given ``level``

      :param data: pointer to the message data




   .. method:: do_get_level(self) -> int

      









   .. method:: do_get_size(self) -> int

      









   .. method:: do_get_type(self) -> int

      









   .. method:: do_serialize(self, data: ~typing.Any) -> None

      






      :param data: 




   .. method:: get_level() -> int

      Returns the "level" (i.e. the originating protocol) of the control message.
      This is often SOL_SOCKET.


      .. versionadded:: 2.22








   .. method:: get_msg_type() -> int

      Returns the protocol specific type of the control message.
      For instance, for UNIX fd passing this would be SCM_RIGHTS.


      .. versionadded:: 2.22








   .. method:: get_size() -> int

      Returns the space required for the control message, not including
      headers or alignment.


      .. versionadded:: 2.22








   .. method:: serialize(data: ~typing.Any) -> None

      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 :func:`~gi.repository.Gio.SocketControlMessage.get_size` on this
      object.


      .. versionadded:: 2.22





      :param data: A buffer to write data to












Virtual Methods
---------------

.. rst-class:: interim-class

.. class:: SocketControlMessage
   :no-index:
   

   .. method:: do_get_level() -> int

      Returns the "level" (i.e. the originating protocol) of the control message.
      This is often SOL_SOCKET.


      .. versionadded:: 2.22








   .. method:: do_get_size() -> int

      Returns the space required for the control message, not including
      headers or alignment.


      .. versionadded:: 2.22








   .. method:: do_get_type() -> int

      The type of the None singleton.










   .. method:: do_serialize(data: ~typing.Any) -> None

      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 :func:`~gi.repository.Gio.SocketControlMessage.get_size` on this
      object.


      .. versionadded:: 2.22





      :param data: A buffer to write data to








Fields
------

.. rst-class:: interim-class

.. class:: SocketControlMessage
   :no-index:
   

   .. attribute:: parent_instance

      






   .. attribute:: priv