# 一键拨号

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# 功能概述

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

# 一键拨号API

## 头文件

*easy_datacall.h*

## 函数概览

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

## 函数详解

### qapp_easy_datacall

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

- **函数原型**

```c
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*](#qappeasydatacallconfigt) |
| *easy_datacall_cb* | 输入 | *qapp_easy_datacall_cb_ptr* | 回调函数指针，拨号全流程状态变更时触发回调；详见 [*qapp_easy_datacall_cb_ptr*](#qappeasydatacallcbptr) |

- **返回值说明**  
  *QAPP_EASY_DATACALL_OK*：函数执行成功  
  其他值：函数执行失败；详见 [*qapp_easy_datacall_error_e*](#qappeasydatacallerrore)

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

#### qapp_easy_datacall_cb_ptr

- **函数原型**

```c
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*](#qappeasydatacallevente) |
| *ctx* | 输入 | void | 业务自定义上下文 |

- **返回值说明**  
  无

### **qapp_easy_datacall_reconnect_stop**

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

- **函数原型**

```c
qapp_easy_datacall_error_e qapp_easy_datacall_reconnect_stop(void);
```

- **参数说明**  
  无

- **返回值说明**  
  *QAPP_EASY_DATACALL_OK*：函数执行成功  
  其他值：函数执行失败；详见 [*qapp_easy_datacall_error_e*](#qappeasydatacallerrore)

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

## 结构体定义

### qapp_easy_datacall_config_t

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

```c
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*](#qappeasydatacallpdpconfig_t) |
| *retry_config* | *qapp_easy_datacall_reconnect_config_t* | 断线重连配置参数；详见 [*qapp_easy_datacall_reconnect_config_t*](#qappeasydatacallreconnectconfig_t) |

### qapp_easy_datacall_pdp_config_t

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

```cpp
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*](#qosadatacallconntypee) |
| *apn* | char | APN |
| *ip_type* | *qosa_pdp_ip_type_e* | IP类型；详见 [*qosa_pdp_ip_type_e*](#qosapdpiptypee) |
| *auth_type* | *qosa_pdp_auth_type_e* | 鉴权类型；详见 [*qosa_pdp_auth_type_e*](#qosapdpauthtypee) |
| *auth_username* | char | 用户名 |
| *auth_password* | char | 密码 |

### qapp_easy_datacall_reconnect_config_t

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

```cpp
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 | 是否开启断线重连功能<br>*QOSA_TRUE*：开启<br>*QOSA_FALSE*：关闭 |
| *reg_timeout* | qosa_uint32_t | 网络注册超时时间；单位：秒 |
| *datacall_reconnect_max_count* | qosa_uint8_t | 重连最大尝试次数 |
| *datacall_timeout* | qosa_uint8_t | 单次拨号最大超时时间；单位：秒 |

## 枚举定义

### qapp_easy_datacall_error_e

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

```c
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

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

```c
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

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

```java
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类型枚举定义如下：

```cpp
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

鉴权类型枚举定义如下：

```cpp
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 |

# 应用逻辑流程图

```{figure} images/board_Y08swDZmQhUZpXb0quKcAawingd.jpg
:align: center
:alt: image
```

# 示例代码

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