一键拨号¶

功能概述¶

一键拨号功能内部集成多个网络和数据拨号接口，可一站式完成PDP Profile配置、数据拨号发起、断线自动重连等流程，旨在为用户提供一套方便快捷的数据拨号与自动重连Open API接口。

一键拨号API¶

头文件¶

easy_datacall.h

函数概览¶

函数	说明
qapp_easy_datacall()	启动一键拨号流程
qapp_easy_datacall_reconnect_stop()	关闭一键拨号内置的自动重连机制

函数详解¶

qapp_easy_datacall¶

功能描述
启动一键拨号流程。此函数封装完整数据拨号流程，可根据传入的配置参数自动完成PDP上下文配置、鉴权参数配置、等待网络附着、发起数据拨号等流程，并且配置开启时附带断线自动重连逻辑。用户可通过回调函数获取拨号成功、失败、断开、重连及网络未注册等事件。
函数原型

qapp_easy_datacall_error_e qapp_easy_datacall(qapp_easy_datacall_config_t config,qapp_easy_datacall_cb_ptr easy_datacall_cb);

参数说明

参数名	输入/输出	类型	说明
config	输入	qapp_easy_datacall_config_t	一键拨号配置参数；详见 qapp_easy_datacall_config_t
easy_datacall_cb	输入	qapp_easy_datacall_cb_ptr	回调函数指针，拨号全流程状态变更时触发回调；详见 qapp_easy_datacall_cb_ptr

返回值说明
QAPP_EASY_DATACALL_OK：函数执行成功
其他值：函数执行失败；详见 qapp_easy_datacall_error_e

备注

此函数同时承载一键拨号与可选自动重连能力。
业务不再需要自动重连时，建议调用 qapp_easy_datacall_reconnect_stop() 关闭自动重连机制。
停止重连仅关闭重试逻辑，不会主动断开当前已建立的数据链路。

qapp_easy_datacall_cb_ptr¶

函数原型

typedef void (*qapp_easy_datacall_cb_ptr)(qapp_easy_datacall_event_e event_id, void *ctx);

参数说明

参数名	输入/输出	类型	说明
event_id	输入	qapp_easy_datacall_event_e	一键拨号事件标识；详见 qapp_easy_datacall_event_e
ctx	输入	void	业务自定义上下文

返回值说明
无

qapp_easy_datacall_reconnect_stop¶

功能描述
关闭一键拨号内置的自动重连机制。调用此函数后，系统将结束内部创建的重连定时器、消息队列、任务等运行资源，停止由 qapp_easy_datacall() 开启的自动重连流程，后续不会再继续执行断线重连处理。
函数原型

qapp_easy_datacall_error_e qapp_easy_datacall_reconnect_stop(void);

参数说明
无
返回值说明
QAPP_EASY_DATACALL_OK：函数执行成功
其他值：函数执行失败；详见 qapp_easy_datacall_error_e

备注

此函数仅用于停止一键拨号内置的自动重连机制，不用于主动断开已建立的数据连接。
如需重新启用一键拨号流程和自动重连能力，需要重新调用 qapp_easy_datacall()。
建议在不再需要自动重连或应用退出相关业务流程前调用此函数，避免继续占用内部资源。

结构体定义¶

qapp_easy_datacall_config_t¶

一键拨号配置参数结构体定义如下：

typedef struct
{
    qapp_easy_datacall_pdp_config_t pdp_config;
    qapp_easy_datacall_reconnect_config_t retry_config;
} qapp_easy_datacall_config_t;

参数	类型	说明
pdp_config	qapp_easy_datacall_pdp_config_t	PDP配置参数；详见 qapp_easy_datacall_pdp_config_t
retry_config	qapp_easy_datacall_reconnect_config_t	断线重连配置参数；详见 qapp_easy_datacall_reconnect_config_t

qapp_easy_datacall_pdp_config_t¶

PDP配置参数结构体定义如下：

typedef struct
{
    qosa_uint8_t simid;                                 
    qosa_uint8_t pdpid;                                 
    qosa_datacall_conn_type_e conn_type;                
    char apn[QOSA_APN_MAX_LEN + 1];                    
    qosa_pdp_ip_type_e ip_type;                       
    qosa_pdp_auth_type_e auth_type;                    
    char auth_username[QOSA_PDP_USER_NAME_MAX_LEN + 1]; 
    char auth_password[QOSA_PDP_USER_PWD_MAX_LEN + 1]; 

} qapp_easy_datacall_pdp_config_t;

参数	类型	说明
simid	qosa_uint8_t	SIM ID
pdpid	qosa_uint8_t	PDP上下文ID
conn_type	qosa_datacall_conn_type_e	数据拨号连接类型；详见 qosa_datacall_conn_type_e
apn	char	APN
ip_type	qosa_pdp_ip_type_e	IP类型；详见 qosa_pdp_ip_type_e
auth_type	qosa_pdp_auth_type_e	鉴权类型；详见 qosa_pdp_auth_type_e
auth_username	char	用户名
auth_password	char	密码

qapp_easy_datacall_reconnect_config_t¶

断线重连配置参数结构体定义如下：

typedef struct
{
    qosa_bool_t reconnect;                      
    qosa_uint32_t reg_timeout;                    

    qosa_uint8_t datacall_reconnect_max_count;      
    qosa_uint8_t datacall_timeout;                

} qapp_easy_datacall_reconnect_config_t;

参数	类型	说明
reconnect	qosa_bool_t	是否开启断线重连功能 QOSA_TRUE：开启 QOSA_FALSE：关闭
reg_timeout	qosa_uint32_t	网络注册超时时间；单位：秒
datacall_reconnect_max_count	qosa_uint8_t	重连最大尝试次数
datacall_timeout	qosa_uint8_t	单次拨号最大超时时间；单位：秒

枚举定义¶

qapp_easy_datacall_error_e¶

一键拨号功能结果码枚举定义如下：

typedef enum {
    QAPP_EASY_DATACALL_OK = 0,
    QAPP_EASY_DATACALL_ERR_INVALID_PARAM,
    QAPP_EASY_DATACALL_ERR_NETWORK_ISSUE,
    QAPP_EASY_DATACALL_ERR_EXECUTE_FAIL,
    QAPP_EASY_DATACALL_ERR_MEMORY_FAILURE,
    QAPP_EASY_DATACALL_ERR_REPEAT_ACT,
} qapp_easy_datacall_error_e;

成员	说明
QAPP_EASY_DATACALL_OK	函数执行成功
QAPP_EASY_DATACALL_ERR_INVALID_PARAM	非法参数
QAPP_EASY_DATACALL_ERR_NETWORK_ISSUE	网络异常
QAPP_EASY_DATACALL_ERR_EXECUTE_FAIL	函数执行失败
QAPP_EASY_DATACALL_ERR_MEMORY_FAILURE	内存分配失败
QAPP_EASY_DATACALL_ERR_REPEAT_ACT	重复操作

qapp_easy_datacall_event_e¶

一键拨号事件标识枚举定义如下：

typedef enum {
    QAPP_EASY_DATACALL_SUCC = 0,
    QAPP_EASY_DATACALL_FAIL,
    QAPP_EASY_DATACALL_DISCONNECT,
    QAPP_EASY_DATACALL_RECONNECT,
    QAPP_EASY_DATACALL_NETWORK_NOT_REG,
} qapp_easy_datacall_event_e;

成员	说明
QAPP_EASY_DATACALL_SUCC	数据拨号成功
QAPP_EASY_DATACALL_FAIL	数据拨号失败
QAPP_EASY_DATACALL_DISCONNECT	连接断开
QAPP_EASY_DATACALL_RECONNECT	断线重连
QAPP_EASY_DATACALL_NETWORK_NOT_REG	网络未注册

qosa_datacall_conn_type_e¶

数据拨号连接类型枚举定义如下：

typedef enum
{
    QOSA_DATACALL_CONN_USBNET = 1, 
    QOSA_DATACALL_CONN_PPP,      
    QOSA_DATACALL_CONN_TCPIP,     
    QOSA_DATACALL_CONN_UNDEFINED,
    QOSA_DATACALL_CONN_MAX,
} qosa_datacall_conn_type_e;

成员	说明
QOSA_DATACALL_CONN_USBNET	USBNET
QOSA_DATACALL_CONN_PPP	PPP
QOSA_DATACALL_CONN_TCPIP	TCP/IP
QOSA_DATACALL_CONN_UNDEFINED	未定义
QOSA_DATACALL_CONN_MAX	最大连接类型数量

qosa_pdp_ip_type_e¶

IP类型枚举定义如下：

typedef enum
{
    QOSA_PDP_INVALID = 0, 
    QOSA_PDP_IPV4 = 1,    
    QOSA_PDP_IPV6 = 2,    
    QOSA_PDP_IPV4V6 = 3  
} qosa_pdp_ip_type_e;

成员	说明
QOSA_PDP_INVALID	无效IP类型
QOSA_PDP_IPV4	IPv4
QOSA_PDP_IPV6	IPv6
QOSA_PDP_IPV4V6	IPv4v6

qosa_pdp_auth_type_e¶

鉴权类型枚举定义如下：

typedef enum
{
    QOSA_PDP_AUTH_TYPE_NONE = 0, 
    QOSA_PDP_AUTH_TYPE_PAP = 1, 
    QOSA_PDP_AUTH_TYPE_CHAP = 2,
} qosa_pdp_auth_type_e;

成员	说明
QOSA_PDP_AUTH_TYPE_NONE	无鉴权
QOSA_PDP_AUTH_TYPE_PAP	PAP
QOSA_PDP_AUTH_TYPE_CHAP	CHAP

应用逻辑流程图¶

示例代码¶

完整示例代码请查看 https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/application/one_touch/datacall.c