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