freesmartphone.org GSM SIM Interface

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:

  • “UNKNOWN” = unknown (possibly due to SIM communication error or SIM not inserted)
  • “READY” = not waiting for any PIN or PUK,
  • “SIM PIN” = waiting for SIM PIN to be given,
  • “SIM PUK” = waiting for SIM PUK to be given,
  • “SIM PIN2” = waiting for SIM PIN 2 to be given,
  • “SIM PUK2” = waiting for SIM PUK 2 to be given.

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.

Implementation Note

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:

  • (“imsi”, string) = The unique subscriber identification stored on your SIM.
  • (“issuer”, string) = The unique subscriber identification stored on your SIM.
  • (“phonebooks”, space-separated string) = The phonebooks stored on this SIM. Expected values are “contacts”, “dialed”, “received”, “own”, “missed”, “emergency”. Other phonebooks are named included with their native code and prefixed “aux:”.
  • (“slots”) = The capacity of the messagebook
  • (“messages”) = The messages in the messagebook

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:

  • 176 = READ BINARY,
  • 178 = READ RECORD,
  • 192 = GET RESPONSE,
  • 214 = UPDATE BINARY,
  • 220 = UPDATE RECORD,
  • 242 = STATUS.

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:

  • (int:index) = storage index.
  • (string:name) = name.
  • (string:number) = number.

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.