第 3 章 - Azure RTOS NetX PPPoE 服务器服务的说明

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

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

nx_pppoe_server_create

创建 PPPoE 服务器实例

原型

UINT nx_pppoe_server_create(
    NX_PPPOE_SERVER *pppoe_server_ptr,
    CHAR *name, NX_IP *ip_ptr,
    UINT interface_index,
    VOID (*pppoe_link_driver)(struct NX_IP_DRIVER_STRUCT *),
    NX_PACKET_POOL *pool_ptr,
    VOID *stack_ptr,
    ULONG stack_size,
    UINT priority);

说明

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

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

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

输入参数

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

返回值

  • NX_PPPOE_SERVER_SUCCESS:(0x00) 已成功创建 PPPoE 服务器。
  • NX_PPPOE_SERVER_PTR_ERROR:(0xC1) PPPoE 服务器、IP、数据包池或堆栈指针无效。
  • NX_PPPOE_SERVER_INVALID_INTERFACE:(0xC2) 接口无效。
  • NX_PPPOE_SERVER_PACKET_PAYLOAD_ERROR:(0xC3) 数据包池的有效负载大小无效。
  • NX_PPPOE_SERVER_MEMORY_SIZE_ERROR:(0xC4) 内存大小无效。
  • NX_PPPOE_SERVER_PRIORITY_ERROR:(0xC5) PPPoE 服务器线程的优先级无效。

允许来自

初始化、线程

示例

/* Create "my_pppoe_server" for IP instance "my_ip". */
status = nx_pppoe_server_create(&my_pppoe_server, "my PPPoE Server", &my_ip,
                                &my_pool, stack_start, 1024, 2);

/* If status is NX_PPPOE_SERVER_SUCCESS, the "my_pppoe_server" was successfully created. */

nx_pppoe_server_delete

删除 PPPoE 服务器实例

原型

UINT nx_pppoe_server_delete(NX_PPPOE_SERVER *pppoe_server_ptr);

说明

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

输入参数

  • pppoe_server_ptr:指向 PPPoE 服务器控制块的指针。

返回值

  • NX_PPPOE_SERVER_SUCCESS:(0x00) 已成功删除 PPPoE 服务器。
  • NX_PPPOE_SERVER_PTR_ERROR:(0xC1) PPPoE 服务器指针无效。

允许来自

线程数

示例

/* Delete PPPoE Server instance "my_pppoe_server". */
status = nx_pppoe_server_delete(&my_pppoe_server);

/* If status is NX_PPPOE_SERVER_SUCCESS, the "my_pppoe_server" was successfully deleted. */

nx_pppoe_server_enable

启用 PPPoE 服务器服务

原型

UINT nx_pppoe_server_enable(NX_PPPOE_SERVER *pppoe_server_ptr);

说明

此服务用于启用 PPPoE 服务器服务。

注意

必须在 nx_pppoe_server_create 和 nx_pppoe_server_callback_notify_set 之后调用此函数 。

输入参数

  • pppoe_server_ptr:指向 PPPoE 服务器控制块的指针。

返回值

  • NX_PPPOE_SERVER_SUCCESS:(0x00) 已成功删除 PPPoE 服务器。
  • NX_PPPOE_SERVER_PTR_ERROR:(0xC1) PPPoE 服务器指针无效。

允许来自

初始化、线程

示例

/* Enable PPPoE Server instance "my_pppoe_server". */
status = nx_pppoe_server_enable(&my_pppoe_server);  

/* If status is NX_PPPOE_SERVER_SUCCESS, the "my_pppoe_server" service has enabled. */

nx_pppoe_server_disable

禁用 PPPoE 服务器服务

原型

UINT nx_pppoe_server_disable(NX_PPPOE_SERVER *pppoe_server_ptr);

说明

此服务用于禁用 PPPoE 服务器服务。

输入参数

  • pppoe_server_ptr:指向 PPPoE 服务器控制块的指针。

返回值

  • NX_PPPOE_SERVER_SUCCESS:(0x00) 已成功删除 PPPoE 服务器。
  • NX_PPPOE_SERVER_PTR_ERROR:(0xC1) PPPoE 服务器指针无效。

允许来自

初始化、线程

示例

/* Disable PPPoE Server instance "my_pppoe_server". */
status = nx_pppoe_server_disable(&my_pppoe_server);

/* If status is NX_PPPOE_SERVER_SUCCESS, the "my_pppoe_server" service has disabled. */

nx_pppoe_server_callback_notify_set

设置 PPPoE 服务器回调通知函数

原型

UINT nx_pppoe_server_callback_notify_set(
    NX_PPPOE_SERVER *pppoe_server_ptr,
    VOID (* pppoe_discover_initiation_notify)
        (UINT session_index,
        ULONG length, 
        UCHAR *data),
    VOID (* pppoe_discover_request_notify)(UINT session_index),
    VOID (* pppoe_discover_terminate_notify)(UINT session_index),
    VOID (* pppoe_discover_terminate_confirm)(UINT session_index),
    VOID (* pppoe_data_receive_notify)(
        UINT session_index,
        ULONG length,
        UCHAR *data,
        UINT packet_id),
    VOID (* pppoe_discover_notify)(
        UINT session_index,
        UCHAR *data))

说明

此服务用于设置 PPPoE 服务器回调通知函数。

注意

必须在 nx_pppoe_server_enable 之前调用此函数,并且必须设置 pppoe_data_receive_notify 函数指针,否则 nx_pppoe_server_enable 将会失败。

输入参数

  • pppoe_server_ptr:指向 PPPoE 服务器控制块的指针。
  • pppoe_discover_initiation_notify:每当收到 PPPoE 发现启动消息时要调用的应用程序函数。 如果此值为 NULL,则会禁用发现启动回调函数。
  • pppoe_discover_request_notify:每当收到 PPPoE 发现请求消息时要调用的应用程序函数。 如果此值为 NULL,则会禁用发现请求回调函数。
  • pppoe_discover_terminate_notify:每当收到 PPPoE 发现终止消息时要调用的应用程序函数。 如果此值为 NULL,则会禁用发现终止回调函数。
  • pppoe_discover_terminate_confirm:每当发送 PPPoE 发现终止消息时要调用的应用程序函数。 如果此值为 NULL,则会禁用发现终止回调函数。
  • pppoe_data_receive_notify:每当收到 PPPoE 数据消息时要调用的应用程序函数。 此值不得为零。
  • pppoe_data_send_notify:每当发送 PPPoE 数据消息时要调用的应用程序函数。 如果此值为 NULL,则会禁用数据发送回调函数。

返回值

  • NX_PPPOE_SERVER_SUCCESS:(0x00) 已成功删除 PPPoE 服务器。
  • NX_PPPOE_SERVER_PTR_ERROR:(0xC1) PPPoE 服务器指针或函数指针无效。

允许来自

初始化、线程

示例

/* Set PPPoE Server callback notify functions, PPPoE Server instance "my_pppoe_server". */

status = nx_pppoe_server_disable(&my_pppoe_server,
                pppoe_discovery_initiation_notify,
                pppoe_discovery_request_notify,
                pppoe_discovery_terminate_notify,
                pppoe_discovery_terminate_confirm,
                pppoe_data_receive_notify,
                pppoe_data_send_notify);  

/* If status is NX_PPPOE_SERVER_SUCCESS, the callback notify functions for "my_pppoe_server" service has set. */

nx_pppoe_server_ac_name_set

设置访问集中器名称

原型

UINT nx_pppoe_server_ac_name_set(
    NX_PPPOE_SERVER *pppoe_server_ptr,
    CHAR *ac_name,
    UINT ac_name_length,
);

说明

此函数用于设置访问集中器名称函数调用。

注意

ac_name 的字符串必须以 NULL 结尾,并且 ac_name 的长度与自变量列表中指定的长度匹配。

输入参数

  • pppoe_server_ptr:指向 PPPoE 服务器控制块的指针。
  • ac_name:访问集中器名称。
  • ac_name_length:ac_ame 的长度。

返回值

  • NX_PPPOE_SERVER_SUCCESS:(0x00) 已成功设置 PPPoE 服务器。
  • NX_PPPOE_SERVER_PTR_ERROR:(0xC1) PPPoE 服务器、IP、数据包池或堆栈指针无效。
  • NX_SIZE_ERROR:(0x09) 检查 name_length 失败。

允许来自

初始化、线程

示例

/* Set "my PPPoE ac name" for Server instance "my_pppoe_server". */
status = nx_pppoe_server_ac_name_set(&my_pppoe_server, "my PPPoE ac name",16);

/* If status is NX_PPPOE_SERVER_SUCCESS, the "my PPPoE ac name" was successfully set. */

nx_pppoe_server_service_name_set

设置 PPPoE 服务器服务名称

原型

UINT nx_pppoe_server_service_name_set(
    NX_PPPOE_SERVER *pppoe_server_ptr,
    UCHAR **service_name,
    UINT service_name_count);

说明

此服务用于设置 PPPoE 服务器服务名称。

输入参数

  • pppoe_server_ptr:指向 PPPoE 服务器控制块的指针。

返回值

  • NX_PPPOE_SERVER_SUCCESS:(0x00) 已成功删除 PPPoE 服务器。
  • NX_PPPOE_SERVER_PTR_ERROR:(0xC1) PPPoE 服务器指针无效。

允许来自

初始化、线程

示例

CHAR *nx_pppoe_service_name[] =
{
    "XBB",
    "PRINTER",
    NX_NULL
};

/* Set service name for PPPoE Server instance "my_pppoe_server". */
status = nx_pppoe_server_service_namet_set(&my_pppoe_server,
                                    nx_pppoe_service_name, 2);  

/* If status is NX_PPPOE_SERVER_SUCCESS, the "my_pppoe_server" service name has set. */

nx_pppoe_server_session_send

将 PPPoE 服务器数据发送到指定的会话

原型

UINT nx_pppoe_server_session_send 
    (NX_PPPOE_SERVER *pppoe_server_ptr,
    UINT session_index,
    UCHAR *data_ptr,
    UINT data_length);

说明

此服务使用指定的会话 ID 发送 PPPoE 帧。

输入参数

  • pppoe_server_ptr:指向 PPPoE 服务器控制块的指针。
  • session_index:会话的索引。
  • data_ptr:指向 PPPoE 服务器数据帧起始位置的指针。
  • data_length:PPPoE 服务器数据帧的长度。

返回值

  • NX_PPPOE_SERVER_SUCCESS:(0x00) 已成功删除 PPPoE 服务器。
  • NX_PPPOE_SERVER_PTR_ERROR:(0xC1) PPPoE 服务器指针无效。
  • NX_PPPOE_SERVER_NOT_ENABLED:(0xC6) 未启用 PPPoE 服务器服务。
  • NX_PPPOE_SERVER_INVALID_SESSION:(0xC7) PPPoE 会话索引无效。
  • NX_PPPOE_SERVER_SESSION_NOT_ESTABLISHED:(0xC8) 未建立 PPPoE 会话。

允许来自

初始化、线程

示例

/* Send PPPoE Server data to specified session, PPPoE Server instance "my_pppoe_server". */
status = nx_pppoe_server_session_send(&my_pppoe_server, 0, my_data_ptr, 1400);  

/* If status is NX_PPPOE_SERVER_SUCCESS, the "my_pppoe_server" data has sent. */

nx_pppoe_server_session_packet_send

将 PPPoE 服务器数据包发送到指定的会话

原型

UINT nx_pppoe_server_session_packet_send (
    NX_PPPOE_SERVER *pppoe_server_ptr,
    UINT session_index,
    NX_PACKET *packet_ptr);

说明

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

输入参数

  • pppoe_server_ptr:指向 PPPoE 服务器控制块的指针。
  • session_index:会话的索引。
  • packet_ptr:指向 PPPoE 数据包的指针。

返回值

  • NX_PPPOE_SERVER_SUCCESS:(0x00) 已成功删除 PPPoE 服务器。
  • NX_PPPOE_SERVER_PTR_ERROR:(0xC1) PPPoE 服务器指针无效。
  • NX_PPPOE_SERVER_PACKET_PAYLOAD_ERROR:(0xC3) PPPoE 服务器数据包无效。
  • NX_PPPOE_SERVER_NOT_ENABLED:(0xC6) 未启用 PPPoE 服务器服务。
  • NX_PPPOE_SERVER_INVALID_SESSION:(0xC7) PPPoE 会话索引无效。
  • NX_PPPOE_SERVER_SESSION_NOT_ESTABLISHED:(0xC8) 未建立 PPPoE 会话。

允许来自

初始化、线程

示例

/* Send PPPoE Server data to specified session, PPPoE Server instance "my_pppoe_server". */
status = nx_pppoe_server_session_packet_send(&my_pppoe_server, 0, packet_ptr);  

/* If status is NX_PPPOE_SERVER_SUCCESS, the "my_pppoe_server" packet has sent. */

nx_pppoe_server_session_terminate

终止指定的 PPPoE 会话

原型

UINT nx_pppoe_server_session_terminate(
    NX_PPPOE_SERVER *pppoe_server_ptr,
    UINT session_index);

说明

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

输入参数

  • pppoe_server_ptr:指向 PPPoE 服务器控制块的指针。
  • session_index:会话的索引。

返回值

  • NX_PPPOE_SERVER_SUCCESS:(0x00) 已成功删除 PPPoE 服务器。
  • NX_PPPOE_SERVER_PTR_ERROR:(0xC1) PPPoE 服务器指针无效。
  • NX_PPPOE_SERVER_NOT_ENABLED:(0xC6) 未启用 PPPoE 服务器服务。
  • NX_PPPOE_SERVER_INVALID_SESSION:(0xC7) PPPoE 会话索引无效。
  • NX_PPPOE_SERVER_SESSION_NOT_ESTABLISHED:(0xC8) 未建立 PPPoE 会话。

允许来自

初始化、线程

示例

/* Terminates the specified PPPoE session, PPPoE Server instance "my_pppoe_server". */
status = nx_pppoe_server_session_send(&my_pppoe_server, 0);  

/* If status is NX_PPPOE_SERVER_SUCCESS, the session indexed with 0 has terminated. */

nx_pppoe_server_session_get

获取指定的 PPPoE 会话信息

原型

UINT nx_pppoe_server_session_get(
    NX_PPPOE_SERVER *pppoe_server_ptr,
    UINT session_index
    ULONG *client_mac_msw,
    ULONG *client_mac_lsw,
    ULONG *session_id);

说明

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

输入参数

  • pppoe_server_ptr:指向 PPPoE 服务器控制块的指针。
  • session_index:会话的索引。
  • client_mac_msw:客户端物理地址 MSW 指针。
  • client_mac_lsw:客户端物理地址 MSW 指针。
  • session_id:会话 ID 指针。

返回值

  • NX_PPPOE_SERVER_SUCCESS:(0x00) 已成功删除 PPPoE 服务器。
  • NX_PPPOE_SERVER_PTR_ERROR:(0xC1) PPPoE 服务器指针无效。
  • NX_PPPOE_SERVER_INVALID_SESSION:(0xC7) PPPoE 会话索引无效。
  • NX_PPPOE_SERVER_SESSION_NOT_ESTABLISHED:(0xC8) 未建立 PPPoE 会话。

允许来自

初始化、线程

示例

/* Gets the specified PPPoE session information, PPPoE Server instance "my_pppoe_server". */
status = nx_pppoe_server_session_get (&my_pppoe_server, 0, &client_mac_msw, &client_mac_lsw, &session_id);

/* If status is NX_PPPOE_SERVER_SUCCESS, the client physical address and session id of the session indexed with 0 has got. */

PppInitInd

配置默认服务名称

原型

VOID PppInitnd(
    UINT length,
    UCHAR *aData);

说明

PPPoE 软件将公开此函数,以允许 TTP 的软件配置 PPPoE 在筛选传入 PADI 请求时应该使用的“默认服务名称”。 PPPoE 软件应记住此信息,如果收到了包含匹配服务名称的 PADI 数据包,则它应该调用 PppDiscoverReq。

输入参数

  • length:默认服务名称的长度。
  • aData:默认服务名称。

返回值

允许来自

初始化、线程

示例

/* Configure the default Service Name. */
PppInitInd (3, "XBB");

PppDiscoverCnf

定义 PADO 数据包的“服务名称”字段

原型

VOID PppDiscoverCnf (
    UINT length,
    UCHAR *aData,
    UINT interfaceHandle);

说明

PPPoE 软件将公开此函数,以允许 TTP 的软件定义 PADO 数据包的“服务名称”字段。 在调用 PppDiscoverCnf 之前,PPPoE 软件不应发送 PADO。

PADO 数据包应该包含 PPPoE 软件初始化时定义的访问集中器名称(使用 RFC2516 中定义的标记 ID 0x0102)。

可在 aData 中传递多个服务名称,其中每个名称以 null 结尾。

Null 字符用作分隔符,以便在需要传入其他命令作为服务名称的一部分时提供最大的灵活性。

输入参数

  • length:默认服务名称的长度。
  • aData:默认服务名称。
  • interfaceHandle:接口句柄。

返回值

获准方式

初始化、线程

示例

/* Define the Service Name field of the PADO packet. */
PppDiscoverCnf (3, "XBB", 0);

PppOpenCnf

接受或拒绝 PPPoE 会话

原型

VOID PppOpenCnf (
    UCHAR accept,
    UINT interfaceHandle);

说明

PPPoE 软件将公开此函数,以允许 TTP 的软件接受或拒绝 PPPoE 会话。  作为响应,PPPoE 堆栈应接受连接,并分配一个与 interfaceHandle 关联的唯一 PPPoE Session_ID 编号。

输入参数

  • accept:如果要接受连接,则此项为 NX_TRUE。
  • interfaceHandle:接口句柄。

返回值

允许来自

初始化、线程

示例

/* Accept the connection. */
PppOpenCnf(NX_TRUE, 0);

PppCloseInd

关闭 PPPoE 会话

原型

VOID PppCloseInd (
    UINT interfaceHandle,
    UCHAR *causeCode);

说明

PPPoE 软件将公开此函数,以允许 TTP 的软件关闭 PPPoE 会话。

PPPoE 软件将在 PADT 消息的 Generic-Error 标记 (0x0203) 中指示原因代码字符串

输入参数

  • interfaceHandle:接口句柄。
  • causeCode:以 Null 结尾的字符串,用于发送有关从 PPPoE 服务器关闭连接的原因的信息。

返回值

允许来自

初始化、线程

示例

/* Close a PPPoE session. */
PppCloseInd(0, NX_NULL);

PppCloseCnf

确认已释放句柄

原型

VOID PppCloseCnf (UINT interfaceHandle);

说明

PPPoE 软件将公开此函数,以允许 TTP 的软件确认句柄已释放。

输入参数

  • interfaceHandle:接口句柄。

返回值

允许来自

初始化、线程

示例

/* Confirm that the handle has been freed. */
PppCloseCnf(0);

PppTransmitDataCnf

允许确认先前的 PPP 数据

原型

VOID PppTransmitDataCnf (
    UINT interfaceHandle,
    UCHAR *aData,
    UINT packet_id);

说明

PPPoE 软件将公开此函数,以允许确认先前的 PppTransmitDataReq。  这意味着,TTP 的软件已经为来自 PPPoE 的新 PPP 帧做好了准备。

输入参数

  • interfaceHandle:接口句柄。
  • aData:指向已接受的 PPP 数据缓冲区的指针。
  • Packet_id:数据包标识符。

返回值

允许来自

初始化、线程

示例

UINT packet_id = 0x20015429

/* Allow a preceding PPP data to be acknowledged, let PPPoE Server release the packet with same packet identifier. */
PppTransmitDataCnf(0, NX_NULL, packet_id);

PppReceiveDataInd

接收通过以太网传输的数据

原型

VOID PppReceiveDataInd(
    UINT interfaceHandle,
    UINT length,
    UCHAR *aData);

说明

PPPoE 软件将公开此函数,以接收通过以太网传输的数据

输入参数

  • interfaceHandle:接口句柄。
  • length:aData 中的字节数。
  • aData:包含 PPP 数据帧的数据缓冲区。

返回值

允许来自

初始化、线程

示例

/* Receive data from transmission over Ethernet, data start pointer is aData.
The number of bytes in aData is 1480. */
PppReceiveDataInd (0, 1480, aData);