doc/service-api.txt

   1 Service hierarchy
   2 =================
   3
   4 Service         net.connman
   5 Interface       net.connman.Service
   6 Object path     [variable prefix]/{service0,service1,...}
   7
   8 Methods         dict GetProperties()
   9
  10                         Returns properties for the service object. See
  11                         the 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 ClearProperty(string name)
  26
  27                         Clears the value of the specified property.
  28
  29                         Possible Errors: [service].Error.InvalidArguments
  30                                          [service].Error.InvalidProperty
  31
  32                 void Connect()
  33
  34                         Connect this service. It will attempt to connect
  35                         WiFi, WiMAX or Bluetooth services.
  36
  37                         For Ethernet devices this method can only be used
  38                         if it has previously been disconnected. Otherwise
  39                         the plugging of a cable will trigger connecting
  40                         automatically. If no cable is plugged in this method
  41                         will fail.
  42
  43                         This method call will only return in case of an
  44                         error or when the service is fully connected. So
  45                         setting a longer D-Bus timeout might be a really
  46                         good idea.
  47
  48                         Possible Errors: [service].Error.InvalidArguments
  49
  50                 void Disconnect()
  51
  52                         Disconnect this service. If the service is not
  53                         connected an error message will be generated.
  54
  55                         On Ethernet devices this will disconnect the IP
  56                         details from the service. It will not magically
  57                         unplug the cable. When no cable is plugged in this
  58                         method will fail.
  59
  60                         This method can also be used to abort a previous
  61                         connectiong attempt via the Connect method.
  62
  63                         Possible Errors: [service].Error.InvalidArguments
  64
  65                 void Remove()
  66
  67                         A successfully connected service with Favorite=true
  68                         can be removed this way. If it is connected, it will
  69                         be automatically disconnected first.
  70
  71                         If the service requires a passphrase it will be
  72                         cleared and forgotten when removing.
  73
  74                         This is similar to setting the Favorite property
  75                         to false, but that is currently not supported.
  76
  77                         In the case a connection attempt failed and the
  78                         service is in the State=failure, this method can
  79                         also be used to reset the service.
  80
  81                         Calling this method on Ethernet devices will cause
  82                         an error message. It is not possible to remove these
  83                         kind of devices.
  84
  85                         Possible Errors: [service].Error.InvalidArguments
  86
  87                 void MoveBefore(object service)
  88
  89                         If a service has been used before, this allows a
  90                         reorder of the favorite services.
  91
  92                         The target service object must be part of this
  93                         profile. Moving between profiles is not supported.
  94
  95                         Possible Errors: [service].Error.InvalidArguments
  96
  97                 void MoveAfter(object service)
  98
  99                         If a service has been used before, this allows a
 100                         reorder of the favorite services.
 101
 102                         The target service object must be part of this
 103                         profile. Moving between profiles is not supported.
 104
 105                         Possible Errors: [service].Error.InvalidArguments
 106
 107                 void ResetCounters()  [experimental]
 108
 109                         Reset the counter statistics.
 110
 111                         Possible Errors: None
 112
 113 Signals         PropertyChanged(string name, variant value)
 114
 115                         This signal indicates a changed value of the given
 116                         property.
 117
 118 Properties      string State [readonly]
 119
 120                         The service state information.
 121
 122                         Valid states are "idle", "failure", "association",
 123                         "configuration", "ready" and "online".
 124
 125                         The "ready" state signals a successfully
 126                         connected device. "online" signals that an
 127                         Internet connection is available and has been
 128                         verified.
 129
 130                 string Error [readonly]
 131
 132                         The service error status details.
 133
 134                         When error occur during connection or disconnection
 135                         the detailed information is represented in this
 136                         property to help the user interface to present the
 137                         user with alternate options.
 138
 139                         This property is only valid when the service is in
 140                         the "failure" state. Otherwise it might be empty or
 141                         not present at all.
 142
 143                         Current defined error code is "dhcp-failed".
 144
 145                 string Name [readonly]
 146
 147                         The service name (for example "Wireless" etc.)
 148
 149                         This name can be used for directly displaying it in
 150                         the application. It has pure informational purpose.
 151
 152                         For Ethernet devices and hidden WiFi networks it is
 153                         not guaranteed that this property is present.
 154
 155                 string Type [readonly]
 156
 157                         The service type (for example "ethernet", "wifi" etc.)
 158
 159                         This information should only be used to determine
 160                         advanced properties or showing the correct icon
 161                         to the user.
 162
 163                 array{string} Security [readonly]
 164
 165                         If the service type is WiFi, then this property is
 166                         present and contains the list of security methods
 167                         or key management settings.
 168
 169                         Possible values are "none", "wep", "psk", "ieee8021x"
 170                         and also "wps".
 171
 172                         This property might be only present for WiFi
 173                         services.
 174
 175                 uint8 Strength [readonly]
 176
 177                         Indicates the signal strength of the service. This
 178                         is a normalized value between 0 and 100.
 179
 180                         This property will not be present for Ethernet
 181                         devices.
 182
 183                 boolean Favorite [readonly]
 184
 185                         Will be true if a cable is plugged in or the user
 186                         selected and successfully connected to this service.
 187
 188                         This value is automatically changed and to revert
 189                         it back to false the Remove() method needs to be
 190                         used.
 191
 192                 boolean Immutable [readonly]
 193
 194                         This value will be set to true if the service is
 195                         configured externally via a configuration file.
 196
 197                         The only valid operation are Connect() and of
 198                         course Disconnect(). The Remove() method will
 199                         result in an error.
 200
 201                 boolean AutoConnect [readwrite]
 202
 203                         If set to true, this service will auto-connect
 204                         when no other connection is available.
 205
 206                         The service won't auto-connect while roaming.
 207
 208                         For favorite services it is possible to change
 209                         this value to prevent or permit automatic
 210                         connection attempts.
 211
 212                 boolean Roaming [readonly]
 213
 214                         This property indicates if this service is roaming.
 215
 216                         In the case of Cellular services this normally
 217                         indicates connections to a foreign provider when
 218                         traveling abroad.
 219
 220                 array{string} Nameservers [readonly]
 221
 222                         The list of currently active nameservers for this
 223                         service. If the server is not in READY or ONLINE
 224                         state than this list will be empty.
 225
 226                         Global nameservers are automatically added to this
 227                         list. The array represents a sorted list of the
 228                         current nameservers. The first one has the highest
 229                         priority and is used by default.
 230
 231                         When using DHCP this array represents the nameservers
 232                         provided by the network. In case of manual settings,
 233                         the ones from Nameservers.Configuration are used.
 234
 235                 array{string} Nameservers.Configuration [readwrite]
 236
 237                         The list of manually configured domain name
 238                         servers. Some cellular networks don't provide
 239                         correct name servers and this allows for an
 240                         override.
 241
 242                         This array is sorted by priority and the first
 243                         entry in the list represents the nameserver with
 244                         the highest priority.
 245
 246                         When using manual configuration and no global
 247                         nameservers are configured, then it is useful
 248                         to configure this setting.
 249
 250                         Changes to the domain name servers can be done
 251                         at any time. It will not cause a disconnect of
 252                         the service. However there might be small window
 253                         where name resolution might fail.
 254
 255                 array{string} Timeservers [readonly]
 256
 257                         The list of currently active timeservers for this
 258                         service. If the server is not in READY or ONLINE
 259                         state than this list will be empty.
 260
 261                 array{string} Timeservers.Configuration [readwrite]
 262
 263                         The list of manually configured time servers.
 264
 265                         The first entry in the list represents the
 266                         timeserver with the highest priority.
 267
 268                         When using manual configuration this setting
 269                         is useful to override all the other timeserver
 270                         settings. This is service specific, hence only
 271                         the values for the default service are used.
 272
 273                         Changes to this property will result in restart
 274                         of NTP query.
 275
 276                 array{string} Domains [readonly]
 277
 278                         The list of currently used search domains.
 279
 280                 array{string} Domains.Configuration [readwrite]
 281
 282                         The list of manually configured search domains.
 283
 284                 dict IPv4 [readonly]
 285
 286                         string Method [readonly]
 287
 288                                 Possible values are "dhcp", "manual"
 289                                 and "off".
 290
 291                                 The value "fixed" indicates an IP address
 292                                 that can not be modified. For example
 293                                 cellular networks return fixed information.
 294
 295                         string Address [readonly]
 296
 297                                 The current configured IPv4 address.
 298
 299                         string Netmask [readonly]
 300
 301                                 The current configured IPv4 netmask.
 302
 303                         string Gateway [readonly]
 304
 305                                 The current configured IPv4 gateway.
 306
 307                 dict IPv4.Configuration [readwrite]
 308
 309                         Same values as IPv4 property. The IPv4 represents
 310                         the actual system configuration while this allows
 311                         user configuration.
 312
 313                         Changing these settings will cause a state change
 314                         of the service. The service will become unavailable
 315                         until the new configuration has been successfully
 316                         installed.
 317
 318                 dict IPv6 [readonly]
 319
 320                         string Method [readonly]
 321
 322                                 Possible values are "auto", "manual", "6to4"
 323                                 and "off".
 324
 325                                 The value "fixed" indicates an IP address
 326                                 that can not be modified. For example
 327                                 cellular networks return fixed information.
 328                                 The value "6to4" is returned if 6to4 tunnel
 329                                 is created by connman. The tunnel can only be
 330                                 created if method was set to "auto" by the
 331                                 user. User cannot set the method to "6to4".
 332
 333                         string Address [readonly]
 334
 335                                 The current configured IPv6 address.
 336
 337                         uint8 PrefixLength [readonly]
 338
 339                                 The prefix length of the IPv6 address.
 340
 341                         string Gateway [readonly]
 342
 343                                 The current configured IPv6 gateway.
 344
 345                         string Privacy [readonly]
 346
 347                                 Enable or disable IPv6 privacy extension
 348                                 that is described in RFC 4941. The value
 349                                 has only meaning if Method is set to "auto".
 350
 351                                 Value "disabled" means that privacy extension
 352                                 is disabled and normal autoconf addresses are
 353                                 used.
 354
 355                                 Value "enabled" means that privacy extension is
 356                                 enabled and system prefers to use public
 357                                 addresses over temporary addresses.
 358
 359                                 Value "prefered" means that privacy extension is
 360                                 enabled and system prefers temporary addresses
 361                                 over public addresses.
 362
 363                                 Default value is "disabled".
 364
 365                 dict IPv6.Configuration [readwrite]
 366
 367                         Same values as IPv6 property. The IPv6 represents
 368                         the actual system configuration while this allows
 369                         user configuration.
 370
 371                         Changing these settings will cause a state change
 372                         of the service. The service will become unavailable
 373                         until the new configuration has been successfully
 374                         installed.
 375
 376                 dict Proxy [readonly]
 377
 378                         string Method [readonly]
 379
 380                                 Possible values are "direct", "auto" and
 381                                 "manual".
 382
 383                                 In case of "auto" method, the URL file can be
 384                                 provided unless you want to let DHCP/WPAD
 385                                 auto-discover to be tried. In such case if DHCP
 386                                 and WPAD auto-discover methods fails then
 387                                 method will be "direct".
 388
 389                                 In case of "direct" no additional information
 390                                 are provided. For the "manual" method the
 391                                 Servers have to be set, Excludes is optional.
 392
 393                         string URL [readonly]
 394
 395                                 Automatic proxy configuration URL. Used by
 396                                 "auto" method.
 397
 398                         array{string} Servers [readonly]
 399
 400                                 Used when "manual" method is set.
 401
 402                                 List of proxy URIs. The URI without a protocol
 403                                 will be interpreted as the generic proxy URI.
 404                                 All others will target a specific protocol and
 405                                 only once.
 406
 407                                 Example for generic proxy server entry would
 408                                 be like this: "server.example.com:911".
 409
 410                         array{string} Excludes [readonly]
 411
 412                                 Used when "manual" method is set.
 413
 414                                 List of hosts which can be accessed directly.
 415
 416                 dict Proxy.Configuration [readwrite]
 417
 418                         Same values as Proxy property. The Proxy represents
 419                         the actual system configuration while this allows
 420                         user configuration.
 421
 422                         If "auto" method is set with an empty URL, then
 423                         DHCP/WPAD auto-discover will be tried. Otherwise the
 424                         specified URL will be used.
 425
 426                 dict Provider [readonly]
 427
 428                         string Host [readonly]
 429
 430                                VPN host IP.
 431
 432                         string Domain [readonly]
 433
 434                                VPN Domain.
 435
 436                         string Name [readonly]
 437
 438                                VPN provider Name.
 439
 440                         string Type [readonly]
 441
 442                                VPN provider type.
 443
 444                 dict Ethernet [readonly]
 445
 446                         string Method [readonly]
 447
 448                                 Possible values are "auto" and "manual".
 449
 450                         string Interface [readonly]
 451
 452                                 Interface name (for example eth0).
 453
 454                         string Address [readonly]
 455
 456                                 Ethernet device address (MAC address).
 457
 458                         uint16 MTU [readonly]
 459
 460                                 The Ethernet MTU (default is 1500).
 461
 462                         uint16 Speed [readonly]
 463
 464                                 Selected speed of the line.
 465
 466                                 This information might not always be
 467                                 available.
 468
 469                         string Duplex [readonly]
 470
 471                                 Selected duplex settings of the line.
 472
 473                                 Possible values are "half" and "full".
 474
 475                                 This information might not always be
 476                                 available.