/*===========================================================================
FILE: 
   QmiWMS.h

DESCRIPTION:
   QMI Wireless Message Service APIs. Service type 0x05

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

#ifndef __QMI_WMS_API_H__
#define __QMI_WMS_API_H__
/*=========================================================================*/
// Definitions
/*=========================================================================*/

/** 
* \defgroup GroupWMS Wireless Message Service
*/
/*@{*/

/*=========================================================================*/
// Structs
/*=========================================================================*/
#ifdef __cplusplus
	extern "C" {
#endif

#ifdef __cplusplus
	};
#endif

/*=========================================================================*/
// Prototypes
/*=========================================================================*/
//////////////////////////////////////////////////////////////////////////////
///
/// This function enables/disables the new SMS callback function
///
/// \param	pCallback
///			[I]	Callback function (0 = disable)
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI SetNewSMSCallback( tFNNewSMS pCallback );

//////////////////////////////////////////////////////////////////////////////
///
/// This function deletes one or more SMS messages from device memory
///	QMI_WMS_DELETE_MSG =                              0x0024
///
/// \param	storageType
///			[I]	SMS message storage type
///			Valid values:
///			\li 0 - STORAGE_TYPE_UIM
///			\li 1 - STORAGE_TYPE_NV
/// \param  pMessageIndex
///			[I]	(Optional) message index
///
/// \param  pMessageTag
///			[I]	(Optional) message tag
///			Valid values:
///			\li 0 - TAG_TYPE_MT_READ
///			\li 1 - TAG_TYPE_MT_NOT_READ
///			\li 2 - TAG_TYPE_MO_SENT
///			\li 3 - TAG_TYPE_MO_NOT_SENT
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI DeleteSMS( 
   ULONG                      storageType, 
   ULONG *                    pMessageIndex, 
   ULONG *                    pMessageTag );

//////////////////////////////////////////////////////////////////////////////
///
/// This function returns the list of SMS messages stored on the device
///	QMI_WMS_LIST_MESSAGES_MSG =                       0x0031
///
/// \param	storageType
///			[I]	SMS message storage type
///			Valid values:
///			\li 0 - STORAGE_TYPE_UIM
///			\li 1 - STORAGE_TYPE_NV
/// \param  pRequestedTag
///			[I]	Message tag
///			Valid values:
///			\li 0 - TAG_TYPE_MT_READ
///			\li 1 - TAG_TYPE_MT_NOT_READ
///			\li 2 - TAG_TYPE_MO_SENT
///			\li 3 - TAG_TYPE_MO_NOT_SENT
///
/// \param  pMessageListSize
///			[I/O]	Upon input the maximum number of elements that the message list array can contain.  Upon successful output the actual number of elements in the message list array
///
/// \param  pMessageListSize
///			[O] The message list array
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI GetSMSList( 
   ULONG                      storageType, 
   ULONG *                    pRequestedTag,
   ULONG *                    pMessageListSize, 
   BYTE *                     pMessageList );

//////////////////////////////////////////////////////////////////////////////
///
/// This function returns an SMS message from device memory
///	QMI_WMS_RAW_READ_MSG =                            0x0022
///
/// \param	storageType
///			[I]	SMS message storage type
///			Valid values:
///			\li 0 - STORAGE_TYPE_UIM
///			\li 1 - STORAGE_TYPE_NV
///
/// \param	messageIndex
///			[I]	message index
///
/// \param	pMessageTag
///			[O]	Message tag
///			Valid values:
///			\li 0 - TAG_TYPE_MT_READ
///			\li 1 - TAG_TYPE_MT_NOT_READ
///			\li 2 - TAG_TYPE_MO_SENT
///			\li 3 - TAG_TYPE_MO_NOT_SENT
///
/// \param	pMessageFormat
///			[O]	Message format
///			\li 0x0 - MESSAGE_FORMAT_CDMA
///			\li 0x02~0x05 - Reserved
///			\li 0x06 - MESSAGE_FORMAT_GW_PP
///			\li 0x08 - MESSAGE_FORMAT_MWI
///
/// \param  pMessageSize
///			[I/O]	Upon input the maximum number of bytes that can be written to the message array.  Upon successful output the actual number of bytes written to the message array
///
/// \param  pMessage
///			[O] The message contents array
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI GetSMS( 
   ULONG                      storageType, 
   ULONG                      messageIndex, 
   ULONG *                    pMessageTag,
   ULONG *                    pMessageFormat,
   ULONG *                    pMessageSize, 
   BYTE *                     pMessage );

//////////////////////////////////////////////////////////////////////////////
///
/// This function modifies the status of an SMS message saved in storage on the device
///	QMI_WMS_MODIFY_TAG_MSG =                          0x0023
///
/// \param	storageType
///			[I]	SMS message storage type
///			Valid values:
///			\li 0 - STORAGE_TYPE_UIM
///			\li 1 - STORAGE_TYPE_NV
///
/// \param	messageIndex
///			[I]	message index
///
/// \param	pMessageTag
///			[I]	Message tag
///			Valid values:
///			\li 0 - TAG_TYPE_MT_READ
///			\li 1 - TAG_TYPE_MT_NOT_READ
///			\li 2 - TAG_TYPE_MO_SENT
///			\li 3 - TAG_TYPE_MO_NOT_SENT
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI ModifySMSStatus( 
   ULONG                      storageType, 
   ULONG                      messageIndex, 
   ULONG                      messageTag );

//////////////////////////////////////////////////////////////////////////////
///
/// This function saves an SMS message to device memory
///	QMI_WMS_RAW_WRITE_MSG =                           0x0021
///
/// \param	storageType
///			[I]	SMS message storage type
///			Valid values:
///			\li 0 - STORAGE_TYPE_UIM
///			\li 1 - STORAGE_TYPE_NV
///
/// \param	messageFormat
///			[I]	Message format
///			\li 0x0 - MESSAGE_FORMAT_CDMA
///			\li 0x02~0x05 - Reserved
///			\li 0x06 - MESSAGE_FORMAT_GW_PP
///			\li 0x08 - MESSAGE_FORMAT_MWI
///
/// \param  pMessageSize
///			[I]	The length of the message contents in bytes
///
/// \param  pMessage
///			[I]	The message contents
///
/// \param  pMessageIndex
///			[O]	message index
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI SaveSMS(    
   ULONG                      storageType, 
   ULONG                      messageFormat, 
   ULONG                      messageSize, 
   BYTE *                     pMessage, 
   ULONG *                    pMessageIndex );

//////////////////////////////////////////////////////////////////////////////
///
/// This function sends an SMS message for immediate over the air transmission
///	QMI_WMS_RAW_SEND_MSG =                            0x0020
///
/// \param	messageFormat
///			[I]	Message format
///			\li 0x0 - MESSAGE_FORMAT_CDMA
///			\li 0x02~0x05 - Reserved
///			\li 0x06 - MESSAGE_FORMAT_GW_PP
///			\li 0x08 - MESSAGE_FORMAT_MWI
///
/// \param  messageSize
///			[I]	The length of the message contents in bytes
///
/// \param  pMessage
///			[I]	The message contents
///
/// \param  link_timer
///			[I]	Keeps the GW SMS link open for the specified number of seconds; can be enabled if more messages are expected to follow
///
/// \param  pMessageFailureCode
///			[O]	Failure code
///			When the function fails due to an error sending the message this parameter may contain the message failure cause code (see 3GPP2 N.S0005 Section 6.5.2.125).  If the cause code is not provided then the value will be 0xFFFFFFFF
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI SendSMS(    
   ULONG                      messageFormat, 
   ULONG                      messageSize, 
   BYTE *                     pMessage, 
   BYTE                       link_timer,
   ULONG *                    pMessageFailureCode );

//////////////////////////////////////////////////////////////////////////////
///
/// This function returns the SMS center address
///	QMI_WMS_GET_SMSC_ADDRESS_MSG =                    0x0034
///
/// \param	addressSize
///			[I]	The maximum number of characters (including NULL terminator) that the SMS center address array can contain
///
/// \param	pSMSCAddress
///			[O]	The SMS center address represented as a NULL terminated string
///
/// \param	typeSize
///			[I]	The maximum number of characters (including NULL terminator) that the SMS center address type array can contain

/// \param	pSMSCType
///			[O]	The SMS center address type represented as a NULL terminated string
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI GetSMSCAddress( 
   BYTE                       addressSize,
   CHAR *                     pSMSCAddress,
   BYTE                       typeSize,
   CHAR *                     pSMSCType );

//////////////////////////////////////////////////////////////////////////////
///
/// This function sets the SMS center address
///	QMI_WMS_SET_SMSC_ADDRESS_MSG =                    0x0035
///
/// \param	pSMSCAddress
///			[I]	The SMS center address represented as a NULL terminated string
///
/// \param	pSMSCType
///			[I]	(optional) The SMS center address type represented as a NULL terminated string
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI SetSMSCAddress( 
   CHAR *                     pSMSCAddress, 
   CHAR *                     pSMSCType );

//////////////////////////////////////////////////////////////////////////////
///
/// This function gets the current incoming SMS routing information
///	QMI_WMS_GET_ROUTES_MSG =                          0x0033
///
/// \param	pRouteSize
///			[I/O]	Upon input the maximum number of elements that the SMS route array can contain. Upon success the actual number of elements in the SMS route array
///
/// \param	pRoutes
///			[O]	The SMS route array 
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI GetSMSRoutes( 
   BYTE *                     pRouteSize, 
   BYTE *                     pRoutes );

//////////////////////////////////////////////////////////////////////////////
///
/// This function sets the desired incoming SMS routing information
///	QMI_WMS_SET_ROUTES_MSG =                          0x0032
///
/// \param	pRouteSize
///			[I]	Upon input the maximum number of elements that the SMS route array can contain. Upon success the actual number of elements in the SMS route array
///
/// \param	pRoutes
///			[I]	The SMS route array 
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI SetSMSRoutes( 
   BYTE *                     pRouteSize, 
   BYTE *                     pRoutes );

//////////////////////////////////////////////////////////////////////////////
///
/// This function queries the SMS message protocol
///
/// \param	pProtocol
///			[O]	SMS message protocol
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI GetSMSProtocol( BYTE * pProtocol );

//////////////////////////////////////////////////////////////////////////////
///
/// This function sets the SMS message protocol
///
/// \param	pProtocol
///			[I]	SMS message protocol
///
/// \return See GobiErrorCodes.h
///
///////////////////////////////////////////////////////////////////////////////
IMPORTGOBI ULONG GOBICMAPI SetSMSProtocol( BYTE protocol );
/*@}*/ // End of WMS group
#endif