EC600G/components/ql-kernel/inc/ql_api_sim.h

/*============================================================================
  Copyright (c) 2020 Quectel Wireless Solution, Co., Ltd.  All Rights Reserved.
  Quectel Wireless Solution Proprietary and Confidential.
 =============================================================================*/
/*===========================================================================

                        EDIT HISTORY FOR MODULE

This section contains comments describing changes made to the module.
Notice that changes are listed in reverse chronological order.


WHEN        WHO            WHAT, WHERE, WHY
----------  ------------   ----------------------------------------------------

=============================================================================*/

#ifndef QL_API_SIM_H
#define QL_API_SIM_H

#include <stddef.h>

#include "ql_api_common.h"
#include "ql_gpio.h"

#ifdef __cplusplus
extern "C" {
#endif

/*========================================================================
 *  Marco Definition
 *========================================================================*/
#define QL_SIM_ERRCODE_BASE (QL_COMPONENT_SIM<<16)

#define QL_SIM_PIN_LEN_MAX  8          // Maximum length of PIN data. 

#define QL_PBK_ITEM_COUNT_MAX 20
#define QL_PBK_USERNAME_LEN_MAX 32
#define QL_PBK_PHONENUM_LEN_MAX 24

/*========================================================================
 *  Enumeration Definition
 *========================================================================*/
//SIM componant detail errcode, 4 bytes
typedef enum
{
    QL_SIM_SUCCESS                          = 0,
    QL_SIM_EXECUTE_ERR                      = 1|QL_SIM_ERRCODE_BASE,
    QL_SIM_MEM_ADDR_NULL_ERR,
    QL_SIM_INVALID_PARAM_ERR,
    QL_SIM_NO_MEMORY_ERR,
    QL_SIM_SEMAPHORE_CREATE_ERR             = 5|QL_SIM_ERRCODE_BASE,
    QL_SIM_SEMAPHORE_TIMEOUT_ERR,
    QL_SIM_NOT_INSERTED_ERR,
    QL_SIM_CFW_IMSI_GET_REQUEST_ERR,
    QL_SIM_CFW_IMSI_GET_RSP_ERR,
    QL_SIM_CFW_ICCID_GET_REQUEST_ERR        = 10|QL_SIM_ERRCODE_BASE,
    QL_SIM_CFW_PHONE_NUM_GET_REQUEST_ERR,
    QL_SIM_CFW_PHONE_NUM_GET_RSP_NULL_ERR,
    QL_SIM_CFW_STATUS_GET_REQUEST_ERR,
    QL_SIM_CFW_PIN_ENABLE_REQUEST_ERR,
    QL_SIM_CFW_PIN_DISABLE_REQUEST_ERR      = 15|QL_SIM_ERRCODE_BASE,
    QL_SIM_CFW_PIN_VERIFY_REQUEST_ERR,
    QL_SIM_CFW_PIN_CHANGE_REQUEST_ERR,
    QL_SIM_CFW_PIN_UNBLOCK_REQUEST_ERR,
    QL_SIM_OPERATION_NOT_ALLOWED_ERR,
    QL_PBK_NOT_EXIT_ERR                     = 100|QL_SIM_ERRCODE_BASE,
    QL_PBK_NOT_INIT_ERR,
    QL_PBK_ITEM_NOT_FOUND_ERR,
} ql_sim_errcode_e;


typedef enum 
{
    QL_SIM_STATUS_READY                 = 0,
    QL_SIM_STATUS_PIN1_READY,
    QL_SIM_STATUS_SIMPIN,
    QL_SIM_STATUS_SIMPUK,
    QL_SIM_STATUS_PHONE_TO_SIMPIN,
    QL_SIM_STATUS_PHONE_TO_FIRST_SIMPIN = 5,
    QL_SIM_STATUS_PHONE_TO_FIRST_SIMPUK,
    QL_SIM_STATUS_SIMPIN2,
    QL_SIM_STATUS_SIMPUK2,
    QL_SIM_STATUS_NETWORKPIN,
    QL_SIM_STATUS_NETWORKPUK            = 10,
    QL_SIM_STATUS_NETWORK_SUBSETPIN,
    QL_SIM_STATUS_NETWORK_SUBSETPUK,
    QL_SIM_STATUS_PROVIDERPIN,
    QL_SIM_STATUS_PROVIDERPUK,
    QL_SIM_STATUS_CORPORATEPIN          = 15,
    QL_SIM_STATUS_CORPORATEPUK,
    QL_SIM_STATUS_NOSIM,
    QL_SIM_STATUS_PIN1BLOCK,
    QL_SIM_STATUS_PIN2BLOCK,
    QL_SIM_STATUS_PIN1_DISABLE          = 20,
    QL_SIM_STATUS_SIM_PRESENT,
    QL_SIM_STATUS_UNKNOW,
}ql_sim_status_e;

typedef enum
{
    QL_SIM_PBK_STORAGE_FD, // (U)SIM fix dialing-phone book
    QL_SIM_PBK_STORAGE_LD, // (U)SIM last-dialing-phone book
    QL_SIM_PBK_STORAGE_ME, // Mobile equipment phonebook
    QL_SIM_PBK_STORAGE_ON, // SIM (or MT) own numbers (MSISDNs) list
    QL_SIM_PBK_STORAGE_SM, // SIM/UICC phonebook
    QL_SIM_PBK_STORAGE_MAX,
} ql_sim_pbk_storage_e;

typedef enum
{
    QL_SIM_PBK_GSM,
    QL_SIM_PBK_HEX,
    QL_SIM_PBK_UCS2,
    QL_SIM_PBK_GBK,
    QL_SIM_PBK_IRA,
    QL_SIM_PBK_ENCODE_MAX,
} ql_sim_pbk_encoding_e;

typedef enum{
    QL_SIM_HOTPLUG_DISABLE          = 0,
    QL_SIM_HOTPLUG_ENABLE           = 1,
}ql_sim_hotplug_e;

typedef enum{
    QL_SIM_HOTPLUG_STATUS_OUT       = 0,
    QL_SIM_HOTPLUG_STATUS_IN        = 1,
}ql_sim_hotplug_status_e;

/*========================================================================
*  Type Definition
*========================================================================*/
typedef struct 
{
    uint8_t                     pin_value[QL_SIM_PIN_LEN_MAX+1];      /*  Value of the PIN */
}ql_sim_verify_pin_info_s;  

typedef struct 
{
    uint8_t                     old_pin_value[QL_SIM_PIN_LEN_MAX+1];  /**< Value of the old PIN as a sequence of ASCII characters. */
    uint8_t                     new_pin_value[QL_SIM_PIN_LEN_MAX+1];  /**< Value of the new PIN as a sequence of ASCII characters. */
}ql_sim_change_pin_info_s; 

typedef struct 
{
    uint8_t                     puk_value[QL_SIM_PIN_LEN_MAX+1];      /**< Value of the PUK as a sequence of ASCII characters. */
    uint8_t                     new_pin_value[QL_SIM_PIN_LEN_MAX+1];  /**< Value of the new PIN as a sequence of ASCII characters. */
}ql_sim_unblock_pin_info_s;

typedef struct
{
    int index;                                 /**< the item index in phone book */
    uint8_t username[QL_PBK_USERNAME_LEN_MAX]; /**< user name */
    uint8_t phonenum[QL_PBK_PHONENUM_LEN_MAX]; /**< phone number, it can include '+'. when write, if phonenum is empty, it means to delete this item specified by index*/
    uint8_t username_len;                      /**< user name len*/
} ql_sim_pbk_item_info_s;

typedef struct
{
    int item_count;                                     /**< the count of items */
    ql_sim_pbk_item_info_s item[QL_PBK_ITEM_COUNT_MAX]; /**< the list of items */
} ql_sim_pbk_itemset_info_s;

typedef struct
{
    ql_GpioNum gpio_num;
    ql_LvlMode gpio_level;
}ql_sim_hotplug_gpio_s;

/*========================================================================
  *  Callback Definition
  *========================================================================*/
typedef void (*ql_pbk_event_handler_t)(uint8_t nSim, int event_id, void *ctx);
extern ql_pbk_event_handler_t ql_pbk_call_callback;

typedef void (*ql_sim_hotplug_cb_t)(uint8_t nSim, ql_sim_hotplug_status_e status);

/*========================================================================
 *	function Definition
 *========================================================================*/
 
/*****************************************************************
* Function: ql_sim_get_imsi
*
* Description:
* 	获取 SIM 卡的 IMSI。
* 
* Parameters:
*	nSim        	[in]    SIM卡索引，取值：0-1
* 	imsi	  		[out] 		SIM 卡的 IMSI，字符串。  
* 	imsi_len	  	[in] 		imsi 数组的长度。
*
* Return:
* 	QL_SIM_SUCCESS			成功。
*	other           		错误码。
*
*****************************************************************/
ql_sim_errcode_e ql_sim_get_imsi(uint8_t nSim, char *imsi, size_t imsi_len);

/*****************************************************************
* Function: ql_sim_get_iccid
*
* Description:
* 	获取 SIM 卡的 ICCID。
* 
* Parameters:
*	nSim        	[in]    SIM卡索引，取值：0-1
* 	iccid	  		[out] 		SIM 卡的 ICCID，字符串。 
* 	iccid_len	  	[in] 		iccid 数组的长度。  
*
* Return:
* 	QL_SIM_SUCCESS			成功。
*	other           		错误码。
*
*****************************************************************/
ql_sim_errcode_e ql_sim_get_iccid(uint8_t nSim, char *iccid, size_t iccid_len);

/*****************************************************************
* Function: ql_sim_get_phonenumber
*
* Description:
* 	获取 SIM 卡本机号码。 
* 
* Parameters:
*	nSim        		[in]    SIM卡索引，取值：0-1
* 	phonenumber	  		[out] 	SIM 卡本机号码，字符串。  
* 	phonenumber_len	  	[in] 	phonenumber 数组的长度。  
*
* Return:
* 	QL_SIM_SUCCESS			成功。
*	other           		错误码。
*
*****************************************************************/
ql_sim_errcode_e ql_sim_get_phonenumber(uint8_t nSim, char *phonenumber,size_t phonenumber_len);
/*****************************************************************
* Function: ql_sim_get_card_status_phy
*
* Description:
* 	获取 SIM 卡实时状态信息。
* 
* Parameters:
*	nSim        	    [in]    SIM卡索引，取值：0-1
* 	card_status	  		[out] 	返回 SIM 卡类型信息，见 ql_sim_status_e 
*
* Return:
* 	QL_SIM_SUCCESS				成功。
*	other           		    错误码。
*
*****************************************************************/
ql_sim_errcode_e ql_sim_get_card_status_phy(uint8_t nSim, ql_sim_status_e *card_status);

/*****************************************************************
* Function: ql_sim_get_card_status
*
* Description:
* 	获取 SIM 卡缓存状态信息。
* 
* Parameters:
*	nSim        	    [in]    SIM卡索引，取值：0-1
* 	card_status	  		[out] 	返回 SIM 卡类型信息，见 ql_sim_status_e 
*
* Return:
* 	QL_SIM_SUCCESS				成功。
*	other           		    错误码。
*
*****************************************************************/
ql_sim_errcode_e ql_sim_get_card_status(uint8_t nSim, ql_sim_status_e *card_status);

/*****************************************************************
* Function: ql_sim_enable_pin
*
* Description:
* 	启用 SIM 卡 PIN 码验证，重启生效。
* 
* Parameters:
*	nSim        	[in]    SIM卡索引，取值：0-1
* 	pt_info	  		[in] 	输入 PIN 码，见 ql_sim_verify_pin_info_s
*
* Return:
* 	QL_SIM_SUCCESS				成功。
*	other           		    错误码。
*
*****************************************************************/
ql_sim_errcode_e ql_sim_enable_pin(uint8_t nSim, ql_sim_verify_pin_info_s *pt_info);

/*****************************************************************
* Function: ql_sim_disable_pin
*
* Description:
* 	关闭 SIM 卡 PIN 码验证。
* 
* Parameters:
*	nSim        	[in]    SIM卡索引，取值：0-1
* 	pt_info	  		[in] 	输入 PIN 码，见 ql_sim_verify_pin_info_s
*
* Return:
* 	QL_SIM_SUCCESS				成功。
*	other           		    错误码。
*
*****************************************************************/
ql_sim_errcode_e ql_sim_disable_pin(uint8_t nSim, ql_sim_verify_pin_info_s *pt_info);

/*****************************************************************
* Function: ql_sim_verify_pin
*
* Description:
* 	当 SIM 状态为请求 PIN/PIN2，输入 PIN/PIN2 码，进行验证。
* 
* Parameters:
*	nSim        	[in]    SIM卡索引，取值：0-1
* 	pt_info	  		[in] 	输入 PIN 码，见 ql_sim_verify_pin_info_s
*
* Return:
* 	QL_SIM_SUCCESS				成功。
*	other           		    错误码。
*
*****************************************************************/
ql_sim_errcode_e ql_sim_verify_pin(uint8_t nSim, ql_sim_verify_pin_info_s *pt_info);

/*****************************************************************
* Function: ql_sim_change_pin
*
* Description:
* 	启用 SIM 卡 PIN 码验证后，更改 SIM 卡的 PIN 码。
* 
* Parameters:
*	nSim        	[in]    SIM卡索引，取值：0-1
* 	pt_info	  		[in] 	输入旧的 PIN 和新的 PIN，见 ql_sim_change_pin_info_s
*
* Return:
* 	QL_SIM_SUCCESS				成功。
*	other           		    错误码。
*
*****************************************************************/
ql_sim_errcode_e ql_sim_change_pin(uint8_t nSim, ql_sim_change_pin_info_s *pt_info);

/*****************************************************************
* Function: ql_sim_change_pin
*
* Description:
* 	当多次错误输入 PIN/PIN2 码后，SIM 卡状态为请求 PUK/PUK2 时，输入 PUK/PUK2 码和新的PIN/PIN2 码进行解锁,
*   解PUK锁成功后，SIM卡会自动启用PIN 码验证，用户需再次调用ql_sim_disable_pin()关闭 SIM 卡 PIN 码验证。
* 
* Parameters:
*	nSim        	[in]    SIM卡索引，取值：0-1
* 	pt_info	  		[in] 	输入 PUK/PUK2 码和新的 PIN/PIN2 码，见 ql_sim_unblock_pin_info_s
*
* Return:
* 	QL_SIM_SUCCESS				成功。
*	other           		    错误码。
*
*****************************************************************/
ql_sim_errcode_e ql_sim_unblock_pin(uint8_t nSim, ql_sim_unblock_pin_info_s *pt_info);

/*****************************************************************
* Function: ql_sim_set_operate_id
*
* Description:
* 	设置需要操作的SIM卡卡槽ID，默认值为0；仅适用于双卡单待应用，以切换操作的物理卡槽。
* 
* Parameters:
*	nSim        	[in]    SIM卡卡槽ID，取值：0-1
*
* Return:
* 	QL_SIM_SUCCESS				成功。
*	other           		    错误码。
*
*****************************************************************/
ql_sim_errcode_e ql_sim_set_operate_id(uint8_t nSim);

/*****************************************************************
* Function: ql_sim_get_operate_id
*
* Description:
* 	获取当前操作的SIM卡卡槽ID；仅适用于双卡单待应用。
* 
* Parameters:
*	NULL
*
* Return:
* 	SIM ID。
*
*****************************************************************/
uint8_t ql_sim_get_operate_id(void);

/*****************************************************************
* Function: ql_sim_set_hotplug
*
* Description:
* 	SIM卡热插拔使能函数
* 
* Parameters:
*   nSim        [in]    SIM卡卡槽ID，取值：0-1
*   status      [in]    SIM卡热插拔是否使能,取值: 1 ENABLE,0 DISABLE
*   gpio_cfg    [in]    SIM卡热插拔GPIO配置结构体,ENABLE时必须传入有效值,DISABLE时必须传入NULL
*
* Return:
* 	QL_SIM_SUCCESS			成功。
*	other           		错误码。
*
*****************************************************************/
ql_sim_errcode_e ql_sim_set_hotplug(uint8_t nSim, ql_sim_hotplug_e status, ql_sim_hotplug_gpio_s* gpio_cfg);


/*****************************************************************
* Function: ql_sim_hotplug_register_cb
*
* Description:
* 	注册SIM卡热插拔回调函数
* 
* Parameters:
*   cb          [in]    SIM卡热插拔回调函数
*
* Return:
* 	QL_SIM_SUCCESS			成功。
*	other           		错误码。
*

*****************************************************************/
ql_sim_errcode_e ql_sim_hotplug_register_cb(ql_sim_hotplug_cb_t cb);

/*****************************************************************
* Function: ql_sim_get_ds_feature
*
* Description:
* 	获取当前应用的双卡类型
* 
* Parameters:
*   None       
*
* Return:
* 	ql_dsim_feature_e	卡类型
*
*****************************************************************/
uint8_t ql_sim_get_ds_feature(void);

/*****************************************************************
* Function: ql_sim_set_ds_feature
*
* Description:
* 	设置应用的双卡类型, 重启后生效.
* 
* Parameters:
*   ds_feature      [in]    卡类型：
*                            DSIM_SINGLE：单卡单待
*                            DSIM_DSSS：双卡单待
*                            DSIM_DSDS：双卡双待
*
* Return:
* 	QL_SIM_SUCCESS			成功。
*	other           		错误码。	
*
*****************************************************************/
ql_sim_errcode_e ql_sim_set_ds_feature(uint8_t ds_feature);

#ifdef CONFIG_QUEC_PROJECT_FEATURE_PBK
/*****************************************************************
* Function: ql_sim_read_pbk_item
*
* Description:
* 	获取SIM卡上指定电话本中的一条或多电话号码记录。
* 
* Parameters:
*	nSim        	[in]    SIM卡索引，取值：0-1
* 	storage	  		[in] 	需要读取电话号码记录的电话本存储位置，见 ql_sim_pbk_storage_e
* 	start_index	  	[in] 	需要读取电话号码记录的起始编号，start_index 为 0 表示不使用编号获取电话号码记录 
* 	end_index	  	[in] 	需要读取电话号码记录的结束编号
* 	username	  	[in] 	当 start_index 为 0 时有效，电话号码中的用户名
* 	username_len	[in] 	当 start_index 为 0 时有效，电话号码中的用户名的长度
* 	itemset	  		[out] 	返回电话号码记录列表，见 ql_sim_pbk_itemset_info_s
*
* Return:
* 	QL_SIM_SUCCESS				成功。
*	other           		    错误码。
*
*****************************************************************/
ql_sim_errcode_e ql_sim_read_pbk_item(uint8_t nSim,
                                      ql_sim_pbk_storage_e storage,
                                      int start_index,
                                      int end_index,
                                      uint8_t *username,
                                      uint8_t username_len,
                                      ql_sim_pbk_itemset_info_s *itemset);

/*****************************************************************
* Function: ql_sim_write_pbk_item
*
* Description:
* 	写入SIM卡上指定电话本中的一条电话号码记录。 
* 
* Parameters:
*	nSim        	[in]    SIM卡索引，取值：0-1
* 	storage	  		[in] 	需要读取电话号码记录的电话本存储位置   
* 	item	  		[in] 	需要写入的电话号码记录，见 ql_sim_pbk_item_info_s
*
* Return:
* 	QL_SIM_SUCCESS				成功。
*	other           		    错误码。
*
*****************************************************************/
ql_sim_errcode_e ql_sim_write_pbk_item(uint8_t nSim,
                                       ql_sim_pbk_storage_e storage,
                                       ql_sim_pbk_item_info_s *item);

/*****************************************************************
* Function: ql_sim_set_pbk_encoding
*
* Description:
* 	设置电话簿字符集,重启后恢复为QL_SIM_PBK_GSM
* 
* Parameters:
*	encoding		 [in]    字符集, 见ql_sim_pbk_encoding_e
*
* Return:
* 	QL_SIM_SUCCESS				成功。
*	other           		    错误码。
*
*****************************************************************/
ql_sim_errcode_e ql_sim_set_pbk_encoding(ql_sim_pbk_encoding_e encoding);

/*****************************************************************
* Function: ql_sim_get_pbk_encoding
*
* Description:
* 	获取电话簿字符集,默认为QL_SIM_PBK_GSM
* 
* Parameters:
*	encoding		 [out]    字符集, 见ql_sim_pbk_encoding_e
*
* Return:
* 	QL_SIM_SUCCESS				成功。
*	other           		    错误码。
*
*****************************************************************/
ql_sim_errcode_e ql_sim_get_pbk_encoding(ql_sim_pbk_encoding_e *encoding);

/*****************************************************************
* Function: ql_pbk_callback_register
*
* Description:
* 	注册电话簿回调函数
* 
* Parameters:
*	cb		        [in]    回调函数
*
*****************************************************************/
void ql_pbk_callback_register(ql_pbk_event_handler_t cb);

#endif
#ifdef __cplusplus
}/*"C" */
#endif

#endif   /*QL_API_SIM_H*/