doc/service-api.txt

   1 Service hierarchy
   2 =================
   3
   4 Service         org.moblin.connman
   5 Interface       org.moblin.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" and "ready".
 124
 125                         Also "login" and "online" states are used. The
 126                         state "online" signals that an Internet connection
 127                         is available and has been verified.
 128
 129                 string Error [readonly]
 130
 131                         The service error status details.
 132
 133                         When error occur during connection or disconnection
 134                         the detailed information are represented in this
 135                         property to help the user interface to present the
 136                         user with alternate options.
 137
 138                         This property is only valid when the service is in
 139                         the "failure" state. Otherwise it might be empty or
 140                         not present at all.
 141
 142                         Current defined error code is "dhcp-failed".
 143
 144                 string Name [readonly]
 145
 146                         The service name (for example "Wireless" etc.)
 147
 148                         This name can be used for directly displaying it in
 149                         the application. It has pure informational purpose.
 150
 151                         For Ethernet devices and hidden WiFi networks it is
 152                         not guaranteed that this property is present.
 153
 154                 string Type [readonly]
 155
 156                         The service type (for example "ethernet", "wifi" etc.)
 157
 158                         This information should only be used to determine
 159                         advanced properties or showing the correct icon
 160                         to the user.
 161
 162                 string Mode [readonly]
 163
 164                         If the service type is WiFi or Cellular, then this
 165                         property is present and contains the mode of the
 166                         network.
 167
 168                         For WiFi services the possible values are "managed"
 169                         and "adhoc". For Cellular services it describes the
 170                         network technology. Possible values are "gprs", "edge"
 171                         and "umts".
 172
 173                         This property might be only present for WiFi and
 174                         Cellular services.
 175
 176                 string Security [readonly]
 177
 178                         If the service type is WiFi, then this property is
 179                         present and contains the security method or key
 180                         management setting.
 181
 182                         Possible values are "none", "wep", "psk" and
 183                         also "ieee8021x". Alternate values for "psk"
 184                         can also be "wpa" and "rsn".
 185
 186                         This property might be only present for WiFi
 187                         services.
 188
 189                 boolean LoginRequired [readonly]
 190
 191                         This property indicates that an additional login
 192                         step is needed before the connection establishment
 193                         can proceed.
 194
 195                 string Passphrase [readwrite]
 196
 197                         If the service type is WiFi, then this property
 198                         can be used to store a passphrase.
 199
 200                         No PropertyChanged signals will be send for this
 201                         property. The PassphraseRequired property should
 202                         be monitored instead.
 203
 204                         This property might also not always be included
 205                         since it is protected by a different security policy.
 206
 207                 boolean PassphraseRequired [readonly]
 208
 209                         If the service type is WiFi, then this property
 210                         indicates if a passphrase is required.
 211
 212                         If a passphrase has been set already or if no
 213                         passphrase is needed, then this property will
 214                         be set to false.
 215
 216                 uint8 Strength [readonly]
 217
 218                         Indicates the signal strength of the service. This
 219                         is a normalized value between 0 and 100.
 220
 221                         This property will not be present for Ethernet
 222                         devices.
 223
 224                 boolean Favorite [readonly]
 225
 226                         Will be true if a cable is plugged in or the user
 227                         selected and successfully connected to this service.
 228
 229                         This value is automatically changed and to revert
 230                         it back to false the Remove() method needs to be
 231                         used.
 232
 233                 boolean Immutable [readonly]
 234
 235                         This value will be set to true if the service is
 236                         configured externally via a configuration file.
 237
 238                         The only valid operation are Connect() and of
 239                         course Disconnect(). The Remove() method will
 240                         result in an error.
 241
 242                 boolean AutoConnect [readwrite]
 243
 244                         If set to true, this service will auto-connect
 245                         when not other connection is available.
 246
 247                         For favorite services it is possible to change
 248                         this value to prevent or permit automatic
 249                         connection attempts.
 250
 251                 boolean SetupRequired [readonly]
 252
 253                         If the service is Cellular, then this property
 254                         indicates that some extra setup steps are required.
 255
 256                         In most cases it is required to fill in the APN
 257                         details.
 258
 259                 string APN [readwrite]
 260
 261                         If the service is Cellular, then this property
 262                         contains the APN details.
 263
 264                         The APN is network provider specific and even
 265                         sometimes data plan specific. Possible examples
 266                         are "isp.cingular" or "internet.t-mobile".
 267
 268                 string MCC [readonly]
 269
 270                         If the service is Cellular, then this property
 271                         contains the Mobile Country Code.
 272
 273                 string MNC [readonly]
 274
 275                         If the service is Cellular, then this property
 276                         contains the Mobile Network Code.
 277
 278                 boolean Roaming [readonly]
 279
 280                         This property indicates if this service is roaming.
 281
 282                         In the case of Cellular services this normally
 283                         indicates connections to a foreign provider when
 284                         traveling abroad.
 285
 286                 array{string} Nameservers [readonly]
 287
 288                         The list of currently active nameservers for this
 289                         service. If the server is not in READY or ONLINE
 290                         state than this list will be empty.
 291
 292                         Global nameservers are automatically added to this
 293                         list. The array represents a sorted list of the
 294                         current nameservers. The first one has the highest
 295                         priority and is used by default.
 296
 297                         When using DHCP this array represents the nameservers
 298                         provided by the network. In case of manual settings,
 299                         the ones from Nameservers.Configuration are used.
 300
 301                 array{string} Nameservers.Configuration [readwrite]
 302
 303                         The list of manually configured domain name
 304                         servers. Some 3G networks don't provide correct
 305                         name servers and this allows for an override.
 306
 307                         This array is sorted by priority and the first
 308                         entry in the list represents the nameserver with
 309                         the highest priority.
 310
 311                         When using manual configuration and no global
 312                         nameservers are configured, then it is useful
 313                         to configure this setting.
 314
 315                         Changes to the domain name servers can be done
 316                         at any time. It will not cause a disconnect of
 317                         the service. However there might be small window
 318                         where name resolution might fail.
 319
 320                 array{string} Domains [readonly]
 321
 322                         The list of currently used search domains.
 323
 324                 array{string} Domains.Configuration [readwrite]
 325
 326                         The list of manually configured search domains.
 327
 328                 dict IPv4 [readonly]
 329
 330                         string Method [readonly]
 331
 332                                 Possible values are "dhcp", "manual"
 333                                 and "off".
 334
 335                                 The value "fixed" indicates an IP address
 336                                 that can not be modified. For example
 337                                 cellular networks return fixed information.
 338
 339                         string Address [readonly]
 340
 341                                 The current configured IPv4 address.
 342
 343                         string Netmask [readonly]
 344
 345                                 The current configured IPv4 netmask.
 346
 347                         string Gateway [readonly]
 348
 349                                 The current configured IPv4 gateway.
 350
 351                 dict IPv4.Configuration [readwrite]
 352
 353                         Same values as IPv4 property. The IPv4 represents
 354                         the actual system configuration while this allows
 355                         user configuration.
 356
 357                         Changing these settings will cause a state change
 358                         of the service. The service will become unavailable
 359                         until the new configuration has been successfully
 360                         installed.
 361
 362                 dict IPv6 [readonly]
 363
 364                         string Method [readonly]
 365
 366                                 Possible values are "dhcp", "manual"
 367                                 and "off".
 368
 369                                 The value "fixed" indicates an IP address
 370                                 that can not be modified. For example
 371                                 cellular networks return fixed information.
 372
 373                                 "dhcp" is not supported currently.
 374
 375                         string Address [readonly]
 376
 377                                 The current configured IPv6 address.
 378
 379                         uint8 PrefixLength [readonly]
 380
 381                                 The prefix length of the IPv6 address.
 382
 383                         string Gateway [readonly]
 384
 385                                 The current configured IPv6 gateway.
 386
 387                 dict IPv6.Configuration [readwrite]
 388
 389                         Same values as IPv6 property. The IPv6 represents
 390                         the actual system configuration while this allows
 391                         user configuration.
 392
 393                         Changing these settings will cause a state change
 394                         of the service. The service will become unavailable
 395                         until the new configuration has been successfully
 396                         installed.
 397
 398                 dict Proxy [readonly]
 399
 400                         string Method [readonly]
 401
 402                                 Possible values are "direct", "auto",
 403                                 "manual" and "auto-config".
 404
 405                                 If the DHCP server provides an automatic
 406                                 configuration URL, then this value is set
 407                                 to "auto-config". The PAC file will be
 408                                 referenced by the URL value.
 409
 410                                 If no automatic configuration is available,
 411                                 then "direct" is set.
 412
 413                                 The values "auto" and "manual" are not yet
 414                                 supported.
 415
 416                         string URL [readonly]
 417
 418                                 Automatic proxy configuration URL.
 419
 420                 dict Proxy.Configuration [readwrite]
 421
 422                         Same values as Proxy property. The Proxy represents
 423                         the actual system configuration while this allows
 424                         user configuration.
 425
 426                         Currently only setting Method to either "direct"
 427                         or "auto" is supported.
 428
 429                 dict Provider [readonly]
 430
 431                         string Host [readonly]
 432
 433                                VPN host IP.
 434
 435                         string Domain [readonly]
 436
 437                                VPN Domain.
 438
 439                         string Name [readonly]
 440
 441                                VPN provider Name.
 442
 443                         string Type [readonly]
 444
 445                                VPN provider type.
 446
 447                 dict Ethernet [readonly]
 448
 449                         string Method [readonly]
 450
 451                                 Possible values are "auto" and "manual".
 452
 453                         string Interface [readonly]
 454
 455                                 Interface name (for example eth0).
 456
 457                         string Address [readonly]
 458
 459                                 Ethernet device address (MAC address).
 460
 461                         uint16 MTU [readonly]
 462
 463                                 The Ethernet MTU (default is 1500).
 464
 465                         uint16 Speed [readonly]
 466
 467                                 Selected speed of the line.
 468
 469                                 This information might not always be
 470                                 available.
 471
 472                         string Duplex [readonly]
 473
 474                                 Selected duplex settings of the line.
 475
 476                                 Possible values are "half" and "full".
 477
 478                                 This information might not always be
 479                                 available.