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