r233 - trunk/specifications/otapi
smartphones-commits at lists.linuxtogo.org
smartphones-commits at lists.linuxtogo.org
Sun Apr 20 18:52:18 CEST 2008
Author: mickeylauer
Date: 2008-04-20 18:52:16 +0200 (Sun, 20 Apr 2008)
New Revision: 233
Modified:
trunk/specifications/otapi/org.freesmartphone.GSM.Device.xml.in
trunk/specifications/otapi/org.freesmartphone.GSM.Network.xml.in
trunk/specifications/otapi/org.freesmartphone.GSM.SIM.xml.in
Log:
otapi/org.freesmartphone.GSM.Device.xml: docs++
otapi/org.freesmartphone.GSM.SIM.xml: add GetSubscriberNumber and GetCountryCode from org.freesmartphone.GSM.Network.xml
otapi/org.freesmartphone.GSM.Network.xml: add documentation for all methods.
Modified: trunk/specifications/otapi/org.freesmartphone.GSM.Device.xml.in
===================================================================
--- trunk/specifications/otapi/org.freesmartphone.GSM.Device.xml.in 2008-04-20 15:33:20 UTC (rev 232)
+++ trunk/specifications/otapi/org.freesmartphone.GSM.Device.xml.in 2008-04-20 16:52:16 UTC (rev 233)
@@ -20,11 +20,11 @@
<doc:doc>
<doc:description>Get information about the manufacturer, model, revision, and IMEI.</doc:description>
<doc:inote>
- This maps to the following GSM 07.07 commands
- +CGMI (see 3GPP TS 07.07 Chapter 5.1)
- +CGMM (see 3GPP TS 07.07 Chapter 5.2)
- +CGMM (see 3GPP TS 07.07 Chapter 5.3)
- +CGSN (see 3GPP TS 07.07 Chapter 5.4)
+ This maps to the following GSM 07.07 commands:
+ +CGMI (see 3GPP TS 07.07 Chapter 5.1)
+ +CGMM (see 3GPP TS 07.07 Chapter 5.2)
+ +CGMM (see 3GPP TS 07.07 Chapter 5.3)
+ +CGSN (see 3GPP TS 07.07 Chapter 5.4)
</doc:inote>
</doc:doc>
<!-- FIXME do we want to return a{sv} instead? -->
@@ -82,7 +82,8 @@
</doc:doc>
<arg type="a{sv}" name="features" direction="out">
<doc:doc>
- <doc:summary>The telephony features supported by this device. Expected tuples are:
+ <doc:summary>
+ The telephony features supported by this device. Expected tuples are:
("GSM", class), ("FAX", class), ("WIRELESS", class), ("GPRS", class).
</doc:summary>
<doc:inote>
Modified: trunk/specifications/otapi/org.freesmartphone.GSM.Network.xml.in
===================================================================
--- trunk/specifications/otapi/org.freesmartphone.GSM.Network.xml.in 2008-04-20 15:33:20 UTC (rev 232)
+++ trunk/specifications/otapi/org.freesmartphone.GSM.Network.xml.in 2008-04-20 16:52:16 UTC (rev 233)
@@ -1,96 +1,135 @@
<?xml version="1.0"?>
<node name="/" xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd" doc:id="freesmartphone-gsm-network-interface">
- <!-- NOTE Taxonomy: We think in terms of (service) providers
- rather than network operators, since multiple (service)
- providers can use the networks from operators, however
- what actually matters most is the provider name, not the
- actual network operator the provider is using. -->
+<doc:doc>
+ <doc:summary>freesmartphone.org GSM Network Interface</doc:summary>
+</doc:doc>
<interface name="org.freesmartphone.GSM.Network">
+ <doc:doc>
+ <doc:para>
+ The Network object is used to give information about the GSM
+ service providers and this device's status with regards to
+ to network registration and connectivity.
+ Taxonomy note: We think in terms of (service) providers
+ rather than (network) operators, since multiple (service)
+ providers can use the networks from operators, however
+ what actually matters most is the provider name, not the
+ actual network operator the provider is using.
+ </doc:para>
+ </doc:doc>
+
<method name="Register">
<annotation name="org.freedesktop.DBus.GLib.Async" value="fso_gsm_network"/>
+ <doc:doc>
+ <doc:description>Register with any available service provider.</doc:description>
+ <doc:inote>This maps to the GSM 07.07 command +COPS=0, see 3GPP TS 07.07 Chapter 7.3.</doc:inote>
+ </doc:doc>
</method>
+ <method name="Unregister">
+ <annotation name="org.freedesktop.DBus.GLib.Async" value="fso_gsm_network"/>
+ <doc:doc>
+ <doc:description>Unregister from service provider.</doc:description>
+ <doc:inote>This maps to the GSM 07.07 command +COPS=2, see 3GPP TS 07.07 Chapter 7.3.</doc:inote>
+ </doc:doc>
+ </method>
+
+ <!-- FIXME I think it makes sense to use a{sv} for GetStatus and Status -->
+
<method name="GetStatus">
<annotation name="org.freedesktop.DBus.GLib.Async" value="fso_gsm_network"/>
- <arg type="s" name="provider_name" direction="out"/>
- <arg type="s" name="status" direction="out" />
- <!--
- Valid values are:
- * 0: Unregistered
- * 1: Registered (Home Network)
- * 2: Busy
- * 3: Denied
- * 4: Unknown
- * 5: Registered (Roaming)
- -->
- <arg type="i" name="strength" direction="out" />
- <!--
- %age, -1 for unknown
- -->
+ <doc:doc>
+ <doc:description>Get Network Status.</doc:description>
+ <doc:inote>
+ This maps to the following GSM 07.07 commands:
+ +CREG? (see 3GPP TS 07.07 Chapter 7.3),
+ +COPS? (see 3GPP TS 07.07 Chapter 7.4),
+ +CSQ (see 3GPP TS 07.07 Chapter 8.5).
+ </doc:inote>
+ </doc:doc>
+ <arg type="s" name="provider_name" direction="out">
+ <doc:doc>
+ <doc:summary>The provider name we are registered with (can be empty).</doc:summary>
+ </doc:doc>
+ </arg>
+ <arg type="s" name="status" direction="out">
+ <doc:doc>
+ <doc:summary>
+ The registration status. Expected values are:
+ "unregistered" = not registered, not trying,
+ "home" = registered to home network,
+ "busy" = not registered, but currently trying,
+ "denied" = no permitted network available,
+ "unknown" = no idea,
+ "roaming" = registered to foreign network.
+ </doc:summary>
+ </doc:doc>
+ </arg>
+ <arg type="i" name="strength" direction="out">
+ <doc:doc>
+ <doc:summary>The strength in percentage (0-100).</doc:summary>
+ </doc:doc>
+ </arg>
</method>
<signal name="Status">
<arg type="s" name="provider_name" />
<arg type="s" name="status" />
- <!--
- Valid values are:
- * 0: Unregistered
- * 1: Registered (Home Network)
- * 2: Busy
- * 3: Denied
- * 4: Unknown
- * 5: Registered (Roaming)
- -->
<arg type="i" name="strength" />
- <!--
- %age, -1 for unknown
- -->
</signal>
<method name="ListProviders">
<annotation name="org.freedesktop.DBus.GLib.Async" value="fso_gsm_network"/>
- <arg type="a(isss)" name="providers" direction="out" />
- <!--
- Returns an array of the following structure:
- # Integer: Operator Code (A unique numerical ID operator)
- # String: Status (0=unknown, 1=available, 2=current, 3=forbidden)
- # String: Name (Long name)
- # String: Nickname (Abbreviated name) (optional, may be empty)
- -->
+ <doc:doc>
+ <doc:description>List available service providers.</doc:description>
+ <doc:inote>This maps to the GSM 07.07 command +COPS=?, see 3GPP TS 07.07 Chapter 7.3</doc:inote>
+ </doc:doc>
+ <arg type="a(isss)" name="providers" direction="out">
+ <doc:doc>
+ <doc:summary>
+ An array of four-tuples with the following structure:
+ 1. Unique numerical operator code,
+ 2. Status ("unknown", "available", "current", "forbidden"),
+ 3. Long Name,
+ 4. Short Name (optional, may be empty).
+ </doc:summary>
+ </doc:doc>
+ </arg>
</method>
<method name="RegisterWithProvider">
<annotation name="org.freedesktop.DBus.GLib.Async" value="fso_gsm_network"/>
- <arg type="i" name="operator_code" direction="in" />
+ <doc:doc>
+ <doc:description>Register to a dedicated service provider.</doc:description>
+ <doc:inote>This maps to the GSM 07.07 command +COPS=1..., see 3GPP TS 07.07 Chapter 7.3</doc:inote>
+ </doc:doc>
+ <arg type="i" name="operator_code" direction="in">
+ <doc:doc>
+ <doc:summary>The operator code.</doc:summary>
+ </doc:doc>
+ </arg>
</method>
- <method name="GetSubscriberNumbers">
- <annotation name="org.freedesktop.DBus.GLib.Async" value="fso_gsm_network"/>
- <!-- is this SIM? -->
- <arg type="as" name="numbers" direction="out" />
- </method>
-
- <signal name="SubscriberNumbers">
- <arg type="as" name="numbers" />
- </signal>
-
<method name="GetCountryCode">
- <annotation name="org.freedesktop.DBus.GLib.Async" value="fso_gsm_network"/>
- <arg type="s" name="dial_code" direction="out" />
+ <annotation name="org.freedesktop.DBus.GLib.Async" value="fso_gsm_network" />
+ <doc:doc>
+ <doc:description>Compute the country code of the current service provider.</doc:description>
+ <doc:inote>
+ This maps to the GSM 07.07 command +COPS?, see 3GPP TS 07.07 Chapter 5.6.
+ Get the dial code by cross-referencing ITU E.212 (Land Mobile Numbering Plan).
+ </doc:inote>
+ </doc:doc>
+ <arg type="s" name="dial_code" direction="out">
+ <doc:doc>
+ <doc:summary>The country dial code (including the +).</doc:summary>
+ </doc:doc>
+ </arg>
</method>
- <method name="GetHomeCountryCode">
- <annotation name="org.freedesktop.DBus.GLib.Async" value="fso_gsm_network"/>
- <arg type="s" name="dial_code" direction="out" />
- </method>
-
- <!--
-
- TODO Possibly more methods for:
+ <!-- FIXME Do we want methods for:
* List available GSM bands
* Get/set preferred GSM band
* List preferred provider
Modified: trunk/specifications/otapi/org.freesmartphone.GSM.SIM.xml.in
===================================================================
--- trunk/specifications/otapi/org.freesmartphone.GSM.SIM.xml.in 2008-04-20 15:33:20 UTC (rev 232)
+++ trunk/specifications/otapi/org.freesmartphone.GSM.SIM.xml.in 2008-04-20 16:52:16 UTC (rev 233)
@@ -26,11 +26,11 @@
<doc:doc>
<doc:summary>
The authentication status for the SIM card. Values to expect:
- * "READY" ME is not pending for any password
- * "SIM PIN" ME is waiting for SIM PIN to be given
- * "SIM PUK" ME is waiting for SIM PUK to be given
- * "SIM PIN2" ME is waiting for SIM PIN 2 to be given
- * "SIM PUK2" ME is waiting for SIM PUK 2 to be given
+ "READY" = ME is not pending for any password,
+ "SIM PIN" = ME is waiting for SIM PIN to be given,
+ "SIM PUK" = ME is waiting for SIM PUK to be given,
+ "SIM PIN2" = ME is waiting for SIM PIN 2 to be given,
+ "SIM PUK2" = ME is waiting for SIM PUK 2 to be given.
<!-- 07.07 8.3 shows many more here, but we will add these
when we actually encounter them in the field -->
</doc:summary>
@@ -101,7 +101,8 @@
<method name="GetImsi">
<annotation name="org.freedesktop.DBus.GLib.Async" value="fso_gsm_sim" />
<doc:doc>
- <doc:description>Request the International Mobile Subscriber Identity (IMSI).</doc:description>
+ <doc:description>Retrieve the International Mobile Subscriber Identity (IMSI).</doc:description>
+ <doc:inote>This maps to the GSM 07.07 command +CIMI, see 3GPP TS 07.07 Chapter 5.6.</doc:inote>
</doc:doc>
<arg type="s" name="imsi" direction="out">
<doc:doc>
@@ -110,6 +111,35 @@
</arg>
</method>
+ <method name="GetSubscriberNumbers">
+ <annotation name="org.freedesktop.DBus.GLib.Async" value="fso_gsm_sim" />
+ <doc:doc>
+ <doc:description>Retrieve the subscriber numers stored on the SIM (or in the modem).</doc:description>
+ <doc:inote>This maps to the GSM 07.07 command +CNUM, see 3GPP TS 07.07 Chapter 7.1.</doc:inote>
+ </doc:doc>
+ <arg type="a{sv}" name="numbers" direction="out">
+ <doc:doc>
+ <doc:summary>The subscriber numbers.</doc:summary>
+ </doc:doc>
+ </arg>
+ </method>
+
+ <method name="GetCountryCode">
+ <annotation name="org.freedesktop.DBus.GLib.Async" value="fso_gsm_sim" />
+ <doc:doc>
+ <doc:description>Compute the country code of the SIM.</doc:description>
+ <doc:inote>
+ This maps to the GSM 07.07 command +CIMI, see 3GPP TS 07.07 Chapter 5.6.
+ Get the dial code by cross-referencing ITU E.212 (Land Mobile Numbering Plan).
+ </doc:inote>
+ </doc:doc>
+ <arg type="s" name="dial_code" direction="out">
+ <doc:doc>
+ <doc:summary>The country dial code (including the +).</doc:summary>
+ </doc:doc>
+ </arg>
+ </method>
+
<!-- FIXME might want to consider additional commands for
* getting retry count left for auth
* lock phone -->
More information about the Smartphones-commits
mailing list