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