1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
Common API
=======================
These calls are shared between async and blocking API.
Default bus
+++++++++++
.. automodule:: sdbus.default_bus
:members:
.. py:currentmodule:: sdbus
D-Bus connections calls
+++++++++++++++++++++++
.. py:function:: sd_bus_open()
Opens a new bus connection. The session bus will be opened
when available or system bus otherwise.
:return: Session or system bus.
:rtype: SdBus
.. py:function:: sd_bus_open_user()
Opens a new user session bus connection.
:return: Session bus.
:rtype: SdBus
.. py:function:: sd_bus_open_system()
Opens a new system bus connection.
:return: System bus.
:rtype: SdBus
.. py:function:: sd_bus_open_system_remote(host)
Opens a new system bus connection on a remote host
through SSH. Host can be prefixed with ``username@`` and
followed by ``:port`` and ``/machine_name`` as in
``systemd-nspawn`` container name.
:param str host: Host name to connect.
:return: Remote system bus.
:rtype: SdBus
.. py:function:: sd_bus_open_system_machine(machine)
Opens a new system bus connection in a systemd-nspawn
container. Machine name can be prefixed with ``username@``.
Special machine name ``.host`` indicates local system.
:param str machine: Machine (container) name.
:return: Remote system bus.
:rtype: SdBus
.. py:function:: sd_bus_open_user_machine(machine)
Opens a new user session bus connection in a systemd-nspawn
container. Opens root user bus session or can be
prefixed with ``username@`` for a specific user.
:param str machine: Machine (container) name.
:return: Remote system bus.
:rtype: SdBus
Helper functions
++++++++++++++++++++++++++++++++++
.. py:function:: encode_object_path(prefix, external)
Encode that arbitrary string as a valid object path prefixed
with prefix.
:param str prefix: Prefix path. Must be a valid object path.
:param str external: Arbitrary string to identify object.
:return: valid object path
:rtype: str
Example on how systemd encodes unit names on D-Bus: ::
from sdbus import encode_object_path
# System uses /org/freedesktop/systemd1/unit as prefix of all units
# dbus.service is a name of D-Bus unit but dot . is not a valid object path
s = encode_object_path('/org/freedesktop/systemd1/unit', 'dbus.service')
print(s)
# Prints: /org/freedesktop/systemd1/unit/dbus_2eservice
.. py:function:: decode_object_path(prefix, full_path)
Decode object name that was encoded with
:py:func:`encode_object_path`.
:param str prefix: Prefix path. Must be a valid object path.
:param str full_path: Full path to be decoded.
:return: Arbitrary name
:rtype: str
Example decoding systemd unit name: ::
from sdbus import decode_object_path
s = decode_object_path(
'/org/freedesktop/systemd1/unit',
'/org/freedesktop/systemd1/unit/dbus_2eservice'
)
print(s)
# Prints: dbus.service
.. _dbus-flags:
Flags
+++++++++++++++++++++++++++++++++++
Flags are :py:obj:`int` values that should be ORed to combine.
Example, :py:obj:`DbusDeprecatedFlag` plus :py:obj:`DbusHiddenFlag`: ``DbusDeprecatedFlag | DbusHiddenFlag``
.. py:data:: DbusDeprecatedFlag
:type: int
Mark this method or property as deprecated in introspection data.
.. py:data:: DbusHiddenFlag
:type: int
Method or property will not show up in introspection data.
.. py:data:: DbusUnprivilegedFlag
:type: int
Mark this method or property as unprivileged. This means anyone can
call it. Only works for system bus as user session bus is fully
trusted by default.
.. py:data:: DbusNoReplyFlag
:type: int
This method does not have a reply message. It instantly returns
and does not have any errors.
.. py:data:: DbusPropertyConstFlag
:type: int
Mark that this property does not change during object life time.
.. py:data:: DbusPropertyEmitsChangeFlag
:type: int
This property emits signal when it changes.
.. py:data:: DbusPropertyEmitsInvalidationFlag
:type: int
This property emits signal when it invalidates. (means the value changed
but does not include new value in the signal)
.. py:data:: DbusPropertyExplicitFlag
:type: int
This property is too heavy to calculate so its not included in GetAll method
call.
.. py:data:: DbusSensitiveFlag
:type: int
Data in messages in sensitive and will be scrubbed from memory after message
is red.
|
