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".
 174
 175                         This property might be only present for WiFi
 176                         services.
 177
 178                 string Passphrase [readwrite]
 179
 180                         If the service type is WiFi, then this property
 181                         can be used to store a passphrase.
 182
 183                         No PropertyChanged signals will be send for this
 184                         property. The PassphraseRequired property should
 185                         be monitored instead.
 186
 187                         This property might also not always be included
 188                         since it is protected by a different security policy.
 189
 190                 boolean PassphraseRequired [readonly]
 191
 192                         If the service type is WiFi, then this property
 193                         indicates if a passphrase is required.
 194
 195                         If a passphrase has been set already or if no
 196                         passphrase is needed, then this property will
 197                         be set to false.
 198
 199                 uint8 Strength [readonly]
 200
 201                         Indicates the signal strength of the service. This
 202                         is a normalized value between 0 and 100.
 203
 204                         This property will not be present for Ethernet
 205                         devices.
 206
 207                 boolean Favorite [readonly]
 208
 209                         Will be true if a cable is plugged in or the user
 210                         selected and successfully connected to this service.
 211
 212                         This value is automatically changed and to revert
 213                         it back to false the Remove() method needs to be
 214                         used.
 215
 216                 boolean AutoConnect [readwrite]
 217
 218                         If set to true, this service will auto-connect
 219                         when not other connection is available.
 220
 221                         For favorite services it is possible to change
 222                         this value to prevent or permit automatic
 223                         connection attempts.
 224
 225                 boolean SetupRequired [readonly]
 226
 227                         If the service is Cellular, then this property
 228                         indicates that some extra setup steps are required.
 229
 230                         In most cases it is required to fill in the APN
 231                         details.
 232
 233                 string APN [readwrite]
 234
 235                         If the service is Cellular, then this property
 236                         contains the APN details.
 237
 238                         The APN is network provider specific and even
 239                         sometimes data plan specific. Possible examples
 240                         are "isp.cingular" or "internet.t-mobile".
 241
 242                 string MCC [readonly]
 243
 244                         If the service is Cellular, then this property
 245                         contains the Mobile Country Code.
 246
 247                 string MNC [readonly]
 248
 249                         If the service is Cellular, then this property
 250                         contains the Mobile Network Code.
 251
 252                 boolean Roaming [readonly]
 253
 254                         This property indicates if this service is roaming.
 255
 256                         In the case of Cellular services this normally
 257                         indicates connections to a foreign provider when
 258                         traveling abroad.
 259
 260                 string IPv4.Method [readwrite]
 261
 262                         The IPv4 configuration method. Possible values here
 263                         are "dhcp" and "static".
 264
 265                 string IPv4.Address [readwrite]
 266
 267                         The current configured IPv4 address.