PING 开发指导_Rev1.2

English

修订记录

版本	日期	作者	审核	修订内容
Rev1.0	2023-09-19	LJZ	zlc	创建文档
Rev1.1	2024-03-25	sxx		更改文档名称
Rev1.2	2025-05-14	LJZ		优化文档格式

1 简介

本文档介绍 LTE-EC71X PING 接口 API 情况， API 接口位于 components/kernel/lierda_api/liot_ping/liot_ping.h 文件声明。

2 API 函数概览

函数	说明
liot_ping_start()	启用ping功能

3 类型说明

3.1 liot_ping_result_code_e

PING 结果错误码。

1. 声明

typedef enum
{
    LIOT_PING_OK                      = 0,
    LIOT_PING_ERR_INVALID_PARAM       = (LIOT_COMPONENT_LWIP_SOCKET << 16) | 552 /* Invalid parameters   */,
    LIOT_PING_ERR_SOCKET_NEW_FAILURE  = (LIOT_COMPONENT_LWIP_SOCKET << 16) | 554 /* Create socket failed */,
    LIOT_PING_ERR_SOCKET_BIND_FAILURE = (LIOT_COMPONENT_LWIP_SOCKET << 16) | 556 /* Socket bind failed   */,
    LIOT_PING_ERR_DNS_FAILURE         = (LIOT_COMPONENT_LWIP_SOCKET << 16) | 565 /* DNS parse failed     */,
    LIOT_PING_ERR_TIMEOUT             = (LIOT_COMPONENT_LWIP_SOCKET << 16) | 569 /* Operation timeout    */,
} liot_ping_result_code_e;

2. 参数

• LIOT_PING_OK：执行成功。

• LIOT_PING_ERR_INVALID_PARAM：参数错误 。

• LIOT_PING_ERR_SOCKET_NEW_FAILURE：创建socket失败。

• LIOT_PING_ERR_SOCKET_BIND_FAILURE：socket绑定失败。

• LIOT_PING_ERR_DNS_FAILURE：DNS解析失败。

• LIOT_PING_ERR_TIMEOUT：操作超时。

3.2 liot_ping_event_type_e

ping事件类型结构体定义如下

1. 声明

typedef enum
{
    LIOT_PING_STATS   = 1,
    LIOT_PING_SUMMARY = 2,
} liot_ping_event_type_e;

2. 参数

• LIOT_PING_STATS：ping过程中的事件 。

• LIOT_PING_SUMMARY：ping结束的事件。

3.3 liot_ping_config_type_s

ping配置信息结构体定义如下

1. 声明

typedef struct
{
    uint32_t num_data_bytes;         /* Data byte size of the ping packet    */
    uint32_t ping_response_time_out; /* Wait time for ping response, ms      */
    uint32_t num_pings;              /* Number of times to ping              */
    uint32_t ttl;                    /* Time To Live for the ping packet     */
} liot_ping_config_type_s;

2. 参数

类型	参数	描述
uint32_t	num_data_bytes	ping数据包payload大小
uint32_t	ping_response_time_out	ping请求回应等待的最大时间
uint32_t	num_pings	ping请求最大次数
uint32_t	ttl	ping请求回应数据包ttl

3.4 liot_ping_stats_type_s

ping请求过程中的状态结构体如下

1. 声明

typedef struct
{
    uint32_t ping_rtt;
    uint32_t ping_size;
    uint32_t ping_ttl;
    char resolved_ip_addr[256];
} liot_ping_stats_type_s;

2. 参数

类型	参数	描述
uint32_t	ping_rtt	ping请求回应数据包rtt
uint32_t	ping_size	发送ping请求字节长度
uint32_t	ping_ttl	ping请求回应数据包ttl
char	resolved_ip_addr	远程服务器 IP 地址

3.5 liot_ping_summary_type_s

ping请求最终结果的状态结构体如下

1. 声明

typedef struct
{
    uint32_t min_rtt;        /* Minimum RTT so far, in millisecs           */
    uint32_t max_rtt;        /* Maximum RTT so far, in millisecs           */
    uint32_t avg_rtt;        /* Average RTT so far, in millisecs           */
    uint32_t num_pkts_sent;  /* Number of pings sent so far          */
    uint32_t num_pkts_recvd; /* Number of responses recieved so far  */
    uint32_t num_pkts_lost;  /* Number of responses not received     */
} liot_ping_summary_type_s;

2. 参数

类型	参数	描述
uint32_t	min_rtt	ping过程中最小rtt
uint32_t	max_rtt	ping过程中最大rtt
unt32_t	avg_rtt	ping过程中平均rtt
uint32_t	num_pkts_sent	Ping 请求发送次数
uint32_t	num_pkts_recvd	得到响应的 Ping 请求个数
uint32_t	num_pkts_lost	超时的 Ping 请求个数

4 API 函数详解

4.1 liot_ping_event_cb

ping执行回调函数

1. 声明

typedef void (*liot_ping_event_cb)(ping_session_id ping_sess_id, uint16_t event_id, int evt_code, void *evt_param);

2. 参数

• ping_sess_id：[In] ping 事件会话id。

• event_id：[In] ping 事件ID, 范围：liot_ping_event_type。

• evt_code：[In] ping 结果码, 范围：liot_ping_result_code。

• evt_param：[In] 回调参数。

4.2 liot_ping_start

该函数用于获取设备的固件版本。

1. 声明

ping_session_id liot_ping_start(
    int cid, int sim_id, const char *host, liot_ping_config_type_s *ping_options, liot_ping_event_cb cb_fcn);

2. 参数

• cid：[In] pdp cid信息。

• sim_id：[In] SIM卡索引，取值：0-1。

• host：[In] ping操作的对端地址。

• ping_options：[In] ping请求发送数据设置,请求字节数,超时时间,最大请求次数，见liot_ping_config_type_s。

• cb_fcn：[In] ping操作的事件回调函数,设置事件类型为ping start,以及对ping回调结果的判断处理。

3. 返回值

• ping_session_id：事件会话id。

新增

5 代码示例

1. 示例代码参考  examples/demo/src/demo_ping.c 文件。

• 运行结果：

如上图所示，则说明获取所有信息正常。