SOCKET 开发指导_Rev1.1

修订记录

版本	日期	作者	审核	修订内容
Rev1.0	2026-01-23	zw	zlc	创建文档
Rev1.1	2026-03-27	zw	zlc	优化文档内容。

1 概述

本文档介绍 LTE-EC71X SOCKET2接口 API 情况，使用流程可参考如下流程图。

上述流程为基于蜂窝网络Cat1模组的Socket通信流程，主要包括初始化、网络注册、数据拨号、Socket连接建立、数据传输及异常处理等环节。具体流程如下：

SOCKET任务启动：程序开始执行Socket通信任务。
网络注册： ○ 检查是否成功注册到蜂窝网络。 ○ 若注册失败，则循环等待或重试，直至注册成功。
数据拨号（Data Call）： ○ 网络注册成功后，发起数据拨号，建立PS域数据连接。 ○ 若拨号失败，则停止并释放资源，流程结束；若成功，则继续下一步。
初始化Socket信息：准备Socket通信所需的参数（如服务器地址、端口等）。
创建Socket并连接服务器：调用?Liot_SocketOpen?创建Socket并尝试连接服务器。连接结果通过回调函数异步通知。
回调事件处理：根据不同的回调事件进行相应处理： ○ LIOT_SOCKET_CONNECT_SUCCESS：连接成功，进入数据收发阶段。 ○ LIOT_SOCKET_RECV_DATA：接收到服务器下发的数据，进行业务处理。 ○ LIOT_SOCKET_DNS_FAIL：域名解析失败，触发异常处理。 ○ LIOT_SOCKET_CONNECT_FAIL：连接服务器失败，触发异常处理。 ○ LIOT_SOCKET_DISCONNECT：连接断开，触发异常处理。
数据收发： ○ 连接成功后，可通过Liot_SocketSend接口向服务器发送数据。 ○ 接收数据时，在LIOT_SOCKET_RECV_DATA事件中处理。
异常错误处理：当出现DNS失败、连接失败或连接断开等异常时，进入异常处理流程，停止数据拨号、释放资源，并结束任务。
正常结束：当通信完成或异常退出时，调用liot_stop_data_call接口停止数据拨号，释放相关资源，流程结束。

整个流程采用异步回调机制，确保网络注册、数据拨号和Socket连接各环节按序执行，并具备异常恢复能力。

2 API 函数概览

函数	说明
`Liot_SocketOpen()`	创建Socket链接，连接服务器。
`Liot_SocketSend()`	发送socket数据。
`Liot_SocketGetStatus()`	获取套接字的当前状态。
`Liot_SocketClose()`	关闭套接字。

3 类型说明

3.1 Liot_SocketEvent_e

枚举定义：

typedef enum
{
    LIOT_SOCKET_CONNECT_SUCCESS = 0,
    LIOT_SOCKET_DNS_FAIL = 1,
    LIOT_SOCKET_CONNECT_FAIL = 2,
    LIOT_SOCKET_RECV_DATA = 3,
    LIOT_SOCKET_DISCONNECT = 4,
}Liot_SocketEvent_e;

枚举说明

变量	说明
LIOT_SOCKET_CONNECT_SUCCESS	连接服务器成功事件。
LIOT_SOCKET_DNS_FAIL	DNS解析失败事件。
LIOT_SOCKET_CONNECT_FAIL	连接服务器失败事件。
LIOT_SOCKET_RECV_DATA	接收数据事件。
LIOT_SOCKET_DISCONNECT	断开服务器事件。

3.2 Liot_Socket_Type_e

枚举定义：

typedef enum
{
    LIOT_SOCKET_TYPE_TCP = 0,
    LIOT_SOCKET_TYPE_UDP = 1,
}Liot_Socket_Type_e;

枚举说明

变量	说明
LIOT_SOCKET_TYPE_TCP	socket连接类型为TCP。
LIOT_SOCKET_TYPE_UDP	socket连接类型为UDP。

3.3 Liot_SocketInfo_t

结构体定义：

typedef struct
{
    int socket_fd;          // socket fd 0-7
    uint8_t cid;            // cid 0-7
    uint8_t socket_type;    //TCP UDP
    uint8_t host[256];      //host name 域名或者IP
    uint16_t port;          //端口号
    uint16_t local_port;    //本地端口
    int32_t keepidle;       //心跳检测间隔
    int32_t keepinterval;   //心跳检测间隔
    int32_t keepcount;      //心跳检测次数
}Liot_SocketInfo_t;

结构体变量说明

变量	说明
socket_fd	socket文件描述符。出参，socket创建成功后有效。
cid	cid 0-7。网络拨号的通道号，通常默认使用 CID 1。入参
socket_type	TCP: LIOT_SOCKET_TYPE_TCP UDP: LIOT_SOCKET_TYPE_UDP 入参
host	host name 域名或者IP。入参
port	服务器端口号。入参
local_port	本地端口号。入参
keepidle	连接空闲多久后开始探测。单位：秒。范围：1 到 0x7FFFFFFF (2,147,483,647) 秒之间，0为默认值7200秒（2小时）。入参
keepinterval	心跳探测包之间的时间间隔。单位：秒。入参
keepcount	心跳最大探测次数。入参

4 API 函数详解

4.1 Liot_SocketOpen

创建Socket链接，连接服务器。

声明

int32_t Liot_SocketOpen(Liot_SocketInfo_t *info, liot_socket_callback callback, void *userdata);

参数

info：

[In] 创建socket使用的参数，见结构体Liot_SocketInfo_t。

callback：

[In] 套接字事件回调函数。回调函数声明如下：

typedef void (*liot_socket_callback)(Liot_SocketEvent_e event, int socket_fd, uint8_t *data, uint32_t data_len, void *user_data);

userdata：

[In]用户数据。

返回值

0：成功。

<0: 失败。

4.2 Liot_SocketSend

发送socket数据。

申明

int32_t Liot_SocketSend(int32_t fd, uint8_t *data, uint16_t len);

参数

fd：

[In] 通过 [Liot_SocketOpen] 获取的套接字文件描述符。

data：

[In] 发送的socket数据。

len：

[In]发送数据长度。

返回值

>0: 成功返回发送的字节数。

<0: 失败返回负值。

4.3 Liot_SocketGetStatus

获取套接字的当前状态。

申明

int32_t Liot_SocketGetStatus(int32_t fd);

参数

fd：

[In] 通过 [Liot_SocketOpen] 获取的套接字文件描述符。

返回值

0: 套接字已连接。

<0: 返回错误码。

4.4 Liot_SocketClose

关闭套接字。

申明

int32_t Liot_SocketClose(int32_t fd);

参数

fd：

[In] 通过 [Liot_SocketOpen] 获取的套接字文件描述符。

返回值

0: 关闭成功。

<0: 失败，返回错误码。