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()
   9
  10                         Returns properties for the service object. See
  11                         the properties section for available properties.
  12
  13                         Possible Errors: [service].Error.InvalidArguments
  14
  15                 void SetProperty(string name, variant value)
  16
  17                         Changes the value of the specified property. Only
  18                         properties that are listed as read-write are
  19                         changeable. On success a PropertyChanged signal
  20                         will be emitted.
  21
  22                         Possible Errors: [service].Error.InvalidArguments
  23                                          [service].Error.InvalidProperty
  24
  25                 void ClearProperty(string name)
  26
  27                         Clears the value of the specified property.
  28
  29                         Possible Errors: [service].Error.InvalidArguments
  30                                          [service].Error.InvalidProperty
  31
  32                 void Connect()
  33
  34                         Connect this service. It will attempt to connect
  35                         WiFi, WiMAX or Bluetooth services.
  36
  37                         For Ethernet devices this method can only be used
  38                         if it has previously been disconnected. Otherwise
  39                         the plugging of a cable will trigger connecting
  40                         automatically. If no cable is plugged in this method
  41                         will fail.
  42
  43                         This method call will only return in case of an
  44                         error or when the service is fully connected. So
  45                         setting a longer D-Bus timeout might be a really
  46                         good idea.
  47
  48                         Possible Errors: [service].Error.InvalidArguments
  49
  50                 void Disconnect()
  51
  52                         Disconnect this service. If the service is not
  53                         connected an error message will be generated.
  54
  55                         On Ethernet devices this will disconnect the IP
  56                         details from the service. It will not magically
  57                         unplug the cable. When no cable is plugged in this
  58                         method will fail.
  59
  60                         This method can also be used to abort a previous
  61                         connectiong attempt via the Connect method.
  62
  63                         Possible Errors: [service].Error.InvalidArguments
  64
  65                 void Remove()
  66
  67                         A successfully connected service with Favorite=true
  68                         can be removed this way. If it is connected, it will
  69                         be automatically disconnected first.
  70
  71                         If the service requires a passphrase it will be
  72                         cleared and forgotten when removing.
  73
  74                         This is similar to setting the Favorite property
  75                         to false, but that is currently not supported.
  76
  77                         In the case a connection attempt failed and the
  78                         service is in the State=failure, this method can
  79                         also be used to reset the service.
  80
  81                         Calling this method on Ethernet devices will cause
  82                         an error message. It is not possible to remove these
  83                         kind of devices.
  84
  85                         Possible Errors: [service].Error.InvalidArguments
  86
  87                 void MoveBefore(object service)
  88
  89                         If a service has been used before, this allows a
  90                         reorder of the favorite services.
  91
  92                         The target service object must be part of this
  93                         profile. Moving between profiles is not supported.
  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                         The target service object must be part of this
 103                         profile. Moving between profiles is not supported.
 104
 105                         Possible Errors: [service].Error.InvalidArguments
 106
 107                 void ResetCounters()
 108
 109                         Reset the counter statistics.
 110
 111                         Possible Errors: None
 112
 113 Signals         PropertyChanged(string name, variant value)
 114
 115                         This signal indicates a changed value of the given
 116                         property.
 117
 118 Properties      string State [readonly]
 119
 120                         The service state information.
 121
 122                         Valid states are "idle", "failure", "association",
 123                         "configuration", "ready" and "online".
 124
 125                         The "ready" state signals a successfully
 126                         connected device. "online" signals that an
 127                         Internet connection is available and has been
 128                         verified.
 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
 152                         For Ethernet devices and hidden WiFi networks it is
 153                         not guaranteed that this property is present.
 154
 155                 string Type [readonly]
 156
 157                         The service type (for example "ethernet", "wifi" etc.)
 158
 159                         This information should only be used to determine
 160                         advanced properties or showing the correct icon
 161                         to the user.
 162
 163                 string Mode [readonly]
 164
 165                         If the service type is WiFi or Cellular, then this
 166                         property is present and contains the mode of the
 167                         network.
 168
 169                         For WiFi services the possible values are "managed"
 170                         and "adhoc". For Cellular services it describes the
 171                         network technology. Possible values are "gprs", "edge"
 172                         and "umts".
 173
 174                         This property might be only present for WiFi and
 175                         Cellular services.
 176
 177                 string Security [readonly]
 178
 179                         If the service type is WiFi, then this property is
 180                         present and contains the security method or key
 181                         management setting.
 182
 183                         Possible values are "none", "wep", "psk" and
 184                         also "ieee8021x". Alternate values for "psk"
 185                         can also be "wpa" and "rsn".
 186
 187                         This property might be only present for WiFi
 188                         services.
 189
 190                 boolean LoginRequired [readonly]
 191
 192                         This property indicates that an additional login
 193                         step, like web based authentication, is needed
 194                         before the connection establishment can proceed.
 195
 196                 string Passphrase [readwrite]
 197
 198                         If the service type is WiFi, then this property
 199                         can be used to store a passphrase.
 200
 201                         No PropertyChanged signals will be sent for this
 202                         property. The PassphraseRequired property should
 203                         be monitored instead.
 204
 205                         This property might also not always be included
 206                         since it is protected by a different security policy.
 207
 208                 boolean PassphraseRequired [readonly]
 209
 210                         If the service type is WiFi, then this property
 211                         indicates if a passphrase is required.
 212
 213                         If a passphrase has been set already or if no
 214                         passphrase is needed, then this property will
 215                         be set to false.
 216
 217                 boolean WPS [readonly]
 218
 219                         If the service type is Wifi, then this property
 220                         indicates if it provides WPS (Wifi Protected Setup).
 221
 222                         If this is set to true, then if no Passphrase is
 223                         provided or if given Passphrase is wrong, WPS
 224                         push-button or pin methods will be available through
 225                         Agent API.
 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 SetupRequired [readonly]
 265
 266                         If the service is Cellular, then this property
 267                         indicates that some extra setup steps are required.
 268
 269                         In most cases it is required to fill in the APN
 270                         details.
 271
 272                 string APN [readwrite]
 273
 274                         If the service is Cellular, then this property
 275                         contains the APN details.
 276
 277                         The APN is network provider specific and even
 278                         sometimes data plan specific. Possible examples
 279                         are "isp.cingular" or "internet.t-mobile".
 280
 281                 boolean Roaming [readonly]
 282
 283                         This property indicates if this service is roaming.
 284
 285                         In the case of Cellular services this normally
 286                         indicates connections to a foreign provider when
 287                         traveling abroad.
 288
 289                 array{string} Nameservers [readonly]
 290
 291                         The list of currently active nameservers for this
 292                         service. If the server is not in READY or ONLINE
 293                         state than this list will be empty.
 294
 295                         Global nameservers are automatically added to this
 296                         list. The array represents a sorted list of the
 297                         current nameservers. The first one has the highest
 298                         priority and is used by default.
 299
 300                         When using DHCP this array represents the nameservers
 301                         provided by the network. In case of manual settings,
 302                         the ones from Nameservers.Configuration are used.
 303
 304                 array{string} Nameservers.Configuration [readwrite]
 305
 306                         The list of manually configured domain name
 307                         servers. Some 3G networks don't provide correct
 308                         name servers and this allows for an override.
 309
 310                         This array is sorted by priority and the first
 311                         entry in the list represents the nameserver with
 312                         the highest priority.
 313
 314                         When using manual configuration and no global
 315                         nameservers are configured, then it is useful
 316                         to configure this setting.
 317
 318                         Changes to the domain name servers can be done
 319                         at any time. It will not cause a disconnect of
 320                         the service. However there might be small window
 321                         where name resolution might fail.
 322
 323                 array{string} Domains [readonly]
 324
 325                         The list of currently used search domains.
 326
 327                 array{string} Domains.Configuration [readwrite]
 328
 329                         The list of manually configured search domains.
 330
 331                 dict IPv4 [readonly]
 332
 333                         string Method [readonly]
 334
 335                                 Possible values are "dhcp", "manual"
 336                                 and "off".
 337
 338                                 The value "fixed" indicates an IP address
 339                                 that can not be modified. For example
 340                                 cellular networks return fixed information.
 341
 342                         string Address [readonly]
 343
 344                                 The current configured IPv4 address.
 345
 346                         string Netmask [readonly]
 347
 348                                 The current configured IPv4 netmask.
 349
 350                         string Gateway [readonly]
 351
 352                                 The current configured IPv4 gateway.
 353
 354                 dict IPv4.Configuration [readwrite]
 355
 356                         Same values as IPv4 property. The IPv4 represents
 357                         the actual system configuration while this allows
 358                         user configuration.
 359
 360                         Changing these settings will cause a state change
 361                         of the service. The service will become unavailable
 362                         until the new configuration has been successfully
 363                         installed.
 364
 365                 dict IPv6 [readonly]
 366
 367                         string Method [readonly]
 368
 369                                 Possible values are "auto", "manual"
 370                                 and "off".
 371
 372                                 The value "fixed" indicates an IP address
 373                                 that can not be modified. For example
 374                                 cellular networks return fixed information.
 375
 376                         string Address [readonly]
 377
 378                                 The current configured IPv6 address.
 379
 380                         uint8 PrefixLength [readonly]
 381
 382                                 The prefix length of the IPv6 address.
 383
 384                         string Gateway [readonly]
 385
 386                                 The current configured IPv6 gateway.
 387
 388                 dict IPv6.Configuration [readwrite]
 389
 390                         Same values as IPv6 property. The IPv6 represents
 391                         the actual system configuration while this allows
 392                         user configuration.
 393
 394                         Changing these settings will cause a state change
 395                         of the service. The service will become unavailable
 396                         until the new configuration has been successfully
 397                         installed.
 398
 399                 dict Proxy [readonly]
 400
 401                         string Method [readonly]
 402
 403                                 Possible values are "direct", "auto" and
 404                                 "manual".
 405
 406                                 In case of "auto" method, the URL file can be
 407                                 provided unless you want to let DHCP/WPAD
 408                                 auto-discover to be tried. In such case if DHCP
 409                                 and WPAD auto-discover methods fails then
 410                                 method will be "direct".
 411
 412                                 In case of "direct" no additional information
 413                                 are provided. For the "manual" method the
 414                                 Servers have to be set, Excludes is optional.
 415
 416                         string URL [readonly]
 417
 418                                 Automatic proxy configuration URL. Used by
 419                                 "auto" method.
 420
 421                         array{string} Servers [readonly]
 422
 423                                 Used when "manual" method is set.
 424
 425                                 List of proxy URIs. The URI without a protocol
 426                                 will be interpreted as the generic proxy URI.
 427                                 All others will target a specific protocol and
 428                                 only once.
 429
 430                                 Example for generic proxy server entry would
 431                                 be like this: "server.example.com:911".
 432
 433                         array{string} Excludes [readonly]
 434
 435                                 Used when "manual" method is set.
 436
 437                                 List of hosts which can be accessed directly.
 438
 439                 dict Proxy.Configuration [readwrite]
 440
 441                         Same values as Proxy property. The Proxy represents
 442                         the actual system configuration while this allows
 443                         user configuration.
 444
 445                         If "auto" method is set with an empty URL, then
 446                         DHCP/WPAD auto-discover will be tried. Otherwise the
 447                         specified URL will be used.
 448
 449                 dict Provider [readonly]
 450
 451                         string Host [readonly]
 452
 453                                VPN host IP.
 454
 455                         string Domain [readonly]
 456
 457                                VPN Domain.
 458
 459                         string Name [readonly]
 460
 461                                VPN provider Name.
 462
 463                         string Type [readonly]
 464
 465                                VPN provider type.
 466
 467                 dict Ethernet [readonly]
 468
 469                         string Method [readonly]
 470
 471                                 Possible values are "auto" and "manual".
 472
 473                         string Interface [readonly]
 474
 475                                 Interface name (for example eth0).
 476
 477                         string Address [readonly]
 478
 479                                 Ethernet device address (MAC address).
 480
 481                         uint16 MTU [readonly]
 482
 483                                 The Ethernet MTU (default is 1500).
 484
 485                         uint16 Speed [readonly]
 486
 487                                 Selected speed of the line.
 488
 489                                 This information might not always be
 490                                 available.
 491
 492                         string Duplex [readonly]
 493
 494                                 Selected duplex settings of the line.
 495
 496                                 Possible values are "half" and "full".
 497
 498                                 This information might not always be
 499                                 available.