colin/ModemManager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

api: update and clarify Location API

Browse Source
This commit is contained in:
Dan Williams
2010-03-11 13:15:33 -08:00
parent 79aef47b25
commit c7739979ed
1 changed files with 101 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
introspection/mm-modem-location.xml
View File

@@ -26,7 +26,9 @@
<method name="Enable">
<tp:docstring>
Enable or disable location information gathering. This method may
require the client to authenticate itself.
require the client to authenticate itself. This method may also cause
any necessary functionality of the mobile be be turned on, including
enabling the modem device itself.
</tp:docstring>
<annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
<annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_modem_location_enable"/>
@@ -92,28 +94,116 @@
</tp:docstring>
<tp:member type="u" name="Type" tp:type="MM_MODEM_LOCATION_CAPABILITIES">
<tp:docstring>
Identifies the type and format of the associated location information. Contrary to the value description, this is not a bitfield but uses the same values as the MM_MODEM_LOCATION_CAPABILITIES bitfield.
Identifies the type and format of the associated location information.
Contrary to the value description, this is not a bitfield but uses the
same values as the MM_MODEM_LOCATION_CAPABILITIES bitfield.
</tp:docstring>
</tp:member>
<tp:member type="v" name="Data">
<tp:docstring>
Contains type-specific location information. GSM_LAC_CI data is a string with the format "LAC,CI" (ex "84CD,00D30156") while GPS_NMEA is a string in NMEA-compatible format.
Contains type-specific location information. See the documentation for
each type for a description of its data format.
</tp:docstring>
</tp:member>
</tp:mapping>
<tp:flags name="MM_MODEM_LOCATION_CAPABILITIES" value-prefix="MM_MODEM_LOCATION_CAPABILITY" type="u">
<tp:flag suffix="UNKNOWN" value="0x0">
<tp:docstring>Unknown or no capabilties.</tp:docstring>
<tp:docstring><p>Unknown or no capabilties.</p></tp:docstring>
</tp:flag>
<tp:flag suffix="ANY" value="0x1">
<tp:docstring>Reserved.</tp:docstring>
<tp:flag suffix="GPS_NMEA" value="0x1">
<tp:docstring>
<p>For capability reporting, indicates the device is capable of
providing GPS NMEA-format location information.</p>
<p>For location reporting, devices supporting this capability return
an array mapping timestamps to specific NMEA sentences (D-Bus
signature 'a(ss)'). The manager will cache the most recent NMEA
sentence of each type for a period of time not less than 30 seconds
and must indicate the time that sentence was receieved from the device
using the timestamp. Timestamps are provided as strings in the "Unix
epoch" format (i.e. number of seconds since 1970-01-01 00:00:00 UTC
with microsecond resolution if available).
</p>
<p>
For example, if at time 1268336242.282202 the device sends a $GPRMC
sentence immediately followed by a $GPGGA sentence, the reported
location array would be:
<pre>
[ '1268336242.282202': '$GPRMC,134523.92,V,,,,,,,030136,,,N*73',
'1268336242.282202': '$GPGGA,,,,,,0,00,0.5,,M,0.0001999,M,0.0000099,0000*45' ]
</pre>
If the device sends a new $GPRMC three seconds later, the new $GPRMC
replaces the previously received $GPRMC sentence, and the updated array
would be:
<pre>
[ '1268336245.282202': '$GPRMC,134526.92,V,,,,,,,030136,,,N*76',
'1268336242.282202': '$GPGGA,,,,,,0,00,0.5,,M,0.0001999,M,0.0000099,0000*45' ]
</pre>
If the device then sends a $GPGSA sentence about 5 seconds later, the
$GPGSA sentence is added to the array (since no $GPGSA sentence was
previously received in this session), the updated array would be:
<pre>
[ '1268336245.282202': '$GPRMC,134526.92,V,,,,,,,030136,,,N*76',
'1268336242.282202': '$GPGGA,,,,,,0,00,0.5,,M,0.0001999,M,0.0000099,0000*45'
'1268336250.395423': '$GPGSA,A,1,,,,,,,,,,,,,1.1,0.5,1.0*34' ]
</pre>
The manager may discard any entries older than 30 seconds.
</p>
<p>This allows clients to read the latest positioning data as soon as
possible after they start, even if the device is not providing
frequent location data updates. Using the timestamp the client can
determine which data is most relevant to its particular uses.
</p>
</tp:docstring>
</tp:flag>
<tp:flag suffix="GPS_NMEA" value="0x2">
<tp:docstring>The device is capable of providing GPS NMEA-format location information.</tp:docstring>
</tp:flag>
<tp:flag suffix="GSM_LAC_CI" value="0x4">
<tp:docstring>The device is capable of providing GSM Location Area Code/Cell ID location information.</tp:docstring>
<tp:flag suffix="GSM_LAC_CI" value="0x2">
<tp:docstring>
<p>For capability reporting, indicates the device is capable of
providing GSM Location Area Code/Cell ID location information.</p>
<p>For location reporting, devices supporting this
capability return a string in the format "MCC,MNC,LAC,CI" (without the
quotes of course) where the following applies:</p>
<ul>
<li>
MCC is the three-digit ITU E.212 Mobile Country Code of the
network provider to which the mobile is currently registered.
This value should be the same MCC as reported by the
org.freedesktop.Modem.Gsm.Network.GetRegistrationInfo() method's
returned "operator code" argument.
e.g. "310"
</li>
<li>
MNC is the two- or three-digit GSM Mobile Network Code of the
network provider to which the mobile is currently registered.
This value should be the same MCC as reported by the
org.freedesktop.Modem.Gsm.Network.GetRegistrationInfo() method's
returned "operator code" argument.
e.g. "26" or "260"
</li>
<li>
LAC is the two-byte Location Area Code of the base station with
which the mobile is registered, in upper-case hexadecimal format
without leading zeros, as specified in 3GPP TS 27.007 section
10.1.19. e.g. "84CD".
</li>
<li>
CI is the two- or four-byte Cell Identifier with which the mobile
is registered, in upper-case hexadecimal format without leading
zeros, as specified in 3GPP TS 27.007. e.g. "2BAF" or "D30156".
</li>
</ul>
<p>The entire string may only be composed of the ASCII digits [0-9],
the alphabetical characters [A-F], and the comma (,) character. No
other characters are allowed. For example: "310,260,8BE3,2BAF" or
"250,40,CE00,1CEAD8F0".</p>
<p>If any of these four items (MCC,MNC,LAC,CI) is unknown or the
mobile is not registered with a network, then the GSM_LAC_CI location
information item should not be provided as a returned value from the
GetLocation() method or in the Location property.</p>
</tp:docstring>
</tp:flag>
</tp:flags>