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