第 3 章 - Azure RTOS NetX PPPoE 客户端服务说明

本章旨在按字母顺序介绍如下所列的所有 Azure RTOS NetX PPPoE 客户端服务。

在以下 API 说明的“返回值”部分中,以粗体显示的值不受 NX_DISABLE_ERROR_CHECKING 定义(用于禁用 API 错误检查)影响,而不以粗体显示的值会被完全禁用。

nx_pppoe_client_create

创建 PPPoE 客户端实例

原型

UINT  nx_pppoe_client_create(
    NX_PPPOE_CLIENT *pppoe_client_ptr,
    CHAR *name, NX_IP *ip_ptr,
    UINT interface_index,
    NX_PACKET_POOL *pool_ptr,
    VOID *stack_ptr, ULONG stack_size,
    UINT priority,
    VOID (*pppoe_link_driver)(struct NX_IP_DRIVER_STRUCT *),
    VOID (*pppoe_packet_receive)(NX_PACKET *packet_ptr));

说明

此服务使用用户提供的链接驱动程序,为指定的 NetX IP 实例创建 PPPoE 客户端实例。 如果尚未初始化和启用链接驱动程序,则 PPPoE 客户端软件会负责初始化链接驱动程序。

此外,应用程序必须为 PPPoE 客户端实例提供先前创建的数据包池,以用于内部数据包分配。

注意

通常情况下,创建 NetX IP 线程的优先级最好高于创建 PPPoE 客户端线程的优先级。 有关指定 IP 线程优先级的详细信息,请参阅“nx_ip_create”服务。

输入参数

  • pppoe_client_ptr:指向 PPPoE 客户端控制块的指针。
  • name:此 PPPoE 客户端实例的名称。
  • ip_ptr:指向 IP 实例控制块的指针。
  • interface_index:接口索引。
  • pool_ptr:指向数据包池的指针。
  • stack_ptr:指向 PPPoE 客户端线程堆栈区域起始位置的指针。
  • stack_size:线程堆栈的大小(以字节为单位)。
  • priority:内部 PPPoE 客户端线程的优先级 (1-31)。
  • pppoe_link_driver:用户提供的链接驱动程序。
  • pppoe_packet_receive:用户提供的数据包接收函数。

返回值

  • NX_PPPOE_CLIENT_SUCCESS (0x00) 成功创建 PPPoE 客户端。
  • NX_PPPOE_CLIENT_PTR_ERROR (0xD1) PPPoE 客户端、IP、数据包池或堆栈指针无效。
  • NX_PPPOE_CLIENT_INVALID_INTERFACE (0xD2) 接口无效。
  • NX_PPPOE_CLIENT_PACKET_PAYLOAD_ERROR (0xD3) 数据包池的有效负载大小无效。
  • NX_PPPOE_CLIENT_MEMORY_SIZE_ERROR (0xD4) 内存大小无效。
  • NX_PPPOE_CLIENT_PRIORITY_ERROR (0xD5) PPPoE 客户端线程的优先级无效。

支持的来源

初始化、线程

示例

/* Create “my_pppoe_client” for IP instance “my_ip”. */
status =  nx_pppoe_client_create(&my_pppoe_client, “my PPPoE Client”, &my_ip,
0, &my_pool, stack_start, 1024, 2,
link_driver, packet_receive);

/* If status is NX_PPPOE_CLIENT_SUCCESS, the “my_pppoe_client” was successfully created. */

nx_pppoe_client_delete

删除 PPPoE 客户端实例

原型

UINT nx_pppoe_client_delete(
    NX_PPPOE_CLIENT *pppoe_client_ptr);

说明

此服务用于删除先前创建的 PPPoE 客户端实例。

输入参数

  • pppoe_client_ptr:指向 PPPoE 客户端控制块的指针

返回值

  • NX_PPPOE_CLIENT_SUCCESS (0x00) 成功删除 PPPoE 客户端。
  • NX_PPPOE_CLIENT_PTR_ERROR (0xD1) PPPoE 客户端指针无效。

支持的来源

线程数

示例

/* Delete PPPoE Client instance “my_pppoe_client”. */
status =  nx_pppoe_client_delete(&my_pppoe_client);

/* If status is NX_PPPOE_CLIENT_SUCCESS, the “my_pppoe_client” was successfully deleted. */

nx_pppoe_client_host_uniq_set

设置 PPPoE 客户端主机唯一标识

原型

UINT nx_pppoe_client_host_uniq_set(
    NX_PPPOE_CLIENT *pppoe_client_ptr,
    UCHAR *host_uniq);

说明

此服务用于设置 PPPoE 客户端主机唯一标识。 主机使用 Host-Uniq,以将访问集中器与特定主机请求进行唯一关联。 Host-Uniq 可以是主机选择的任何值和长度的二进制数据。

注意

主机唯一标识必须为以 Null 结尾的字符串。

注意

此服务已弃用。 鼓励开发人员迁移至 nx_pppoe_client_host_uniq_set_extended

输入参数

  • pppoe_client_ptr:指向 PPPoE 客户端控制块的指针。
  • host_uniq:指向主机唯一标识的指针。 主机唯一标识必须为以 Null 结尾的字符串。

返回值

  • NX_PPPOE_CLIENT_SUCCESS (0x00) 成功设置 PPPoE 客户端主机唯一标识。
  • NX_PPPOE_CLIENT_PTR_ERROR (0xD1) PPPoE 客户端指针无效。

支持的来源

初始化、线程

示例

/* Set service name for PPPoE Client instance “my_pppoe_client”. */
status =  nx_pppoe_client_host_uniq_set(&my_pppoe_client,
“220000000000000041000000”);

/* If status is NX_PPPOE_CLIENT_SUCCESS, the “my_pppoe_client” host unique has set. */

nx_pppoe_client_host_uniq_set_extended

设置 PPPoE 客户端主机唯一标识

原型

UINT nx_pppoe_client_host_uniq_set_extended(
    NX_PPPOE_CLIENT *pppoe_client_ptr,
    UCHAR *host_uniq,UINT host_uniq_length);

说明

此服务用于设置 PPPoE 客户端主机唯一标识。 主机使用 Host-Uniq,以将访问集中器与特定主机请求进行唯一关联。 Host-Uniq 可以是主机选择的任何值和长度的二进制数据。

注意

主机唯一标识必须为以 Null 结尾的字符串。

注意

此服务用于替代 nx_pppoe_client_host_uniq_set。 这一版本向此服务提供其他长度信息。

输入参数

  • pppoe_client_ptr:指向 PPPoE 客户端控制块的指针。
  • host_uniq:指向主机唯一标识的指针。 主机唯一标识必须为以 Null 结尾的字符串。
  • host_uniq_length:host_uniq 的长度

返回值

  • NX_PPPOE_CLIENT_SUCCESS (0x00) 成功设置 PPPoE 客户端主机唯一标识。
  • NX_PPPOE_CLIENT_PTR_ERROR (0xD1) PPPoE 客户端指针无效。
  • NX_SIZE_ERROR (0X09) 无法检查 host_uniq_length

支持的来源

初始化、线程

示例

/* Set service name for PPPoE Client instance “my_pppoe_client”. */
status =  nx_pppoe_client_host_uniq_set_extended(&my_pppoe_client,
“220000000000000041000000”,24);

/* If status is NX_PPPOE_CLIENT_SUCCESS, the “my_pppoe_client” host unique has set. */

nx_pppoe_client_service_name_set

设置 PPPoE 客户端服务名称

原型

UINT nx_pppoe_client_service_name_set(
    NX_PPPOE_CLIENT *pppoe_client_ptr,
    UCHAR *service_name);

说明

此服务用于设置 PPPoE 客户端服务名称。 服务名称表示主机正在请求的服务。 如果未设置服务名称,则表示主机将接受任意数量的服务。

注意

服务名称必须为以 Null 结尾的字符串

注意

此服务已弃用。 鼓励开发人员迁移至 nx_pppoe_client_service_name_set_extended

输入参数

  • pppoe_client_ptr:指向 PPPoE 客户端控制块的指针。
  • service_name:指向服务名称的指针。 服务名称必须为以 Null 结尾的字符串。

返回值

  • NX_PPPOE_CLIENT_SUCCESS (0x00) 成功设置 PPPoE 客户端服务名称。
  • NX_PPPOE_CLIENT_PTR_ERROR (0xD1) PPPoE 客户端指针无效。

支持的来源

初始化、线程

示例

/* Set service name for PPPoE Client instance “my_pppoe_client”. */
status =  nx_pppoe_client_service_name_set(&my_pppoe_client,
“BRAS”);

/* If status is NX_PPPOE_CLIENT_SUCCESS, the “my_pppoe_client” service name has set. */

nx_pppoe_client_service_name_set_extended

设置 PPPoE 客户端服务名称

原型

UINT nx_pppoe_client_service_name_set_extended(
    NX_PPPOE_CLIENT *pppoe_client_ptr,
    UCHAR *service_name,
    UINT service_name_length);

说明

此服务用于设置 PPPoE 客户端服务名称。 服务名称表示主机正在请求的服务。 如果未设置服务名称,则表示主机将接受任意数量的服务。

注意

服务名称必须为以 Null 结尾的字符串。

注意

此服务用于替代 nx_pppoe_client_service_name_set。 这一版本向此函数提供其他服务名称长度信息。

输入参数

  • pppoe_client_ptr:指向 PPPoE 客户端控制块的指针。
  • service_name:指向服务名称的指针。 服务名称必须为以 Null 结尾的字符串。
  • service_name_length:service_name 的长度

返回值

  • NX_PPPOE_CLIENT_SUCCESS (0x00) 成功设置 PPPoE 客户端服务名称。
  • NX_PPPOE_CLIENT_PTR_ERROR (0xD1) PPPoE 客户端指针无效。
  • NX_SIZE_ERROR (0X09) 无法检查 service_name_length

支持的来源

初始化、线程

示例

/* Set service name for PPPoE Client instance “my_pppoe_client”. */
status =  nx_pppoe_client_service_name_set_extended(&my_pppoe_client,
“BRAS”,4);

/* If status is NX_PPPOE_CLIENT_SUCCESS, the “my_pppoe_client” service name has set. */

nx_pppoe_client_session_connect

连接 PPPoE 客户端会话

原型

UINT nx_pppoe_client_session_connect(
    NX_PPPOE_CLIENT *pppoe_client_ptr,
    ULONG wait_option);

说明

此服务使用先前创建的 PPPoE 客户端,与指定的 PPPoE 服务器建立 PPPoE 会话连接。

注意

必须在 nx_pppoe_client_create、nx_pppoe_client_host_uniq_set 和 nx_pppoe_client_service_name_set 之后调用此函数。

输入参数

  • pppoe_client_ptr:指向 PPPoE 客户端控制块的指针。
  • wait_option:建立连接时的等待选项。

返回值

  • NX_PPPOE_CLIENT_SUCCESS (0x00) 成功连接 PPPoE 客户端会话。
  • NX_PPPOE_CLIENT_PTR_ERROR (0xD1) PPPoE 客户端指针无效。

支持的来源

初始化、线程

示例

/* Enable PPPoE Client instance “my_pppoe_client”. */
status =  nx_pppoe_client_session_connect(&my_pppoe_client);

/* If status is NX_PPPOE_CLIENT_SUCCESS, the “my_pppoe_client” session connection has connected. */

nx_pppoe_client_session_packet_send

将 PPPoE 客户端数据包发送至指定会话

原型

UINT nx_pppoe_client_session_packet_send(
    NX_PPPOE_CLIENT *pppoe_client_ptr,
    NX_PACKET *packet_ptr);

说明

此服务使用指定的会话 ID 发送 PPPoE 数据包。

输入参数

  • pppoe_client_ptr:指向 PPPoE 客户端控制块的指针。
  • packet_ptr:指向 PPPoE 数据包的指针。

返回值

  • NX_PPPOE_CLIENT_SUCCESS (0x00) 成功发送 PPPoE 客户端数据包。
  • NX_PPPOE_CLIENT_PTR_ERROR (0xD1) PPPoE 客户端指针无效。
  • NX_PPPOE_CLIENT_PACKET_PAYLOAD_ERROR (0xD3) PPPoE 客户端数据包无效。
  • NX_PPPOE_CLIENT_SESSION_NOT_ESTABLISHED (0xD8) 未建立 PPPoE 会话。

支持的来源

初始化、线程

示例

/* Send PPPoE client packet to specified session, PPPoE Client instance “my_pppoe_client”. */
status =  nx_pppoe_client_session_packet_send(&my_pppoe_client, packet_ptr);

/* If status is NX_PPPOE_CLIENT_SUCCESS, the “my_pppoe_client” packet has sent. */

nx_pppoe_client_session_terminate

终止 PPPoE 客户端会话

原型

UINT nx_pppoe_client_session_terminate(NX_PPPOE_CLIENT *pppoe_client_ptr);

说明

此服务用于终止指定的 PPPoE 会话。

输入参数

  • pppoe_client_ptr:指向 PPPoE 客户端控制块的指针。

返回值

  • NX_PPPOE_CLIENT_SUCCESS (0x00) 成功终止 PPPoE 客户端会话。
  • NX_PPPOE_CLIENT_PTR_ERROR (0xD1) PPPoE 客户端指针无效。

支持的来源

初始化、线程

示例

/* Terminates the specified PPPoE session, PPPoE Client instance “my_pppoe_client”. */
status =  nx_pppoe_client_session_terminate(&my_pppoe_client);

/* If status is NX_PPPOE_CLIENT_SUCCESS, the session has terminated. */

nx_pppoe_client_session_get

获取指定的 PPPoE 会话信息

原型

UINT nx_pppoe_client_session_get(
    NX_PPPOE_CLIENT *pppoe_client_ptr,
    ULONG *server_mac_msw,
    ULONG *server_mac_lsw,
    ULONG *session_id);

说明

此服务用于获取指定的 PPPoE 会话信息、服务器物理地址和会话 ID。

输入参数

  • pppoe_server_ptr:指向 PPPoE 客户端控制块的指针。
  • server_mac_msw:服务器物理地址 MSW 指针。
  • server_mac_lsw:服务器物理地址 LSW 指针。
  • session_id:会话 ID 指针。

返回值

  • NX_PPPOE_CLIENT_SUCCESS (0x00) 成功获取 PPPoE 客户端会话。
  • NX_PPPOE_CLIENT_PTR_ERROR (0xD1) PPPoE 客户端指针无效。
  • NX_PPPOE_CLIENT_SESSION_NOT_ESTABLISHED (0xD8) 未建立 PPPoE 会话。

支持的来源

初始化、线程

示例

/* Gets the specified PPPoE session information, PPPoE Client instance “my_pppoe_client”. */
status =  nx_pppoe_client_session_get (&my_pppoe_client, &server_mac_msw, &server_mac_lsw, &session_id);

/* If status is NX_PPPOE_CLIENT_SUCCESS, the server physical address and session id
   of the session has got. */