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