summaryrefslogtreecommitdiffstats
path: root/doc/network-api.txt
blob: 4cb6366dcdead505a36bbb643fe81fe12ebdccb6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
Network registration hierarchy
==============================

Service		org.ofono
Interface	org.ofono.NetworkRegistration
Object path	[variable prefix]/{modem0,modem1,...}

Methods		dict GetProperties()

			Returns all network registration properties. See the
			properties section for available properties.

			Possible Errors: [service].Error.InvalidArguments

		void SetProperty(string name, variant value)

			Changes the value of the specified property. Only
			properties that are listed as readwrite are
			changeable. On success a PropertyChanged signal
			will be emitted.

			Possible Errors: [service].Error.InvalidArguments
					 [service].Error.DoesNotExist

		void Register()

			Attempts to register to the default network. The
			default network is normally selected by the settings
			from the SIM card.

			Possible Errors: [service].Error.InvalidArguments

		array{object,dict} GetOperators()

			Retrieve array of operator object and properties.

			This method can be used to retrieve the current
			operator list.  This is either an empty list (when
			not registered to any network) or a list with one
			or more operators (when registered).

			This list will also return cached values of previously
			seen networks.  Manual updates to list can only be
			done via the Scan method call.

		array{object,dict} Scan()

			Runs a network operator scan to discover the currently
			available operators.  This operation can take several
			seconds, and up to several minutes on some modems.
			This can be used to help the user determine what is
			the best operator to use if forced to roam on a
			foreign network.

			NOTE: The operator scan can interfere with any active
			GPRS contexts.  Expect the context to be unavailable
			for the duration of the operator scan.

Signals		PropertyChanged(string property, variant value)

			This signal indicates a changed value of the given
			property.

Properties	string Mode [readonly]

			The current registration mode. The default of this
			is "auto", but can be changed during operation. This
			property will change to "manual" if the Register()
			method of an operator is called.

			The possible values are:
				"auto"       Network registration is performed
				             automatically.
				"auto-only"  Network registration is performed
				             automatically, and manual
				             selection is disabled.
				"manual"     Network operator is selected
				             manually. If the operator is
				             currently not selected,
				             registration is not attempted.

		string Status [readonly]

			The current registration status of a modem.

			The possible values are:
				"unregistered"  Not registered to any network
				"registered"    Registered to home network
				"searching"     Not registered, but searching
				"denied"        Registration has been denied
				"unknown"       Status is unknown
				"roaming"       Registered, but roaming

		uint16 LocationAreaCode [readonly, optional]

			Contains the current location area code.

			TODO: Agent based location signalling would be better.

		uint32 CellId [readonly, optional]

			Contains the current network cell id.

			TODO: Agent based location signalling would be better.

		string MobileCountryCode [readonly, optional]

			Contains the Mobile Country Code (MCC).  This is
			repeated here for convenience.  It can also be obtained
			from the NetworkOperator interface.

		string MobileNetworkCode [readonly, optional]

			Contains the Mobile Network Code (MNC).  This is
			repeated here for convenience.  It can also be obtained
			from the NetworkOperator interface.

		string Technology [readonly, optional]

			Contains the technology of the current network.

			The possible values are: "gsm", "edge", "umts", "hspa",
							"lte"

			TODO: Values for CDMA and EVDO based networks.

		string Name [readonly]

			Contains the current operator name, suitable for
			display on the idle screen or an empty string if
			not registered to a network.

		byte Strength [readonly, optional]

			Contains the current signal strength as a percentage
			between 0-100 percent.

		string BaseStation [readonly, optional]

			If the Cell Broadcast service is available and
			properly configured, this attribute will contain the
			name of the current service cell.  This is typically a
			descriptive name of the local area, e.g. name of the
			suburb.  If no name is provided or becomes
			unavailable, this property will not be returned by
			GetProperties or will be set to an empty string.


Network operator hierarchy
==========================

Service		org.ofono
Interface	org.ofono.NetworkOperator
Object path	[variable prefix]/{modem0,modem1,...}/{operator0,operator1,...}

Methods		dict GetProperties()

			Returns all network operator properties. See the
			properties section for available properties.

			Possible Errors: [service].Error.InvalidArguments

		void Register()

			Attempts to register to this network operator.

			The method will return immediately, the result should
			be observed by tracking the NetworkRegistration Status
			property.

			Possible Errors: [service].Error.InvalidArguments

Signals		PropertyChanged(string property, variant value)

			This signal indicates a changed value of the given
			property.

Properties	string Name [readonly]

			Contains the name of the operator, suitable for using
			as a string handle in a UI widget used for manual
			network selection. For a proper display name of the
			current operator, use the Name property of the
			NetworkRegistration interface instead.

		string Status [readonly]

			Contains the status of the operator.

			The possible values are: "unknown", "available",
						 "current" and "forbidden"

		string MobileCountryCode [readonly, optional]

			Contains the Mobile Country Code (MCC).

		string MobileNetworkCode [readonly, optional]

			Contains the Mobile Network Code (MNC)

		array{string} Technologies [readonly, optional]

			Contains a list of technologies currently available
			from this network provider.

			The possible values are: "gsm", "edge", "umts", "hspa",
							"lte"

		string AdditionalInformation [readonly, optional]

			Contains a short description of the operator.  This is
			typically stored on the SIM and might be available
			only for select operators.