freesmartphone.org Framework DBus Interface Specification

org.freesmartphone.GSM.SIM

Description

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.

Namespace

org.freesmartphone.GSM.SIM

Methods

Signals

Errors

Methods

GetAuthStatus ( ) → s

Description: Retrieve the authentication status for the SIM card.

This maps to the GSM 07.07 command +CPIN=?, see 3GPP TS 07.07 Chapter 8.3.

Returns

s: status

The authentication status for the SIM card. Values to expect:

SendAuthCode ( s )

Description: Send authentication code (PIN) for the SIM card.

This maps to the GSM 07.07 command +CPIN="(pin)", see 3GPP TS 07.07 Chapter 8.3.

Parameters

s: pin

The authentication code.

Unlock ( ss )

Description: Send unlock code (PUK) and new authentication code (PIN).

This maps to the GSM 07.07 command +CPIN="(puk)","(new_pin)", see 3GPP TS 07.07 Chapter 8.3.

Parameters

s: puk

The unlock code.

s: new_pin

The new authentication code.

ChangeAuthCode ( ss )

Description: Change the authentication code.

This maps to the GSM 07.07 command +CPWD="SC","(old_pin)","(new_pin)", see 3GPP TS 07.07 Chapter 7.5.

Parameters

s: old_pin

The old authentication code.

s: new_pin

The new authentication code.

SetAuthCodeRequired ( bs )

Description: Enable or disable checking for the SIM card authentification on startup.

This maps to the GSM 07.07 command +CLCK,"SC",(check),"(pin)", see 3GPP TS 07.07 Chapter 7.4.

Parameters

b: check

True, to turn SIM card authentification on. False, to turn it off.

s: pin

A valid authentication code.

GetAuthCodeRequired ( ) → b

Description: Retrieve whether the SIM card checks for authentification on startup.

This maps to the GSM 07.07 command +CLCK,"SC",2, see 3GPP TS 07.07 Chapter 7.4.

Returns

b: check

True, if SIM card authentification is turned on. False, otherwise.

GetSimReady ( ) → b

Description: Retrieve whether the SIM data can be accessed.

Implementation of this command is optional. Implementing this method does not free from raising Busy when appropriate.

Returns

b: status

True, if the data files on the SIM can be accessed. False, otherwise.

GetSimInfo ( ) → a{sv}

Description: Get information about the IMSI, the subscriber numbers, and the country code of the SIM card.

This can map to the following GSM 07.07 commands:

The dial code is computed by cross-referencing ITU E.212 (Land Mobile Numbering Plan).

Returns

a{sv}: info

Information about the SIM card. Required tuples are:

Optional tuples are: The subscriber_numbers array contains two-tuples formatted as (string:line-name, string:line-number).

SendGenericSimCommand ( s ) → s

Description: Send a generic SIM command to the SIM card.

This maps to the GSM 07.07 command +CSIM=(command), see 3GPP TS 07.07 Chapter 8.17.

Parameters

s: command

The command to send, encoded as described in GSM 11.11.

Returns

s: result

The result of the command, encoded as described in GSM 11.11.

SendRestrictedSimCommand ( iiiiis ) → s

Description: Send a restricted SIM command to the SIM card.

This maps to the GSM 07.07 command +CRSM=(command),(fileid),(p1),(p2),(p3),(data), see 3GPP TS 07.07 Chapter 8.18.

Parameters

i: command

The command to send. Valid values are:

i: fileid

The identifier of an elementary datafile on SIM. Mandatory for every command except STATUS.

i: p1

Parameter 1 passed to the SIM. Mandatory for every command except STATUS and GET RESPONSE.

i: p2

Parameter 1 passed to the SIM. Mandatory for every command except STATUS and GET RESPONSE.

i: p3

Parameter 1 passed to the SIM. Mandatory for every command except STATUS and GET RESPONSE.

s: data

The command data to the SIM, encoded as described in GSM 11.11.

Returns

s: result

The result of the command, encoded as described in GSM 11.11.

GetHomeZones ( ) → a(siii)

Description: Retrieve the homezones coordinates, if stored on the SIM.

This maps to the GSM 07.07 command +CRSM=176,28512,0,0,123, see 3GPP TS 07.07 Chapter 8.17.

Returns

a(siii): homezones

An array containing up to four homezones in Gauss-Krueger coordinates. The array contains of four-tuples with the following format:

  1. (name:string), the name of the zone,
  2. (x:int), the X value of the zone center in Gauss-Krueger format,
  3. (y:int), the Y value of the zone center in Gauss-Krueger format,
  4. (r:radious), the R*R value of the zone dimension in meters.

GetIssuer ( ) → s

Description: Retrieve the name of the SIM issuer, if stored on the SIM.

This maps to the GSM 07.07 command +CRSM=176,28486,0,0,17, see 3GPP TS 07.07 Chapter 8.17.

Returns

s: name

The name of the SIM issuer. This can be an actual network provider or a mobile virtual network operator (MVNO).

GetProviderList ( ) → a{ss}

Description: Retrieve the list of known providers, if stored on the SIM. Note that this needs an unlocked SIM on some devices. Additionally, some devices have a fallback table in ROM that gets sent when the SIM is not unlocked while other devices only use a ROM-based table.

This maps to the GSM 07.07 command +COPN, see 3GPP TS 07.07 Chapter 7.19.

Returns

a{ss}: providers

An map containing of known providers as tuples. The key is the provider code (mccmnc), the value is the alphanumerical provider name.

ListPhonebooks ( ) → as

Description: Retrieve the list of available phonebooks on the SIM.

This maps to the GSM 07.07 command +CPBS=?, see 3GPP TS 07.07 Chapter 8.12.

Returns

as: categories

The available phonebooks, if any. Expected values are:

GetPhonebookInfo ( s ) → a{sv}

Description: Request information about the SIM phonebook.

This maps to the GSM 07.07 command +CPBR=?, see 3GPP TS 07.07 Chapter 8.12.

Parameters

s: category

The phonebook storage category. See ListPhonebooks for valid categories.

Returns

a{sv}: info

Information about the SIM phonebook storage. Tuples to expect:

RetrievePhonebook ( s ) → a(iss)

Description: Retrieve all entries from the SIM phonebook.

This vaguely maps to the GSM 07.05 command +CPBR=(index1),(index2), see 3GPP TS 07.07 Chapter 8.12.

Parameters

s: category

The phonebook storage category. See ListPhonebooks for a list of valid categories.

Returns

a(iss): entries

The phonebook entries. This is an array of three-tuples. Every entry has the following structure:

DeleteEntry ( si )

Description: Delete an entry in the SIM phonebook.

This maps to the GSM 07.07 command +CPBW=, see 3GPP TS 07.07 Chapter 8.14.

Parameters

s: category

The phonebook storage category. See ListPhonebooks for a list of valid categories.

i: index

Index of entry to delete.

StoreEntry ( siss )

Description: Store an entry in the SIM phonebook.

This maps to the GSM 07.07 command +CPBW=(index),"(name)",(number),(ntype), see 3GPP TS 07.07 Chapter 8.14.

Parameters

s: category

The phonebook storage category. See ListPhonebooks for a list of valid categories.

i: index

The index of the entry to store.

s: name

The name corresponding to the number.

s: number

The number corresponding to the name.

RetrieveEntry ( si ) → ss

Parameters

s: category

The phonebook storage category. See ListPhonebooks for a list of valid categories.

i: index

The index of the entry to retrieve.

Returns

s: name

The name corresponding to the number.

s: number

The number corresponding to the name.

GetMessagebookInfo ( ) → a{sv}

Description: Request information about the SIM messagebook.

This maps to the GSM 07.05 command +CPMS="SM","SM","SM", see 3GPP TS 07.07 Chapter 3.2.2.

Returns

a{sv}: info

Information about the SIM messagebook storage. Tuples to expect:

RetrieveMessagebook ( s ) → a(isssa{sv})

Description: Retrieve all messages from the SIM messagebook that match a given category.

This vaguely maps to the GSM 07.05 command +CMGL="(category)", see 3GPP TS 07.07 Chapter 3.4.2.

Parameters

s: category

The category of messages you want to receive. Valid categories are:

Returns

a(isssa{sv}): messages

Messages matching the given category. This is an array of four-tuples. Every entry has the following structure:

GetServiceCenterNumber ( ) → s

Description: Retrieve phone number of SMS Center Number.

This maps to the GSM 07.05 command +CSCA?, see 3GPP TS 07.05 Chapter 3.3.1.

Returns

s: number

The SMS Center Number.

SetServiceCenterNumber ( s )

Description: Set phone number of SMS Center Number.

This maps to the GSM 07.05 command +CSCA=(number),(type), see 3GPP TS 07.05 Chapter 3.3.1.

Parameters

s: number

The SMS Center Number.

DeleteMessage ( i )

Description: Delete a message in the SIM messagebook.

This maps to the GSM 07.05 command +CMGD=(index), see 3GPP TS 07.05 Chapter 3.5.4.

Parameters

i: index

The storage index of the message to delete.

StoreMessage ( ssa{sv} ) → i

Description: Store a message in the SIM messagebook.

This maps to the GSM 07.05 command +CMGW=..., see 3GPP TS 07.05 Chapter 3.5.3.

Parameters

s: recipient_number

The number of the recipient.

s: contents

The contents of the message.

a{sv}: properties

For a list of valid properties see SendMessage

Returns

i: index

The index of the new message.

SendStoredMessage ( i ) → is

Description: Sends a message stored in the SIM messagebook.

This maps to the GSM 07.05 command +CMGS=(index)..., see 3GPP TS 07.05 Chapter 3.5.x.

Parameters

i: index

The index of the message.

Returns

i: transaction_index

The given transaction index for this message.

s: timestamp

The timestamp this message was received by the SMSC

RetrieveMessage ( i ) → sssa{sv}

Description: Retrieve a message from the SIM messagebook.

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.

Parameters

i: index

The index of the message to retrieve.

Returns

s: status

The category the message is in, one of ("read", "sent", "unread", "unsent").

s: sender_number

The number of the sender.

s: contents

The contents of the message.

a{sv}: properties

The one mandatory property is

For a list of valid properties:

Signals

AuthStatus ( s )

Description: Sent, when the authentication status for the SIM card changes.

Parameters

s: status

The authentication status for the SIM card. See GetAuthStatus for a list of expected values.

ReadyStatus ( b )

Description: Sent, when the data files on the SIM become (not) ready for access.

Parameters

b: status

True, if the data files on the SIM can be accessed. False, otherwise.

IncomingStoredMessage ( i )

Description: Sent, when a new message has been received and stored on the SIM card.

Parameters

i: index

The storage index of the new message.

Errors

NotPresent

Description: Raised, if there is no SIM card present.

AuthFailed

Description: Raised, if the SIM authentication code is not accepted.

Blocked

Description: Raised, if the SIM has been deactivated or is otherwise not allowed to join a network.

NotFound

Description: Raised, if a data record on the SIM is not present.

MemoryFull

Description: Raised, if there is not enough space for a data record on the SIM.

InvalidIndex

Description: Raised, if the requested messagebook or phonebook entry is out of bounds.


| Specified 2008 by the Freesmartphone.org team. | Join us and discuss further drafts smartphones-standards (at) linuxtogo (dot) org