doc/network-api.txt

   1 Network registration hierarchy
   2 ==============================
   3
   4 Service         org.ofono
   5 Interface       org.ofono.NetworkRegistration
   6 Object path     [variable prefix]/{modem0,modem1,...}
   7
   8 Methods         dict GetProperties()
   9
  10                         Returns all network registration properties. See the
  11                         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 readwrite are
  19                         changeable. On success a PropertyChanged signal
  20                         will be emitted.
  21
  22                         Possible Errors: [service].Error.InvalidArguments
  23                                          [service].Error.DoesNotExist
  24
  25                 void Register()
  26
  27                         Attempts to register to the default network. The
  28                         default network is normally selected by the settings
  29                         from the SIM card.
  30
  31                         Possible Errors: [service].Error.InvalidArguments
  32
  33                 array{object,dict} GetOperators()
  34
  35                         Retrieve array of operator object and properties.
  36
  37                         This method can be used to retrieve the current
  38                         operator list.  This is either an empty list (when
  39                         not registered to any network) or a list with one
  40                         or more operators (when registered).
  41
  42                         This list will also return cached values of previously
  43                         seen networks.  Manual updates to list can only be
  44                         done via the Scan method call.
  45
  46                 array{object,dict} Scan()
  47
  48                         Runs a network operator scan to discover the currently
  49                         available operators.  This operation can take several
  50                         seconds, and up to several minutes on some modems.
  51                         This can be used to help the user determine what is
  52                         the best operator to use if forced to roam on a
  53                         foreign network.
  54
  55                         NOTE: The operator scan can interfere with any active
  56                         GPRS contexts.  Expect the context to be unavailable
  57                         for the duration of the operator scan.
  58
  59 Signals         PropertyChanged(string property, variant value)
  60
  61                         This signal indicates a changed value of the given
  62                         property.
  63
  64 Properties      string Mode [readonly]
  65
  66                         The current registration mode. The default of this
  67                         is "auto", but can be changed during operation. This
  68                         property will change to "manual" if the Register()
  69                         method of an operator is called.
  70
  71                         The possible values are:
  72                                 "auto"       Network registration is performed
  73                                              automatically.
  74                                 "auto-only"  Network registration is performed
  75                                              automatically, and manual
  76                                              selection is disabled.
  77                                 "manual"     Network operator is selected
  78                                              manually. If the operator is
  79                                              currently not selected,
  80                                              registration is not attempted.
  81
  82                 string Status [readonly]
  83
  84                         The current registration status of a modem.
  85
  86                         The possible values are:
  87                                 "unregistered"  Not registered to any network
  88                                 "registered"    Registered to home network
  89                                 "searching"     Not registered, but searching
  90                                 "denied"        Registration has been denied
  91                                 "unknown"       Status is unknown
  92                                 "roaming"       Registered, but roaming
  93
  94                 uint16 LocationAreaCode [readonly, optional]
  95
  96                         Contains the current location area code.
  97
  98                         TODO: Agent based location signalling would be better.
  99
 100                 uint32 CellId [readonly, optional]
 101
 102                         Contains the current network cell id.
 103
 104                         TODO: Agent based location signalling would be better.
 105
 106                 string MobileCountryCode [readonly, optional]
 107
 108                         Contains the Mobile Country Code (MCC).  This is
 109                         repeated here for convenience.  It can also be obtained
 110                         from the NetworkOperator interface.
 111
 112                 string MobileNetworkCode [readonly, optional]
 113
 114                         Contains the Mobile Network Code (MNC).  This is
 115                         repeated here for convenience.  It can also be obtained
 116                         from the NetworkOperator interface.
 117
 118                 string Technology [readonly, optional]
 119
 120                         Contains the technology of the current network.
 121
 122                         The possible values are: "gsm", "edge", "umts", "hspa",
 123                                                         "lte"
 124
 125                         TODO: Values for CDMA and EVDO based networks.
 126
 127                 string Name [readonly]
 128
 129                         Contains the current operator name, suitable for
 130                         display on the idle screen or an empty string if
 131                         not registered to a network.
 132
 133                 byte Strength [readonly, optional]
 134
 135                         Contains the current signal strength as a percentage
 136                         between 0-100 percent.
 137
 138                 string BaseStation [readonly, optional]
 139
 140                         If the Cell Broadcast service is available and
 141                         properly configured, this attribute will contain the
 142                         name of the current service cell.  This is typically a
 143                         descriptive name of the local area, e.g. name of the
 144                         suburb.  If no name is provided or becomes
 145                         unavailable, this property will not be returned by
 146                         GetProperties or will be set to an empty string.
 147
 148
 149 Network operator hierarchy
 150 ==========================
 151
 152 Service         org.ofono
 153 Interface       org.ofono.NetworkOperator
 154 Object path     [variable prefix]/{modem0,modem1,...}/{operator0,operator1,...}
 155
 156 Methods         dict GetProperties()
 157
 158                         Returns all network operator properties. See the
 159                         properties section for available properties.
 160
 161                         Possible Errors: [service].Error.InvalidArguments
 162
 163                 void Register()
 164
 165                         Attempts to register to this network operator.
 166
 167                         The method will return immediately, the result should
 168                         be observed by tracking the NetworkRegistration Status
 169                         property.
 170
 171                         Possible Errors: [service].Error.InvalidArguments
 172
 173 Signals         PropertyChanged(string property, variant value)
 174
 175                         This signal indicates a changed value of the given
 176                         property.
 177
 178 Properties      string Name [readonly]
 179
 180                         Contains the name of the operator, suitable for using
 181                         as a string handle in a UI widget used for manual
 182                         network selection. For a proper display name of the
 183                         current operator, use the Name property of the
 184                         NetworkRegistration interface instead.
 185
 186                 string Status [readonly]
 187
 188                         Contains the status of the operator.
 189
 190                         The possible values are: "unknown", "available",
 191                                                  "current" and "forbidden"
 192
 193                 string MobileCountryCode [readonly, optional]
 194
 195                         Contains the Mobile Country Code (MCC).
 196
 197                 string MobileNetworkCode [readonly, optional]
 198
 199                         Contains the Mobile Network Code (MNC)
 200
 201                 array{string} Technologies [readonly, optional]
 202
 203                         Contains a list of technologies currently available
 204                         from this network provider.
 205
 206                         The possible values are: "gsm", "edge", "umts", "hspa",
 207                                                         "lte"
 208
 209                 string AdditionalInformation [readonly, optional]
 210
 211                         Contains a short description of the operator.  This is
 212                         typically stored on the SIM and might be available
 213                         only for select operators.