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                 boolean GetUserFavorite() [experimental]
 126
 127                         This function is used to check whether this service
 128                         is favorite to the current user.
 129
 130                         Possible Errors: None
 131
 132 Signals         PropertyChanged(string name, variant value)
 133
 134                         This signal indicates a changed value of the given
 135                         property.
 136
 137 Properties      string State [readonly]
 138
 139                         The service state information.
 140
 141                         Valid states are "idle", "failure", "association",
 142                         "configuration", "ready", "disconnect" and "online".
 143
 144                         The "ready" state signals a successfully
 145                         connected device. "online" signals that an
 146                         Internet connection is available and has been
 147                         verified.
 148
 149                         See doc/overview-api.txt for more information about
 150                         state transitions.
 151
 152                 string Error [readonly]
 153
 154                         The service error status details.
 155
 156                         When error occur during connection or disconnection
 157                         the detailed information is represented in this
 158                         property to help the user interface to present the
 159                         user with alternate options.
 160
 161                         This property is only valid when the service is in
 162                         the "failure" state. Otherwise it might be empty or
 163                         not present at all.
 164
 165                         Current defined error code is "dhcp-failed".
 166
 167                 string Name [readonly]
 168
 169                         The service name (for example "Wireless" etc.)
 170
 171                         This name can be used for directly displaying it in
 172                         the application. It has pure informational purpose
 173                         and no attempt should be made to translate it.
 174
 175                         For Ethernet devices and hidden WiFi networks this
 176                         property is not present.
 177
 178                 string Type [readonly]
 179
 180                         The service type (for example "ethernet", "wifi" etc.)
 181
 182                         This information should only be used to determine
 183                         advanced properties or showing the correct icon
 184                         to the user.
 185
 186                         Together with a missing Name property, this can
 187                         be used to identify hidden WiFi networks.
 188
 189                 array{string} Security [readonly]
 190
 191                         If the service type is WiFi, then this property is
 192                         present and contains the list of security methods
 193                         or key management settings.
 194
 195                         Possible values are "none", "wep", "psk", "ieee8021x"
 196                         and also "wps".
 197
 198                         This property might be only present for WiFi
 199                         services.
 200
 201                 string BSSID [readonly]
 202
 203                         If the service type is WiFi, then this property
 204                         indicates the BSSID of the service.
 205
 206                 uint32 MaxRate [readonly]
 207
 208                         If the service type is WiFi, then this property
 209                         indicates the Maximum speed(bps) of the service.
 210
 211                 uint16 Frequency [readonly]
 212
 213                         If the service type is WiFi, then this property
 214                         indicates the frequency band(MHz) of the service.
 215
 216                 string EncryptionMode [readonly]
 217
 218                         If the service type is WiFi, then this property
 219                         indicates the key encryption mode.
 220
 221                         Possible values are "none", "wep", "tkip", "aes"
 222                         and "mixed".
 223
 224                         This property might be only present for WiFi
 225                         services.
 226
 227                 uint8 Strength [readonly]
 228
 229                         Indicates the signal strength of the service. This
 230                         is a normalized value between 0 and 100.
 231
 232                         This property will not be present for Ethernet
 233                         devices.
 234
 235                 boolean Favorite [readonly]
 236
 237                         Will be true if a cable is plugged in or the user
 238                         selected and successfully connected to this service.
 239
 240                         This value is automatically changed and to revert
 241                         it back to false the Remove() method needs to be
 242                         used.
 243
 244                 boolean Immutable [readonly]
 245
 246                         This value will be set to true if the service is
 247                         configured externally via a configuration file.
 248
 249                         The only valid operation are Connect() and of
 250                         course Disconnect(). The Remove() method will
 251                         result in an error.
 252
 253                 boolean AutoConnect [readwrite]
 254
 255                         If set to true, this service will auto-connect
 256                         when no other connection is available.
 257
 258                         The service won't auto-connect while roaming.
 259
 260                         For favorite services it is possible to change
 261                         this value to prevent or permit automatic
 262                         connection attempts.
 263
 264                 boolean Roaming [readonly]
 265
 266                         This property indicates if this service is roaming.
 267
 268                         In the case of Cellular services this normally
 269                         indicates connections to a foreign provider when
 270                         traveling abroad.
 271
 272                 array{string} Nameservers [readonly]
 273
 274                         The list of currently active nameservers for this
 275                         service. If the server is not in READY or ONLINE
 276                         state than this list will be empty.
 277
 278                         Global nameservers are automatically added to this
 279                         list. The array represents a sorted list of the
 280                         current nameservers. The first one has the highest
 281                         priority and is used by default.
 282
 283                         When using DHCP this array represents the nameservers
 284                         provided by the network. In case of manual settings,
 285                         the ones from Nameservers.Configuration are used.
 286
 287                 array{string} Nameservers.Configuration [readwrite]
 288
 289                         The list of manually configured domain name
 290                         servers. Some cellular networks don't provide
 291                         correct name servers and this allows for an
 292                         override.
 293
 294                         This array is sorted by priority and the first
 295                         entry in the list represents the nameserver with
 296                         the highest priority.
 297
 298                         When using manual configuration and no global
 299                         nameservers are configured, then it is useful
 300                         to configure this setting.
 301
 302                         Changes to the domain name servers can be done
 303                         at any time. It will not cause a disconnect of
 304                         the service. However there might be small window
 305                         where name resolution might fail.
 306
 307                 array{string} Timeservers [readonly]
 308
 309                         The list of currently active timeservers for this
 310                         service. If the server is not in READY or ONLINE
 311                         state than this list will be empty.
 312
 313                 array{string} Timeservers.Configuration [readwrite]
 314
 315                         The list of manually configured time servers.
 316
 317                         The first entry in the list represents the
 318                         timeserver with the highest priority.
 319
 320                         When using manual configuration this setting
 321                         is useful to override all the other timeserver
 322                         settings. This is service specific, hence only
 323                         the values for the default service are used.
 324
 325                         Changes to this property will result in restart
 326                         of NTP query.
 327
 328                 array{string} Domains [readonly]
 329
 330                         The list of currently used search domains taken
 331                         from Domains.Configurations if set, otherwise a
 332                         domain name if provided by DHCP or VPNs.
 333
 334                 array{string} Domains.Configuration [readwrite]
 335
 336                         The list of manually configured search domains.
 337
 338                 dict IPv4 [readonly]
 339
 340                         string Method [readonly]
 341
 342                                 Possible values are "dhcp", "manual"
 343                                 and "off".
 344
 345                                 The value "fixed" indicates an IP address
 346                                 that can not be modified. For example
 347                                 cellular networks return fixed information.
 348
 349                         string Address [readonly]
 350
 351                                 The current configured IPv4 address.
 352
 353                         string Netmask [readonly]
 354
 355                                 The current configured IPv4 netmask.
 356
 357                         string Gateway [readonly]
 358
 359                                 The current configured IPv4 gateway.
 360
 361                 dict IPv4.Configuration [readwrite]
 362
 363                         Same values as IPv4 property. The IPv4 represents
 364                         the actual system configuration while this allows
 365                         user configuration.
 366
 367                         Changing these settings will cause a state change
 368                         of the service. The service will become unavailable
 369                         until the new configuration has been successfully
 370                         installed.
 371
 372                 dict IPv6 [readonly]
 373
 374                         string Method [readonly]
 375
 376                                 Possible values are "auto", "manual", "6to4"
 377                                 and "off".
 378
 379                                 The value "fixed" indicates an IP address
 380                                 that can not be modified. For example
 381                                 cellular networks return fixed information.
 382                                 The value "6to4" is returned if 6to4 tunnel
 383                                 is created by connman. The tunnel can only be
 384                                 created if method was set to "auto" by the
 385                                 user. User cannot set the method to "6to4".
 386
 387                         string Address [readonly]
 388
 389                                 The current configured IPv6 address.
 390
 391                         uint8 PrefixLength [readonly]
 392
 393                                 The prefix length of the IPv6 address.
 394
 395                         string Gateway [readonly]
 396
 397                                 The current configured IPv6 gateway.
 398
 399                         string Privacy [readonly]
 400
 401                                 Enable or disable IPv6 privacy extension
 402                                 that is described in RFC 4941. The value
 403                                 has only meaning if Method is set to "auto".
 404
 405                                 Value "disabled" means that privacy extension
 406                                 is disabled and normal autoconf addresses are
 407                                 used.
 408
 409                                 Value "enabled" means that privacy extension is
 410                                 enabled and system prefers to use public
 411                                 addresses over temporary addresses.
 412
 413                                 Value "prefered" means that privacy extension is
 414                                 enabled and system prefers temporary addresses
 415                                 over public addresses.
 416
 417                                 Default value is "disabled".
 418
 419                 dict IPv6.Configuration [readwrite]
 420
 421                         Same values as IPv6 property. The IPv6 represents
 422                         the actual system configuration while this allows
 423                         user configuration.
 424
 425                         Changing these settings will cause a state change
 426                         of the service. The service will become unavailable
 427                         until the new configuration has been successfully
 428                         installed.
 429
 430                 dict Proxy [readonly]
 431
 432                         string Method [readonly]
 433
 434                                 Possible values are "direct", "auto" and
 435                                 "manual".
 436
 437                                 In case of "auto" method, the URL file can be
 438                                 provided unless you want to let DHCP/WPAD
 439                                 auto-discover to be tried. In such case if DHCP
 440                                 and WPAD auto-discover methods fails then
 441                                 method will be "direct".
 442
 443                                 In case of "direct" no additional information
 444                                 are provided. For the "manual" method the
 445                                 Servers have to be set, Excludes is optional.
 446
 447                         string URL [readonly]
 448
 449                                 Automatic proxy configuration URL. Used by
 450                                 "auto" method.
 451
 452                         array{string} Servers [readonly]
 453
 454                                 Used when "manual" method is set.
 455
 456                                 List of proxy URIs. The URI without a protocol
 457                                 will be interpreted as the generic proxy URI.
 458                                 All others will target a specific protocol and
 459                                 only once.
 460
 461                                 Example for generic proxy server entry would
 462                                 be like this: "server.example.com:911".
 463
 464                         array{string} Excludes [readonly]
 465
 466                                 Used when "manual" method is set.
 467
 468                                 List of hosts which can be accessed directly.
 469
 470                 dict Proxy.Configuration [readwrite]
 471
 472                         Same values as Proxy property. The Proxy represents
 473                         the actual system configuration while this allows
 474                         user configuration.
 475
 476                         If "auto" method is set with an empty URL, then
 477                         DHCP/WPAD auto-discover will be tried. Otherwise the
 478                         specified URL will be used.
 479
 480                 dict Provider [readonly]
 481
 482                         string Host [readonly]
 483
 484                                 VPN host IP.
 485
 486                         string Domain [readonly]
 487
 488                                 VPN Domain.
 489
 490                         string Name [readonly]
 491
 492                                 VPN provider Name.
 493
 494                         string Type [readonly]
 495
 496                                 VPN provider type.
 497
 498                 dict Ethernet [readonly]
 499
 500                         string Method [readonly]
 501
 502                                 Possible values are "auto" and "manual".
 503
 504                         string Interface [readonly]
 505
 506                                 Interface name (for example eth0).
 507
 508                         string Address [readonly]
 509
 510                                 Ethernet device address (MAC address).
 511
 512                         uint16 MTU [readonly]
 513
 514                                 The Ethernet MTU (default is 1500).
 515
 516                         uint16 Speed [readonly] [deprecated]
 517
 518                                 Selected speed of the line.
 519
 520                                 This information is not available.
 521
 522                         string Duplex [readonly] [deprecated]
 523
 524                                 Selected duplex settings of the line.
 525                                 Possible values are "half" and "full".
 526
 527                                 This information is not available.