mbtk/include/ql_v2/ql_sim.h

/*-----------------------------------------------------------------------------------------------*/
/**
  @file ql_sim.h 
  @brief SIM service API 
*/
/*-----------------------------------------------------------------------------------------------*/

/*-------------------------------------------------------------------------------------------------
  Copyright (c) 2024 mobiletek Wireless Solution, Co., Ltd. All Rights Reserved.
  mobiletek Wireless Solution Proprietary and Confidential.
-------------------------------------------------------------------------------------------------*/

/*-------------------------------------------------------------------------------------------------
  EDIT HISTORY
  This section contains comments describing changes made to the file.
  Notice that changes are listed in reverse chronological order.
  $Header: $
  when       who          what, where, why
  --------   ---------    -----------------------------------------------------------------
  20241022    yq.wang      Created .
-------------------------------------------------------------------------------------------------*/

#ifndef __QL_SIM_H__
#define __QL_SIM_H__

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>

#define QL_SIM_IMSI_LENGTH      16      /**<  Maximum length of IMSI data. */
#define QL_SIM_ICCID_LENGTH     20      /**<  Maximum length of ICCID data. */
#define QL_SIM_PUK_LENGTH       8       /**<  Maximum length of PUK data. */
#define QL_SIM_NUM_OPERATOR_MAX 24      /**<  Maximum number of operators */
#define QL_SIM_PATH_MAX         20      /**<  Maximum length of a full file path in ASCII format. */
#define QL_SIM_DATA_MAX         4096    /**<  Maximum size of data to be read/written. */
#define QL_SIM_PIN_MAX          8       /**<  Maximum length of PIN data. */
#define QL_SIM_MAX_NUM_CARDS    2       /**<  Maximum number of cards. */
#define QL_SIM_PHONE_NUMBER_MAX 82      /**<  Maximum phone number length. */
#define QL_SIM_MCC_LENGHT       3       /**<  Length of the MCC. */
#define QL_SIM_MNC_MAX          3       /**<  Maximum length of the MNC. */

#define QL_SIM_PHONE_BOOK_NAME_MAX      15  /**<  Maximum length of phone book user name. */
#define QL_SIM_PHONE_BOOK_NUMBER_MAX    25  /**<  Maximum length of phone book number. */

#define QL_SIM_APDU_DATA_MAX    1024  /**<  Maximum number of APDU data. */

#define QL_SIM_PB_DEFAULT_PATH   "3F007F106F3A"   /**< Default phone book path. */

/** Ligcial slot */
/**> Currently only one active slot is supported, so slot should be always QL_SIM_SLOT_1.*/
typedef enum 
{
    QL_SIM_SLOT_INVALID = 0x000, /**< Invalid slot.  */   
    QL_SIM_SLOT_1       = 0xB01, /**< Identify card in slot 1.  */
    QL_SIM_SLOT_2       = 0xB02, /**< Identify card in slot 2.  */
} QL_SIM_SLOT_E;

/** Physical slot */
typedef enum 
{
    QL_SIM_PHY_SLOT_INVALID = 0x000, /**< Invalid slot.  */   
    QL_SIM_PHY_SLOT_1       = 0xB01, /**< Identify card in slot 1.  */
    QL_SIM_PHY_SLOT_2       = 0xB02, /**< Identify card in slot 2.  */
} QL_SIM_PHY_SLOT_E;


typedef enum 
{
    QL_SIM_PIN_1 = 0xB01, /**< Level 1 user verification.  */
    QL_SIM_PIN_2 = 0xB02, /**< Level 2 user verification.  */
} QL_SIM_PIN_E;


/** Application Type */
typedef enum
{
    QL_SIM_APP_TYPE_UNKNOWN = 0xB00, /**<  Unknown application type  */
    QL_SIM_APP_TYPE_3GPP    = 0xB01, /**< Identify the SIM/USIM application on the card.  */
    QL_SIM_APP_TYPE_3GPP2   = 0xB02, /**< Identify the RUIM/CSIM application on the card.  */
    QL_SIM_APP_TYPE_ISIM    = 0xB03, /**< Identify the ISIM application on the card.  */
} QL_SIM_APP_TYPE_E;

typedef struct 
{
    char mcc[QL_SIM_MCC_LENGHT];    /**< MCC value in ASCII characters.*/
    uint8_t mnc_len;                /**< The number of elements in the MNC, 2 or 3. */
    char mnc[QL_SIM_MNC_MAX];       /**< MNC value in ASCII characters.*/
} ql_sim_operator_t;

typedef struct 
{
    int len;    /**< Length of actual operators */
    ql_sim_operator_t operators[QL_SIM_NUM_OPERATOR_MAX];
} ql_sim_operator_list_t;

typedef enum {
    /** Card state unknown. */
    QL_SIM_CARD_STATE_UNKNOWN                       = 0xB01,
    /** Card is absent. */
    QL_SIM_CARD_STATE_ABSENT                        = 0xB02,  
    /** Card is present. */
    QL_SIM_CARD_STATE_PRESENT                       = 0xB03,
    /** Unknown error state. */
    QL_SIM_CARD_STATE_ERROR_UNKNOWN                 = 0xB04,
    /** Power down. */
    QL_SIM_CARD_STATE_ERROR_POWER_DOWN              = 0xB05,
    /** Poll error. */
    QL_SIM_CARD_STATE_ERROR_POLL_ERROR              = 0xB06,  
    /**  Failed to receive an answer to reset.  */
    QL_SIM_CARD_STATE_ERROR_NO_ATR_RECEIVED         = 0xB07, 
    /** Voltage mismatch. */
    QL_SIM_CARD_STATE_ERROR_VOLT_MISMATCH           = 0xB08, 
    /** Parity error. */
    QL_SIM_CARD_STATE_ERROR_PARITY_ERROR            = 0xB09,    
    /** Card returned technical problems. */
    QL_SIM_CARD_STATE_ERROR_SIM_TECHNICAL_PROBLEMS  = 0xB0A,  
} QL_SIM_CARD_STATE_E;  /**< Card state. */

typedef enum {
    QL_SIM_SUBSCRIPTION_NONE    = 0xB00, /**<  Nonprovisioning.  */
    QL_SIM_SUBSCRIPTION_PRI     = 0xB01, /**<  Primary provisioning subscription.  */
    QL_SIM_SUBSCRIPTION_SEC     = 0xB02, /**<  Secondary provisioning subscription.  */
} QL_SIM_SUBSCRIPTION_E;

typedef enum
{
    QL_SIM_CARD_TYPE_UNKNOWN    = 0xB00, /**<  Unidentified card type.  */
    QL_SIM_CARD_TYPE_ICC        = 0xB01, /**<  Card of SIM or RUIM type.  */
    QL_SIM_CARD_TYPE_UICC       = 0xB02, /**<  Card of USIM or CSIM type.  */
} QL_SIM_CARD_TYPE_E;

typedef enum {
    QL_SIM_APP_STATE_UNKNOWN                    = 0xB00, /**<  Application state unknown. */
    QL_SIM_APP_STATE_DETECTED                   = 0xB01, /**<  Detected state.  */
    QL_SIM_APP_STATE_PIN1_REQ                   = 0xB02, /**<  PIN1 required.  */
    QL_SIM_APP_STATE_PUK1_REQ                   = 0xB03, /**<  PUK1 required.  */
    QL_SIM_APP_STATE_INITALIZATING              = 0xB04, /**<  Initializing.  */
    QL_SIM_APP_STATE_PERSO_CK_REQ               = 0xB05, /**<  Personalization control key required.  */
    QL_SIM_APP_STATE_PERSO_PUK_REQ              = 0xB06, /**<  Personalization unblock key required.  */
    QL_SIM_APP_STATE_PERSO_PERMANENTLY_BLOCKED  = 0xB07, /**<  Personalization is permanently blocked.  */
    QL_SIM_APP_STATE_PIN1_PERM_BLOCKED          = 0xB08, /**<  PIN1 is permanently blocked.  */
    QL_SIM_APP_STATE_ILLEGAL                    = 0xB09, /**<  Illegal application state.  */
    QL_SIM_APP_STATE_READY                      = 0xB0A, /**<  Application ready state. */
} QL_SIM_APP_STATE_E;

typedef enum {
    /**  Unknown personalization feature.  */
    QL_SIM_PERSO_FEATURE_UNKNOWN                = 0xB00,
    /**  Featurization based on 3GPP MCC and MNC.  */
    QL_SIM_PERSO_FEATURE_3GPP_NETWORK           = 0xB01, 
    /**  Featurization based on 3GPP MCC, MNC, and IMSI digits 6 and 7.  */
    QL_SIM_PERSO_FEATURE_3GPP_NETWORK_SUBSET    = 0xB02, 
    /**  Featurization based on 3GPP MCC, MNC, and GID1.  */
    QL_SIM_PERSO_FEATURE_3GPP_SERVICE_PROVIDER  = 0xB03,
    /**  Featurization based on 3GPP MCC, MNC, GID1, and GID2.  */
    QL_SIM_PERSO_FEATURE_3GPP_CORPORATE         = 0xB04, 
    /**  Featurization based on the 3GPP IMSI.  */
    QL_SIM_PERSO_FEATURE_3GPP_SIM               = 0xB05, 
    /**  Featurization based on 3GPP2 MCC and MNC.  */
    QL_SIM_PERSO_FEATURE_3GPP2_NETWORK_TYPE_1   = 0xB06, 
    /**  Featurization based on 3GPP2 IRM code.  */
    QL_SIM_PERSO_FEATURE_3GPP2_NETWORK_TYPE_2   = 0xB07, 
    /**  Featurization based on 3GPP2 IMSI_M.  */
    QL_SIM_PERSO_FEATURE_3GPP2_RUIM             = 0xB08, 
} QL_SIM_PERSO_FEATURE_E;

typedef enum {
    /** Unknown PIN state. */
    QL_SIM_PIN_STATE_UNKNOWN                = 0xB01, 
    /**  PIN required, but has not been verified.  */
    QL_SIM_PIN_STATE_ENABLED_NOT_VERIFIED   = 0xB02, 
    /**  PIN required and has been verified.  */
    QL_SIM_PIN_STATE_ENABLED_VERIFIED       = 0xB03, 
    /**  PIN not required.  */
    QL_SIM_PIN_STATE_DISABLED               = 0xB04, 
    /**  PIN verification has failed too many times and is blocked. Recoverable through PUK verification.  */
    QL_SIM_PIN_STATE_BLOCKED                = 0xB05, 
    /**  PUK verification has failed too many times and is not recoverable.  */
    QL_SIM_PIN_STATE_PERMANENTLY_BLOCKED    = 0xB06, 
 } QL_SIM_PIN_STATE_E;

typedef struct {
    /**   Type of subscription (i.e., primary, secondary, etc.). */
    QL_SIM_SUBSCRIPTION_E subscription;				/**nonsupport*/
    /**   Current state of the application. */
    QL_SIM_APP_STATE_E app_state;
    /**   Current personalization state and feature enabled. */
    QL_SIM_PERSO_FEATURE_E perso_feature;			/**nonsupport*/
    /**   Number of personalization retries. */
    uint8_t perso_retries;				/**nonsupport*/
    /**   Number of personalization unblock retries. */
    uint8_t perso_unblock_retries;			/**nonsupport*/
    /**   Current PIN 1 state. */
    QL_SIM_PIN_STATE_E pin1_state;			/**nonsupport*/
    /**   Number of PIN 1 retries. */
    uint8_t pin1_num_retries;
    /**   Number of PUK 1 retries. */
    uint8_t puk1_num_retries;
    /**   Current PIN 2 state. */
    QL_SIM_PIN_STATE_E pin2_state;			/**nonsupport*/
    /**   Number of PIN 2 retries. */
    uint8_t pin2_num_retries; 
    /**   Number of PUK 2 retries. */
    uint8_t puk2_num_retries;
}ql_sim_app_info_t;  /* Type */

typedef struct
{
    QL_SIM_CARD_STATE_E state;
    QL_SIM_CARD_TYPE_E type;
    ql_sim_app_info_t app_3gpp;     /**<   Stores 3GPP application information. */
    ql_sim_app_info_t app_3gpp2;    /**<   Stores 3GPP2 application information. */
    ql_sim_app_info_t app_isim;     /**<   Stores ISIM application information. */
} ql_sim_card_info_t;

typedef struct {
    uint32_t path_len;          /**< Must be set to the number of elements in the path. */
    char path[QL_SIM_PATH_MAX]; /**< File path in ASCII characters. */
    /** Offset is only required for write transparent file access where data length is indicated.*/
    uint16_t offset; 
    /** Index of records involved in file access. A record index of 0 indicates transparent file access.*/
    uint8_t record_idx;

    /* == filled by caller when writing file == */
    uint32_t data_len;  /**< When reading file, it's the length of file data been read.
                             When writing file, it's the length of file data to be written. */
    uint8_t data[QL_SIM_DATA_MAX];
} ql_sim_file_t;  /* Type */

typedef enum {
    QL_SIM_FILE_TYPE_UNKNOWN        = 0xB00, /**<  Unknown file type  */
    QL_SIM_FILE_TYPE_TRANSPARENT    = 0xB01, /**< File structure consisting of a sequence of bytes.  */
    QL_SIM_FILE_TYPE_CYCLIC         = 0xB02, /**< File structure consisting of a sequence of records,
                                                  each containing the same fixed size in 
                                                  chronological order.Once all the records have been
                                                  used, the oldest data is overwritten.  */
    QL_SIM_FILE_TYPE_LINEAR_FIXED   = 0xB03, /**< File structure consisting of a sequence of records, 
                                                  each containing the same fixed size.  */
} QL_SIM_FILE_TYPE_E;


typedef struct {
    /* == filled by caller == */
    uint32_t path_len;          /**< Must be set to the number of elements in the path. */
    char path[QL_SIM_PATH_MAX]; /**< File path in ASCII characters. */

    /* == filled by callee == */
    QL_SIM_FILE_TYPE_E file_type;   /**<   File type */
    uint16_t file_size;             /**<   Size of transparent files.*/
    uint16_t record_size;           /**<   Size of each cyclic or linear fixed file record.*/
    uint16_t record_count;          /**<   Number of cyclic or linear fixed file records.*/
} ql_sim_file_info_t;  /* Type */

typedef struct 
{
    /** User name. Null-terminated */
    char name[QL_SIM_PHONE_BOOK_NAME_MAX];   
    /** Phone number, a '+' can also be preappended to the number. Null-terminated. */
    char number[QL_SIM_PHONE_BOOK_NUMBER_MAX]; 
} ql_sim_phone_book_record_t;

typedef struct
{
    uint32_t req_apdu_len;                      /**< Request APDU data length. */
    uint8_t req_apdu[QL_SIM_APDU_DATA_MAX];     /**< Request APDU data. */

    uint32_t resp_apdu_len;                     /**< Response APDU data length. */
    uint8_t resp_apdu[QL_SIM_APDU_DATA_MAX];    /**< Response APDU data. */
} ql_sim_apdu_t;

typedef void (*ql_sim_card_status_cb_f)(QL_SIM_SLOT_E slot, ql_sim_card_info_t *p_info);

typedef struct 
{
    int active_slots_len;
    QL_SIM_PHY_SLOT_E active_slots[QL_SIM_MAX_NUM_CARDS];
} ql_sim_active_slots_t;

typedef void (*ql_sim_service_error_cb_f)(int error);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Initializes SIM service.
  @note You must call this function before other functions can be used in this module.
  @return Whether the SIM service was intialized successfully.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_init(void);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Deinitializes SIM service.
  @return Whether the SIM service was deintialized successfully.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_deinit(void);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Gets the IMSI (for 3GPP) or IMSI_M (for 3GPP2) from the SIM in ASCII form.
  @param [in] slot Slot to be used.
  @param [in] app_type Application type.
  @param [out] imsi Buffer to fill IMSI data.
  @param [in] imsi_len Buffer length.
  @return Whether the IMSI was successfully obtained.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_get_imsi(QL_SIM_SLOT_E slot, QL_SIM_APP_TYPE_E app_type, char *imsi, int imsi_len);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Retrieves the Integrated Circuit Card ID (ICCID) stored on the card.
  @param [in] slot Slot to be used.
  @param [out] iccid Buffer to fill ICCID data.
  @param [in] iccid_len Buffer length.
  @return Whether the ICCID was successfully obtained.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_get_iccid(QL_SIM_SLOT_E slot, char *iccid, int iccid_len);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Retrieves the device phone number stored on the card.
  @param [in] slot Slot to be used.
  @param [in] app_type Application type.
  @param [out] phone_num Buffer to fill phone number.
  @param [in] phone_num_len Buffer length.
  @return Whether the phone number was successfully retrieved.
  @retval QL_ERR_OK successful
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_get_phone_num(QL_SIM_SLOT_E slot, QL_SIM_APP_TYPE_E app_type, 
                          char *phone_num, int phone_num_len);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Retrieves the preferred operators stored on the card.
  @param [in] slot Slot to be used.
  @param [in] list Buffer to hold operators
  @note This function is only supported by 3GPP applications.
  @return Whether the preferred operators were successfully retrieved.
  @retval QL_ERR_OK successful
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_get_operators(QL_SIM_SLOT_E slot, ql_sim_operator_list_t *list);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Enables the PIN on an application.
  @param [in] slot Slot to be used.
  @param [in] app_type Application type.
  @param [in] pin PIN to be used.
  @param [in] pin_value PIN value. NULL terminated.
  @return Whether the PIN was successfully enabled.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_enable_pin(QL_SIM_SLOT_E slot, QL_SIM_APP_TYPE_E app_type, 
                             QL_SIM_PIN_E pin, const char *pin_value);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Disables the PIN on an application.
  @param [in] slot Slot to be used.
  @param [in] app_type Application type.
  @param [in] pin PIN to be used.
  @param [in] pin_value PIN value. NULL terminated.
  @return Whether the PIN was successfully disabled.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_disable_pin(QL_SIM_SLOT_E slot, QL_SIM_APP_TYPE_E app_type, 
                             QL_SIM_PIN_E pin, const char *pin_value);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Verifies the PIN value of an application.
  @param [in] slot Slot to be used.
  @param [in] app_type Application type.
  @param [in] pin PIN to be used.
  @param [in] pin_value PIN value. NULL terminated.
  @note PIN must be enabled before calling this function.
  @return Whether the PIN was successfully verified.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_verify_pin(QL_SIM_SLOT_E slot, QL_SIM_APP_TYPE_E app_type, 
                             QL_SIM_PIN_E pin, const char *pin_value);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Changes the PIN value of an application.
  @param [in] slot Slot to be used.
  @param [in] app_type Application type.
  @param [in] pin PIN to be used.
  @param [in] old_pin_value Old PIN value. NULL terminated.
  @param [in] new_pin_value New PIN value. NULL terminated.
  @return Whether the PIN was successfully changed.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_change_pin(QL_SIM_SLOT_E slot, QL_SIM_APP_TYPE_E app_type, 
                             QL_SIM_PIN_E pin, const char *old_pin_value, const char *new_pin_value);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Unblocks a blocked PIN using the PUK code.
  @param [in] slot Slot to be used.
  @param [in] app_type Application type.
  @param [in] pin PIN to be used.
  @param [in] puk_value PUK value.  NULL terminated.
  @param [in] pin_value New PIN value.  NULL terminated.
  @note The user must pass PUK1 to unblock PIN1 or PUK2 to unblock PIN2.
  @return Whether the PIN was successfully unblocked.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_unblock_pin(QL_SIM_SLOT_E slot, QL_SIM_APP_TYPE_E app_type, 
                             QL_SIM_PIN_E pin, const char *puk_value, const char *pin_value);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Retrieves the card info stored on a card.
  @param [in] slot Slot to be used.
  @param [out] p_info Pointer of ql_sim_card_info_t.
  @return Whether the card info was successfully retrieved.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_get_card_info(QL_SIM_SLOT_E slot, ql_sim_card_info_t *p_info);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Reads data from a specific file on a specified application on the card.
  @param [in] slot Slot to be used.
  @param [in] app_type Application type.
  @param [inout] p_file Pointer of ql_sim_file_t.
  @return Whether the file was successfully read.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_read_file(QL_SIM_SLOT_E slot, QL_SIM_APP_TYPE_E app_type, ql_sim_file_t *p_file);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Writes data to a specific file on a specified application on the card. 
  @param [in] slot Slot to be used.
  @param [in] app_type Application type.
  @param [in] p_file Pointer of ql_sim_file_t
  @note The type of file is determined by the record number field,
    which indicates a transparent file when zero and a record-based file otherwise.
  @return Whether the file was successfully written.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_write_file(QL_SIM_SLOT_E slot, QL_SIM_APP_TYPE_E app_type, ql_sim_file_t *p_file);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Retrieves the info of a specific file on a specified application on the card.
  @param [in] slot Slot to be used.
  @param [in] app_type Application type.
  @param [inout] p_info Pointer of ql_sim_file_info_t.
  @return Whether the file info was successfully retrieved.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_get_file_info(QL_SIM_SLOT_E slot, QL_SIM_APP_TYPE_E app_type, 
                                 ql_sim_file_info_t *p_info);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Reads phone book on a specified application on the card.
  @param [in] slot Slot to be used.
  @param [in] app_type Spplication type.
  @param [in] pb_path Phone book path. NULL terminated.
  @param [in] record_idx Record index to read. Starts from 1.
  @param [out] p_record Pointer of ql_sim_phone_book_record_t.
  @return Whether the phone book record was successfully retrieved.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_read_phone_book(QL_SIM_SLOT_E slot, QL_SIM_APP_TYPE_E app_type,
                                    const char *pb_path, uint8_t record_idx,
                                    ql_sim_phone_book_record_t *p_record);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Writes phone book on a specified application on the card.
  @param [in] slot Slot to be used.
  @param [in] app_type Application type.
  @param [in] pb_path Phone book path. NULL terminated.
  @param [in] record_idx Record index to write. Starts from 1.
  @param [in] p_record Pointer of ql_sim_phone_book_record_t.
  @note If p_record->name[0] = 0 and p_record->number[0] = 0, record will be deleted.
  @return Whether the phone book record was successfully saved.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_write_phone_book(QL_SIM_SLOT_E slot, QL_SIM_APP_TYPE_E app_type, 
                                    const char *pb_path, uint8_t record_idx,
                                    ql_sim_phone_book_record_t *p_record);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Opens a logical channel on a UICC card.
  @param [in] slot Slot to be used.
  @param [out] channel_id Channel opened.
  @return Whether the logical channel was successfully opened.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_open_logical_channel(QL_SIM_SLOT_E slot, uint8_t *channel_id);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Closes a logical channel on a UICC card.
  @param [in] slot Slot to be used.
  @param [in] channel_id Channel to be closed.
  @return Whether the logical channel was successfully closed.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_close_logical_channel(QL_SIM_SLOT_E slot, uint8_t channel_id);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Sends an APDU to the card.
  @param [in] slot Slot to be used.
  @param [in] channel_id Channel to be used.
  @param [inout] p_apdu Pointer of ql_sim_apdu_t.
  @note You must call ql_sim_open_logical_channel before sending an APDU.
  @return Whether the APDU was successfully sent.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_send_apdu(QL_SIM_SLOT_E slot, uint8_t channel_id, ql_sim_apdu_t *p_apdu);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief  Sets SIM card status callback handler
  @param[in] cb call back handler.
  @return Whether the card status callback handler was successfully set.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_set_card_status_cb(ql_sim_card_status_cb_f cb);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Switches slot.
  @param [in] log_slot Logical slot to be switched.
  @param [in] phy_slot Physical slot to be switched.
  @return Whether the slot was successfully switched.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_switch_slot(QL_SIM_SLOT_E log_slot, QL_SIM_PHY_SLOT_E phy_slot);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Gets active slots.
  @param [Out] p_active_slots Active slots.
  @return Whether the active slots were successfully obtained.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_SERVICE_NOT_READY service is not ready, need to retry.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_get_active_slots(ql_sim_active_slots_t *p_active_slots);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Registration server error callback. Currently, only if the server exits abnormally, 
  the callback function will be executed, and the error code is QL_ERR_ABORTED;
  @param[in] cb  Callback function 
  @return
  QL_ERR_OK - successful
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_sim_set_service_error_cb(ql_sim_service_error_cb_f cb);

//int ql_sim_switch_slot(QL_SIM_SLOT_E log_slot, QL_SIM_PHY_SLOT_E phy_slot);
//int ql_sim_get_active_slots(ql_sim_active_slots_t *p_active_slots);

#ifdef __cplusplus
}
#endif

#endif  /* __QL_SIM_H__ */