/*===========================================================================
FILE: 
   GobiPbMgmtAPI.h

DESCRIPTION:
   Gobi Phonebook Management APIs

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

#ifndef GobiPbMgmtAPI_H
#define GobiPbMgmtAPI_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 GroupPbm Phonebook Management Service
*/
/*@{*/

/*=========================================================================*/
// Structs
/*=========================================================================*/
#define MAX_PB_NO_LEN				81
#define MAX_NO_OF_PB				10
#define MAX_PB_DESCRIPTION_LENGTH	255

typedef struct
{
 	WORD recordID;
    BYTE numType;
    BYTE numPlan;
    BYTE numLen;
	BYTE number[MAX_PB_DESCRIPTION_LENGTH];
	BYTE nameLen;
	BYTE name[MAX_PB_DESCRIPTION_LENGTH];	
} phonebookEntry;

//emergencyNumberEntry
typedef struct
{
	BYTE emergencyNumberType;
	BYTE sessionTypeValid;
	BYTE sessionType;
	BYTE categoryValid;
	BYTE category;
	BYTE numLen;
	BYTE number[MAX_PB_NO_LEN];
} emergencyNumberEntry;

/**
 *  This structure contains an array of PhoneBook Entry
 *
 *  \param  numInstances
 *          - Number of phonebookEntry that follow.
 *          - If zero(0) then no further information exists.
 *
 *  \param  phonebookEntry[MAX_NO_OF_PB]
 *          - Array of phonebookEntry.
 *          - See \ref phonebookEntry for more information.
 *
 */
typedef struct
{
	BYTE			numInstances;
	phonebookEntry 	phoneInfo[MAX_NO_OF_PB];
} arrPBInfo;

/*=========================================================================*/
// Callbacks
/*=========================================================================*/
// Phonebook Record Read callback function
typedef void (GOBICALLBACK * tFNPbRecordRead)(
	BYTE sessionType,
	WORD pbType,
	arrPBInfo* phoneBookEntry );

// Phonebook Ready callback function
typedef void (GOBICALLBACK * tFNAllPbInitDone)(
	BYTE noOfInstance,
	BYTE* arrSessionType,
	WORD* arrPbBitMask);

//Phonebook Emergency List callback function
typedef void (GOBICALLBACK * tFNEmergencyList)(
	BYTE noOfInstance,
	emergencyNumberEntry* arrEmergencyNumberEntry);

#ifdef __cplusplus
	};
#endif

/*=========================================================================*/
// Prototypes
/*=========================================================================*/
//////////////////////////////////////////////////////////////////////////////
///
/// This function retrieves the capabilities of the Phonebook requested. Service ID 0x0C, Message ID 0x0002.
///
/// \param	pSessionType
///			[I]	Session Type of the requested Phonebook
///			Valid values:
///			\li 0 – GSM/WCDMA (GW) primary
///				Used to access the phonebooks under GSM DF (for ICC) or USIM application (for UICC), which are used to acquire a GSM or WCDMA network, respectively.
///			\li 1 – 1X primary
///				Used to access the phonebooks under CDMA DF (for ICC) or CSIM application (for UICC), which are used to acquire a 1x/DO network.
///			\li 2 – GW secondary
///				Used to access the phonebooks under GSM DF (for ICC) or USIM application (for UICC), which are used to acquire a GSM or WCDMA network, respectively (Dual Standby).
///			\li 3 – 1X secondary 
///				Used to access the phonebooks under CDMA DF (for ICC) or CSIM application (for UICC), which are used to acquire a 1x/DO network (Dual Standby).
///			\li 4 – Nonprovisioning on slot 1 (not supported)
///				Used to access phonebooks under a nonprovisioning application available on the UICC card in slot 1. The nonprovisioning application can be an ISIM or a USIM that is currently not being used to acquire the network.
///			\li 5 – Nonprovisioning on slot 2 (not supported)
///				Used to access phonebooks under a nonprovisioning application available on the UICC card in slot 2. The nonprovisioning application can be an ISIM or a USIM that is currently not being used to acquire the network.
///			\li 6 – Global phonebook on slot 1
///				Used to access phonebooks that are not in any application of the card in slot 1.
///			\li 7 – Global phonebook on slot 2
///				Used to access phonebooks that are not in any application of the card in slot 2.
///
/// \param  pPbType
///			[I]	Phonebook Type of the requested Phonebook
///			Valid values:
///			\li 0x0001 – ADN (Abbreviated Dialing Number)
///			\li 0x0002 – FDN (Fixed Dialing Number)
///			\li 0x0004 – MSISDN (Mobile Subscriber Integrated Services Digital Network) 
///			\li 0x0008 – MBDN (Mail Box Dialing Number)
///			\li 0x0010 – SDN (Service Dialing Number) 
///			\li 0x0020 – BDN (Barred Dialing Number)
///			\li 0x0040 – LND (Last Number Dialed)
///			\li 0x0080 – MBN (Mail Box Number)
///
/// \param  pUsedRecords
///			[O]	Records used.
/// \param  pMaxRecords
///			[O]	Maximum possible records for this phonebook.
/// \param  pMaxNumLen
///			[O]	Maximum number length.
/// \param  pMaxNameLen
///			[O]	Maximum name length.
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI GetPhonebookCapabilities(
	BYTE*		pSessionType,
	WORD*		pPbType,
	WORD*		pUsedRecords,
	WORD*		pMaxRecords,
	BYTE*		pMaxNumLen,
	BYTE*		pMaxNameLen
	);

//////////////////////////////////////////////////////////////////////////////
///
/// This function initiates the Record Read operation by specifying the range of the records to be read. Service ID 0x0C, Message ID 0x0004.
///
/// \param	pSessionType
///			[I]	Session Type of the requested Phonebook
///			Valid values:
///			\li 0 – GSM/WCDMA (GW) primary
///				Used to access the phonebooks under GSM DF (for ICC) or USIM application (for UICC), which are used to acquire a GSM or WCDMA network, respectively.
///			\li 1 – 1X primary
///				Used to access the phonebooks under CDMA DF (for ICC) or CSIM application (for UICC), which are used to acquire a 1x/DO network.
///			\li 2 – GW secondary
///				Used to access the phonebooks under GSM DF (for ICC) or USIM application (for UICC), which are used to acquire a GSM or WCDMA network, respectively (Dual Standby).
///			\li 3 – 1X secondary 
///				Used to access the phonebooks under CDMA DF (for ICC) or CSIM application (for UICC), which are used to acquire a 1x/DO network (Dual Standby).
///			\li 4 – Nonprovisioning on slot 1 (not supported)
///				Used to access phonebooks under a nonprovisioning application available on the UICC card in slot 1. The nonprovisioning application can be an ISIM or a USIM that is currently not being used to acquire the network.
///			\li 5 – Nonprovisioning on slot 2 (not supported)
///				Used to access phonebooks under a nonprovisioning application available on the UICC card in slot 2. The nonprovisioning application can be an ISIM or a USIM that is currently not being used to acquire the network.
///			\li 6 – Global phonebook on slot 1
///				Used to access phonebooks that are not in any application of the card in slot 1.
///			\li 7 – Global phonebook on slot 2
///				Used to access phonebooks that are not in any application of the card in slot 2.
///
/// \param  pPbType
///			[I]	Phonebook Type of the requested Phonebook
///			Valid values:
///			\li 0x0001 – ADN (Abbreviated Dialing Number)
///			\li 0x0002 – FDN (Fixed Dialing Number)
///			\li 0x0004 – MSISDN (Mobile Subscriber Integrated Services Digital Network) 
///			\li 0x0008 – MBDN (Mail Box Dialing Number)
///			\li 0x0010 – SDN (Service Dialing Number) 
///			\li 0x0020 – BDN (Barred Dialing Number)
///			\li 0x0040 – LND (Last Number Dialed)
///			\li 0x0080 – MBN (Mail Box Number)
/// \param  pStartId
///			[I]	Start identifier of the record to be read.
/// \param  pEndId
///			[I]	End identifier of the record to be read.
/// \param  pNumOfRecords
///			[O]	Indicates the total number of records returned in the subsequent QMI_PBM_RECORD_READ_IND(s).
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI ReadPhonebookRecords(
	BYTE*		pSessionType,
	WORD*		pPbType,
	WORD*		pStartId,
	WORD*		pEndId,
	WORD*		pNumOfRecords
	);

//////////////////////////////////////////////////////////////////////////////
///
/// This function adds a new record or modifies an existing record. Service ID 0x0C, Message ID 0x0005.
///
/// \param	pSessionType
///			[I]	Session Type of the requested Phonebook
///			Valid values:
///			\li 0 – GSM/WCDMA (GW) primary
///				Used to access the phonebooks under GSM DF (for ICC) or USIM application (for UICC), which are used to acquire a GSM or WCDMA network, respectively.
///			\li 1 – 1X primary
///				Used to access the phonebooks under CDMA DF (for ICC) or CSIM application (for UICC), which are used to acquire a 1x/DO network.
///			\li 2 – GW secondary
///				Used to access the phonebooks under GSM DF (for ICC) or USIM application (for UICC), which are used to acquire a GSM or WCDMA network, respectively (Dual Standby).
///			\li 3 – 1X secondary 
///				Used to access the phonebooks under CDMA DF (for ICC) or CSIM application (for UICC), which are used to acquire a 1x/DO network (Dual Standby).
///			\li 4 – Nonprovisioning on slot 1 (not supported)
///				Used to access phonebooks under a nonprovisioning application available on the UICC card in slot 1. The nonprovisioning application can be an ISIM or a USIM that is currently not being used to acquire the network.
///			\li 5 – Nonprovisioning on slot 2 (not supported)
///				Used to access phonebooks under a nonprovisioning application available on the UICC card in slot 2. The nonprovisioning application can be an ISIM or a USIM that is currently not being used to acquire the network.
///			\li 6 – Global phonebook on slot 1
///				Used to access phonebooks that are not in any application of the card in slot 1.
///			\li 7 – Global phonebook on slot 2
///				Used to access phonebooks that are not in any application of the card in slot 2.
///
/// \param  pPbType
///			[I]	Phonebook Type of the requested Phonebook
///			Valid values:
///			\li 0x0001 – ADN (Abbreviated Dialing Number)
///			\li 0x0002 – FDN (Fixed Dialing Number)
///			\li 0x0004 – MSISDN (Mobile Subscriber Integrated Services Digital Network) 
///			\li 0x0008 – MBDN (Mail Box Dialing Number)
///			\li 0x0010 – SDN (Service Dialing Number) 
///			\li 0x0020 – BDN (Barred Dialing Number)
///			\li 0x0040 – LND (Last Number Dialed)
///			\li 0x0080 – MBN (Mail Box Number)
///
/// \param  pRecordId
///			[I]	Record identifier.
///
/// \param  pNumType
///			[I]	Type of number as per 3GPP TS 24.008 V7.13.0 (2008-09)
///			\li 0x00 – NUM_TYPE_UNKNOWN
///			\li 0x01 – NUM_TYPE_INTERNATIONAL
///			\li 0x02 – NUM_TYPE_NATIONAL
///			\li 0x03 – NUM_TYPE_NETWORK_SPECIFIC
///			\li 0x04 – NUM_TYPE_DEDICATED_ACCESS
///
/// \param  pNumPlan
///			[I]	Number plan
///			\li 0x00 – NUM_PLAN_UNKNOWN
///			\li 0x01 – NUM_PLAN_ISDN
///			\li 0x02 – NUM_PLAN_DATA
///			\li 0x03 – NUM_PLAN_TELEX
///			\li 0x04 – NUM_PLAN_NATIONAL
///			\li 0x05 – NUM_PLAN_PRIVATE
///
/// \param  pNumLen
///			[I]	Length of the number
///
/// \param  pArrNum
///			[I]	Number in ASCII
///
/// \param  pNameLen
///			[I]	Length of name (counted in bytes)
///
/// \param  pArrName
///			[I]	Name in UCS2.
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI WritePhonebookRecord(
		BYTE*	pSessionType,
		WORD*	pPbType,
		WORD*	pRecordId,
		BYTE*	pNumType,
		BYTE*	pNumPlan,
		BYTE*	pNumLen,
		BYTE*	pArrNum,
		BYTE*	pNameLen,
		BYTE*	pArrName
	);

//////////////////////////////////////////////////////////////////////////////
///
/// This function adds a new record or modifies an existing record. Service ID 0x0C, Message ID 0x0005.
///
/// \param	pSessionType
///			[I]	Session Type of the requested Phonebook
///			Valid values:
///			\li 0 – GSM/WCDMA (GW) primary
///				Used to access the phonebooks under GSM DF (for ICC) or USIM application (for UICC), which are used to acquire a GSM or WCDMA network, respectively.
///			\li 1 – 1X primary
///				Used to access the phonebooks under CDMA DF (for ICC) or CSIM application (for UICC), which are used to acquire a 1x/DO network.
///			\li 2 – GW secondary
///				Used to access the phonebooks under GSM DF (for ICC) or USIM application (for UICC), which are used to acquire a GSM or WCDMA network, respectively (Dual Standby).
///			\li 3 – 1X secondary 
///				Used to access the phonebooks under CDMA DF (for ICC) or CSIM application (for UICC), which are used to acquire a 1x/DO network (Dual Standby).
///			\li 4 – Nonprovisioning on slot 1 (not supported)
///				Used to access phonebooks under a nonprovisioning application available on the UICC card in slot 1. The nonprovisioning application can be an ISIM or a USIM that is currently not being used to acquire the network.
///			\li 5 – Nonprovisioning on slot 2 (not supported)
///				Used to access phonebooks under a nonprovisioning application available on the UICC card in slot 2. The nonprovisioning application can be an ISIM or a USIM that is currently not being used to acquire the network.
///			\li 6 – Global phonebook on slot 1
///				Used to access phonebooks that are not in any application of the card in slot 1.
///			\li 7 – Global phonebook on slot 2
///				Used to access phonebooks that are not in any application of the card in slot 2.
///
/// \param  pPbType
///			[I]	Phonebook Type of the requested Phonebook
///			Valid values:
///			\li 0x0001 – ADN (Abbreviated Dialing Number)
///			\li 0x0002 – FDN (Fixed Dialing Number)
///			\li 0x0004 – MSISDN (Mobile Subscriber Integrated Services Digital Network) 
///			\li 0x0008 – MBDN (Mail Box Dialing Number)
///			\li 0x0010 – SDN (Service Dialing Number) 
///			\li 0x0020 – BDN (Barred Dialing Number)
///			\li 0x0040 – LND (Last Number Dialed)
///			\li 0x0080 – MBN (Mail Box Number)
///
/// \param  pRecordId
///			[I]	Record identifier.
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
	IMPORTGOBI ULONG GOBICMAPI DeletePhonebookRecord(
	BYTE*		pSessionType,
	WORD*		pPbType,
	WORD*		pRecordId
	);

//////////////////////////////////////////////////////////////////////////////
///
/// This function enables/disables the Emergency number list callback function. Service ID 0x0C, Message ID 0x000C.
///
/// \param	pCallback
///			[I]	Callback function pointer.
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI SetEmergencyListCallback(
	tFNEmergencyList pCallback);

//////////////////////////////////////////////////////////////////////////////
///
/// This function enables/disables the All Phonebook Init Done callback function. Service ID 0x0C, Message ID 0x000D. The callback will be invoked when all Phonebooks in the specified sessions (in the callback) are ready to be accessed.
///
/// \param	pCallback
///			[I]	Callback function pointer.
///
/// \return	See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI SetAllPhonebookInitDoneCallback(
	tFNAllPbInitDone pCallback);

/*@}*/ // End of PBM group

#endif //GobiPbMgmtAPI_H
