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