Chapter 3 - Description of Azure RTOS NetX PPPoE Client Services

This chapter contains a description of all Azure RTOS NetX PPPoE Client services (listed below) in alphabetic order.

In the Return Values section in the following API descriptions, values in BOLD are not affected by the NX_DISABLE_ERROR_CHECKING define that is used to disable API error checking, while non-bold values are completely disabled.

nx_pppoe_client_create

Create a PPPoE Client instance

Prototype

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));

Description

This service creates a PPPoE Client instance with the user supplied link driver for the specified NetX IP instance. If link driver has not been initialized, and enabled, PPPoE Client software is responsible initializing the link driver.

In addition, the application must supply a previously created packet pool for the PPPoE Client instance to use for internal packet allocation.

Note

Generally a good idea to create the NetX IP thread at a higher priority than the PPPoE Client thread priority. Please refer to the nx_ip_create service for more information on specifying the IP thread priority.

Input Parameters

  • pppoe_client_ptr: Pointer to PPPoE Client control block.
  • name: Name of this PPPoE Client instance.
  • ip_ptr: Pointer to control block for IP instance.
  • interface_index: Interface index.
  • pool_ptr: Pointer to packet pool.
  • stack_ptr: Pointer to start of PPPoE Client thread’s stack area.
  • stack_size: Size in bytes in the thread’s stack.
  • priority: Priority of internal PPPoE Client threads (1-31).
  • pppoe_link_driver: User supplied link driver.
  • pppoe_packet_receive: User supplied packet receive function.

Return Values

  • NX_PPPOE_CLIENT_SUCCESS (0x00) Successful PPPoE Client create.
  • NX_PPPOE_CLIENT_PTR_ERROR (0xD1) Invalid PPPoE Client, IP, packet pool, or stack pointer.
  • NX_PPPOE_CLIENT_INVALID_INTERFACE (0xD2) Invalid interface.
  • NX_PPPOE_CLIENT_PACKET_PAYLOAD_ERROR (0xD3) Invalid payload size of packet pool.
  • NX_PPPOE_CLIENT_MEMORY_SIZE_ERROR (0xD4) Invalid memory size.
  • NX_PPPOE_CLIENT_PRIORITY_ERROR (0xD5) Invalid priority of PPPoE Client thread.

Allowed From

Initialization, threads

Example

/* 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

Delete a PPPoE Client instance

Prototype

UINT nx_pppoe_client_delete(
    NX_PPPOE_CLIENT *pppoe_client_ptr);

Description

This service deletes the previously created PPPoE Client instance.

Input Parameters

  • pppoe_client_ptr: Pointer to PPPoE Client control block

Return Values

  • NX_PPPOE_CLIENT_SUCCESS (0x00) Successful PPPoE Client delete.
  • NX_PPPOE_CLIENT_PTR_ERROR (0xD1) Invalid PPPoE Client pointer.

Allowed From

Threads

Example

/* 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

Set PPPoE Client host unique

Prototype

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

Description

This service sets PPPoE Client host unique. Host-Uniq is used by a host to uniquely associate an Access Concentrator to a particular Host request. It can be binary data of any value and length that the Host chooses.

Note

host unique must be Null-terminated string.

Note

This service is deprecated. Developers are encouraged to migrate to nx_pppoe_client_host_uniq_set_extended.

Input Parameters

  • pppoe_client_ptr: Pointer to PPPoE Client control block.
  • host_uniq: Pointer to an host unique. Host unique must be Null-terminated string.

Return Values

  • NX_PPPOE_CLIENT_SUCCESS (0x00) Successful PPPoE Client host unique set.
  • NX_PPPOE_CLIENT_PTR_ERROR (0xD1) Invalid PPPoE Client pointer.

Allowed From

Initialization, threads

Example

/* 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

Set PPPoE Client host unique

Prototype

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

Description

This service sets PPPoE Client host unique. Host-Uniq is used by a host to uniquely associate an Access Concentrator to a particular Host request. It can be binary data of any value and length that the Host chooses.

Note

host unique must be Null-terminated string.

Note

This service replaces nx_pppoe_client_host_uniq_set. This version supplies additional length information to the service.

Input Parameters

  • pppoe_client_ptr: Pointer to PPPoE Client control block.
  • host_uniq: Pointer to an host unique. Host unique must be Null-terminated string.
  • host_uniq_length: Length of host_uniq

Return Values

  • NX_PPPOE_CLIENT_SUCCESS (0x00) Successful PPPoE Client host unique set.
  • NX_PPPOE_CLIENT_PTR_ERROR (0xD1) Invalid PPPoE Client pointer.
  • NX_SIZE_ERROR (0x09) Check host_uniq_length fail

Allowed From

Initialization, threads

Example

/* 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

Set PPPoE Client service name

Prototype

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

Description

This service sets PPPoE Client service name. The Service-Name indicating the service the Host is requesting. If Service-Name is not set, indicating Host will accept any number of services.

Note

service name must be Null-terminated string

Note

This service is deprecated. Developers are encouraged to migrate to nx_pppoe_client_service_name_set_extended.

Input Parameters

  • pppoe_client_ptr: Pointer to PPPoE Client control block.
  • service_name: Pointer to an service name. Service name must be Null-terminated string.

Return Values

  • NX_PPPOE_CLIENT_SUCCESS (0x00) Successful PPPoE Client service name set.
  • NX_PPPOE_CLIENT_PTR_ERROR (0xD1) Invalid PPPoE Client pointer.

Allowed From

Initialization, threads

Example

/* 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

Set PPPoE Client service name

Prototype

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

Description

This service sets PPPoE Client service name. The Service-Name indicating the service the Host is requesting. If Service-Name is not set, indicating Host will accept any number of services.

Note

service name must be Null-terminated string.

Note

This service replaces nx_pppoe_client_service_name_set. This version supplies additional service name length information to the function.

Input Parameters

  • pppoe_client_ptr: Pointer to PPPoE Client control block.
  • service_name: Pointer to an service name. Service name must be Null-terminated string.
  • service_name_length: Length of service_name

Return Values

  • NX_PPPOE_CLIENT_SUCCESS (0x00) Successful PPPoE Client service name set.
  • NX_PPPOE_CLIENT_PTR_ERROR (0xD1) Invalid PPPoE Client pointer.
  • NX_SIZE_ERROR (0x09) Check service_name_length fail

Allowed From

Initialization, threads

Example

/* 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

Connect PPPoE Client session

Prototype

UINT nx_pppoe_client_session_connect(
    NX_PPPOE_CLIENT *pppoe_client_ptr,
    ULONG wait_option);

Description

This service makes PPPoE session connection using a previously created PPPoE Client to the specified PPPoE Server.

Note

This function must be called after nx_pppoe_client_create, nx_pppoe_client_host_uniq_set and nx_pppoe_client_service_name_set.

Input Parameters

  • pppoe_client_ptr: Pointer to PPPoE Client control block.
  • wait_option: Wait option while the connection is being established.

Return Values

  • NX_PPPOE_CLIENT_SUCCESS (0x00) Successful PPPoE Client session connect.
  • NX_PPPOE_CLIENT_PTR_ERROR (0xD1) Invalid PPPoE Client pointer.

Allowed From

Initialization, threads

Example

/* 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

Send PPPoE Client packet to specified session

Prototype

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

Description

This service sends PPPoE packet using specified session ID.

Input Parameters

  • pppoe_client_ptr: Pointer to PPPoE Client control block.
  • packet_ptr: Pointer to PPPoE packet.

Return Values

  • NX_PPPOE_CLIENT_SUCCESS (0x00) Successful PPPoE Client packet send.
  • NX_PPPOE_CLIENT_PTR_ERROR (0xD1) Invalid PPPoE Client pointer.
  • NX_PPPOE_CLIENT_PACKET_PAYLOAD_ERROR (0xD3) Invalid PPPoE Client packet.
  • NX_PPPOE_CLIENT_SESSION_NOT_ESTABLISHED (0xD8) PPPoE session is not established.

Allowed From

Initialization, threads

Example

/* 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

Terminate PPPoE Client session

Prototype

UINT nx_pppoe_client_session_terminate(NX_PPPOE_CLIENT *pppoe_client_ptr);

Description

This service terminates the specified PPPoE session.

Input Parameters

  • pppoe_client_ptr: Pointer to PPPoE Client control block.

Return Values

  • NX_PPPOE_CLIENT_SUCCESS (0x00) Successful PPPoE Client session terminate.
  • NX_PPPOE_CLIENT_PTR_ERROR (0xD1) Invalid PPPoE Client pointer.

Allowed From

Initialization, threads

Example

/* 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

Get the specified PPPoE session information

Prototype

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

Description

This service gets the specified PPPoE session information, server physical address and session id.

Input Parameters

  • pppoe_server_ptr: Pointer to PPPoE Client control block.
  • server_mac_msw: Server Physical address MSW pointer.
  • server_mac_lsw: Server Physical address MSW pointer.
  • session_id: Session ID pointer.

Return Values

  • NX_PPPOE_CLIENT_SUCCESS (0x00) Successful PPPoE Client session get.
  • NX_PPPOE_CLIENT_PTR_ERROR (0xD1) Invalid PPPoE Client pointer.
  • NX_PPPOE_CLIENT_SESSION_NOT_ESTABLISHED (0xD8) PPPoE session is not established.

Allowed From

Initialization, threads

Example

/* 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. */