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                         Calling this method on Ethernet devices will cause
  78                         an error message. It is not possible to remove these
  79                         kind of devices.
  80
  81                         Possible Errors: [service].Error.InvalidArguments
  82
  83                 void MoveBefore(object service)
  84
  85                         If a service has been used before, this allows a
  86                         reorder of the favorite services.
  87
  88                         The target service object must be part of this
  89                         profile. Moving between profiles is not supported.
  90
  91                         Possible Errors: [service].Error.InvalidArguments
  92
  93                 void MoveAfter(object service)
  94
  95                         If a service has been used before, this allows a
  96                         reorder of the favorite services.
  97
  98                         The target service object must be part of this
  99                         profile. Moving between profiles is not supported.
 100
 101                         Possible Errors: [service].Error.InvalidArguments
 102
 103 Signals         PropertyChanged(string name, variant value)
 104
 105                         This signal indicates a changed value of the given
 106                         property.
 107
 108 Properties      string State [readonly]
 109
 110                         The service state information.
 111
 112                         Valid states are "idle", "failure", "association",
 113                         "configuration" and "ready".
 114
 115                 string Error [readonly]
 116
 117                         The service error status details.
 118
 119                         When error occur during connection or disconnection
 120                         the detailed information are represented in this
 121                         property to help the user interface to present the
 122                         user with alternate options.
 123
 124                         This property is only valid when the service is in
 125                         the "failure" state. Otherwise it might be empty or
 126                         not present at all.
 127
 128                         Current defined error code is "dhcp-failed".
 129
 130                 string Name [readonly]
 131
 132                         The service name (for example "Wireless" etc.)
 133
 134                         This name can be used for directly displaying it in
 135                         the application. It has pure informational purpose.
 136
 137                         For Ethernet devices and hidden WiFi networks it is
 138                         not guaranteed that this property is present.
 139
 140                 string Type [readonly]
 141
 142                         The service type (for example "ethernet", "wifi" etc.)
 143
 144                         This information should only be used to determine
 145                         advanced properties or showing the correct icon
 146                         to the user.
 147
 148                 string Mode [readonly]
 149
 150                         If the service type is WiFi or Cellular, then this
 151                         property is present and contains the mode of the
 152                         network.
 153
 154                         For WiFi services the possible values are "managed"
 155                         and "adhoc". For Cellular services it describes the
 156                         network technology. Possible values are "gprs", "edge"
 157                         and "umts".
 158
 159                         This property might be only present for WiFi and
 160                         Cellular services.
 161
 162                 string Security [readonly]
 163
 164                         If the service type is WiFi, then this property is
 165                         present and contains the security method or key
 166                         management setting.
 167
 168                         Possible values are "none", "wep", "wpa" and "rsn".
 169
 170                         This property might be only present for WiFi
 171                         services.
 172
 173                 string Passphrase [readwrite]
 174
 175                         If the service type is WiFi, then this property
 176                         can be used to store a passphrase.
 177
 178                         No PropertyChanged signals will be send for this
 179                         property. The PassphraseRequired property should
 180                         be monitored instead.
 181
 182                         This property might also not always be included
 183                         since it is protected by a different security policy.
 184
 185                 boolean PassphraseRequired [readonly]
 186
 187                         If the service type is WiFi, then this property
 188                         indicates if a passphrase is required.
 189
 190                         If a passphrase has been set already or if no
 191                         passphrase is needed, then this property will
 192                         be set to false.
 193
 194                 uint8 Strength [readonly]
 195
 196                         Indicates the signal strength of the service. This
 197                         is a normalized value between 0 and 100.
 198
 199                         This property will not be present for Ethernet
 200                         devices.
 201
 202                 boolean Favorite [readonly]
 203
 204                         Will be true if a cable is plugged in or the user
 205                         selected and successfully connected to this service.
 206
 207                         This value is automatically changed and to revert
 208                         it back to false the Remove() method needs to be
 209                         used.
 210
 211                 boolean AutoConnect [readwrite]
 212
 213                         If set to true, this service will auto-connect
 214                         when not other connection is available.
 215
 216                         For favorite services it is possible to change
 217                         this value to prevent or permit automatic
 218                         connection attempts.
 219
 220                 boolean SetupRequired [readonly]
 221
 222                         If the service is Cellular, then this property
 223                         indicates that some extra setup steps are required.
 224
 225                         In most cases it is required to fill in the APN
 226                         details.
 227
 228                 string APN [readwrite]
 229
 230                         If the service is Cellular, then this property
 231                         contains the APN details.
 232
 233                         The APN is network provider specific and even
 234                         sometimes data plan specific. Possible examples
 235                         are "isp.cingular" or "internet.t-mobile".
 236
 237                 string MCC [readonly]
 238
 239                         If the service is Cellular, then this property
 240                         contains the Mobile Country Code.
 241
 242                 string MNC [readonly]
 243
 244                         If the service is Cellular, then this property
 245                         contains the Mobile Network Code.
 246
 247                 boolean Roaming [readonly]
 248
 249                         This property indicates if this service is roaming.
 250
 251                         In the case of Cellular services this normally
 252                         indicates connections to a foreign provider when
 253                         traveling abroad.
 254
 255                 string IPv4.Method [readwrite]
 256
 257                         The IPv4 configuration method. Possible values here
 258                         are "dhcp" and "static".
 259
 260                 string IPv4.Address [readwrite]
 261
 262                         The current configured IPv4 address.