doc/manager-api.txt

   1 Manager hierarchy
   2 =================
   3
   4 Service         net.connman
   5 Interface       net.connman.Manager
   6 Object path     /
   7
   8 Methods         dict GetProperties()
   9
  10                         Returns all global system properties. See the
  11                         properties section for available properties.
  12
  13                         Possible Errors: [service].Error.InvalidArguments
  14
  15                 void SetProperty(string name, variant value)
  16
  17                         Changes the value of the specified property. Only
  18                         properties that are listed as read-write are
  19                         changeable. On success a PropertyChanged signal
  20                         will be emitted.
  21
  22                         Possible Errors: [service].Error.InvalidArguments
  23                                          [service].Error.InvalidProperty
  24
  25                 array{object,dict} GetTechnologies()
  26
  27                         Returns a list of tuples with technology object
  28                         path and dictionary of technology properties.
  29
  30                         Possible Errors: [service].Error.InvalidArguments
  31
  32                 array{object,dict} GetServices()
  33
  34                         Returns a sorted list of tuples with service
  35                         object path and dictionary of service properties.
  36
  37                         This list will not contain sensitive information
  38                         like passphrases etc.
  39
  40                         Possible Errors: [service].Error.InvalidArguments
  41
  42                 array{object,dict} GetPeers() [experimental]
  43
  44                         Returns a sorted list of tuples with peer object path
  45                         and dictionary of peer properties
  46
  47                         Possible Errors: [service].Error.InvalidArguments
  48
  49                 array{string} GetTetheringClients() [experimental]
  50
  51                         Returns a sorted list of MAC addresses of clients
  52                         connected to tethered technologies.
  53
  54                 object ConnectProvider(dict provider)   [deprecated]
  55
  56                         Connect to a VPN specified by the given provider
  57                         properties.
  58
  59                         When successful this method will return the object
  60                         path of the VPN service object.
  61
  62                         This method can also be used to connect to an
  63                         already existing VPN.
  64
  65                         This method call will only return in case of an
  66                         error or when the service is fully connected. So
  67                         setting a longer D-Bus timeout might be a really
  68                         good idea.
  69
  70                         When 'SessionMode' property is enabled, this method
  71                         call is disallowed.
  72
  73                         This API is deprecated and should not be used.
  74                         The VPN configuration API is provided by ConnMan
  75                         VPN daemon and user should use that one instead.
  76
  77                         Possible Errors: [service].Error.InvalidArguments
  78
  79                 void RemoveProvider(object path)        [deprecated]
  80
  81                         Remove a VPN specified by the object path.
  82
  83                 void RegisterAgent(object path)
  84
  85                         Register new agent for handling user requests.
  86
  87                         Possible Errors: [service].Error.InvalidArguments
  88
  89                 void UnregisterAgent(object path)
  90
  91                         Unregister an existing agent.
  92
  93                         Possible Errors: [service].Error.InvalidArguments
  94
  95                 void RegisterCounter(object path, uint32 accuracy, uint32 period)  [experimental]
  96
  97                         Register a new counter for user notifications.
  98
  99                         The accuracy is specified in kilo-bytes and defines
 100                         a threshold for counter updates. Together with the
 101                         period value it defines how often user space needs
 102                         to be updated. The period value is in seconds.
 103
 104                         This interface is not meant for time tracking. If
 105                         the time needs to be tracked down to the second, it
 106                         is better to have a real timer running inside the
 107                         application than using this interface.
 108
 109                         Also getting notified for every kilo-byte is a bad
 110                         choice (even if the interface supports it). Something
 111                         like 10 kilo-byte units or better 1 mega-byte seems
 112                         to be a lot more reasonable and better for the user.
 113
 114                         Possible Errors: [service].Error.InvalidArguments
 115
 116                 void UnregisterCounter(object path)  [experimental]
 117
 118                         Unregister an existing counter.
 119
 120                         Possible Errors: [service].Error.InvalidArguments
 121
 122                 object CreateSession(dict settings, object notifier)  [experimental]
 123
 124                         Create a new session for the application. Every
 125                         application can create multiple session with
 126                         different settings. The settings are described
 127                         as part of the session interface.
 128
 129                         The notifier allows asynchronous notification about
 130                         session specific changes. These changes can be
 131                         for online/offline state or IP address changes or
 132                         similar things the application is required to
 133                         handle.
 134
 135                         Every application should at least create one session
 136                         to inform about its requirements and it purpose.
 137
 138                 void DestroySession(object session)  [experimental]
 139
 140                         Remove the previously created session.
 141
 142                         If an application exits unexpectatly the session
 143                         will be automatically destroyed.
 144
 145                 object path, dict, fd RequestPrivateNetwork(dict options)
 146                                                                 [experimental]
 147
 148                         Request a new Private Network, which includes the
 149                         creation of a tun/tap interface, and IP
 150                         configuration, NAT and IP forwarding on that
 151                         interface.
 152                         An object path, a dictionary and a file descriptor
 153                         with IP settings are returned.
 154
 155                         Possible Errors: [service].Error.InvalidArguments
 156                                          [service].Error.NotSupported
 157
 158                 void ReleasePrivateNetwork(object path) [experimental]
 159
 160                         Releases a private network.
 161
 162                         Possible Errors: [service].Error.InvalidArguments
 163
 164                 void RegisterPeerService(dict specification, boolean master)
 165                            [experimental]
 166
 167                         Registers a local P2P Peer service
 168
 169                         Even if p2p techonology is not available, it will be
 170                         possible to register peer services, since a p2p
 171                         enabled WiFi device might appear at anytime. The
 172                         registered peer services will automatically be enabled
 173                         for the p2p WiFi device; the application does not need
 174                         to do any re-registration.
 175
 176                         A Peer service belongs to the process that registers
 177                         it, thus if that process dies, its Peer services will
 178                         be destroyed as well.
 179
 180                         The specification dict follows the format described
 181                         in the Peer API document.
 182
 183                         ConnMan will be able to determine in most cases
 184                         whether to be the P2P Group Owner or not. If the
 185                         service for some reason must belong to a group that
 186                         this device manages, the "master" property can be
 187                         set. Do not enable the "master" property unless it
 188                         is absolutely sure that this is needed for the
 189                         provided peer service.
 190
 191                         Possible Errors: [service].Error.InvalidArguments
 192                                          [service].Error.AlreadyExists
 193                                          [service].Error.NotSupported
 194
 195                 void UnregisterPeerService(dict specification) [experimental]
 196
 197                         Unregisters an existing local P2P Peer service
 198
 199                         Possible Errors: [service].Error.InvalidArguments
 200                                          [service].Error.NotRegistered
 201
 202 Signals         TechnologyAdded(object path, dict properties)
 203
 204                         Signal that is sent when a new technology is added.
 205
 206                         It contains the object path of the technology and
 207                         also its properties.
 208
 209                 TechnologyRemoved(object path)
 210
 211                         Signal that is sent when a technology has been removed.
 212
 213                         The object path is no longer accessible after this
 214                         signal and only emitted for reference.
 215
 216                 ServicesChanged(array{object, dict}, array{object})
 217
 218                         This signal indicates a change in the services.
 219                         List of all services currently registered is passed
 220                         via the first array. And a list of services that have
 221                         been removed via the second array.
 222
 223                         The list of all services is sorted. The dictionary
 224                         with the properties might be empty in case none of
 225                         the properties have changed. Or only contains the
 226                         properties that have changed.
 227
 228                         For newly added services the whole set of properties
 229                         will be present.
 230
 231                         The list of removed services can be empty.
 232
 233                         This signal will only be triggered when the sort
 234                         order of the service list or the number of services
 235                         changes. It will not be emitted if only a property
 236                         of the service object changes. For that it is
 237                         required to watch the PropertyChanged signal of
 238                         the service object.
 239
 240                 PeersChanged(array{object, dict}, array{object}) [experimental]
 241
 242                         This signal indicates a change in the peers. List of
 243                         all peers currently registered is passed via the first
 244                         array. And a list of peers that have been removed via
 245                         the second array.
 246
 247                         The list of all peers is sorted. The dictionary
 248                         with the properties might be empty in case none of the
 249                         properties have changed. Or only contains the
 250                         properties that have changed.
 251
 252                         For newly added peers the whole set of properties will
 253                         be present.
 254
 255                         The list of removed peers can be empty.
 256
 257                         This signal will only be triggered when the sort order
 258                         of the peer list or the number of peers changes. It
 259                         will not be emitted if only a property of the peer
 260                         object changes. For that it is required to watch the
 261                         PropertyChanged signal of the peer object.
 262
 263                 TetheringClientsChanged(array{string}, array{string}) [experimental]
 264
 265                         This signal indicates a change in the tethering clients.
 266                         List of all tethering clients currently registered connman is
 267                         passed via the first array. And a list of tethering clients that
 268                         have been removed via the second array.
 269
 270                 PropertyChanged(string name, variant value)
 271
 272                         This signal indicates a changed value of the given
 273                         property.
 274
 275 Properties      string State [readonly]
 276
 277                         The global connection state of a system. Possible
 278                         values are "offline", "idle", "ready" and "online".
 279
 280                         If the device is in offline mode, the value "offline"
 281                         indicates this special global state. It can also be
 282                         retrieved via the OfflineMode property, but is kept
 283                         here for consistency and to differentiate from "idle".
 284
 285                         However when OfflineMode property is true, the State
 286                         property can still be "idle", "ready" or "online"
 287                         since it is possible by the end user to re-enable
 288                         individual technologies like WiFi and Bluetooth while
 289                         in offline mode.
 290
 291                         The states "idle", "ready" and "online" match to
 292                         states from the services. If no service is in
 293                         either "ready" or "online" state it will indicate
 294                         the "idle" state.
 295
 296                         If at least one service is in "ready" state and no
 297                         service is in "online" state, then it will indicate
 298                         the "ready" state.
 299
 300                         When at least one service is in "online" state,
 301                         this property will indicate "online" as well.
 302
 303                 boolean OfflineMode [readwrite]
 304
 305                         The offline mode indicates the global setting for
 306                         switching all radios on or off. Changing offline mode
 307                         to true results in powering down all devices. When
 308                         leaving offline mode the individual policy of each
 309                         device decides to switch the radio back on or not.
 310
 311                         During offline mode, it is still possible to switch
 312                         certain technologies manually back on. For example
 313                         the limited usage of WiFi or Bluetooth devices might
 314                         be allowed in some situations.
 315
 316                 boolean SessionMode [readwrite]  [experminental][deprecated]
 317
 318                         This property exists only for compatibility reasons
 319                         and does not affect ConnMan in any way.
 320
 321                         The default value is false.