mbtk/libql_lib_v2_rilv2/ql_ms_sim.c

/*-----------------------------------------------------------------------------------------------*/
/**
  @file ql_ms_sim.h 
  @brief subscriber identity module service API, support Dual Sim Dual Active(DSDA). 
*/
/*-----------------------------------------------------------------------------------------------*/

/*-------------------------------------------------------------------------------------------------
  Copyright (c) 2021 Quectel Wireless Solution, Co., Ltd. All Rights Reserved.
  Quectel 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
  --------   ---          ----------------------------------------------------------
  20200720   solomon.cui  Created .
-------------------------------------------------------------------------------------------------*/
#ifndef __QL_MS_SIM_H__
#define __QL_MS_SIM_H__

#ifdef __cplusplus
extern "C" {
#endif

#include "ql_type.h"
#include "ql_sim.h"

typedef void (*ql_ms_sim_card_status_cb_f)(int sim_id, ql_sim_card_info_t *p_info);

/*-----------------------------------------------------------------------------------------------*/
/**
  @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_ms_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_ms_sim_deinit(void);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Gets the IMSI (for 3GPP) or IMSI_M (for 3GPP2) from the SIM in ASCII form.
  @param [in] sim_id sim_id 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_ms_sim_get_imsi(int sim_id, 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] sim_id sim_id 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_ms_sim_get_iccid(int sim_id, char *iccid, int iccid_len);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Retrieves the device phone number stored on the card.
  @param [in] sim_id sim_id 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_ms_sim_get_phone_num(int sim_id, 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] sim_id sim_id 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_ms_sim_get_operators(int sim_id, ql_sim_operator_list_t *list);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Enables the PIN on an application.
  @param [in] sim_id sim_id 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_ms_sim_enable_pin(int sim_id, 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] sim_id sim_id 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_ms_sim_disable_pin(int sim_id, 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] sim_id sim_id 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_ms_sim_verify_pin(int sim_id, 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] sim_id sim_id 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_ms_sim_change_pin(int sim_id, 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] sim_id sim_id 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_ms_sim_unblock_pin(int sim_id, 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] sim_id sim_id to be used.
  @param [out] p_info Pointer of ql_ms_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_ms_sim_get_card_info(int sim_id, ql_sim_card_info_t *p_info);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Reads data from a specific file on a specified application on the card.
  @param [in] sim_id sim_id to be used.
  @param [in] app_type Application type.
  @param [inout] p_file Pointer of ql_ms_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_ms_sim_read_file(int sim_id, 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] sim_id sim_id to be used.
  @param [in] app_type Application type.
  @param [in] p_file Pointer of ql_ms_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_ms_sim_write_file(int sim_id, 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] sim_id sim_id to be used.
  @param [in] app_type Application type.
  @param [inout] p_info Pointer of ql_ms_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_ms_sim_get_file_info(int sim_id, 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] sim_id sim_id 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_ms_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_ms_sim_read_phone_book(int sim_id, 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] sim_id sim_id 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_ms_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_ms_sim_write_phone_book(int sim_id, 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] sim_id sim_id 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_ms_sim_open_logical_channel(int sim_id, uint8_t *channel_id);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Closes a logical channel on a UICC card.
  @param [in] sim_id sim_id 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_ms_sim_close_logical_channel(int sim_id, uint8_t channel_id);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief  Sends an APDU to the card.
  @param [in] sim_id sim_id to be used.
  @param [in] channel_id Channel to be used.
  @param [inout] p_apdu Pointer of ql_ms_sim_apdu_t.
  @note You must call ql_ms_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_ms_sim_send_apdu(int sim_id, uint8_t channel_id, ql_sim_apdu_t *p_apdu);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief  Sets SIM card status callback handler
  @param [in] sim_id sim_id to be used.
  @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_ms_sim_set_card_status_cb(int sim_id, ql_ms_sim_card_status_cb_f cb);
/*-----------------------------------------------------------------------------------------------*/
/**
  @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_ms_sim_set_service_error_cb(ql_sim_service_error_cb_f cb);

int ql_ms_sim_switch_slot(int sim_id, QL_SIM_PHY_SLOT_E phy_slot);
int ql_ms_sim_get_active_slots(int sim_id, ql_sim_active_slots_t *p_active_slots);

#ifdef __cplusplus
}
#endif


#endif