api,dbus: rewrite Methods, Properties and Signals for gdbus-codegen
This commit is contained in:
Aleksander Morgado
@@ -1,111 +1,253 @@
|
||||
<?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
|
||||
<!--
|
||||
ModemManager 0.6 Interface Specification
|
||||
|
||||
Copyright (C) 2008 Novell, Inc.
|
||||
Copyright (C) 2008-2011 Red Hat, Inc.
|
||||
Copyright (C) 2011 The Chromium OS Authors
|
||||
Copyright (C) 2011 Google, Inc.
|
||||
-->
|
||||
|
||||
<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
|
||||
|
||||
<!--
|
||||
org.freedesktop.ModemManager1.Modem.Location:
|
||||
@short_description: The ModemManager Location interface.
|
||||
|
||||
The Location 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>
|
||||
-->
|
||||
<interface name="org.freedesktop.ModemManager1.Modem.Location">
|
||||
|
||||
<property name="Capabilities" type="u" access="read" tp:type="MM_MODEM_LOCATION_CAPABILITIES">
|
||||
<tp:docstring>
|
||||
Location capabilities of the device.
|
||||
</tp:docstring>
|
||||
</property>
|
||||
<!--
|
||||
Enable:
|
||||
@enable: %TRUE to enable location information gathering, %FALSE to disable.
|
||||
@signal_location: Flag to control whether the device emits signals with the new location information. This argument is ignored when disabling location information gathering.
|
||||
|
||||
<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>
|
||||
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.
|
||||
|
||||
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, the
|
||||
@signal_location argument can be set to %FALSE to disable location
|
||||
updates via D-Bus signals and require applications to call
|
||||
authenticated APIs (like
|
||||
<link linkend="gdbus-method-org-freedesktop-ModemManager1-Modem-Location.GetLocation">GetLocation()</link>
|
||||
) to get
|
||||
location information.
|
||||
-->
|
||||
<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>
|
||||
<arg name="enable" type="b" direction="in" />
|
||||
<arg name="signal_location" type="b" direction="in" />
|
||||
</method>
|
||||
|
||||
<!--
|
||||
GetLocation:
|
||||
@location: Dictionary of available location information when location information gathering is enabled.
|
||||
|
||||
Return current location information, if any. If the modem supports
|
||||
multiple location types it may return more than one. See the
|
||||
#org.freedesktop.ModemManager1.Modem.Location:Location property
|
||||
for more information on the dictionary returned at @location.
|
||||
|
||||
This method may require the client to authenticate itself.
|
||||
-->
|
||||
<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>
|
||||
<arg name="Location" type="a{uv}" direction="out" />
|
||||
</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>
|
||||
<!--
|
||||
Capabilities:
|
||||
|
||||
<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>
|
||||
Bitmask of <link linkend="MMModemLocationSource">MMModemLocationSource</link>
|
||||
values, specifying the location retrieval capabilities of the device.
|
||||
-->
|
||||
<property name="Capabilities" type="u" access="read" />
|
||||
|
||||
<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>
|
||||
<!--
|
||||
Enabled:
|
||||
|
||||
%TRUE if location information gathering is enabled for this device,
|
||||
%FALSE if it is disabled. When disabled, the device will not provide
|
||||
location information.
|
||||
-->
|
||||
<property name="Enabled" type="b" access="read" />
|
||||
|
||||
<!--
|
||||
SignalsLocation:
|
||||
|
||||
%TRUE if location updates will be emitted via D-Bus signals, %FALSE if
|
||||
location updates will not be emitted.
|
||||
|
||||
See the
|
||||
<link linkend="gdbus-method-org-freedesktop-ModemManager1-Modem-Location.Enable">Enable()</link>
|
||||
method for more information.
|
||||
-->
|
||||
<property name="SignalsLocation" type="b" access="read" />
|
||||
|
||||
<!--
|
||||
Location:
|
||||
|
||||
Dictionary 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.
|
||||
|
||||
This dictionary is composed of a
|
||||
<link linkend="MMModemLocationSource">MMModemLocationSource</link>
|
||||
key, with an associated data which contains type-specific location
|
||||
information:
|
||||
|
||||
<variablelist>
|
||||
<varlistentry><term><link linkend="MM-MODEM-LOCATION-SOURCE-GSM-LAC-CI:CAPS">MM_MODEM_LOCATION_SOURCE_GSM_LAC_CI</link></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Devices supporting this
|
||||
capability return a string in the format <literal>"MCC,MNC,LAC,CI"</literal> (without the
|
||||
quotes of course) where the following applies:
|
||||
</para>
|
||||
<variablelist>
|
||||
<varlistentry><term><literal>MCC</literal></term>
|
||||
<listitem>
|
||||
This is the three-digit ITU E.212 Mobile Country Code of the
|
||||
network provider to which the mobile is currently registered.
|
||||
e.g. <literal>"310"</literal>.
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry><term><literal>MNC</literal></term>
|
||||
<listitem>
|
||||
This is the two- or three-digit GSM Mobile Network Code of the
|
||||
network provider to which the mobile is currently registered.
|
||||
e.g. <literal>"26"</literal> or <literal>"260"</literal>.
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry><term><literal>LAC</literal></term>
|
||||
<listitem>
|
||||
This 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. <literal>"84CD"</literal>.
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry><term><literal>CI</literal></term>
|
||||
<listitem>
|
||||
This 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. <literal>"2BAF"</literal> or <literal>"D30156"</literal>.
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
<para>
|
||||
The entire string may only be composed of the ASCII digits <literal>[0-9]</literal>,
|
||||
the alphabetical characters <literal>[A-F]</literal>, and the comma (<literal>,</literal>) character.
|
||||
No other characters are allowed. For example: <literal>"310,260,8BE3,2BAF"</literal> or
|
||||
<literal>"250,40,CE00,1CEAD8F0"</literal>.
|
||||
</para>
|
||||
<para>
|
||||
If any of these four items (<literal>MCC</literal>, <literal>MNC</literal>,
|
||||
<literal>LAC</literal>, <literal>CI</literal>) is unknown or the
|
||||
mobile is not registered with a network, then the
|
||||
<link linkend="MM-MODEM-LOCATION-SOURCE-GSM-LAC-CI:CAPS">MM_MODEM_LOCATION_SOURCE_GSM_LAC_CI</link>
|
||||
location
|
||||
information item should not be provided as a returned value from the
|
||||
<link linkend="gdbus-method-org-freedesktop-ModemManager1-Modem-Location.GetLocation">GetLocation()</link>
|
||||
method or in the #org.freedesktop.ModemManager1.Modem.Location:Location property.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry><term><link linkend="MM-MODEM-LOCATION-SOURCE-GPS-RAW:CAPS">MM_MODEM_LOCATION_SOURCE_GPS_RAW</link></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Devices supporting this
|
||||
capability return a D-Bus dictionary (signature <literal>"a{sv}"</literal>) mapping well-known
|
||||
keys to values with defined formats.
|
||||
</para>
|
||||
<para>
|
||||
The allowed key/value pairs and their formats are:
|
||||
</para>
|
||||
<variablelist>
|
||||
<varlistentry><term><literal>"latitude"</literal></term>
|
||||
<listitem>
|
||||
(Required) Latitude in Decimal Degrees (positive numbers mean N quadrasphere, negative mean S quadrasphere), given as a double value (signature <literal>"d"</literal>). e.g. <literal>38.889722</literal>, meaning 38d 53' 22" N.
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry><term><literal>"longitude"</literal></term>
|
||||
<listitem>
|
||||
(Required) Longitude in Decimal Degrees (positive numbers mean E quadrasphere, negative mean W quadrasphere), given as a double value (signature <literal>"d"</literal>). e.g. <literal>-77.008889</literal>, meaning 77d 0' 32" W.
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry><term><literal>"altitude"</literal></term>
|
||||
<listitem>
|
||||
(Optional) Altitude above sea level in meters, given as a double value (signature <literal>"d"</literal>). e.g. <literal>33.5</literal>.
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry><term><literal>"horizontal-velocity"</literal></term>
|
||||
<listitem>
|
||||
(Optional) Horizontal velocity in meters-per-second, given as a double value (signature <literal>"d"</literal>). e.g. <literal>0.5</literal>.
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry><term><literal>"vertical-velocity"</literal></term>
|
||||
<listitem>
|
||||
(Optional) Vertical velocity in meters-per-second, given as a double value (signature <literal>"d"</literal>). e.g. <literal>0.01</literal>.
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry><term><link linkend="MM-MODEM-LOCATION-SOURCE-GPS-NMEA:CAPS">MM_MODEM_LOCATION_SOURCE_GPS_NMEA</link></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Devices supporting this capability return
|
||||
a string containing one or more NMEA sentences (D-Bus signature <literal>'s'</literal>).
|
||||
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 (<literal><CR><LF></literal>) sequence.
|
||||
</para>
|
||||
<para>
|
||||
For example, if the device sends a <literal>$GPRMC</literal> sentence immediately
|
||||
followed by a <literal>$GPGGA</literal> sentence, the reported location string would be
|
||||
(where of course the <literal><CR><LF></literal> is replaced with the actual
|
||||
ASCII <literal>CR</literal> (0x0D) and <literal>LF</literal> (0x0A) control characters):
|
||||
<para><literal>
|
||||
$GPRMC,134523.92,V,,,,,,,030136,,,N*73<CR><LF>$GPGGA,,,,,,0,00,0.5,,M,0.0001999,M,0.0000099,0000*45
|
||||
</literal></para>
|
||||
If the device sends a new <literal>$GPRMC</literal> three seconds later, the new <literal>$GPRMC</literal>
|
||||
replaces the previously received <literal>$GPRMC</literal> sentence, and the updated
|
||||
string would be:
|
||||
<para><literal>
|
||||
$GPRMC,134526.92,V,,,,,,,030136,,,N*76<CR><LF>$GPGGA,,,,,,0,00,0.5,,M,0.0001999,M,0.0000099,0000*45
|
||||
</literal></para>
|
||||
If the device then sends a <literal>$GPGSA</literal> sentence about 5 seconds later, the
|
||||
<literal>$GPGSA</literal> sentence is added to the string (since no <literal>$GPGSA</literal> sentence was
|
||||
literalviously received in this session), the updated string would be:
|
||||
<para><literal>
|
||||
$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
|
||||
</literal></para>
|
||||
The manager may discard any cached sentences older than 30 seconds.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
-->
|
||||
<property name="Location" type="a{uv}" access="read" />
|
||||
|
||||
<!-- ENUMS -->
|
||||
|
||||
<tp:flags name="MM_MODEM_LOCATION_CAPABILITIES" value-prefix="MM_MODEM_LOCATION_CAPABILITY" type="u">
|
||||
<tp:flag suffix="UNKNOWN" value="0x0">
|
||||
|
||||
Reference in New Issue
Block a user