Warning: Can't synchronize with repository "(default)" (No changeset 96d22ec3fa3ef6de3ea8dc0d7d398adc9aa071cf in the repository). Look in the Trac log for more information.

source: Dbus API specifications/html/org.freesmartphone.GSM.SIM.html @ 41a0c40

Revision 41a0c40, 19.4 KB checked in by Michael 'Mickey' Lauer <mickey@…>, 5 years ago (diff)

regenerate everything as per tools update
  • Property mode set to 100644
Line 
1
2<!-- Warning: This file has been autogenerated by tools/makedoc.py. Manual edits will be overwritten. -->
3<html>
4    <head>
5        <title>freesmartphone.org GSM SIM Interface</title>
6        <link rel="stylesheet" type="text/css" href="http://git.freesmartphone.org/?p=specs.git;a=blob_plain;f=html/style.css;hb=HEAD" />
7    </head>
8    <body>
9    <div class="topbox">freesmartphone.org Framework DBus Interface Specification</div>
10
11
12<h1>org.freesmartphone.GSM.SIM</h1><h2>Description</h2>
13<p>The SIM interface is used to access the Subscriber Identification Module (SIM)  plugged as a card into the GSM device. Use it to authenticate yourself  against the GSM network and read/store data from/to the embedded SIM card memory.  Limited support for accessing the on-card phonebook and messagebook is provided.</p>
14<h2>Namespace</h2>
15<p><tt>org.freesmartphone.GSM.SIM</tt></p>
16<h2>Methods</h2><ul>
17<li><a href="#GetAuthStatus">GetAuthStatus</a></li>
18<li><a href="#SendAuthCode">SendAuthCode</a></li>
19<li><a href="#Unlock">Unlock</a></li>
20<li><a href="#ChangeAuthCode">ChangeAuthCode</a></li>
21<li><a href="#SetAuthCodeRequired">SetAuthCodeRequired</a></li>
22<li><a href="#GetAuthCodeRequired">GetAuthCodeRequired</a></li>
23<li><a href="#GetSimInfo">GetSimInfo</a></li>
24<li><a href="#SendGenericSimCommand">SendGenericSimCommand</a></li>
25<li><a href="#SendRestrictedSimCommand">SendRestrictedSimCommand</a></li>
26<li><a href="#GetHomeZones">GetHomeZones</a></li>
27<li><a href="#ListPhonebooks">ListPhonebooks</a></li>
28<li><a href="#GetPhonebookInfo">GetPhonebookInfo</a></li>
29<li><a href="#RetrievePhonebook">RetrievePhonebook</a></li>
30<li><a href="#DeleteEntry">DeleteEntry</a></li>
31<li><a href="#StoreEntry">StoreEntry</a></li>
32<li><a href="#RetrieveEntry">RetrieveEntry</a></li>
33<li><a href="#GetMessagebookInfo">GetMessagebookInfo</a></li>
34<li><a href="#RetrieveMessagebook">RetrieveMessagebook</a></li>
35<li><a href="#GetServiceCenterNumber">GetServiceCenterNumber</a></li>
36<li><a href="#SetServiceCenterNumber">SetServiceCenterNumber</a></li>
37<li><a href="#DeleteMessage">DeleteMessage</a></li>
38<li><a href="#StoreMessage">StoreMessage</a></li>
39<li><a href="#SendStoredMessage">SendStoredMessage</a></li>
40<li><a href="#RetrieveMessage">RetrieveMessage</a></li>
41</ul>
42<h2>Signals</h2><ul>
43<li><a href="#AuthStatus">AuthStatus</a></li>
44<li><a href="#IncomingStoredMessage">IncomingStoredMessage</a></li>
45</ul>
46<h2>Errors</h2><ul>
47<li><a href="#NotPresent">NotPresent</a></li>
48<li><a href="#AuthFailed">AuthFailed</a></li>
49<li><a href="#Blocked">Blocked</a></li>
50<li><a href="#NotFound">NotFound</a></li>
51<li><a href="#MemoryFull">MemoryFull</a></li>
52<li><a href="#InvalidIndex">InvalidIndex</a></li>
53</ul>
54<h1>Methods</h1><h3><a name="GetAuthStatus">GetAuthStatus</a> ( ) &rarr; s</h3>
55<p><i>Description:</i> Retrieve the authentication status for the SIM card. </p><p><div class="rationale"><p>This maps to the GSM 07.07 command +CPIN=?, see 3GPP TS 07.07 Chapter 8.3.</p></div></p><h4>Returns</h4><i>s: status</i><p>The authentication status for the SIM card. Values to expect:  <ul>  <li>"READY" = not waiting for any PIN or PUK,</li>  <li>"SIM PIN" = waiting for SIM PIN to be given,</li>  <li>"SIM PUK" = waiting for SIM PUK to be given,</li>  <li>"SIM PIN2" = waiting for SIM PIN 2 to be given,</li>  <li>"SIM PUK2" = waiting for SIM PUK 2 to be given.</li>  </ul></p>
56<h3><a name="SendAuthCode">SendAuthCode</a> ( s )</h3>
57<p><i>Description:</i> Send authentication code (PIN) for the SIM card. </p><p><div class="rationale"><p>This maps to the GSM 07.07 command +CPIN="(pin)", see 3GPP TS 07.07 Chapter 8.3.</p></div></p><h4>Parameters</h4><i>s: pin</i><p>The authentication code.</p>
58<h3><a name="Unlock">Unlock</a> ( ss )</h3>
59<p><i>Description:</i> Send unlock code (PUK) and new authentication code (PIN). </p><p><div class="rationale"><p>This maps to the GSM 07.07 command +CPIN="(puk)","(new_pin)", see 3GPP TS 07.07 Chapter 8.3.</p></div></p><h4>Parameters</h4><i>s: puk</i><p>The unlock code.</p><i>s: new_pin</i><p>The new authentication code.</p>
60<h3><a name="ChangeAuthCode">ChangeAuthCode</a> ( ss )</h3>
61<p><i>Description:</i> Change the authentication code. </p><p><div class="rationale"><p>This maps to the GSM 07.07 command +CPWD="SC","(old_pin)","(new_pin)", see 3GPP TS 07.07 Chapter 7.5.</p></div></p><h4>Parameters</h4><i>s: old_pin</i><p>The old authentication code.</p><i>s: new_pin</i><p>The new authentication code.</p>
62<h3><a name="SetAuthCodeRequired">SetAuthCodeRequired</a> ( bs )</h3>
63<p><i>Description:</i> Enable or disable checking for the SIM card authentification on startup. </p><p><div class="rationale"><p>This maps to the GSM 07.07 command +CLCK,"SC",(check),"(pin)", see 3GPP TS 07.07 Chapter 7.4.</p></div></p><h4>Parameters</h4><i>b: check</i><p>True, to turn SIM card authentification on. False, to turn it off.</p><i>s: pin</i><p>A valid authentication code.</p>
64<h3><a name="GetAuthCodeRequired">GetAuthCodeRequired</a> ( ) &rarr; b</h3>
65<p><i>Description:</i> Retrieve whether the SIM card checks for authentification on startup. </p><p><div class="rationale"><p>This maps to the GSM 07.07 command +CLCK,"SC",2, see 3GPP TS 07.07 Chapter 7.4.</p></div></p><h4>Returns</h4><i>b: check</i><p>True, if SIM card authentification is turned on. False, otherwise.</p>
66<h3><a name="GetSimInfo">GetSimInfo</a> ( ) &rarr; a{sv}</h3>
67<p><i>Description:</i> Get information about the IMSI, the subscriber numbers,  and the country code of the SIM card. </p><p><div class="rationale"><p>This can map to the following GSM 07.07 commands:  <ul>  <li>+CIMI (see 3GPP TS 07.07 Chapter 5.6),</li>  <li>+CNUM (see 3GPP TS 07.07 Chapter 7.1).</li>  </ul>  The dial code is computed by cross-referencing ITU E.212 (Land Mobile Numbering Plan).</p></div></p><h4>Returns</h4><i>a{sv}: info</i><p>Information about the SIM card. Required tuples are:  <ul>  <li>("imsi", string) = The unique subscriber identification stored on your SIM.</li>  </ul>  Optional tuples are:  <ul>  <li>("subscriber_numbers", array),</li>  <li>("dial_prefix", string),</li>  <li>("country", string).</li>  </ul>  The subscriber_numbers array contains two-tuples formatted as (string:line-name, string:line-number).</p>
68<h3><a name="SendGenericSimCommand">SendGenericSimCommand</a> ( s ) &rarr; s</h3>
69<p><i>Description:</i> Send a generic SIM command to the SIM card. </p><p><div class="rationale"><p>This maps to the GSM 07.07 command +CSIM=(command), see 3GPP TS 07.07 Chapter 8.17.</p></div></p><h4>Parameters</h4><i>s: command</i><p>The command to send, encoded as described in GSM 11.11.</p><h4>Returns</h4><i>s: result</i><p>The result of the command, encoded as described in GSM 11.11.</p>
70<h3><a name="SendRestrictedSimCommand">SendRestrictedSimCommand</a> ( iiiiis ) &rarr; s</h3>
71<p><i>Description:</i> Send a restricted SIM command to the SIM card. </p><p><div class="rationale"><p>This maps to the GSM 07.07 command +CRSM=(command),(fileid),(p1),(p2),(p3),(data), see 3GPP TS 07.07 Chapter 8.18.</p></div></p><h4>Parameters</h4><i>i: command</i><p>The command to send. Valid values are:  <ul>  <li>176 = READ BINARY,</li>  <li>178 = READ RECORD,</li>  <li>192 = GET RESPONSE,</li>  <li>214 = UPDATE BINARY,</li>  <li>220 = UPDATE RECORD,</li>  <li>242 = STATUS.</li>  </ul></p><i>i: fileid</i><p>The identifier of an elementary datafile on SIM. Mandatory for every command except STATUS.</p><i>i: p1</i><p>Parameter 1 passed to the SIM. Mandatory for every command except STATUS and GET RESPONSE.</p><i>i: p2</i><p>Parameter 1 passed to the SIM. Mandatory for every command except STATUS and GET RESPONSE.</p><i>i: p3</i><p>Parameter 1 passed to the SIM. Mandatory for every command except STATUS and GET RESPONSE.</p><i>s: data</i><p>The command data to the SIM, encoded as described in GSM 11.11.</p><h4>Returns</h4><i>s: result</i><p>The result of the command, encoded as described in GSM 11.11.</p>
72<h3><a name="GetHomeZones">GetHomeZones</a> ( ) &rarr; a(siii)</h3>
73<p><i>Description:</i> Retrieve the homezones coordinates, if stored on SIM. </p><p><div class="rationale"><p>This maps to the GSM 07.07 command +CRSM=176,28512,0,0,123, see 3GPP TS 07.07 Chapter 8.17.</p></div></p><h4>Returns</h4><i>a(siii): homezones</i><p>An array containing up to four homezones in Gauss-Krueger coordinates. The array contains of four-tuples with the following format:  <ol>  <li>(name:string), the name of the zone,</li>  <li>(x:int), the X value of the zone center in Gauss-Krueger format,</li>  <li>(y:int), the Y value of the zone center in Gauss-Krueger format,</li>  <li>(r:radious), the R*R value of the zone dimension in meters.</li>  </ol></p>
74<h3><a name="ListPhonebooks">ListPhonebooks</a> ( ) &rarr; as</h3>
75<p><i>Description:</i> Retrieve the list of available phonebooks on the SIM. </p><p><div class="rationale"><p>This maps to the GSM 07.07 command +CPBS=?, see 3GPP TS 07.07 Chapter 8.12.</p></div></p><h4>Returns</h4><i>as: categories</i><p>The available phonebooks.</p>
76<h3><a name="GetPhonebookInfo">GetPhonebookInfo</a> ( s ) &rarr; a{sv}</h3>
77<p><i>Description:</i> Request information about the SIM phonebook. </p><p><div class="rationale"><p>This maps to the GSM 07.07 command +CPBR=?, see 3GPP TS 07.07 Chapter 8.12.</p></div></p><h4>Parameters</h4><i>s: category</i><p>The phonebook storage category. See org.freesmartphone.GSM.SIM.ListPhonebooks  for valid categories.</p><h4>Returns</h4><i>a{sv}: info</i><p>Information about the SIM phonebook storage. Tuples to expect:  <ul>  <li>("min_index", int:value) = lowest entry index for given phonebook on the SIM,</li>  <li>("max_index", int:value) = highest entry index for given phonebook on the SIM,</li>  <li>("number_length", int:value) = maximum length for the number,</li>  <li>("name_length", int:value) = maximum length for the name.</li>  </ul></p>
78<h3><a name="RetrievePhonebook">RetrievePhonebook</a> ( s ) &rarr; a(iss)</h3>
79<p><i>Description:</i> Retrieve all entries from the SIM phonebook. </p><p><div class="rationale"><p>This vaguely maps to the GSM 07.05 command +CPBR=(index1),(index2), see 3GPP TS 07.07 Chapter 8.12.</p></div></p><h4>Parameters</h4><i>s: category</i><p>The phonebook storage category. See org.freesmartphone.GSM.SIM.ListPhonebooks  for valid categories.</p><h4>Returns</h4><i>a(iss): entries</i><p>The phonebook entries. This is an array of three-tuples. Every entry has the following structure:  <ul>  <li>(int:index) = storage index,</li>  <li>(string:name) = name,</li>  <li>(string:number) = number.</li>  </ul></p>
80<h3><a name="DeleteEntry">DeleteEntry</a> ( si )</h3>
81<p><i>Description:</i> Delete an entry in the SIM phonebook. </p><p><div class="rationale"><p>This maps to the GSM 07.07 command +CPBW=, see 3GPP TS 07.07 Chapter 8.14.</p></div></p><h4>Parameters</h4><i>s: category</i><p>The phonebook storage category. See org.freesmartphone.GSM.SIM.ListPhonebooks  for valid categories.</p><i>i: index</i><p>Index of entry to delete.</p>
82<h3><a name="StoreEntry">StoreEntry</a> ( siss )</h3>
83<p><i>Description:</i> Store an entry in the SIM phonebook. </p><p><div class="rationale"><p>This maps to the GSM 07.07 command +CPBW=(index),"(name)",(number),(ntype), see 3GPP TS 07.07 Chapter 8.14.</p></div></p><h4>Parameters</h4><i>s: category</i><p>The phonebook storage category. See org.freesmartphone.GSM.SIM.ListPhonebooks  for valid categories.</p><i>i: index</i><p>The index of the entry to store.</p><i>s: name</i><p>The name corresponding to the number.</p><i>s: number</i><p>The number corresponding to the name.</p>
84<h3><a name="RetrieveEntry">RetrieveEntry</a> ( si ) &rarr; ss</h3>
85<h4>Parameters</h4><i>s: category</i><p>The phonebook storage category. See org.freesmartphone.GSM.SIM.ListPhonebooks  for valid categories.</p><i>i: index</i><p>The index of the entry to retrieve.</p><h4>Returns</h4><i>s: name</i><p>The name corresponding to the number.</p><i>s: number</i><p>The number corresponding to the name.</p>
86<h3><a name="GetMessagebookInfo">GetMessagebookInfo</a> ( ) &rarr; a{sv}</h3>
87<p><i>Description:</i> Request information about the SIM messagebook. </p><p><div class="rationale"><p>This maps to the GSM 07.05 command +CPMS="SM","SM","SM", see 3GPP TS 07.07 Chapter 3.2.2.</p></div></p><h4>Returns</h4><i>a{sv}: info</i><p>Information about the SIM messagebook storage. Tuples to expect:  <ul>  <li>("first", int:value) = first storage index of messages on the SIM,</li>  <li>("last", int:value) = last index of messages stored on the SIM,</li>  <li>("used", int:value) = number of messages currently stored on the SIM.</li>  </ul></p>
88<h3><a name="RetrieveMessagebook">RetrieveMessagebook</a> ( s ) &rarr; a(isssa{sv})</h3>
89<p><i>Description:</i> Retrieve all messages from the SIM messagebook that match a given category. </p><p><div class="rationale"><p>This vaguely maps to the GSM 07.05 command +CMGL="(category)", see 3GPP TS 07.07 Chapter 3.4.2.</p></div></p><h4>Parameters</h4><i>s: category</i><p>The category of messages you want to receive. Valid categories are:  <ul>  <li>"all" = all messages,</li>  <li>"read" = message you have received and read,</li>  <li>"unread" = new messages you have received,</li>  <li>"sent" = messages you have sent,</li>  <li>"unsent" = message you have not sent yet.</li>  </ul></p><h4>Returns</h4><i>a(isssa{sv}): messages</i><p>Messages matching the given category. This is an array of four-tuples. Every entry has the following structure:  <ul>  <li>(int:index) = storage index,</li>  <li>(string:status) = status of message, one of ("read", "unread", "sent", "unsent"),</li>  <li>(string:number) = sender or receiver number.</li>  <li>(string:content) = contents of the message.</li>  <li>(map:properties) = Map with additional properties (see RetrieveMessage)</li>  </ul></p>
90<h3><a name="GetServiceCenterNumber">GetServiceCenterNumber</a> ( ) &rarr; s</h3>
91<p><i>Description:</i> Retrieve phone number of SMS Center Number. </p><p><div class="rationale"><p>This maps to the GSM 07.05 command +CSCA?, see 3GPP TS 07.05 Chapter 3.3.1.</p></div></p><h4>Returns</h4><i>s: number</i><p>The SMS Center Number.</p>
92<h3><a name="SetServiceCenterNumber">SetServiceCenterNumber</a> ( s )</h3>
93<p><i>Description:</i> Set phone number of SMS Center Number. </p><p><div class="rationale"><p>This maps to the GSM 07.05 command +CSCA=(number),(type), see 3GPP TS 07.05 Chapter 3.3.1.</p></div></p><h4>Parameters</h4><i>s: number</i><p>The SMS Center Number.</p>
94<h3><a name="DeleteMessage">DeleteMessage</a> ( i )</h3>
95<p><i>Description:</i> Delete a message in the SIM messagebook. </p><p><div class="rationale"><p>This maps to the GSM 07.05 command +CMGD=(index), see 3GPP TS 07.05 Chapter 3.5.4.</p></div></p><h4>Parameters</h4><i>i: index</i><p>The storage index of the message to delete.</p>
96<h3><a name="StoreMessage">StoreMessage</a> ( ssa{sv} ) &rarr; i</h3>
97<p><i>Description:</i> Store a message in the SIM messagebook. </p><p><div class="rationale"><p>This maps to the GSM 07.05 command +CMGW=..., see 3GPP TS 07.05 Chapter 3.5.3.</p></div></p><h4>Parameters</h4><i>s: recipient_number</i><p>The number of the recipient.</p><i>s: contents</i><p>The contents of the message.</p><i>a{sv}: properties</i><p>Additional properties of the message. Valid tuples are:  <ul>  <li>(string:type) = The type of the SMS, must be one of ("SMS_SUBMIT", "SMS_DELIVER", "SMS_COMMAND", "SMS_SUBMIT_REPORT", "SMS_DELIVER_REPORT"),</li>  <li>(string:alphabet) = Encoding of the short message, must be one of ("binary", "gsm", "usc2"),</li>  <li>Properties for concatenated short messages (CSM):  <ul>  <li>(int:csm_id) = Id of the CSM (messages belonging to the same csm must have the same id),</li>  <li>(int:csm_num) = Total number of messages in this CSM,</li>  <li>(int:csm_seq) = Number defining the order of the messages in the CSM.</li>  </ul>  </li>  <li>Properties for port addressing (similar to UDP ports):  <ul>  <li>(int:src_port) = Source port this short message comes from,</li>  <li>(int:dst_port) = Destination port this short message should be routed to.</li>  </ul>  </li>  </ul></p><h4>Returns</h4><i>i: index</i><p>The index of the new message.</p>
98<h3><a name="SendStoredMessage">SendStoredMessage</a> ( i ) &rarr; i</h3>
99<p><i>Description:</i> Sends a message stored in the SIM messagebook. </p><p><div class="rationale"><p>This maps to the GSM 07.05 command +CMGS=(index)..., see 3GPP TS 07.05 Chapter 3.5.x.</p></div></p><h4>Parameters</h4><i>i: index</i><p>The index of the message.</p><h4>Returns</h4><i>i: transaction_index</i><p>The given transaction index for this message.</p>
100<h3><a name="RetrieveMessage">RetrieveMessage</a> ( i ) &rarr; sssa{sv}</h3>
101<p><i>Description:</i> Retrieve a message from the SIM messagebook. </p><p><div class="rationale"><p>This can map to the GSM 07.05 command +CMGR=(index), see 3GPP TS 07.05 Chapter 3.4.3.  It might also map to the GSM 07.05 command +CMGL=(storage_spec), see 3GPP TS 07.05 Chapter 3.4.2.</p></div></p><h4>Parameters</h4><i>i: index</i><p>The index of the message to retrieve.</p><h4>Returns</h4><i>s: status</i><p>The category the message is in, one of ("read", "sent", "unread", "unsent").</p><i>s: sender_number</i><p>The number of the sender.</p><i>s: contents</i><p>The contents of the message.</p><i>a{sv}: properties</i><p>Additional properties of the message. Tuples to expect:  <ul>  <li>(string:type) = Type of the SMS, must be one of ("SMS_SUBMIT", "SMS_DELIVER", "SMS_COMMAND", "SMS_SUBMIT_REPORT", "SMS_DELIVER_REPORT"),</li>  <li>(string:alphabet) = Encoding of the short message, must be one of ("binary", "gsm", "usc2"),</li>  <li>(string:timestamp) = Timestamp when the message was received by the service center,</li>  <li>Properties for concatenated short messages (CSM):  <ul>  <li>(int:csm_id) = Id of the CSM (messages belonging to the same CSM must have the same id),</li>  <li>(int:csm_num) = Total number of messages in this CSM,</li>  <li>(int:csm_seq) = Number defining the order of the messages in the CSM.</li>  </ul>  </li>  <li>Properties for port addressing (similar to UDP ports):  <ul>  <li>(int:src_port) = Source port this short message comes from,</li>  <li>(int:dst_port) = Destination port this short message should be routed to.</li>  </ul>  </li>  </ul></p>
102<h1>Signals</h1><h3><h3><a name="AuthStatus">AuthStatus</a> ( s )</h3><p><i>Description:</i> Sent, when the authentication status for the SIM card changes. </p><h4>Parameters</h4><i>s: status</i><p>The authentication status for the SIM card. See method GetAuthStatus for expected values.</p></h3>
103<h3><h3><a name="IncomingStoredMessage">IncomingStoredMessage</a> ( i )</h3><p><i>Description:</i> Sent, when a new message has been received and stored on the SIM card. </p><h4>Parameters</h4><i>i: index</i><p>The storage index of the new message.</p></h3>
104<h1>Errors</h1><h3><a name="NotPresent">NotPresent</a></h3><p><i>Description:</i> Raised, if there is no SIM card present. </p>
105<h3><a name="AuthFailed">AuthFailed</a></h3><p><i>Description:</i> Raised, if the SIM authentication code is not accepted. </p>
106<h3><a name="Blocked">Blocked</a></h3><p><i>Description:</i> Raised, if the SIM has been deactivated or is otherwise not allowed to join a network. </p>
107<h3><a name="NotFound">NotFound</a></h3><p><i>Description:</i> Raised, if a data record on the SIM is not present. </p>
108<h3><a name="MemoryFull">MemoryFull</a></h3><p><i>Description:</i> Raised, if there is not enough space for a data record on the SIM. </p>
109<h3><a name="InvalidIndex">InvalidIndex</a></h3><p><i>Description:</i> Raised, if the requested messagebook or phonebook entry is out of bounds. </p>
110
111    <hr/>
112    <small>
113    | Specified 2008 by the <a href="http://www.freesmartphone.org">Freesmartphone.org</a> team. | Join us and discuss further drafts smartphones-standards (at) linuxtogo (dot) org
114    </small>
115    <hr/>
116    </body>
117</html>
118
Note: See TracBrowser for help on using the repository browser.