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                 string GetState()
  26
  27                         Return global connection state of a system. The
  28                         same value is return via the State property.
  29
  30                         Possible Errors: [service].Error.InvalidArguments
  31
  32                 void RequestScan(string type)
  33
  34                         Request to trigger a scan for the specified
  35                         technology. The empty string "" triggers scanning
  36                         on all technologies.
  37
  38                         Possible Errors: [service].Error.InvalidArguments
  39
  40                 void EnableTechnology(string type)
  41
  42                         Enable specified type of technologies.
  43
  44                         Possible Errors: [service].Error.InvalidArguments
  45
  46                 void DisableTechnology(string type)
  47
  48                         Disable specified type of technologies.
  49
  50                         Possible Errors: [service].Error.InvalidArguments
  51
  52                 array{object,dict} GetServices()
  53
  54                         Returns a sorted list of tuples with service
  55                         object path and dictionary of service properties.
  56
  57                         This list will not contain sensitive information
  58                         like passphrases etc.
  59
  60                         Possible Errors: [service].Error.InvalidArguments
  61
  62                 object LookupService(string pattern)
  63
  64                         Lookup a service matching the specific pattern.
  65
  66                         Examples are interface names like "eth0", "wlan0"
  67                         etc. or service names like "hotspot" etc.
  68
  69                         In case of multiple services match the the pattern
  70                         an error is returned.
  71
  72                         Possible Errors: [service].Error.InvalidArguments
  73                                          [service].Error.NotUnique
  74                                          [service].Error.NotFound
  75
  76                 object ConnectService(dict network)
  77
  78                         Connect to a network specified by the given
  79                         properties.
  80
  81                         For connecting to a hidden WiFi network for example
  82                         it is required that Type = "wifi" and the SSID
  83                         properties are provided.
  84
  85                         When successful this method will return object
  86                         path of the service object.
  87
  88                         This method can also be used to connect to an
  89                         already existing service. It works exactly the
  90                         same as executing the Connect method from the
  91                         service interface.
  92
  93                         This method call will only return in case of an
  94                         error or when the service is fully connected. So
  95                         setting a longer D-Bus timeout might be a really
  96                         good idea.
  97
  98                         When 'SessionMode' property is enabled, this method
  99                         call is disallowed.
 100
 101                         Possible Errors: [service].Error.InvalidArguments
 102
 103                 void ProvisionService(string configuration)
 104
 105                         Provide a configuration for services.
 106
 107                         Service configuration is provided as a single string
 108                         that follows the same format as configuration files,
 109                         see config-format.txt. An exception to this format
 110                         is that only one service can be provisioned per call.
 111
 112                         Possible Errors: [service].Error.InvalidArguments
 113
 114                 object ConnectProvider(dict provider)
 115
 116                         Connect to a VPN specified by the given provider
 117                         properties.
 118
 119                         When successful this method will return the object
 120                         path of the VPN service object.
 121
 122                         This method can also be used to connect to an
 123                         already existing VPN.
 124
 125                         This method call will only return in case of an
 126                         error or when the service is fully connected. So
 127                         setting a longer D-Bus timeout might be a really
 128                         good idea.
 129
 130                         When 'SessionMode' property is enabled, this method
 131                         call is disallowed.
 132
 133                         Possible Errors: [service].Error.InvalidArguments
 134
 135                 void RegisterAgent(object path)
 136
 137                         Register new agent for handling user requests.
 138
 139                         Possible Errors: [service].Error.InvalidArguments
 140
 141                 void UnregisterAgent(object path)
 142
 143                         Unregister an existing agent.
 144
 145                         Possible Errors: [service].Error.InvalidArguments
 146
 147                 void RegisterCounter(object path, uint32 accuracy, uint32 period)
 148
 149                         Register a new counter for user notifications.
 150
 151                         The accuracy is specified in kilo-bytes and defines
 152                         a threshold for counter updates. Together with the
 153                         period value it defines how often user space needs
 154                         to be updated. The period value is in seconds.
 155
 156                         This interface is not meant for time tracking. If
 157                         the time needs to be tracked down to the second, it
 158                         is better to have a real timer running inside the
 159                         application than using this interface.
 160
 161                         Also getting notified for every kilo-byte is a bad
 162                         choice (even if the interface supports it). Something
 163                         like 10 kilo-byte units or better 1 mega-byte seems
 164                         to be a lot more reasonable and better for the user.
 165
 166                         Possible Errors: [service].Error.InvalidArguments
 167
 168                 void UnregisterCounter(object path)
 169
 170                         Unregister an existing counter.
 171
 172                         Possible Errors: [service].Error.InvalidArguments
 173
 174                 object CreateSession(dict settings, object notifier)
 175
 176                         Create a new session for the application. Every
 177                         application can create multiple session with
 178                         different settings. The settings are described
 179                         as part of the session interface.
 180
 181                         The notifier allows asynchronous notification about
 182                         session specific changes. These changes can be
 183                         for online/offline state or IP address changes or
 184                         similar things the application is required to
 185                         handle.
 186
 187                         Every application should at least create one session
 188                         to inform about its requirements and it purpose.
 189
 190                 void DestroySession(object session)
 191
 192                         Remove the previously created session. The notifier
 193                         will be informed via its release method.
 194
 195                         If an application exits unexpectatly the session
 196                         will be automatically destroyed.
 197
 198                 fd, dict {settings} RequestPrivateNetwork(dict options)
 199                                                                 [experimental]
 200
 201                         Request a new Private Network, whick includes the
 202                         creation of a tun/tap interface, and IP
 203                         configuration, NAT and IP forwarding on that
 204                         interface.
 205                         A file descritor to the interface is returned together
 206                         with the IP, gateway and DNS settings for the
 207                         interface.
 208
 209                         Possible Errors: [service].Error.InvalidArguments
 210                                          [service].Error.NotSupported
 211
 212                 void ReleasePrivateNetwork(fd) [experimental]
 213
 214                         Releases a private network.
 215
 216                         Possible Errors: [service].Error.InvalidArguments
 217
 218 Signals         PropertyChanged(string name, variant value)
 219
 220                         This signal indicates a changed value of the given
 221                         property.
 222
 223                 StateChanged(string state)
 224
 225                         This signal is similar to the PropertyChanged signal
 226                         for the State property.
 227
 228                         It exists for application state only care about the
 229                         current state and so can avoid to be woken up when
 230                         other details changes.
 231
 232 Properties      string State [readonly]
 233
 234                         The global connection state of a system. Possible
 235                         values are "online" if at least one connection exists
 236                         and "offline" if no device is connected.
 237
 238                         In certain situations the state might change to
 239                         the value "connected". This can only be seen if
 240                         previously no connection was present.
 241
 242                 array{string} AvailableTechnologies [readonly]
 243
 244                         The list of available technologies. The strings
 245                         are the same as the ones from the service types.
 246
 247                 array{string} EnabledTechnologies [readonly]
 248
 249                         The list of enabled technologies. The strings
 250                         are the same as the ones from the service types.
 251
 252                 array{string} ConnectedTechnologies [readonly]
 253
 254                         The list of connected technologies. The strings
 255                         are the same as the ones from the service type.
 256
 257                 string DefaultTechnology [readonly]
 258
 259                         The current connected technology which holds the
 260                         default route.
 261
 262                 boolean OfflineMode [readwrite]
 263
 264                         The offline mode indicates the global setting for
 265                         switching all radios on or off. Changing offline mode
 266                         to true results in powering down all devices. When
 267                         leaving offline mode the individual policy of each
 268                         device decides to switch the radio back on or not.
 269
 270                         During offline mode, it is still possible to switch
 271                         certain technologies manually back on. For example
 272                         the limited usage of WiFi or Bluetooth devices might
 273                         be allowed in some situations.
 274
 275                 object ActiveProfile [readwrite]
 276
 277                         Object path of the current active profile.
 278
 279                 array{object} Technologies [readonly]
 280
 281                         List of technology object paths.
 282
 283                 array{object} Services [readonly]
 284
 285                         List of service object paths. The list is sorted
 286                         internally to have the service with the default
 287                         route always first and then the favorite services
 288                         followed by scan results.
 289
 290                         This list represents the available services for the
 291                         current selected profile. If the profile gets changed
 292                         then this list will be updated.
 293
 294                         The same list is available via the profile object
 295                         itself. It is just provided here for convenience of
 296                         applications only dealing with the current active
 297                         profile.
 298
 299                 boolean SessionMode [readwrite]
 300
 301                         This disables the auto connect feature. It should be
 302                         enabled when the Session API is used. When SessionMode
 303                         is enabled, 'ConnectService' and 'ConnectProvider'
 304                         method calls are disallowed.
 305
 306                         The default value is false.