xf_ping

ping 功能实现。 更多...

xf_ping 的协作图:

结构体
struct	_xf_ping_cfg_t
	ping 配置类型。 更多...
struct	_xf_ping_cfg_update_flags_t
	ping 更新配置标志。 更多...
struct	_xf_ping_ctx_t
	ping 会话的上下文。 更多...

宏定义
#define	XF_PING_THREAD_NAME   "xf_ping"
#define	XF_PING_DEFAULT_CONFIG()
	默认 ping 配置

类型定义
typedef struct _xf_ping_ctx_t *	xf_ping_t
	ping 会话句柄。
typedef struct _xf_ping_cfg_t	xf_ping_cfg_t
	ping 配置类型。
typedef struct _xf_ping_cfg_update_flags_t	xf_ping_cfg_update_flags_t
	ping 更新配置标志。
typedef enum _xf_ping_event_code_t	xf_ping_event_code_t
	Ping 事件声明。
typedef int32_t	xf_ping_event_id_t
	ping 事件 id。见 xf_ping_event_code_t.
typedef void(*	xf_ping_cb_t) (xf_ping_event_id_t event_id, xf_ping_t hdl, void *user_args)
	ping 回调函数原型。
typedef struct _xf_ping_ctx_t	xf_ping_ctx_t
	ping 会话的上下文。

枚举
enum	_xf_ping_event_code_t {   XF_PING_EVENT_SUCC = 0x00 , XF_PING_EVENT_TIMEOUT , XF_PING_EVENT_END , XF_PING_EVENT_DELETE ,   XF_PING_EVENT_MAX }
	Ping 事件声明。 更多...

函数
xf_err_t	xf_ping_new_session (const xf_ping_cfg_t *p_cfg, xf_ping_cb_t cb_func, void *user_args, xf_ping_t *hdl_out)
	创建 ping 会话。
xf_err_t	xf_ping_delete_session (xf_ping_t hdl)
	删除 ping 会话。
xf_err_t	xf_ping_start (xf_ping_t hdl)
	启动 ping 会话。
xf_err_t	xf_ping_restart (xf_ping_t hdl, const xf_ping_cfg_t *p_cfg, xf_ping_cfg_update_flags_t *p_flags)
	重新启动 ping 会话。
bool	xf_ping_is_running (xf_ping_t hdl)
	检查 ping 是否正在运行。
xf_err_t	xf_ping_stop (xf_ping_t hdl)
	停止 ping 会话。

详细描述

ping 功能实现。

宏定义说明

XF_PING_THREAD_NAME

#define XF_PING_THREAD_NAME   "xf_ping"

在文件 xf_ping.h 第 44 行定义.

XF_PING_DEFAULT_CONFIG

#define XF_PING_DEFAULT_CONFIG

(

)

值:

        (xf_ping_cfg_t) { \
        .count = 5, \
        .interval_ms = 1000, \
        .timeout_ms = 1000, \
        .data_size = 64, \
        .tos = 0, \
        .ttl = IP_DEFAULT_TTL, \
        .target_addr = *(IP_ANY_TYPE), \
        .task_stack_size = (4 * 1024), \
        .task_prio = XF_OSAL_PRIORITY_NORMOL, \
        .interface = 0, \
        .auto_delete_flag = 0, \
    }

默认 ping 配置

示例

examples/protocols/icmp_echo/main/xf_main.c.

在文件 xf_ping.h 第 93 行定义.

类型定义说明

xf_ping_t

typedef struct _xf_ping_ctx_t* xf_ping_t

ping 会话句柄。

在文件 xf_ping.h 第 56 行定义.

xf_ping_cfg_t

typedef struct _xf_ping_cfg_t xf_ping_cfg_t

ping 配置类型。

xf_ping_cfg_update_flags_t

typedef struct _xf_ping_cfg_update_flags_t xf_ping_cfg_update_flags_t

ping 更新配置标志。

xf_ping_event_code_t

typedef enum _xf_ping_event_code_t xf_ping_event_code_t

Ping 事件声明。

注意

1. 注意，出于安全性考虑，禁止在回调中删除会话。
2. 如果需要一次性 ping 会话，请设置 <xf_ping_cfg_t>.auto_delete_flag = true. 将会在运行一次结束后，内部 task 自动删除 ping 会话。 此时注意通过 XF_PING_EVENT_DELETE 事件将 xf_ping_new_session() 传出的句柄 置为空指针，防止野指针。 设置了 <xf_ping_cfg_t>.auto_delete_flag = true 后，不需要再调用 xf_ping_delete_session()。
3. 如果 <xf_ping_cfg_t>.auto_delete_flag = false， 当一个 ping 会话不再需要后，请通过 xf_ping_delete_session() 删除会话， 并将外部保存的句柄置为 NULL。

xf_ping_event_id_t

typedef int32_t xf_ping_event_id_t

ping 事件 id。见 xf_ping_event_code_t.

在文件 xf_ping.h 第 134 行定义.

xf_ping_cb_t

typedef void(* xf_ping_cb_t) (xf_ping_event_id_t event_id, xf_ping_t hdl, void *user_args)

ping 回调函数原型。

参数

event_id	事件 id. 根据事件类型, 见 xf_ping_event_code_t.
hdl	事件数据. 需要根据事件 id 强转为对应的类型.
user_args	用户数据. xf_ping_new_session() 时传入.

在文件 xf_ping.h 第 143 行定义.

xf_ping_ctx_t

typedef struct _xf_ping_ctx_t xf_ping_ctx_t

ping 会话的上下文。

注意

只有 public: 部分是在回调中可读的， 用户 禁止 修改其中任何内容。

枚举类型说明

_xf_ping_event_code_t

enum _xf_ping_event_code_t

Ping 事件声明。

注意

1. 注意，出于安全性考虑，禁止在回调中删除会话。
2. 如果需要一次性 ping 会话，请设置 <xf_ping_cfg_t>.auto_delete_flag = true. 将会在运行一次结束后，内部 task 自动删除 ping 会话。 此时注意通过 XF_PING_EVENT_DELETE 事件将 xf_ping_new_session() 传出的句柄 置为空指针，防止野指针。 设置了 <xf_ping_cfg_t>.auto_delete_flag = true 后，不需要再调用 xf_ping_delete_session()。
3. 如果 <xf_ping_cfg_t>.auto_delete_flag = false， 当一个 ping 会话不再需要后，请通过 xf_ping_delete_session() 删除会话， 并将外部保存的句柄置为 NULL。

枚举值
XF_PING_EVENT_SUCC	收到 ICMP 应答数据包。
XF_PING_EVENT_TIMEOUT	ICMP 应答数据包超时。
XF_PING_EVENT_END	ping 会话完成。
XF_PING_EVENT_DELETE	ping 会话已删除。
XF_PING_EVENT_MAX	ping 事件 ID 最大值，无效 ID。

在文件 xf_ping.h 第 122 行定义.

函数说明

xf_ping_new_session()

xf_err_t xf_ping_new_session	(	const xf_ping_cfg_t *	p_cfg,
		xf_ping_cb_t	cb_func,
		void *	user_args,
		xf_ping_t *	hdl_out
	)

创建 ping 会话。

参数

	p_cfg	ping 配置。
	cb_func	ping 事件回调。
	user_args	ping 事件回调中的用户参数。
[out]	hdl_out	ping 会话句柄。

返回

• XF_ERR_INVALID_ARG 无效参数（例如配置为空等）
• XF_ERR_NO_MEM 内存不足
• XF_FAIL 其他内部错误（例如套接字错误）
• XF_OK 成功

< 任务句柄唯一，视为 ping ID

在文件 xf_ping.c 第 70 行定义.

xf_ping_delete_session()

xf_err_t xf_ping_delete_session

(

xf_ping_t

hdl

)

删除 ping 会话。

参数

hdl	ping 会话句柄。

返回

• XF_ERR_INVALID_ARG 无效参数
• XF_OK 成功

在文件 xf_ping.c 第 196 行定义.

xf_ping_start()

xf_err_t xf_ping_start

(

xf_ping_t

hdl

)

启动 ping 会话。

参数

hdl

ping 会话句柄

返回

• XF_ERR_INVALID_ARG 无效参数
• XF_OK 成功

在文件 xf_ping.c 第 224 行定义.

xf_ping_restart()

xf_err_t xf_ping_restart	(	xf_ping_t	hdl,
		const xf_ping_cfg_t *	p_cfg,
		xf_ping_cfg_update_flags_t *	p_flags
	)

重新启动 ping 会话。

参数

hdl	ping 会话句柄
p_cfg	需要更新的 ping 配置，为 NULL 时跳过更新配置。
p_flags	ping 配置中需要更新的部分。

返回

• XF_ERR_INVALID_ARG 无效参数
• XF_ERR_BUSY ping 会话正在运行，无法重新开始
• XF_OK 成功

在文件 xf_ping.c 第 239 行定义.

xf_ping_is_running()

bool xf_ping_is_running

(

xf_ping_t

hdl

)

检查 ping 是否正在运行。

参数

hdl

ping 会话句柄

返回

• true 是
• false 否

在文件 xf_ping.c 第 320 行定义.

xf_ping_stop()

xf_err_t xf_ping_stop

(

xf_ping_t

hdl

)

停止 ping 会话。

参数

hdl

ping 会话句柄

返回

• XF_ERR_INVALID_ARG 无效参数
• XF_OK 成功

在文件 xf_ping.c 第 331 行定义.