SwiApiGsmSim.h File Reference

This file contains definitions, enumerations, structures and forward declarations for SwiApiGsmSim.c file. More...

#include "SwiDataTypes.h"
#include "SwiRcodes.h"

Go to the source code of this file.

Data Structures
struct	SWI_STRUCT_SIM_Verify
struct	SWI_STRUCT_SIM_Password
struct	SWI_STRUCT_SIM_EnableLock
struct	SWI_STRUCT_SIM_LockStatus
struct	SWI_STRUCT_SIM_StatusExp
struct	SWI_STRUCT_MEP_Unlock
struct	SWI_STRUCT_IccId
struct	SWI_STRUCT_SimAuth

Macros
#define	LENGTH_MaxCHV   9
#define	LENGTH_MEPCode   13
#define	LENGTH_IccId   10
#define	LENGTH_RandNum   16
#define	LENGTH_Kc   8

Enumerations
enum	SWI_TYPE_SIM_Password {   SWI_SIMPASSWORD_Reserved, SWI_SIMPASSWORD_CHV1, SWI_SIMPASSWORD_CHV2, SWI_SIMPASSWORD_UnblockingCHV1,   SWI_SIMPASSWORD_UnblockingCHV2 }
enum	SWI_TYPE_SIM_StatusExp {   SWI_SIMSTATUSEXP_OK, SWI_SIMSTATUSEXP_NotInserted, SWI_SIMSTATUSEXP_Removed, SWI_SIMSTATUSEXP_InitializeFailure,   SWI_SIMSTATUSEXP_GeneralFailure, SWI_SIMSTATUSEXP_Locked, SWI_SIMSTATUSEXP_PIN1Blocked, SWI_SIMSTATUSEXP_PIN2Blocked,   SWI_SIMSTATUSEXP_PIN1Rejected, SWI_SIMSTATUSEXP_PIN2Rejected, SWI_SIMSTATUSEXP_MEPLocked, SWI_SIMSTATUSEXP_NetworkReject }
enum	SWI_TYPE_SIM_RequiredOperation {   SWI_REQUIREDOPERATON_NoOperation, SWI_REQUIREDOPERATON_EnterPIN, SWI_REQUIREDOPERATON_EnterPIN2, SWI_REQUIREDOPERATON_EnterPUK,   SWI_REQUIREDOPERATON_EnterPUK2, SWI_REQUIREDOPERATON_EnterMEP }
enum	SWI_TYPE_SIM_PreviousOperation {   SWI_PREVIOUSOPERATION_None, SWI_PREVIOUSOPERATION_ChangePIN, SWI_PREVIOUSOPERATION_ChangePIN2, SWI_PREVIOUSOPERATION_EnableDisablePINVerification,   SWI_PREVIOUSOPERATION_VerifyPIN, SWI_PREVIOUSOPERATION_VerifyPIN2, SWI_PREVIOUSOPERATION_VerifyPUK, SWI_PREVIOUSOPERATION_VerifyPUK2,   SWI_PREVIOUSOPERATION_MEPUnlock, SWI_PREVIOUSOPERATION_EnablePIN, SWI_PREVIOUSOPERATION_DisablePIN }
enum	SWI_TYPE_SIM_PreviousActionResult { SWI_PREVIOUSACTIONRESULT_Succeeded, SWI_PREVIOUSACTIONRESULT_Failed, SWI_PREVIOUSACTIONRESULT_PINVerifyDisabled, SWI_PREVIOUSACTIONRESULT_PINStartsEmergency }
enum	SWI_TYPE_SIM_RetryInformation { SWI_TYPE_RETRYINFORMATION_Pin, SWI_TYPE_RETRYINFORMATION_Pin2, SWI_TYPE_RETRYINFORMATION_Puk, SWI_TYPE_RETRYINFORMATION_Puk2 }
enum	SWI_TYPE_SIM_Chv2KickType { SWI_TYPE_CHV2KICKTYPE_Verify, SWI_TYPE_CHV2KICKTYPE_Change }

Functions
SWI_API SWI_RCODE	SwiSetSimVerify (const struct SWI_STRUCT_SIM_Verify *pSim, swi_uint32 timeout)
SWI_API SWI_RCODE	SwiSetSimLock (const struct SWI_STRUCT_SIM_EnableLock *pSim, swi_uint32 timeout)
SWI_API SWI_RCODE	SwiGetSimLock (struct SWI_STRUCT_SIM_LockStatus *pSim, swi_uint32 timeout)
SWI_API SWI_RCODE	SwiSetSimPassword (const struct SWI_STRUCT_SIM_Password *pSim, swi_uint32 timeout)
SWI_API SWI_RCODE	SwiChv2StatusKick (enum SWI_TYPE_SIM_Chv2KickType eKickType, swi_uint32 timeout)
SWI_API SWI_RCODE	SwiSetMEPUnlock (const struct SWI_STRUCT_MEP_Unlock *pMEP, swi_uint32 timeout)
SWI_API SWI_RCODE	SwiGetGsmIMSI (swi_charp szMSIN, swi_uint32 sizeBuffer, swi_uint32 *pMCC, swi_uint32 *pMNC, swi_uint32 timeout)
SWI_API SWI_RCODE	SwiGetIccId (struct SWI_STRUCT_IccId *sIccId, swi_uint32 timeout)
SWI_API SWI_RCODE	SwiGetNetworkProviderID (swi_charp szName, swi_uint32 sizeBuffer, swi_uint32 timeout)
SWI_API SWI_RCODE	SwiSetSimAuthentication (struct SWI_STRUCT_SimAuth *pSimAuth, swi_uint32 timeout)

Detailed Description

This file contains definitions, enumerations, structures and forward declarations for SwiApiGsmSim.c file.

Copyright (c) 2011 Sierra Wireless, Inc. All rights reserved

Macro Definition Documentation

#define LENGTH_IccId   10

#define LENGTH_Kc   8

#define LENGTH_MaxCHV   9

#define LENGTH_MEPCode   13

#define LENGTH_RandNum   16

Enumeration Type Documentation

enum SWI_TYPE_SIM_Chv2KickType

An enumeration of PIN2 kick types.

See Also

SwiChv2StatusKick

Enumerator
SWI_TYPE_CHV2KICKTYPE_Verify	Verifying PIN2.
SWI_TYPE_CHV2KICKTYPE_Change	Changing PIN2.

enum SWI_TYPE_SIM_Password

An enumeration of SIM password types.

See Also

SWI_STRUCT_SIM_Verify

SWI_STRUCT_SIM_Password

Enumerator
SWI_SIMPASSWORD_Reserved	Unused password enumeration.
SWI_SIMPASSWORD_CHV1	CHV1 (Card Holder Verification 1) is commonly referred to as PIN1. This code cannot match or begin with an emergency number.
SWI_SIMPASSWORD_CHV2	CHV2 (Card Holder Verification 2) is commonly referred to as PIN2.
SWI_SIMPASSWORD_UnblockingCHV1	The unblocking code for CHV1 is commonly referred to as PUK1.
SWI_SIMPASSWORD_UnblockingCHV2	The unblocking code for CHV2 is commonly referred to as PUK2.

enum SWI_TYPE_SIM_PreviousActionResult

An enumeration of SIM previous operation results.

See Also

SWI_STRUCT_SIM_StatusExp

Enumerator
SWI_PREVIOUSACTIONRESULT_Succeeded	Operation succeeded.
SWI_PREVIOUSACTIONRESULT_Failed	Operation failed.
SWI_PREVIOUSACTIONRESULT_PINVerifyDisabled	Operation failed because PIN1 is not enabled.
SWI_PREVIOUSACTIONRESULT_PINStartsEmergency	Operation failed because the new PIN1 starts with an emergency number.

enum SWI_TYPE_SIM_PreviousOperation

An enumeration of previous SIM operations.

See Also

SWI_STRUCT_SIM_StatusExp

Enumerator
SWI_PREVIOUSOPERATION_None	No previous operation.
SWI_PREVIOUSOPERATION_ChangePIN	Change PIN1 operation.
SWI_PREVIOUSOPERATION_ChangePIN2	Change PIN2 operation.
SWI_PREVIOUSOPERATION_EnableDisablePINVerification	Enable/disable PIN1 verification
SWI_PREVIOUSOPERATION_VerifyPIN	Verify PIN1 operation.
SWI_PREVIOUSOPERATION_VerifyPIN2	Verify PIN2 operation.
SWI_PREVIOUSOPERATION_VerifyPUK	Verify PIN1 unblocking code.
SWI_PREVIOUSOPERATION_VerifyPUK2	Verify PIN2 unblocking code.
SWI_PREVIOUSOPERATION_MEPUnlock	Verify MEP unlocking code.
SWI_PREVIOUSOPERATION_EnablePIN	Enable PIN1.
SWI_PREVIOUSOPERATION_DisablePIN	Disable PIN1.

enum SWI_TYPE_SIM_RequiredOperation

An enumeration of required SIM operations.

See Also

SWI_STRUCT_SIM_StatusExp

Enumerator
SWI_REQUIREDOPERATON_NoOperation	No operation required.
SWI_REQUIREDOPERATON_EnterPIN	Enter PIN1.
SWI_REQUIREDOPERATON_EnterPIN2	Enter PIN2.
SWI_REQUIREDOPERATON_EnterPUK	Enter PIN1 unblocking code.
SWI_REQUIREDOPERATON_EnterPUK2	Enter PIN2 unblocking code.
SWI_REQUIREDOPERATON_EnterMEP	Enter MEP unlocking code.

enum SWI_TYPE_SIM_RetryInformation

An enumeration of SIM code retry information types.

See Also

SWI_STRUCT_SIM_StatusExp

Enumerator
SWI_TYPE_RETRYINFORMATION_Pin	PIN1 retry count.
SWI_TYPE_RETRYINFORMATION_Pin2	PIN2 retry count.
SWI_TYPE_RETRYINFORMATION_Puk	PIN1 unblocking code retry count.
SWI_TYPE_RETRYINFORMATION_Puk2	PIN2 unblocking code retry count.

enum SWI_TYPE_SIM_StatusExp

An enumeration of SIM status codes.

See Also

SWI_STRUCT_SIM_StatusExp

Enumerator
SWI_SIMSTATUSEXP_OK	Success.
SWI_SIMSTATUSEXP_NotInserted	SIM is not inserted.
SWI_SIMSTATUSEXP_Removed	SIM has been removed.
SWI_SIMSTATUSEXP_InitializeFailure	SIM has failed to initialize
SWI_SIMSTATUSEXP_GeneralFailure	General SIM failure.
SWI_SIMSTATUSEXP_Locked	SIM is locked.
SWI_SIMSTATUSEXP_PIN1Blocked	PIN1 is blocked.
SWI_SIMSTATUSEXP_PIN2Blocked	PIN2 is blocked.
SWI_SIMSTATUSEXP_PIN1Rejected	PIN1 is rejected.
SWI_SIMSTATUSEXP_PIN2Rejected	PIN2 is rejected.
SWI_SIMSTATUSEXP_MEPLocked	MEP check failed.
SWI_SIMSTATUSEXP_NetworkReject	SIM is rejected by the network.

Function Documentation

SWI_API SWI_RCODE SwiChv2StatusKick	(	enum SWI_TYPE_SIM_Chv2KickType	eKickType,
		swi_uint32	timeout
	)

This function is used to get CHV2 status from the modem.

SIM API functions can not be called until a SWI_NOTIFY_SimsStatusExp notification is received. This indicates that the SIM is ready to process user requests.

The kick type determines if the user is prompted to enter the CHV2. For example, if the card is kicked for CHV2 verify, then SWI_NOTIFY_SimsStatusExp will contain a user prompt to enter CHV2. If the card is kicked for CHV2 change, SWI_NOTIFY_SimsStatusExp will not contain user prompts.

Parameters

eKickType,:	[IN] CHV2 kick type
timeout,:	[IN] Response timeout value in milliseconds

Returns

SWI_RCODE_OK: The request has been processed. The SWI_NOTIFY_SimStatusExp notification indicates the result of the operation and any additional actions required by the user.

See Also

See SWI_RCODE for other error return codes.

SWI_TYPE_SIM_Chv2KickType

SWI_NOTIFY_SimStatusExp

SWI_API SWI_RCODE SwiGetGsmIMSI	(	swi_charp	szMSIN,
		swi_uint32	sizeBuffer,
		swi_uint32 *	pMCC,
		swi_uint32 *	pMNC,
		swi_uint32	timeout
	)

This function is used to retrieve the IMSI from the SIM.

The IMSI is comprised of three elements: the MSIN, the MCC and the MNC.

Parameters

szMSIN,:	[OUT] MSIN (NULL terminated)
sizeBuffer,:	[IN] The size of the buffer provided for the MSIN.
pMCC,:	[OUT] Mobile country code
pMNC,:	[OUT] Mobile network code
timeout,:	[IN] Response timeout value in milliseconds.

Returns

SWI_RCODE_OK: The request has been processed and values returned are valid.

See Also

See SWI_RCODE for other error return codes.

SWI_API SWI_RCODE SwiGetIccId	(	struct SWI_STRUCT_IccId *	sIccId,
		swi_uint32	timeout
	)

This function is used to retrieve the ICC ID of the SIM.

This function should not be called until the SWI_NOTIFY_SimStatusExp has been received indicating the SIM is ready.

Parameters

sIddId,:	[OUT] ICC ID
timeout,:	[IN] Response timeout value in milliseconds

Returns

SWI_RCODE_OK: The request has been processed and values returned are valid.

See Also

See SWI_RCODE for other error return codes.

SWI_STRUCT_IccId

SWI_NOTIFY_SimStatusExp

SWI_API SWI_RCODE SwiGetNetworkProviderID	(	swi_charp	szName,
		swi_uint32	sizeBuffer,
		swi_uint32	timeout
	)

This function reports the current service provider's identification code.

The provider ID for GSM is a string provided by the carrier on the SIM.

Parameters

szName,:	[OUT] Network provider name (NULL terminated)
sizeBuffer,:	[IN] Size of buffer provided for the network provider name
timeout,:	[IN] Response timeout value in milliseconds

See Also

See SWI_RCODE for additional information.

SWI_API SWI_RCODE SwiGetSimLock	(	struct SWI_STRUCT_SIM_LockStatus *	pSim,
		swi_uint32	timeout
	)

This function is used to determine whether CHV1 is enabled.

SIM API functions can not be called until a SWI_NOTIFY_SimsStatusExp notification is received. This indicates that the SIM is ready to process user requests.

Parameters

pSim,:	[OUT] SIM CHV1 lock status
timeout,:	[IN] Response timeout value in milliseconds

Returns

SWI_RCODE_OK: The request has been processed and values returned are valid.

See Also

See SWI_RCODE for other error return codes.

SWI_STRUCT_SIM_LockStatus

SWI_NOTIFY_SimsStatusExp

SWI_API SWI_RCODE SwiSetMEPUnlock	(	const struct SWI_STRUCT_MEP_Unlock *	pMEP,
		swi_uint32	timeout
	)

This function is used to enter the MEP code and disable the mechanism that restricts which SIMs can be used with the modem.

SIM API functions can not be called until a SWI_NOTIFY_SimsStatusExp notification is received. This indicates that the SIM is ready to process user requests.

Once this function is called do not call it again until the result from the current request has been received in the next SWI_NOTIFY_SimStatusExp notification.

The first time that this function is called, there is a 30 second delay before the SWI_NOTIFY_SimStatusExp notification responds. This delay is doubled with each attempt. (That is, the second time the function is called, there is a one minute delay. The third time it is called, there is a two minute delay.) The delay is intended to discourage users from trying new codes until the SIM becomes blocked.

Parameters

pMEP,:	[IN] MEP unlocking code
timeout,:	[IN] Response timeout value in milliseconds

Returns

SWI_RCODE_OK: The request has been processed. The SWI_NOTIFY_SimStatusExp notification indicates the result of the operation.

See Also

SWI_RCODE for other error return codes.

SWI_STRUCT_MEP_Unlock

SWI_NOTIFY_SimStatusExp

SWI_API SWI_RCODE SwiSetSimAuthentication	(	struct SWI_STRUCT_SimAuth *	pSimAuth,
		swi_uint32	timeout
	)

This function is used to send a sixteen byte random number to the SIM. The SIM will run its algorithm on the provided random number and it will output a thirty two bit SIM response and eight byte ciphering key.

SIM API functions can not be called until a SWI_NOTIFY_SimsStatusExp notification is received. This indicates that the SIM is ready to process user requests.

Parameters

pSimAuth,:	[IN/OUT] SIM authentication information. The size of the structure and random number must be provided by the caller. The response will contain the 32-bit SIM response and ciphering key.
timeout,:	[IN] Response timeout value in milliseconds

Returns

SWI_RCODE_OK: The request has been processed and values returned are valid.

See Also

See SWI_RCODE for other error return codes.

SWI_STRUCT_SimAuth

SWI_NOTIFY_SimsStatusExp

SWI_API SWI_RCODE SwiSetSimLock	(	const struct SWI_STRUCT_SIM_EnableLock *	pSim,
		swi_uint32	timeout
	)

This function is used to enable or disable CHV1.

SIM API functions can not be called until a SWI_NOTIFY_SimsStatusExp notification is received. This indicates that the SIM is ready to process user requests.

Parameters

pSim,:	[IN] SIM CHV1 lock information. The caller must provide the password required to enable/disable CHV1.
timeout,:	[IN] Response timeout value in milliseconds

Returns

SWI_RCODE_OK: The request has been processed. The SWI_NOTIFY_SimStatusExp notification indicates the result of the operation.

See Also

See SWI_RCODE for other error return codes.

SWI_STRUCT_SIM_EnableLock

SWI_NOTIFY_SimStatusExp

SWI_API SWI_RCODE SwiSetSimPassword	(	const struct SWI_STRUCT_SIM_Password *	pSim,
		swi_uint32	timeout
	)

This function is used to change CHV1 or CHV2 codes.

SIM API functions can not be called until a SWI_NOTIFY_SimsStatusExp notification is received. This indicates that the SIM is ready to process user requests.

The CHV1 code can only be changed when enabled (using SwiSetSimLock). Emergency numbers cannot be used as CHV1 codes, or as the beginning of CHV1 codes. PUK1 and PUK2 are not valid parameters, although the data structure includes them.

Parameters

pSim,:	[IN] SIM password information
timeout,:	[IN] Response timeout value in milliseconds

Returns

SWI_RCODE_OK: The request has been processed. The SWI_NOTIFY_SimStatusExp notification indicates the result of the operation.

See Also

See SWI_RCODE for other error return codes.

SWI_STRUCT_SIM_Password

SWI_NOTIFY_SimStatusExp

SWI_API SWI_RCODE SwiSetSimVerify	(	const struct SWI_STRUCT_SIM_Verify *	pSim,
		swi_uint32	timeout
	)

This function is used to enter a SIM requested code.

SIM API functions can not be called until a SWI_NOTIFY_SimsStatusExp notification is received. This indicates that the SIM is ready to process user requests.

The SIM can request the user to enter any one of the following four codes: CHV1, CHV2, unblocking CHV1 and unblocking CHV2. The SIM uses this to verify the identify of the user. This function allows the caller to pass the user entered code to the SIM on the modem. A request containing the code is sent to the modem. The modem will respond to the request to indicate that the code is being verified by the SIM. The result of the SIM verification will be reflected in the SWI_NOTIFY_SimStatusExp notification.

If three failures in entering a correct CHV1 or CHV2 occur, this notification shows that the SIM has become blocked (CHV1) or the CHV2 features have become blocked.

GSM standards designate 10 as the number of permitted attempts at correctly entering PUK codes. This number is SIM dependent and carriers do not necessarily adhere to this standard. If 10 failures in entering the PUK occur, this notification shows the SIM has become permanently blocked or the CHV2 features have become permanently blocked.

Parameters

pSim,:	[IN] SIM requested code.
timeout,:	[IN] Response timeout value in milliseconds

Returns

SWI_RCODE_OK: The request has been processed. The SWI_NOTIFY_SimStatusExp notification indicates whether the designated code matched. It also shows the number of attempts at entering the code correctly.

See Also

See SWI_RCODE for other error return codes.

SWI_STRUCT_SIM_Verify

SWI_NOTIFY_SimStatusExp