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