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
- GetAuthStatus
- SendAuthCode
- GetUnlockCounters
- Unlock
- ChangeAuthCode
- SetAuthCodeRequired
- GetAuthCodeRequired
- GetSimInfo
- SendGenericSimCommand
- SendRestrictedSimCommand
- GetHomeZoneParameters
- GetPhonebookInfo
- DeleteEntry
- StoreEntry
- RetrievePhonebook
- GetServiceCenterNumber
- SetServiceCenterNumber
- DeleteMessage
- StoreMessage
- SendStoredMessage
- RetrieveMessage
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:
- (name:string), the name of the zone,
- (x:int), the X value of the zone center in Gauss-Krueger format,
- (y:int), the Y value of the zone center in Gauss-Krueger format,
- (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.