Skip to content

Commit 6eee9f7

Browse files
author
Tony Crisci
committed
document unix file descriptors
1 parent c169a89 commit 6eee9f7

File tree

4 files changed

+67
-40
lines changed

4 files changed

+67
-40
lines changed

‎docs/high-level-client/index.rst

+2
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,8 @@ The proxy object is obtained by the :class:`MessageBus <dbus_next.message_bus.Ba
4646

4747
Once you have a proxy object, use the :func:`get_proxy_interface() <dbus_next.proxy_object.BaseProxyObject.get_interface>` method to create an interface passing the name of the interface to get. Each message bus has its own implementation of the proxy interface which behaves slightly differently. This is an example of how to use a proxy interface for the asyncio :class:`MessageBus <dbus_next.aio.MessageBus>`.
4848

49+
If any file descriptors are sent or received (DBus type ``h``), the variable refers to the file descriptor itself. You are responsible for closing any file descriptors sent or received by the bus. You must set the ``negotiate_unix_fd`` flag to ``True`` in the ``MessageBus`` constructor to use unix file descriptors.
50+
4951
:example:
5052

5153
.. code-block:: python3

‎docs/high-level-service/index.rst

+2
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ A class method decorated with ``@method()`` or ``@dbus_property()`` may throw a
2222

2323
After the service interface is defined, call :func:`MessageBus.export() <dbus_next.message_bus.BaseMessageBus.export>` on a connected message bus and the service will be made available on the given object path.
2424

25+
If any file descriptors are sent or received (DBus type ``h``), the variable refers to the file descriptor itself. You are responsible for closing any file descriptors sent or received by the bus. You must set the ``negotiate_unix_fd`` flag to ``True`` in the ``MessageBus`` constructor to use unix file descriptors.
26+
2527
:example:
2628

2729
.. code-block:: python3

‎docs/low-level-interface/index.rst

+22
Original file line numberDiff line numberDiff line change
@@ -67,3 +67,25 @@ Mixed use of the low and high level interfaces on the same bus connection is not
6767
'com.test.interface',
6868
'SomeSignal',
6969
's', ['a signal']))
70+
71+
:example: Send a file descriptor. The message format will be the same when
72+
received on the client side. You are responsible for closing any file
73+
descriptor that is sent or received by the bus. You must set the
74+
``negotiate_unix_fd`` flag to ``True`` in the ``MessageBus``
75+
constructor to use unix file descriptors.
76+
77+
.. code-block:: python3
78+
79+
bus = await MessageBus().connect(negotiate_unix_fd=True)
80+
81+
fd = os.open('/dev/null', os.O_RDONLY)
82+
83+
msg = Message(destination='org.test.destination',
84+
path='/org/test/destination',
85+
interface='org.test.interface',
86+
member='TestMember',
87+
signature='h',
88+
body=[0],
89+
unix_fds=[fd])
90+
91+
await bus.send(msg)

‎docs/type-system/index.rst

+41-40
Original file line numberDiff line numberDiff line change
@@ -22,46 +22,47 @@ the bus for clients.
2222
Each token in the signature is mapped to a Python type as shown in the table
2323
below.
2424

25-
+-------------+-------+---------+---------------------------------------------------+
26-
| Name | Token | Python | Notes |
27-
| | | Type | |
28-
+-------------+-------+---------+---------------------------------------------------+
29-
| BYTE | y | int | An integer 0-255. In an array, it has type |
30-
| | | | ``bytes``. |
31-
+-------------+-------+---------+---------------------------------------------------+
32-
| BOOLEAN | b | bool | |
33-
+-------------+-------+---------+---------------------------------------------------+
34-
| INT16 | n | int | |
35-
+-------------+-------+---------+---------------------------------------------------+
36-
| UINT16 | q | int | |
37-
+-------------+-------+---------+---------------------------------------------------+
38-
| INT32 | i | int | |
39-
+-------------+-------+---------+---------------------------------------------------+
40-
| UINT32 | u | int | |
41-
+-------------+-------+---------+---------------------------------------------------+
42-
| INT64 | x | int | |
43-
+-------------+-------+---------+---------------------------------------------------+
44-
| UINT64 | t | int | |
45-
+-------------+-------+---------+---------------------------------------------------+
46-
| DOUBLE | d | float | |
47-
+-------------+-------+---------+---------------------------------------------------+
48-
| STRING | s | str | |
49-
+-------------+-------+---------+---------------------------------------------------+
50-
| OBJECT_PATH | o | str | Must be a valid object path. |
51-
+-------------+-------+---------+---------------------------------------------------+
52-
| SIGNATURE | g | str | Must be a valid signature. |
53-
+-------------+-------+---------+---------------------------------------------------+
54-
| ARRAY | a | list | Must be followed by a complete type which |
55-
| | | | specifies the child type. |
56-
+-------------+-------+---------+---------------------------------------------------+
57-
| STRUCT | ( | list | Types in the Python ``list`` must match the types |
58-
| | | | between the parens. |
59-
+-------------+-------+---------+---------------------------------------------------+
60-
| VARIANT | v | Variant | This class is provided by the library. |
61-
| | | | |
62-
+-------------+-------+---------+---------------------------------------------------+
63-
| DICT_ENTRY | { | dict | Must be included in an array to be a ``dict``. |
64-
+-------------+-------+---------+---------------------------------------------------+
25+
+-------------+-------+--------------------------------------+-------------------------------------------------------------------------+
26+
| Name | Token | Python | Notes |
27+
| | | Type | |
28+
+-------------+-------+--------------------------------------+-------------------------------------------------------------------------+
29+
| BYTE | y | int | An integer 0-255. In an array, it has type ``bytes``. |
30+
+-------------+-------+--------------------------------------+-------------------------------------------------------------------------+
31+
| BOOLEAN | b | bool | |
32+
+-------------+-------+--------------------------------------+-------------------------------------------------------------------------+
33+
| INT16 | n | int | |
34+
+-------------+-------+--------------------------------------+-------------------------------------------------------------------------+
35+
| UINT16 | q | int | |
36+
+-------------+-------+--------------------------------------+-------------------------------------------------------------------------+
37+
| INT32 | i | int | |
38+
+-------------+-------+--------------------------------------+-------------------------------------------------------------------------+
39+
| UINT32 | u | int | |
40+
+-------------+-------+--------------------------------------+-------------------------------------------------------------------------+
41+
| INT64 | x | int | |
42+
+-------------+-------+--------------------------------------+-------------------------------------------------------------------------+
43+
| UINT64 | t | int | |
44+
+-------------+-------+--------------------------------------+-------------------------------------------------------------------------+
45+
| DOUBLE | d | float | |
46+
+-------------+-------+--------------------------------------+-------------------------------------------------------------------------+
47+
| STRING | s | str | |
48+
+-------------+-------+--------------------------------------+-------------------------------------------------------------------------+
49+
| OBJECT_PATH | o | str | Must be a valid object path. |
50+
+-------------+-------+--------------------------------------+-------------------------------------------------------------------------+
51+
| SIGNATURE | g | str | Must be a valid signature. |
52+
+-------------+-------+--------------------------------------+-------------------------------------------------------------------------+
53+
| UNIX_FD | h | int | In the low-level interface, an index pointing to a file descriptor |
54+
| | | | in the ``unix_fds`` member of the :class:`Message <dbus_next.Message>`. |
55+
| | | | In the high-level interface, it is the file descriptor itself. |
56+
+-------------+-------+--------------------------------------+-------------------------------------------------------------------------+
57+
| ARRAY | a | list | Must be followed by a complete type which specifies the child type. |
58+
+-------------+-------+--------------------------------------+-------------------------------------------------------------------------+
59+
| STRUCT | ( | list | Types in the Python ``list`` must match the types between the parens. |
60+
+-------------+-------+--------------------------------------+-------------------------------------------------------------------------+
61+
| VARIANT | v | :class:`Variant <dbus_next.Variant>` | This class is provided by the library. |
62+
| | | | |
63+
+-------------+-------+--------------------------------------+-------------------------------------------------------------------------+
64+
| DICT_ENTRY | { | dict | Must be included in an array to be a ``dict``. |
65+
+-------------+-------+--------------------------------------+-------------------------------------------------------------------------+
6566

6667
The types ``a``, ``(``, ``v``, and ``{`` are container types that hold
6768
other values. Examples of container types and Python examples are in the

0 commit comments

Comments
 (0)