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 a GSM device. Use it to authenticate yourself against the GSM network and read/store data from/to the embedded SIM card memory. Support for accessing the on-card phonebooks and messagebook is also provided.

Namespace

org.freesmartphone.GSM.SIM

Methods

Signals

Properties

None

Errors

None

Methods

GetAuthStatus ( ) → s

Description: Retrieve the authentication status for the SIM card.

Returns

s: status

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

SendAuthCode ( s )

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

Parameters

s: pin

The authentication code.

GetUnlockCounters ( ) → a{sv}

Description: Retrieve the unlock counters for the SIM card.

This is outside the GSM standard and only supported on some devices.

Returns

a{sv}: counters

The unlock counters for the SIM card.

Unlock ( ss )

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

Parameters

s: puk

The unlock code.

s: new_pin

The new authentication code.

ChangeAuthCode ( ss )

Description: Change the authentication code.

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.

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.

Returns

b: check

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

GetSimInfo ( ) → a{sv}

Description: Get information stored on the SIM card.

Returns

a{sv}: info

Information about the SIM card. Possible tuples are:

SendGenericSimCommand ( s ) → s

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

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.

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.

GetHomeZoneParameters ( ) → a(siii)

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

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:radius), the R*R value of the zone dimension in meters.

GetPhonebookInfo ( s ) → iii

Description: Request information about a phonebook.

Parameters

s: category

The phonebook storage category. See GetSimInfo for valid categories.

Returns

i: slots

Capacity of the phonebook.

i: numberlength

Maximum length for the phone number.

i: namelength

Maximum length for the associated name.

DeleteEntry ( si )

Description: Delete an entry in the SIM phonebook.

Parameters

s: category

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

i: index

Index of entry to delete.

StoreEntry ( siss )

Description: Store an entry in the SIM phonebook.

Parameters

s: category

The phonebook storage category. See GetSimInfo 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.

RetrievePhonebook ( sii ) → a(iss)

Description: Retrieve (parts of) a SIM phonebook.

Parameters

s: category

The phonebook storage category. Use GetSimInfo to gather the list of valid categories.

i: mindex

The minimum index of the entry to retrieve.

i: maxdex

The maximum index of entries to receive.

Returns

a(iss): entries

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

GetServiceCenterNumber ( ) → s

Description: Retrieve phone number of SMS Center.

Returns

s: number

The SMS Center Number.

SetServiceCenterNumber ( s )

Description: Set phone number of SMS Center.

Parameters

s: number

The SMS Center Number.

DeleteMessage ( i )

Description: Delete a message in the SIM messagebook.

Parameters

i: index

The storage index of the message to delete.

StoreMessage ( ssa{sv} ) → i

Description: Store a message in the SIM messagebook.

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.

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.

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

Additional properties (TBD).

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.

IncomingMessage ( 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.


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