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. Only
  34                         the readonly Error property can be cleared using
  35                         this method call. When cleared the service is reset
  36                         to the idle state.
  37
  38                         Possible Errors: [service].Error.InvalidProperty
  39
  40                 void Connect()
  41
  42                         Connect this service. It will attempt to connect
  43                         WiFi or Bluetooth services.
  44
  45                         For Ethernet devices this method can only be used
  46                         if it has previously been disconnected. Otherwise
  47                         the plugging of a cable will trigger connecting
  48                         automatically. If no cable is plugged in this method
  49                         will fail.
  50
  51                         This method call will only return in case of an
  52                         error or when the service is fully connected. So
  53                         setting a longer D-Bus timeout might be a really
  54                         good idea.
  55
  56                         Calling Connect() on a hidden WiFi service entry will
  57                         query the missing SSID via the Agent API causing a
  58                         WiFi service with the given SSID to be scanned,
  59                         created and connected.
  60
  61                         Possible Errors: [service].Error.InvalidArguments
  62
  63                 void Disconnect()
  64
  65                         Disconnect this service. If the service is not
  66                         connected an error message will be generated.
  67
  68                         On Ethernet devices this will disconnect the IP
  69                         details from the service. It will not magically
  70                         unplug the cable. When no cable is plugged in this
  71                         method will fail.
  72
  73                         This method can also be used to abort a previous
  74                         connection attempt via the Connect method.
  75
  76                         Hidden WiFi service entries cannot be disconnected
  77                         as they always stay in idle state.
  78
  79                         Possible Errors: [service].Error.InvalidArguments
  80
  81                 void Remove()
  82
  83                         A successfully connected service with Favorite=true
  84                         can be removed this way. If it is connected, it will
  85                         be automatically disconnected first.
  86
  87                         If the service requires a passphrase it will be
  88                         cleared and forgotten when removing.
  89
  90                         This is similar to setting the Favorite property
  91                         to false, but that is currently not supported.
  92
  93                         In the case a connection attempt failed and the
  94                         service is in the state "failure", "idle" or
  95                         "disconnect", this method can also be used
  96                         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" and "wps_advertising".
 192
 193                         Value "wps" means that the service supports WPS. A
 194                         service advertising itself as WPS registrar contains
 195                         the additional value "wps_advertising" for as long as
 196                         it is advertising. That is, while "wps_advertising" is
 197                         listed, WPS is active and it should be possible to
 198                         connect to the corresponding service via WPS.
 199
 200                         This property might be only present for WiFi
 201                         services.
 202
 203                 uint8 Strength [readonly]
 204
 205                         Indicates the signal strength of the service. This
 206                         is a normalized value between 0 and 100.
 207
 208                         This property will not be present for Ethernet
 209                         devices.
 210
 211                 boolean Favorite [readonly]
 212
 213                         Will be true if a cable is plugged in or the user
 214                         selected and successfully connected to this service.
 215
 216                         This value is automatically changed and to revert
 217                         it back to false the Remove() method needs to be
 218                         used.
 219
 220                 boolean Immutable [readonly]
 221
 222                         This value will be set to true if the service is
 223                         configured externally via a configuration file.
 224
 225                         The only valid operations are Connect(), Disconnect()
 226                         and changing the AutoConnect property. The Remove()
 227                         method will result in an error.
 228
 229                 boolean AutoConnect [readwrite]
 230
 231                         If set to true, this service will auto-connect
 232                         when no other connection is available.
 233
 234                         The service won't auto-connect while roaming.
 235
 236                         For favorite services it is possible to change
 237                         this value to prevent or permit automatic
 238                         connection attempts.
 239
 240                 boolean Roaming [readonly]
 241
 242                         This property indicates if this service is roaming.
 243
 244                         In the case of Cellular services this normally
 245                         indicates connections to a foreign provider when
 246                         traveling abroad.
 247
 248                 array{string} Nameservers [readonly]
 249
 250                         The list of currently active nameservers for this
 251                         service. If the server is not in READY or ONLINE
 252                         state than this list will be empty.
 253
 254                         Global nameservers are automatically added to this
 255                         list. The array represents a sorted list of the
 256                         current nameservers. The first one has the highest
 257                         priority and is used by default.
 258
 259                         When using DHCP this array represents the nameservers
 260                         provided by the network. In case of manual settings,
 261                         the ones from Nameservers.Configuration are used.
 262
 263                 array{string} Nameservers.Configuration [readwrite]
 264
 265                         The list of manually configured domain name
 266                         servers. Some cellular networks don't provide
 267                         correct name servers and this allows for an
 268                         override.
 269
 270                         This array is sorted by priority and the first
 271                         entry in the list represents the nameserver with
 272                         the highest priority.
 273
 274                         When using manual configuration and no global
 275                         nameservers are configured, then it is useful
 276                         to configure this setting.
 277
 278                         Changes to the domain name servers can be done
 279                         at any time. It will not cause a disconnect of
 280                         the service. However there might be small window
 281                         where name resolution might fail.
 282
 283                 array{string} Timeservers [readonly]
 284
 285                         The list of currently active timeservers for this
 286                         service. If the server is not in READY or ONLINE
 287                         state than this list will be empty.
 288
 289                 array{string} Timeservers.Configuration [readwrite]
 290
 291                         The list of manually configured time servers.
 292
 293                         The first entry in the list represents the
 294                         timeserver with the highest priority.
 295
 296                         When using manual configuration this setting
 297                         is useful to override all the other timeserver
 298                         settings. This is service specific, hence only
 299                         the values for the default service are used.
 300
 301                         Changes to this property will result in restart
 302                         of NTP query.
 303
 304                 array{string} Domains [readonly]
 305
 306                         The list of currently used search domains taken
 307                         from Domains.Configurations if set, otherwise a
 308                         domain name if provided by DHCP or VPNs.
 309
 310                 array{string} Domains.Configuration [readwrite]
 311
 312                         The list of manually configured search domains.
 313
 314                 dict IPv4 [readonly]
 315
 316                         string Method [readonly]
 317
 318                                 Possible values are "dhcp", "manual", "auto"
 319                                 and "off".
 320
 321                                 It could be "auto" in case address was got
 322                                 through IPv4LL after DHCP failed. In this
 323                                 case also IPv4.Configuration will become
 324                                 "auto" to allow user to ask for a DHCP
 325                                 address at any time.
 326
 327                                 The value "fixed" indicates an IP address
 328                                 that can not be modified. For example
 329                                 cellular networks return fixed information.
 330
 331                         string Address [readonly]
 332
 333                                 The current configured IPv4 address.
 334
 335                         string Netmask [readonly]
 336
 337                                 The current configured IPv4 netmask.
 338
 339                         string Gateway [readonly]
 340
 341                                 The current configured IPv4 gateway.
 342
 343                 dict IPv4.Configuration [readwrite]
 344
 345                         Same values as IPv4 property. The IPv4 represents
 346                         the actual system configuration while this allows
 347                         user configuration.
 348
 349                         Changing these settings will cause a state change
 350                         of the service. The service will become unavailable
 351                         until the new configuration has been successfully
 352                         installed.
 353
 354                 dict IPv6 [readonly]
 355
 356                         string Method [readonly]
 357
 358                                 Possible values are "auto", "manual", "6to4"
 359                                 and "off".
 360
 361                                 The value "fixed" indicates an IP address
 362                                 that can not be modified. For example
 363                                 cellular networks return fixed information.
 364                                 The value "6to4" is returned if 6to4 tunnel
 365                                 is created by connman. The tunnel can only be
 366                                 created if method was set to "auto" by the
 367                                 user. User cannot set the method to "6to4".
 368
 369                         string Address [readonly]
 370
 371                                 The current configured IPv6 address.
 372
 373                         uint8 PrefixLength [readonly]
 374
 375                                 The prefix length of the IPv6 address.
 376
 377                         string Gateway [readonly]
 378
 379                                 The current configured IPv6 gateway.
 380
 381                         string Privacy [readonly]
 382
 383                                 Enable or disable IPv6 privacy extension
 384                                 that is described in RFC 4941. The value
 385                                 has only meaning if Method is set to "auto".
 386
 387                                 Value "disabled" means that privacy extension
 388                                 is disabled and normal autoconf addresses are
 389                                 used.
 390
 391                                 Value "enabled" means that privacy extension is
 392                                 enabled and system prefers to use public
 393                                 addresses over temporary addresses.
 394
 395                                 Value "prefered" means that privacy extension is
 396                                 enabled and system prefers temporary addresses
 397                                 over public addresses.
 398
 399                                 Default value is "disabled".
 400
 401                 dict IPv6.Configuration [readwrite]
 402
 403                         Same values as IPv6 property. The IPv6 represents
 404                         the actual system configuration while this allows
 405                         user configuration.
 406
 407                         Changing these settings will cause a state change
 408                         of the service. The service will become unavailable
 409                         until the new configuration has been successfully
 410                         installed.
 411
 412                 dict Proxy [readonly]
 413
 414                         string Method [readonly]
 415
 416                                 Possible values are "direct", "auto" and
 417                                 "manual".
 418
 419                                 In case of "auto" method, the URL file can be
 420                                 provided unless you want to let DHCP/WPAD
 421                                 auto-discover to be tried. In such case if DHCP
 422                                 and WPAD auto-discover methods fails then
 423                                 method will be "direct".
 424
 425                                 In case of "direct" no additional information
 426                                 are provided. For the "manual" method the
 427                                 Servers have to be set, Excludes is optional.
 428
 429                         string URL [readonly]
 430
 431                                 Automatic proxy configuration URL. Used by
 432                                 "auto" method.
 433
 434                         array{string} Servers [readonly]
 435
 436                                 Used when "manual" method is set.
 437
 438                                 List of proxy URIs. The URI without a protocol
 439                                 will be interpreted as the generic proxy URI.
 440                                 All others will target a specific protocol and
 441                                 only once.
 442
 443                                 Example for generic proxy server entry would
 444                                 be like this: "server.example.com:911".
 445
 446                         array{string} Excludes [readonly]
 447
 448                                 Used when "manual" method is set.
 449
 450                                 List of hosts which can be accessed directly.
 451
 452                 dict Proxy.Configuration [readwrite]
 453
 454                         Same values as Proxy property. The Proxy represents
 455                         the actual system configuration while this allows
 456                         user configuration.
 457
 458                         If "auto" method is set with an empty URL, then
 459                         DHCP/WPAD auto-discover will be tried. Otherwise the
 460                         specified URL will be used.
 461
 462                 dict Provider [readonly]
 463
 464                         string Host [readonly]
 465
 466                                 VPN host IP.
 467
 468                         string Domain [readonly]
 469
 470                                 VPN Domain.
 471
 472                         string Name [readonly]
 473
 474                                 VPN provider Name.
 475
 476                         string Type [readonly]
 477
 478                                 VPN provider type.
 479
 480                 dict Ethernet [readonly]
 481
 482                         string Method [readonly]
 483
 484                                 Possible values are "auto" and "manual".
 485
 486                         string Interface [readonly]
 487
 488                                 Interface name (for example eth0).
 489
 490                         string Address [readonly]
 491
 492                                 Ethernet device address (MAC address).
 493
 494                         uint16 MTU [readonly]
 495
 496                                 The Ethernet MTU (default is 1500).
 497
 498                         uint16 Speed [readonly] [deprecated]
 499
 500                                 Selected speed of the line.
 501
 502                                 This information is not available.
 503
 504                         string Duplex [readonly] [deprecated]
 505
 506                                 Selected duplex settings of the line.
 507                                 Possible values are "half" and "full".
 508
 509                                 This information is not available.
 510
 511                 bool mDNS [readonly]
 512
 513                         Whether or not mDNS support is enabled. Note
 514                         that mDNS requires a DNS backend which
 515                         supports it. Currently the only DNS backend
 516                         which supports mDNS is systemd-resolved.
 517
 518                 bool mDNS.Configuration [readwrite]
 519
 520                         Same values as mDNS property. The mDNS
 521                         represents the actual system configuration
 522                         while this allows user configuration.
 523
 524                 dict LastAddressConflict [readonly]
 525
 526                         This property contains information about the previously detected
 527                         address conflict. If there has been no address conflict then
 528                         IPv4 Address is "0.0.0.0", Ethernet Address is "00:00:00:00:00:00",
 529                         Timestamp is zero and Resolved is true.
 530
 531                         dict IPv4 [readonly]
 532
 533                                 string Address [readonly]
 534
 535                                 The IPv4 address which had a conflict.
 536
 537                         dict Ethernet [readonly]
 538
 539                                 string Address [readonly]
 540
 541                                 The ethernet device address (MAC address) of the conflicting
 542                                 host.
 543
 544                         int64 Timestamp [readonly]
 545
 546                                 A timestamp when the conflict was detected in microseconds
 547                                 since January 1, 1970 UTC.
 548
 549                         bool Resolved [readonly]
 550
 551                                 Set to false when an address conflict occurs.
 552                                 If a previous conflict could be resolved by probing another
 553                                 IPv4 address (which is not an IPv4LL) then this boolean is set
 554                                 to true.