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
|
********* NOTE *********
This document is for historical reference only. The autogenerated 'spec.html' is the canonical D-Bus reference.
********* NOTE *********
NetworkManager DBUS API (unstable)
----------------------------------
NetworkManager (NM) exposes a DBUS service and API for two purposes: for programs to obtain information about the network state and network devices, and for programs or users to alter the network state in limited ways. This API is currently unstable and is likely to change in the future. Any methods or objects NOT described in this document are not part of the official API, are not meant for general use, and are not supported in any way.
There are three types of "objects" that NM allows other programs to interact with: the NetworkManager object, Device objects, and Network objects. There is only one NetworkManager object as it performs system-wide networking functions and controls each Device. There can be a arbitrary number of Devices, including no Devices at all, each of which represent a network device present in the system. A Network is the representation of a wireless network, of which each Device object may have an arbitrary number (as long as it is a wireless device).
Object structure:
NetworkManager
/ \
Device Device
/ \ (no networks)
Network Network
The NetworkManager object
-------------------------
The following constants are used to uniquely refer to the NetworkManager object when making DBUS method calls against NetworkManager:
DBUS Service: "org.freedesktop.NetworkManager"
DBUS Object Path: "/org/freedesktop/NetworkManager"
DBUS Interface: "org.freedesktop.NetworkManager"
Methods:
Name: getDevices Get the list of network devices NM knows about
Args: (none)
Returns: DBUS String Array Each item in the array is the NM identifier of a Device object
Name: getActiveDevice Return the currently active network device
Args: (none)
Returns: DBUS_TYPE_STRING The NM identifier of a Device object
Name: setActiveDevice Force NM to use a particular network device
Args: 1) Device object (DBUS_TYPE_STRING) - Network device to switch to
2) Wireless Network ESSID (DBUS_TYPE_STRING, optional) - ESSID of the wireless network to switch to
Returns: (nothing)
Name: status Retrieve status information about the network state
Args: (none)
Returns: DBUS_TYPE_STRING "connecting" - there is a pending network connection (waiting for a
DHCP request to complete, waiting for an encryption
key/passphrase, waiting for a wireless network, etc)
"connected" - there is an active network connection
"scanning" - there is no active network connection, but NetworkManager
is looking for an access point to associate with
"disconnected" - there is no network connection
Signals:
Name: DeviceNoLongerActive Signals that a network device is no longer active
Args: 1) Device object (DBUS_TYPE_STRING) - The deactivated network device
Name: DeviceNowActive Signals that a network device is newly activated
Args: 1) Device object (DBUS_TYPE_STRING) - The newly activated network device
Name: DeviceActivating Signals that a network device is about to become active
Args: 1) Device object (DBUS_TYPE_STRING) - The device about to become active
Name: DevicesChanged Signals that a device was either added or removed from the system
Args: 1) Device object (DBUS_TYPE_STRING) - The device which was added or removed
Name: DeviceActivationFailed Signals that activation for a device could not complete (dhcp failed or so)
Args: 1) Device object (DBUS_TYPE_STRING) - The device for which activation failed
2) Network name (DBUS_TYPE_STRING, optional) - ESSID of failed wireless network
Name: DeviceStrengthChanged Signals that the wireless strength percentage for the device has changed.
Args: 1) Device object (DBUS_TYPE_STRING) - The device for which strength changed
2) Strength (DBUS_TYPE_INT32) - The new strength percentage
NOTE: the following 3 Signals are likely to change in the near future
Name: DeviceIP4AddressChange Signals that a device's IPv4 address was changed
Args: 1) Device object (DBUS_TYPE_STRING) - The device whose IPv4 address changed
Name: WirelessNetworkAppeared Signals that a device found a new wireless network
Args: 1) Device object (DBUS_TYPE_STRING) - The device which noticed the wireless network
2) Network object (DBUS_TYPE_STRING) - The new wireless network's identifier
Name: WirelessNetworkDisappeared Signals that a device lost a new wireless network
Args: 1) Device object (DBUS_TYPE_STRING) - The device which lost the wireless network
2) Network object (DBUS_TYPE_STRING) - The no-longer-visible wireless network's identifier
The Device object
-----------------
The Device object is the NM representation of a network device. To refer to a NM Device, you must use the following constants when creating your DBUS message:
DBUS Service: "org.freedesktop.NetworkManager"
DBUS Interface: "org.freedesktop.NetworkManager.Devices"
Note that there is no DBUS Object Path listed above, the object path will always the the NM Device identfier returned from such methods as "getActiveDevice" and "getDevices".
Methods:
Name: getName Returns the system device name of the Device object (i.e. eth0)
Args: (none)
Returns: DBUS_TYPE_STRING The system device name
Name: getType Returns the type of the device (ie wired, wireless, isdn, bluetooth, etc)
Args: (none)
Returns: DBUS_TYPE_INT32 0 - unknown type
1 - Wired ethernet
2 - Wireless (802.11a/b/g)
Name: getHalUdi Returns the HAL UDI of the device
Args: (none)
Returns: DBUS_TYPE_STRING
Name: getIP4Address Returns the IPv4 address of the device
Args: (none)
Returns: DBUS_TYPE_UINT32 The IPv4 address in network byte order
Name: getLinkActive Returns the link state of the device
Args: (none)
Returns: DBUS_TYPE_BOOLEAN TRUE - the device has a valid network link
Wired: cable is plugged in
Wireless: good link to a base station
FALSE - the device has no network link
Wired: no cable plugged in
Wireless: no base station, or bad encryption key
Name: getActiveNetwork (Wireless only) Returns the Network object indentifier of the wireless network
this device is currently associated with, if any
Args: (none)
Returns: DBUS_TYPE_STRING
Name: getNetworks (Wireless only) Returns a list of Network objects this device knows about
Args: (none)
Returns: DBUS String Array Each item in the array is a Network object identifier
The Network object
------------------
Each Device object that is of type 2 (Wireless device) keeps a list of Network objects that it knows about. Use the following constants to specify a Network object when creating DBUS method calls:
DBUS Service: "org.freedesktop.NetworkManager"
DBUS Interface: "org.freedesktop.NetworkManager.Devices"
Again, note that there is no DBUS Object Path above, since the object path used for the method call will be the Network object indentifier returned from a Device object's "getActiveNetwork" or "getNetworks" methods.
Methods:
Name: getName Return the name of the network (ESSID)
Args: (none)
Returns: DBUS_TYPE_STRING
Name: getAddress Returns the hardware address of the base station this wireless network belongs to.
NOTE: this may change in the near future to an array of addresses.
Args: (none)
Returns: DBUS_TYPE_STRING
Name: getStrength Return the strength percentage of the current wireless network
Args: (none)
Returns: DBUS_TYPE_INT32 The strength percentage of the current wireless network
Name: getFrequency Returns the frequency/channel this wireless network
Args: (none)
Returns: DBUS_TYPE_DOUBLE A frequency in GHz (i.e. 2.417)
Name: getRate Returns the max data rate this wireless network supports
Args: (none)
Returns: DBUS_TYPE_INT32 The max data rate in Mbps (i.e. 11)
Name: getEncrypted Returns whether or not this wireless network requires encryption
Args: (none)
Returns: DBUS_TYPE_BOOLEAN
|
