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