Chapter 3 - Description of Azure RTOS NetX PPPoE Server Services

This chapter contains a description of all Azure RTOS NetX PPPoE Server 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_server_create

Create a PPPoE Server instance

Prototype

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

Description

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

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

Note that it is generally a good idea to create the NetX IP thread at a higher priority than the PPPoE Server thread priority. Please refer to the nx_ip_create service for more information on specifying the IP thread priority.

Input Parameters

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

Return Values

  • NX_PPPOE_SERVER_SUCCESS: (0x00) Successful PPPoE Server create.
  • NX_PPPOE_SERVER_PTR_ERROR: (0xC1) Invalid PPPoE Server, IP, packet pool, or stack pointer.
  • NX_PPPOE_SERVER_INVALID_INTERFACE: (0xC2) Invalid interface.
  • NX_PPPOE_SERVER_PACKET_PAYLOAD_ERROR: (0xC3) Invalid payload size of packet pool.
  • NX_PPPOE_SERVER_MEMORY_SIZE_ERROR: (0xC4) Invalid memory size.
  • NX_PPPOE_SERVER_PRIORITY_ERROR: (0xC5) Invalid priority of PPPoE Server thread.

Allowed From

Initialization, threads

Example

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

Delete a PPPoE Server instance

Prototype

UINT nx_pppoe_server_delete(NX_PPPOE_SERVER *pppoe_server_ptr);

Description

This service deletes the previously created PPPoE Server instance.

Input Parameters

  • pppoe_server_ptr: Pointer to PPPoE Server control block.

Return Values

  • NX_PPPOE_SERVER_SUCCESS: (0x00) Successful PPPoE Server delete.
  • NX_PPPOE_SERVER_PTR_ERROR: (0xC1) Invalid PPPoE Server pointer.

Allowed From

Threads

Example

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

Enable PPPoE Server service

Prototype

UINT nx_pppoe_server_enable(NX_PPPOE_SERVER *pppoe_server_ptr);

Description

This service enables the PPPoE Server services.

Note

This function must be called after nx_pppoe_server_create and nx_pppoe_server_callback_notify_set.

Input Parameters

  • pppoe_server_ptr: Pointer to PPPoE Server control block.

Return Values

  • NX_PPPOE_SERVER_SUCCESS: (0x00) Successful PPPoE Server delete.
  • NX_PPPOE_SERVER_PTR_ERROR: (0xC1) Invalid PPPoE Server pointer.

Allowed From

Initialization, threads

Example

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

Disable PPPoE Server service

Prototype

UINT nx_pppoe_server_disable(NX_PPPOE_SERVER *pppoe_server_ptr);

Description

This service disables the PPPoE Server services.

Input Parameters

  • pppoe_server_ptr: Pointer to PPPoE Server control block.

Return Values

  • NX_PPPOE_SERVER_SUCCESS: (0x00) Successful PPPoE Server delete.
  • NX_PPPOE_SERVER_PTR_ERROR: (0xC1) Invalid PPPoE Server pointer.

Allowed From

Initialization, threads

Example

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

Set PPPoE Server callback notify functions

Prototype

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

Description

This service sets PPPoE Server callback notify functions.

Note

This function must be called before nx_pppoe_server_enable, and the pppoe_data_receive_notify function pointer must be set, if not, nx_pppoe_server_enable will be failure.

Input Parameters

  • pppoe_server_ptr: Pointer to PPPoE Server control block.
  • pppoe_discover_initiation_notify: Application function that is called whenever PPPoE discover initiation message is received. If this value is NULL, discover initiation callback function is disabled.
  • pppoe_discover_request_notify: Application function that is called whenever PPPoE discover request message is received. If this value is NULL, discover request callback function is disabled.
  • pppoe_discover_terminate_notify: Application function that is called whenever PPPoE discover terminate message is received. If this value is NULL, discover terminate callback function is disabled.
  • pppoe_discover_terminate_confirm: Application function that is called whenever PPPoE discover terminate message is sent. If this value is NULL, discover terminate callback function is disabled.
  • pppoe_data_receive_notify: Application function that is called whenever PPPoE data message is received. This value must not be zero.
  • pppoe_data_send_notify: Application function that is called whenever PPPoE data message is sent. If this value is NULL, data send callback function is disabled.

Return Values

  • NX_PPPOE_SERVER_SUCCESS: (0x00) Successful PPPoE Server delete.
  • NX_PPPOE_SERVER_PTR_ERROR: (0xC1) Invalid PPPoE Server pointer or function pointer.

Allowed From

Initialization, threads

Example

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

Set Access Concentrator name

Prototype

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

Description

This function set Access Concentrator name function call.

Note

The string of ac_name must be NULL-terminated and length of ac_name matches the length specified in the argument list.

Input Parameters

  • pppoe_server_ptr: Pointer to PPPoE Server control block.
  • ac_name: Access Concentrator name.
  • ac_name_length: Length of ac_ame.

Return Values

  • NX_PPPOE_SERVER_SUCCESS: (0x00) Successful PPPoE Server set.
  • NX_PPPOE_SERVER_PTR_ERROR: (0xC1) Invalid PPPoE Server, IP, packet pool, or stack pointer.
  • NX_SIZE_ERROR: (0x09) Check name_length fail.

Allowed From

Initialization, threads

Example

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

Set PPPoE Server service name

Prototype

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

Description

This service sets PPPoE Server service name.

Input Parameters

  • pppoe_server_ptr: Pointer to PPPoE Server control block.

Return Values

  • NX_PPPOE_SERVER_SUCCESS: (0x00) Successful PPPoE Server delete.
  • NX_PPPOE_SERVER_PTR_ERROR: (0xC1) Invalid PPPoE Server pointer.

Allowed From

Initialization, threads

Example

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

Send PPPoE Server data to specified session

Prototype

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

Description

This service sends PPPoE frame using specified session ID.

Input Parameters

  • pppoe_server_ptr: Pointer to PPPoE Server control block.
  • session_index: The index of session.
  • data_ptr: Pointer to start of PPPoE Server data frame.
  • data_length: Length of PPPoE Server data frame.

Return Values

  • NX_PPPOE_SERVER_SUCCESS: (0x00) Successful PPPoE Server delete.
  • NX_PPPOE_SERVER_PTR_ERROR: (0xC1) Invalid PPPoE Server pointer.
  • NX_PPPOE_SERVER_NOT_ENABLED: (0xC6) PPPoE Server service is not enabled.
  • NX_PPPOE_SERVER_INVALID_SESSION: (0xC7) Invalid PPPoE session index.
  • NX_PPPOE_SERVER_SESSION_NOT_ESTABLISHED: (0xC8) PPPoE session is not established.

Allowed From

Initialization, threads

Example

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

Send PPPoE Server packet to specified session

Prototype

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

Description

This service sends PPPoE packet using specified session ID.

Input Parameters

  • pppoe_server_ptr: Pointer to PPPoE Server control block.
  • session_index: The index of session.
  • packet_ptr: Pointer to PPPoE packet.

Return Values

  • NX_PPPOE_SERVER_SUCCESS: (0x00) Successful PPPoE Server delete.
  • NX_PPPOE_SERVER_PTR_ERROR: (0xC1) Invalid PPPoE Server pointer.
  • NX_PPPOE_SERVER_PACKET_PAYLOAD_ERROR: (0xC3) Invalid PPPoE Server packet.
  • NX_PPPOE_SERVER_NOT_ENABLED: (0xC6) PPPoE Server service is not enabled.
  • NX_PPPOE_SERVER_INVALID_SESSION: (0xC7) Invalid PPPoE session index.
  • NX_PPPOE_SERVER_SESSION_NOT_ESTABLISHED: (0xC8) PPPoE session is not established.

Allowed From

Initialization, threads

Example

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

Terminate the specified PPPoE session

Prototype

UINT nx_pppoe_server_session_terminate(
    NX_PPPOE_SERVER *pppoe_server_ptr,
    UINT session_index);

Description

This service terminates the specified PPPoE session.

Input Parameters

  • pppoe_server_ptr: Pointer to PPPoE Server control block.
  • session_index: The index of session.

Return Values

  • NX_PPPOE_SERVER_SUCCESS: (0x00) Successful PPPoE Server delete.
  • NX_PPPOE_SERVER_PTR_ERROR: (0xC1) Invalid PPPoE Server pointer.
  • NX_PPPOE_SERVER_NOT_ENABLED: (0xC6) PPPoE Server service is not enabled.
  • NX_PPPOE_SERVER_INVALID_SESSION: (0xC7) Invalid PPPoE session index.
  • NX_PPPOE_SERVER_SESSION_NOT_ESTABLISHED: (0xC8) PPPoE session is not established.

Allowed From

Initialization, threads

Example

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

Get the specified PPPoE session information

Prototype

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

Description

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

Input Parameters

  • pppoe_server_ptr: Pointer to PPPoE Server control block.
  • session_index: The index of session.
  • client_mac_msw: Client Physical address MSW pointer.
  • client_mac_lsw: Client Physical address MSW pointer.
  • session_id: Session ID pointer.

Return Values

  • NX_PPPOE_SERVER_SUCCESS: (0x00) Successful PPPoE Server delete.
  • NX_PPPOE_SERVER_PTR_ERROR: (0xC1) Invalid PPPoE Server pointer.
  • NX_PPPOE_SERVER_INVALID_SESSION: (0xC7) Invalid PPPoE session index.
  • NX_PPPOE_SERVER_SESSION_NOT_ESTABLISHED: (0xC8) PPPoE session is not established.

Allowed From

Initialization, threads

Example

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

Configure the default Service Name

Prototype

VOID PppInitnd(
    UINT length,
    UCHAR *aData);

Description

The PPPoE software will expose this function to allow TTP's software to configure the 'default Service Name' that the PPPoE should use to filter incoming PADI requests. The PPPoE software should remember this information, and if a PADI packet is received containing a service name that matches then it should call PppDiscoverReq.

Input Parameters

  • length: Length of default service name.
  • aData: Default service name.

Return Values

None

Allowed From

Initialization, threads

Example

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

PppDiscoverCnf

Define the Service Name field of the PADO packet

Prototype

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

Description

The PPPoE software will expose this function to allow TTP's software to define the Service Name field of the PADO packet. The PPPoE software should not send the PADO until the PppDiscoverCnf is called.

The PADO packet shall contain an access concentrator name (using the tag id 0x0102 as defined in RFC2516), defined on initialization of the PPPoE software.

Multiple service names can be passed in aData, with each name to be null terminated.

Null character is used as a separator to provide maximum flexibility in case other commands need to be passed in as part of the service name.

Input Parameters

  • length: Length of default service name.
  • aData: Default service name.
  • interfaceHandle: Interface handle.

Return Values

None

Allowed From

Initialization, threads

Example

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

PppOpenCnf

Accept or reject the PPPoE session

Prototype

VOID PppOpenCnf (
    UCHAR accept,
    UINT interfaceHandle);

Description

The PPPoE software will expose this function to allow TTP's software to accept or reject the PPPoE session.  In response to this the PPPoE stack should accept the connection and assign a unique PPPoE Session_ID number associated with the interfaceHandle.

Input Parameters

  • accept: NX_TRUE if the connection is to be accepted.
  • interfaceHandle: Interface handle.

Return Values

None

Allowed From

Initialization, threads

Example

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

PppCloseInd

Close a PPPoE session

Prototype

VOID PppCloseInd (
    UINT interfaceHandle,
    UCHAR *causeCode);

Description

The PPPoE software will expose this function to allow TTP's software to close a PPPoE session.

The PPPoE software will indicate the cause code string in the Generic-Error tag (0x0203) in the PADT message

Input Parameters

  • interfaceHandle: Interface handle.
  • causeCode: Null terminated string for sending information about the reason for closing the connection from the PPPoE Server.

Return Values

None

Allowed From

Initialization, threads

Example

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

PppCloseCnf

Confirm that the handle has been freed

Prototype

VOID PppCloseCnf (UINT interfaceHandle);

Description

The PPPoE software will expose this function to allow TTP's software to confirm that the handle has been freed.

Input Parameters

  • interfaceHandle: Interface handle.

Return Values

None

Allowed From

Initialization, threads

Example

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

PppTransmitDataCnf

Allow a preceding PPP data to be acknowledged

Prototype

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

Description

The PPPoE software will expose this function to allow a preceding PppTransmitDataReq to be acknowledged.  It implies that TTP's software is ready for a new PPP frame from PPPoE.

Input Parameters

  • interfaceHandle: Interface handle.
  • aData: Pointer the PPP data buffer that has been accepted.
  • Packet_id: Packet identifier.

Return Values

None

Allowed From

Initialization, threads

Example

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

Receive data from transmission over Ethernet

Prototype

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

Description

The PPPoE software will expose this function to receive data for transmission over Ethernet

Input Parameters

  • interfaceHandle: Interface handle.
  • length: The number of bytes in aData.
  • aData: Data buffer containing the frame of PPP data.

Return Values

None

Allowed From

Initialization, threads

Example

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