| <?xml version="1.0" encoding="UTF-8" ?> |
| |
| <node name="/" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> |
| <interface name="org.freedesktop.ModemManager1.Modem.Location"> |
| <tp:docstring> |
| This interface allows devices to provide location information to client |
| applications. Not all devices can provide this information, or even if |
| they do, they may not be able to provide it while a data session is |
| active. |
| </tp:docstring> |
| |
| <property name="Capabilities" type="u" access="read" tp:type="MM_MODEM_LOCATION_CAPABILITIES"> |
| <tp:docstring> |
| Location capabilities of the device. |
| </tp:docstring> |
| </property> |
| |
| <property name="Enabled" type="b" access="read"> |
| <tp:docstring> |
| TRUE if location information gathering is enabled for this device, FALSE |
| if it is disabled. When disabled, the device will not provide location |
| information. |
| </tp:docstring> |
| </property> |
| |
| <method name="Enable"> |
| <tp:docstring> |
| Enable or disable location information gathering. This method may |
| 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"/> |
| <arg name="enable" type="b" direction="in"> |
| <tp:docstring> |
| TRUE to enable location information gathering, FALSE to disable. |
| </tp:docstring> |
| </arg> |
| <arg name="signal_location" type="b" direction="in"> |
| <tp:docstring> |
| When enabling location information gathering, this argument controls |
| whether the device emits signals with new location information or not. |
| When signals are emitted, any client application (including malicious |
| ones!) can listen for location updates unless D-Bus permissions |
| restrict these signals from certain users. If further security is |
| desired, this argument can be set to FALSE to disable location |
| updates via D-Bus signals and require applications to call |
| authenticated APIs (like GetLocation) to get location information. |
| This argument is ignored when disabling location information |
| gathering. |
| </tp:docstring> |
| </arg> |
| </method> |
| |
| <method name="GetLocation"> |
| <tp:docstring> |
| Return current location information, if any. This method may require |
| the client to authenticate itself. |
| </tp:docstring> |
| <annotation name="org.freedesktop.DBus.GLib.Async" value=""/> |
| <annotation name="org.freedesktop.DBus.GLib.CSymbol" value="impl_modem_location_get_location"/> |
| <arg name="Location" type="a{uv}" direction="out" tp:type="Location_Information_Map"> |
| <tp:docstring> |
| Dict of available location information when location information |
| gathering is enabled. If the modem supports multiple location types |
| it may return more than one here. |
| </tp:docstring> |
| </arg> |
| </method> |
| |
| <property name="SignalsLocation" type="b" access="read"> |
| <tp:docstring> |
| TRUE if location updates will be emitted via D-Bus signals, FALSE |
| if location updates will not be emitted. See the Enable method for |
| more information. |
| </tp:docstring> |
| </property> |
| |
| <property name="Location" type="a{uv}" access="read" tp:type="Location_Information_Map"> |
| <tp:docstring> |
| Dict of available location information when location information |
| gathering is enabled. If the modem supports multiple location types |
| it may return more than one here. Note that if the device was told |
| not to emit updated location information when location information |
| gathering was initially enabled, this property may not return |
| any location information for security reasons. |
| </tp:docstring> |
| </property> |
| |
| <tp:mapping name="Location_Information_Map"> |
| <tp:docstring> |
| A mapping from location type to type-specific location information. |
| </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. |
| </tp:docstring> |
| </tp:member> |
| <tp:member type="v" name="Data"> |
| <tp:docstring> |
| 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><p>Unknown or no capabilties.</p></tp:docstring> |
| </tp:flag> |
| <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 |
| a string containing one or more NMEA sentences (D-Bus signature 's'). |
| The manager will cache the most recent NMEA sentence of each type for |
| a period of time not less than 30 seconds. When reporting multiple |
| NMEA sentences, sentences shall be separated by an ASCII Carriage |
| Return and Line Feed (<CR><LF>) sequence. |
| </p> |
| <p> |
| For example, if the device sends a $GPRMC sentence immediately |
| followed by a $GPGGA sentence, the reported location string would be |
| (where of course the <CR><LF> is replaced with the actual |
| ASCII CR (0x0D) and LF (0x0A) control characters): |
| <pre> |
| $GPRMC,134523.92,V,,,,,,,030136,,,N*73<CR><LF>$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 |
| string would be: |
| <pre> |
| $GPRMC,134526.92,V,,,,,,,030136,,,N*76<CR><LF>$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 string (since no $GPGSA sentence was |
| previously received in this session), the updated string would be: |
| <pre> |
| $GPRMC,134526.92,V,,,,,,,030136,,,N*76<CR><LF>$GPGGA,,,,,,0,00,0.5,,M,0.0001999,M,0.0000099,0000*45<CR><LF>$GPGSA,A,1,,,,,,,,,,,,,1.1,0.5,1.0*34 |
| </pre> |
| The manager may discard any cached sentences 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. |
| </p> |
| </tp:docstring> |
| </tp:flag> |
| <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:flag suffix="GPS_RAW" value="0x4"> |
| <tp:docstring> |
| <p>For capability reporting, indicates the device is capable of |
| providing raw GPS information using a series of defined key/value |
| pairs.</p> |
| |
| <p>For location reporting, devices supporting this |
| capability return a D-Bus dict (signature a{sv}) mapping well-known |
| keys to values with defined formats. The allowed key/value pairs |
| and their formats are:</p> |
| <table> |
| <tr><th>Key</th><th>Value Type</th><th>Value contents</th><th>Example</th></tr> |
| <tr> |
| <td>latitude</td> |
| <td>d</td> |
| <td>Latitude in Decimal Degrees (positive numbers mean N quadrasphere, negative mean S quadrasphere)</td> |
| <td>38.889722 (ie, 38d 53' 22" N)</td> |
| </tr> |
| <tr> |
| <td>longitude</td> |
| <td>d</td> |
| <td>Longitude in Decimal Degrees (positive numbers mean E quadrasphere, negative mean W quadrasphere)</td> |
| <td>-77.008889 (ie, 77d 0' 32" W)</td> |
| </tr> |
| <tr> |
| <td>altitude</td> |
| <td>d</td> |
| <td>Altitude above sea level in meters</td> |
| <td>33.5</td> |
| </tr> |
| <tr> |
| <td>horiz-velocity</td> |
| <td>d</td> |
| <td>Horizontal velocity in meters-per-second</td> |
| <td>.5</td> |
| </tr> |
| <tr> |
| <td>vert-velocity</td> |
| <td>d</td> |
| <td>Vertical velocity in meters-per-second</td> |
| <td>.01</td> |
| </tr> |
| </table> |
| <p>The 'latitude' and 'longitude' keys are required; other keys are |
| optional.</p> |
| </tp:docstring> |
| </tp:flag> |
| </tp:flags> |
| |
| </interface> |
| </node> |
| |