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