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