/*===========================================================================
FILE: 
   GobiUimMgmtAPI.h

DESCRIPTION:
   Sierra Wireless UIM APIs

Copyright (C) 2014 Sierra Wireless Incorporated. All rights reserved.
                   Sierra Wireless Proprietary/GTDR
==========================================================================*/

#ifndef GobiUimMgmtAPI_H
#define GobiUimMgmtAPI_H
/*=========================================================================*/
// Definitions
/*=========================================================================*/
#ifdef GOBIAPI_EXPORTS
	#define IMPORTGOBI extern "C" __declspec( dllexport )   
#else  //GOBIAPI_EXPORTS
	#ifdef __cplusplus
		/* C++ callable DLL */
		#define IMPORTGOBI extern "C" __declspec( dllimport )   
	#else
		/* C callable DLL */
		#define IMPORTGOBI __declspec( dllimport )
	#endif
#endif //GOBIAPI_EXPORTS

// Calling convention for API
#define GOBICALLBACK __stdcall
#define GOBICMAPI __stdcall

#ifdef __cplusplus
   extern "C" {
#endif

/** 
* \defgroup GroupUim User Identity Module Service
*/
/*@{*/

/*=========================================================================*/
// Structs
/*=========================================================================*/
//QMI_UIM_GET_CARD_STATUS_RESP
typedef struct 
{
	BYTE app_type;	//• 0 – Unknown
					//• 1 – SIM card
					//• 2 – USIM application
					//• 3 – RUIM card
					//• 4 – CSIM application
					//• 5 – ISIM application
					//Other values are reserved for the future
					//and are to be handled as “Unknown”.
	BYTE app_state;	//• 0 – Unknown
					//• 1 – Detected
					//• 2 – PIN1 or UPIN is required
					//• 3 – PUK1 or PUK for UPIN is required
					//• 4 – Personalization state must be checked
					//• 5 – PIN1 is blocked
					//• 6 – Illegal
					//• 7 – Ready
	BYTE perso_state;//• 0 – Unknown
					//• 1 – Personalization operation is in progress
					//• 2 – Ready
					//• 3 – Personalization code is required
					//• 4 – PUK for personalization code is required
					//• 5 – Permanently blocked
	BYTE perso_feature; //• 0 – GW network personalization
						//• 1 – GW network subset personalization
						//• 2 – GW service provider
						//personalization
						//• 3 – GW corporate personalization
						//• 4 – GW UIM personalization
						//• 5 – 1X network type 1 personalization
						//• 6 – 1X network type 2 personalization
						//• 7 – 1X HRPD personalization
						//• 8 – 1X service provider personalization
						//• 9 – 1X corporate personalization
						//• 10 – 1X RUIM personalization
						//• 11 – Unknown
	BYTE perso_retries;
	BYTE perso_unblock_retries;
	BYTE aid_len;
	CHAR aid_value[255];
	BYTE univ_pin;	//• 0 – PIN1 is used
					//• 1 – UPIN replaces PIN1
	BYTE pin1_state;//• 0 – Unknown
					//• 1 – Enabled and not verified
					//• 2 – Enabled and verified
					//• 3 – Disabled
					//• 4 – Blocked
					//• 5 – Permanently blocked
	BYTE pin1_retries;
	BYTE puk1_retries;
	BYTE pin2_state;//• 0 – Unknown
					//• 1 – Enabled and not verified
					//• 2 – Enabled and verified
					//• 3 – Disabled
					//• 4 – Blocked
					//• 5 – Permanently blocked
	BYTE pin2_retries;
	BYTE puk2_retries;
	//not supported
	//BYTE extended_hot_swap_len;
	//BYTE *extended_hot_swap;
	

	
}QMI_UIM_GET_CARD_STATUS_RESP_APPL; 

#define QMI_UIM_GET_CARD_STATUS_MAX_APPL 4
typedef struct
{
	BYTE card_state;
	BYTE upin_state;//0:unknown
					//1:enabled and not verified
					//2:enabled and verified
					//3:disabled
					//4:blocked
					//5:permanently blocked
	BYTE upin_retries;
	BYTE upuk_retries;
	BYTE error_code;//• 0 - Unknown
					//• 1 - Power down
					//• 2 - Poll error
					//• 3 - No ATR received
					//• 4 - Volt mismatch
					//• 5 - Parity error
					//• 6 - Unknown; possibly removed
					//• 7 - Card returned technical problems
					//Other values are possible and reserved
					//for future use. When an unknown value
					//is received, it is to be handled as
					//“Unknown”.
	BYTE num_app;
	QMI_UIM_GET_CARD_STATUS_RESP_APPL appls[QMI_UIM_GET_CARD_STATUS_MAX_APPL];
}QMI_UIM_GET_CARD_STATUS_RESP_SLOT;

#define QMI_UIM_GET_CARD_STATUS_MAX_SLOT 2
typedef struct {
	WORD		index_gw_pri;
	WORD		index_1x_pri;
	WORD		index_gw_sec;
	WORD		index_1x_sec;
	BYTE		num_slot;
	QMI_UIM_GET_CARD_STATUS_RESP_SLOT slots[QMI_UIM_GET_CARD_STATUS_MAX_SLOT];	
}QMI_UIM_GET_CARD_STATUS_RESP;

//QMI_UIM_STATUS_CHANGE_IND
#define QMI_UIM_CARD_STATUS QMI_UIM_GET_CARD_STATUS_RESP
#define QMI_UIM_STATUS_CHANGE_IND_RESP QMI_UIM_CARD_STATUS

//QMI_UIM_VERIFY_PIN_REQ
typedef struct
{
	BYTE		session_type;	//Primary GW provisioning 0 Accesses the GSM DF (for ICC) or USIM application
								//(for UICC) used to acquire a GSM, a WCDMA or an
								//LTE network.
								//Primary 1X provisioning 1 Accesses the CDMA DF (for ICC) or CSIM application
								//(for UICC) used to acquire a 1X/DO network.
								//Secondary GW provisioning 2 Accesses the GSM DF (for ICC) or USIM application
								//(for UICC) used to acquire a GSM, a WCDMA or an
								//LTE network (Dual Standby).
								//Secondary 1X provisioning 3 Accesses the CDMA DF (for ICC) or CSIM application
								//(for UICC) used to acquire 1X/DO network (Dual
								//Standby).
	BYTE		aid_len;
	BYTE		aid[255]; 
}QMI_UIM_VERIFY_PIN_REQ_SESSION_INFORMATION;
typedef struct
{
	BYTE		pin_id;	//• 1 - PIN1 (also called PIN)
						//• 2 - PIN2
						//• 3 - Universal PIN
						//• 4 - Hidden key 
	BYTE		pin_len;
	char		pin_value[255];//ASCII
}QMI_UIM_VERIFY_PIN_REQ_VERIFY_PIN;
	
typedef struct 
{
	BYTE		verify_left;
	BYTE		unblock_left;
}QMI_UIM_VERIFY_PIN_RESP_RETRIES_REMAINING;

	
typedef struct
{
	BYTE		session_type;	//Primary GW provisioning 0 Accesses the GSM DF (for ICC) or USIM application
								//(for UICC) used to acquire a GSM, a WCDMA or an
								//LTE network.
								//Primary 1X provisioning 1 Accesses the CDMA DF (for ICC) or CSIM application
								//(for UICC) used to acquire a 1X/DO network.
								//Secondary GW provisioning 2 Accesses the GSM DF (for ICC) or USIM application
								//(for UICC) used to acquire a GSM, a WCDMA or an
								//LTE network (Dual Standby).
								//Secondary 1X provisioning 3 Accesses the CDMA DF (for ICC) or CSIM application
								//(for UICC) used to acquire 1X/DO network (Dual
								//Standby).
	BYTE		aid_len;
	BYTE		aid[255]; 
}QMI_UIM_UNBLOCK_PIN_REQ_SESSION_INFORMATION;

typedef struct
{
	BYTE		pin_id;	//• 1 - PIN1 (also called PIN)
						//• 2 - PIN2
						//• 3 - Universal PIN
	BYTE		puk_len;
	char		puk_value[255];//ascii
	BYTE		new_pin_len;
	char		new_pin_value[255];
}QMI_UIM_UNBLOCK_PIN_REQ_UNBLOCK_PIN;

typedef struct
{
	BYTE		verify_left;
	BYTE		unblock_left;
}QMI_UIM_UNBLOCK_PIN_RESP_RETRIES_REMAINING;

typedef struct
{
	BYTE		session_type;	//Primary GW provisioning 0 Accesses the GSM DF (for ICC) or USIM application
								//(for UICC) used to acquire a GSM, a WCDMA or an
								//LTE network.
								//Primary 1X provisioning 1 Accesses the CDMA DF (for ICC) or CSIM application
								//(for UICC) used to acquire a 1X/DO network.
								//Secondary GW provisioning 2 Accesses the GSM DF (for ICC) or USIM application
								//(for UICC) used to acquire a GSM, a WCDMA or an
								//LTE network (Dual Standby).
								//Secondary 1X provisioning 3 Accesses the CDMA DF (for ICC) or CSIM application
								//(for UICC) used to acquire 1X/DO network (Dual
								//Standby).
	BYTE		aid_len;
	BYTE		aid[255]; 
}QMI_UIM_SET_PIN_PROTECTION_REQ_SESSION_INFORMATION;

typedef struct
{
		BYTE pin_id;	//• 1 - PIN1 (also called PIN)
						//• 2 - PIN2
						//• 3 - Universal PIN
						//• 4 - Hidden key
		BYTE pin_operation;//• 0 - disable the pin
						   //• 1 - enable the pin
		BYTE pin_len;
		char pin_value[255];
}QMI_UIM_SET_PIN_PROTECTION_REQ_SET_PIN_PROTECTION;

typedef struct
{
		BYTE		verify_left;
		BYTE		unblock_left;
}QMI_UIM_SET_PIN_PROTECTION_RESP_RETRIES_REMAINING;
	
	

typedef struct
{
	BYTE		session_type;	//Primary GW provisioning 0 Accesses the GSM DF (for ICC) or USIM application
								//(for UICC) used to acquire a GSM, a WCDMA or an
								//LTE network.
								//Primary 1X provisioning 1 Accesses the CDMA DF (for ICC) or CSIM application
								//(for UICC) used to acquire a 1X/DO network.
								//Secondary GW provisioning 2 Accesses the GSM DF (for ICC) or USIM application
								//(for UICC) used to acquire a GSM, a WCDMA or an
								//LTE network (Dual Standby).
								//Secondary 1X provisioning 3 Accesses the CDMA DF (for ICC) or CSIM application
								//(for UICC) used to acquire 1X/DO network (Dual
								//Standby).
	BYTE		aid_len;
	BYTE		aid[255]; 
}QMI_UIM_CHANGE_PIN_REQ_SESSION_INFORMATION;

typedef struct
{
	BYTE		pin_id;	//• 1 - PIN1 (also called PIN)
						//• 2 - PIN2
						//• 3 - Universal PIN
						//• 4 - Hidden key
	BYTE		old_pin_len;
	char		old_pin_value[255]; 
	BYTE		new_pin_len;
	char		new_pin_value[255]; 
}QMI_UIM_CHANGE_PIN_REQ_CHANGE_PIN;

typedef struct
{
		BYTE		verify_left;
		BYTE		unblock_left;
}QMI_UIM_CHANGE_PIN_RESP_RETRIES_REMAINING;

/*=========================================================================*/
// Callbacks
/*=========================================================================*/
typedef void (GOBICALLBACK * tFNUIMStatusChangeIndCallback)(
	//parameters
	QMI_UIM_CARD_STATUS* pCardStatus);


#ifdef __cplusplus
   };
#endif

/*=========================================================================*/
// Prototypes
/*=========================================================================*/
//////////////////////////////////////////////////////////////////////////////
///
/// This function enables or disables the protection of the UIM contents by a specific PIN. Service ID 0x0B, Message ID 0x0025.
///
/// \param	pSessionInformation
///			[I/O]	Session Information
///
/// \param  pSetPINProtection
///			[I/O]	Contains the information to set the protection of the UIM, including PIN type, enable/disable  and the PIN value
///
/// \param  pRetriesRemaining
///			[I/O]	Contains the number of retries left
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI UIMSetPINProtection(
	QMI_UIM_SET_PIN_PROTECTION_REQ_SESSION_INFORMATION *pSessionInformation,
	QMI_UIM_SET_PIN_PROTECTION_REQ_SET_PIN_PROTECTION* pSetPINProtection,
	QMI_UIM_SET_PIN_PROTECTION_RESP_RETRIES_REMAINING * pRetriesRemaining
	);


//////////////////////////////////////////////////////////////////////////////
///
/// This function verifies the PIN before the card content is accessed. Service ID 0x0B, Message ID 0x0026.
///
/// \param	pSessionInformation
///			[I/O]	Session Information
///
/// \param  pVerifyPIN
///			[I/O]	Contains the information to verify the PIN, including PIN type, PIN value.
///
/// \param  pRetriesRemaining
///			[I/O]	Contains the number of retries left
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI UIMVerifyPIN(
	QMI_UIM_VERIFY_PIN_REQ_SESSION_INFORMATION *pSessionInformation,
	QMI_UIM_VERIFY_PIN_REQ_VERIFY_PIN* pVerifyPIN,
	QMI_UIM_VERIFY_PIN_RESP_RETRIES_REMAINING * pRetriesRemaining
	);


//////////////////////////////////////////////////////////////////////////////
///
/// This function unblocks a blocked PIN using the PUK code. Service ID 0x0B, Message ID 0x0027.
///
/// \param	pSessionInformation
///			[I/O]	Session Information
///
/// \param  pUnblockPIN
///			[I/O]	Contains the information to unblock the PIN, including PIN type, PUK value and new PIN value.
///
/// \param  pRetriesRemaining
///			[I/O]	Contains the number of retries left
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI UIMUnblockPIN(
	QMI_UIM_UNBLOCK_PIN_REQ_SESSION_INFORMATION *pSessionInformation,
	QMI_UIM_UNBLOCK_PIN_REQ_UNBLOCK_PIN* pUnblockPIN,
	QMI_UIM_UNBLOCK_PIN_RESP_RETRIES_REMAINING * pRetriesRemaining
	);


//////////////////////////////////////////////////////////////////////////////
///
/// This function changes the value of the specified PIN. Service ID 0x0B, Message ID 0x0028.
///
/// \param	pSessionInformation
///			[I/O]	Session Information
///
/// \param  pChangePIN
///			[I/O]	Contains the information to change the value of the PIN, including the PIN type, old value and new value.
///
/// \param  pRetriesRemaining
///			[I/O]	Contains the number of retries left
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI UIMChangePIN(
	QMI_UIM_CHANGE_PIN_REQ_SESSION_INFORMATION *pSessionInformation,
	QMI_UIM_CHANGE_PIN_REQ_CHANGE_PIN* pChangePIN,
	QMI_UIM_CHANGE_PIN_RESP_RETRIES_REMAINING * pRetriesRemaining
	);


//////////////////////////////////////////////////////////////////////////////
///
/// This function retrieves the current status of the card. Service ID 0x0B, Message ID 0x002F.
///
/// \param	pExtendedCardStatus
///			[I]	Indicates whether the extended card status is requested.
///			Valid values:
///			\li 0 – Legacy card status (up to 2 cards)
///			\li 1 – Extended card status
///
/// \param  pCardStatus
///			[O]	UIM card status information
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI UIMGetCardStatus(
	BOOL *pExtendedCardStatus,
	QMI_UIM_GET_CARD_STATUS_RESP* pCardStatus
	);


//////////////////////////////////////////////////////////////////////////////
///
/// This function enables/disables the UIM status change callback function. Service ID 0x0B, Message ID 0x0032.
///
/// \param	pCallback
///			[I]	Callback function pointer.
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI SetUIMStatusChangeCallback( 
	tFNUIMStatusChangeIndCallback pCallback );



/*@}*/ // End of UIM group

#endif //GobiUimMgmtAPI_H
