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
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
Common API
=======================
These calls are shared between async and blocking API.
.. py:currentmodule:: sdbus
D-Bus connections calls
++++++++++++++++++++++++++++++++++
.. py:function:: request_default_bus_name_async(new_name, allow_replacement, replace_existing, queue)
:async:
Acquire a name on the default bus async.
:param str new_name: the name to acquire.
Must be a valid D-Bus service name.
:param str new_name: the name to acquire.
Must be a valid D-Bus service name.
:param bool allow_replacement: If name was acquired allow other peers
to take away the name.
:param bool replace_existing: If current name owner allows, take
away the name.
:param bool queue: Queue up for name acquisition.
:py:exc:`.SdBusRequestNameInQueueError` will be raised when successfully
placed in queue. :py:meth:`Ownership change signal <sdbus_async.dbus_daemon.FreedesktopDbus.name_owner_changed>`
should be monitored get notified when the name was acquired.
:raises: :ref:`name-request-exceptions` and other D-Bus exceptions.
.. py:function:: request_default_bus_name(new_name, allow_replacement, replace_existing, queue)
Acquire a name on the default bus.
:param str new_name: the name to acquire.
Must be a valid D-Bus service name.
:param bool allow_replacement: If name was acquired allow other peers
to take away the name.
:param bool replace_existing: If current name owner allows, take
away the name.
:param bool queue: Queue up for name acquisition.
:py:exc:`.SdBusRequestNameInQueueError` will be raised when successfully
placed in queue. :py:meth:`Ownership change signal <sdbus_async.dbus_daemon.FreedesktopDbus.name_owner_changed>`
should be monitored get notified when the name was acquired.
:raises: :ref:`name-request-exceptions` and other D-Bus exceptions.
.. py:function:: set_default_bus(new_default)
Sets default bus.
Should be called before you create any objects that might use
default bus.
Default bus can be replaced but the change will only affect
newly created objects.
:param SdBus new_default: The bus object to set default to.
.. py:function:: get_default_bus(new_default)
Gets default bus.
:return: default 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.
|
