mbtk/libql_lib_v2_rilv2/ql_ms_nw.c

/*-----------------------------------------------------------------------------------------------*/
/**
  @file ql_ms_nw.h 
  @brief network registration 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
  --------   ---          ----------------------------------------------------------
  20200518   rambo.shan   Add WEA and ETWS alert indication.
  20191225   stan.li      Modify function description.
  20191202   stan.li      change the name of ql_nw_pref_nwmode_roming_info_t
  20190528   stan.li      Created .
-------------------------------------------------------------------------------------------------*/

#ifndef __QL_MS_NW_H__
#define __QL_MS_NW_H__

#ifdef __cplusplus
extern "C" {
#endif

#include "ql_type.h"
#include "ql_nw.h"

typedef void (*ql_ms_nw_voice_reg_ind_cb)(int sim_id, ql_nw_reg_status_info_t *p_info);

typedef void (*ql_ms_nw_data_reg_ind_cb)(int sim_id, ql_nw_reg_status_info_t *p_info);

typedef void (*ql_ms_nw_signal_strength_ind_cb)(int sim_id, ql_nw_signal_strength_info_t *p_info, QL_NW_SIGNAL_STRENGTH_LEVEL_E level);

typedef void (*ql_ms_nw_cell_access_status_ind_cb)(int sim_id, QL_NW_CELL_ACCESS_STATE_TYPE_E status);

typedef void (*ql_ms_nw_nitz_time_update_ind_cb)(int sim_id, ql_nw_nitz_time_info_t *p_info);

typedef void (*ql_ms_nw_network_scan_async_cb)(int sim_id, int async_index, ql_nw_scan_result_list_info_t *p_info);

typedef void (*ql_ms_nw_wea_reg_ind_cb)(int sim_id, ql_nw_wea_alert_info_t *p_info);

typedef void (*ql_ms_nw_etws_reg_ind_cb)(int sim_id, ql_nw_etws_alert_info_t *p_info);

/*-----------------------------------------------------------------------------------------------*/
/**
  @brief Initialize NW service.
  @note You must call this function before other functions can be used in this module.
  @return Whether the NW service was successfully intialized.
  @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_nw_init(void);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief  Deinitializes NW service.
  @return Whether the NW service was deinitialized successfully.
  @retval QL_ERR_OK successful.
  @retval Other error code defined by ql_type.h.
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_deinit(void);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief scan network status.
  @param[in] sim id number
  @param[out] async_index The index of request msg
  @param[in] async_cb The callback function of request msg
  @return Whether to successfully trigger the network scan operation
  @retval QL_ERR_OK  successful
  @retval QL_ERR_NOT_INIT  uninitialized
  @retval QL_ERR_SERVICE_NOT_READY  service is not ready
  @retval QL_ERR_INVALID_ARG  Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_network_scan(int sim_id, int *async_index, ql_ms_nw_network_scan_async_cb async_cb);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief set power mode.
  @param[in] sim id number
  @param[in] lower_mode, defined by QL_NW_LOWER_POWER_MASK_XXX
  @return Whether to successfully set the power mode
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_set_power_mode(int sim_id, uint8_t lower_mode);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief set perferred NW mode and roaming indicator.
  @param[in] sim id number
  @param[in] p_info Pointer that point to ql_nw_pref_nwmode_roaming_info_t
  @return Whether to successfully set nwmode and roaming
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_set_pref_nwmode_roaming(int sim_id, ql_nw_pref_nwmode_roaming_info_t *p_info);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief get perferred NW mode and roaming indicator.
  @param[in] sim id number
  @param[out] p_info Pointer that point to ql_nw_pref_nwmode_roaming_info_t 
  @return Whether to successfully get nwmode and roaming
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_get_pref_nwmode_roaming(int sim_id, ql_nw_pref_nwmode_roaming_info_t *p_info);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief get mobile operator name.
  @param[in] sim id number
  @param[out] p_info Pointer that point to ql_nw_mobile_operator_name_info_t
  @return Whether to successfully get the mobile operator name
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_get_mobile_operator_name(int sim_id, ql_nw_mobile_operator_name_info_t *p_info);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief get cell information.
  @param[in] sim id number
  @param[out] p_info Pointer that point to ql_nw_cell_info_t
  @return Whether to successfully get the cell information
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_get_cell_info(int sim_id, ql_nw_cell_info_t *p_info);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief get voice registration status.
  @param[in] sim id number
  @param[out] p_info Pointer that point to ql_nw_reg_status_info_t
  @return Whether to successfully get the voice registration status
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_get_voice_reg_status(int sim_id, ql_nw_reg_status_info_t *p_info);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief get data registration status.
  @param[in] sim id number
  @param[out] p_info Pointer that point to ql_nw_reg_status_info_t
  @return Whether to successfully get the data registration status
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_get_data_reg_status(int sim_id, ql_nw_reg_status_info_t *p_info);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief get current signal strength.
  @param[in] sim id number
  @param[out] p_info Pointer that point to ql_nw_signal_strength_info_t
  @param[out] p_level: signal strength level
  @return Whether to successfully get the signal strength
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_get_signal_strength(int sim_id, ql_nw_signal_strength_info_t *p_info, QL_NW_SIGNAL_STRENGTH_LEVEL_E* p_level);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief get current cell acccess status.
  @param[in] sim id number
  @param[out] p_info Pointer that point to QL_NW_CELL_ACCESS_STATE_TYPE_E
  @return Whether to successfully get the cell access status
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_get_cell_access_status(int sim_id, QL_NW_CELL_ACCESS_STATE_TYPE_E *p_info);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief get network time.
  @param[in] sim id number
  @param[out] p_info Pointer that point to ql_nw_nitz_time_info_t 
  @return Whether to successfully get the network time
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_get_nitz_time_info(int sim_id, ql_nw_nitz_time_info_t *p_info);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief register voice registration event.
  @param[in] sim id number
  @param[in] cb_func Voice registration indication callback function
  @return Whether the voice registration event was successfully registered.
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
 */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_set_voice_reg_ind_cb(int sim_id, ql_ms_nw_voice_reg_ind_cb cb_func);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief register data registration event.
  @param[in] sim id number
  @param[in] cb_func Data registration indication callback function
  @return Whether the data registration event was successfully registered.
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_set_data_reg_ind_cb(int sim_id, ql_ms_nw_data_reg_ind_cb cb_func);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief register signal strength event.
  @param[in] sim id number
  @param[in] cb_func Signal strength indication callback function
  @return Whether the signal strength event was successfully registered
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_set_signal_strength_ind_cb(int sim_id, ql_ms_nw_signal_strength_ind_cb cb_func);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief register cell access status event.
  @param[in] sim id number
  @param[in] cb_func Cell access status indication callback function
  @return Whether the cell access status event was successfully registered
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_set_cell_access_status_ind_cb(int sim_id, ql_ms_nw_cell_access_status_ind_cb cb_func);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief register network time event.
  @param[in] sim id number
  @param[in] cb_func nitz time update indication callback function
  @return Whether the network time event was successfully registered
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_set_nitz_time_update_ind_cb(int sim_id, ql_ms_nw_nitz_time_update_ind_cb cb_func);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief register wea alert event.
  @param[in] sim id number
  @param[in] cb_func wea alert indication callback function
  @return Whether the network time event was successfully registered
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_set_wea_alert_ind_cb(int sim_id, ql_ms_nw_wea_reg_ind_cb cb_func);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief register etws alert event.
  @param[in] sim id number
  @param[in] cb_func etws alert indication callback function
  @return Whether the network time event was successfully registered
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_set_etws_alert_ind_cb(int sim_id, ql_ms_nw_etws_reg_ind_cb cb_func);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief set wea alert config.
  @param[in] sim id number
  @param[in] item Items to set.
  @param[in] p_info Pointer that point to ql_nw_wea_config_t.
  @return Whether to successfully set the wea config.
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_set_wea_config(int sim_id, int item, ql_nw_wea_config_t *p_info);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief  Gets wea config.
  @param[in] sim id number
  @param[out] p_config wea config.
  @return Whether the wea config was successfully obtained.
  @retval QL_ERR_OK successful.
  @retval QL_ERR_INVALID_ARG invalid argument.
  @retval QL_ERR_UNKNOWN unknown error, failed to connect to service.
  @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_nw_get_wea_config(int sim_id, ql_nw_wea_config_t *p_config);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief set etws alert config.
  @param[in] sim id number
  @param[in] etws config.
  @return Whether to successfully set the etws config.
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_set_etws_config(int sim_id, uint8_t enable_etws);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief get etws alert config.
  @param[in] sim id number
  @param[out] p_enable_etws Pointer.
  @return Whether to successfully set the etws config.
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_get_etws_config(int sim_id, uint8_t* p_enable_etws);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief get high capability subscription.
  @param[in] sim id number
  @param[out] p_high_cap pointer that point to QL_NW_BIND_SUB_TYPE_E
  @return Whether the high capability subscription was successfully obtained.
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_get_high_cap_sub(QL_NW_BIND_SUB_TYPE_E *p_high_cap);

/*-----------------------------------------------------------------------------------------------*/
/** 
  @brief set the SIM card index that can uniquely register to the 5G network. 
  the main difference between high and non-high capability subscription is that high capability 
  subscription can register to 5G network while non-high capability subscription can only 
  register to LTE or GSM.
  @param[in] sim id number
  @param[in] high_cap high capability subscription 
  @return Whether to successfully set the high capability subscription.
  @retval QL_ERR_OK successful
  @retval QL_ERR_NOT_INIT uninitialized
  @retval QL_ERR_SERVICE_NOT_READY service is not ready
  @retval QL_ERR_INVALID_ARG Invalid arguments
  @retval Other error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_set_high_cap_sub(QL_NW_BIND_SUB_TYPE_E high_cap);

/*-----------------------------------------------------------------------------------------------*/
/**
  @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] sim id number
  @param[in] cb  Callback function 
  @return
  QL_ERR_OK - successful
  Other - error code defined by ql_type.h
  */
/*-----------------------------------------------------------------------------------------------*/
int ql_ms_nw_set_service_error_cb(ql_nw_service_error_cb_f cb);

#ifdef __cplusplus
}
#endif


#endif