This chapter contains a description of all NetX Duo PPP 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.
Receive a byte from serial ISR
UINT nx_ppp_byte_receive(
NX_PPP *ppp_ptr,
UCHAR byte);
This service is typically called from the application’s serial driver Interrupt Service Routine (ISR) to transfer a received byte to PPP. When called, this routine places the received byte into a circular byte buffer and notifies the appropriate PPP thread for processing.
Threads, ISRs
/* Notify "my_ppp" of a received byte. */
status = nx_ppp_byte_receive(&my_ppp, new_byte);
/* If status is NX_SUCCESS the received byte was successfully
buffered. */
Generate a CHAP challenge
UINT nx_ppp_chap_challenge(NX_PPP *ppp_ptr);
This service initiates a CHAP challenge after the PPP connection is already up and running. This gives the application the ability to verify the authenticity of the connection on a periodic basis. If the challenge is unsuccessful, the PPP link is closed.
Threads
/* Initiate a PPP challenge for instance "my_ppp". */
status = nx_ppp_chap_challenge(&my_ppp);
/* If status is NX_SUCCESS a CHAP challenge "my_ppp" was successfully
initiated. */
Enable CHAP authentication
UINT nx_ppp_chap_enable(
NX_PPP *ppp_ptr,
UINT (*get_challenge_values)(
CHAR *rand_value,
CHAR *id,
CHAR *name),
UINT (*get_responder_values)(
CHAR *system,
CHAR *name,
CHAR *secret),
UINT (*get_verification_values)(
CHAR *system,
CHAR *name,
CHAR *secret));
This service enables the Challenge-Handshake Authentication Protocol (CHAP) for the specified PPP instance.
If the “get_challenge_values” and “get_verification_values” function pointers are specified, CHAP is required by this PPP instance. Otherwise, CHAP only responds to the peer’s challenge requests.
There are several data items referenced below in the required callback functions. The data items secret, name, and system are expected to be NULL-terminated strings with a maximum size of NX_PPP_NAME_SIZE-1. The data item rand_value is expected to be a NULL-terminated string with a maximum size of NX_PPP_VALUE_SIZE-1. The data item id is a simple unsigned character type.
Note: This function must be called after nx_ppp_create but before nx_ip_create or nx_ip_interface_attach.
Initialization, threads
CHAR name_string[] = "username";
CHAR rand_value_string[] = "123456";
CHAR system_string[] = "system";
CHAR secret_string[] = "secret";
/* Enable CHAP in both directions (CHAP challenger and CHAP responder) for
"my_ppp". */
status = nx_ppp_chap_enable(&my_ppp, get_challenge_values,
get_responder_values,
get_verification_values);
/* If status is NX_SUCCESS, "my_ppp" has CHAP enabled. */
/* Define the CHAP enable routines. */
UINT get_challenge_values(CHAR *rand_value, CHAR *id, CHAR *name)
{
UINT i;
for (i = 0; i< (NX_PPP_NAME_SIZE-1); i++)
{
name[i] = name_string[i];
}
name[i] = 0;
*id = '1'; /* One byte */
for (i = 0; i< (NX_PPP_VALUE_SIZE-1); i++)
{
rand_value[i] = rand_value_string[i];
}
rand_value[i] = 0;
return(NX_SUCCESS);
}
UINT get_responder_values(CHAR *system, CHAR *name, CHAR *secret)
{
UINT i;
for (i = 0; i< (NX_PPP_NAME_SIZE-1); i++)
{
name[i] = name_string[i];
}
name[i] = 0;
for (i = 0; i< (NX_PPP_NAME_SIZE-1); i++)
{
system[i] = system_string[i];
}
system[i] = 0;
for (i = 0; i< (NX_PPP_NAME_SIZE-1); i++)
{
secret[i] = secret_string[i];
}
secret[i] = 0;
return(NX_SUCCESS);
}
UINT get_verification_values(CHAR *system, CHAR *name, CHAR *secret)
{
UINT i;
for (i = 0; i< (NX_PPP_NAME_SIZE-1); i++)
{
name[i] = name_string[i];
}
name[i] = 0;
for (i = 0; i< (NX_PPP_NAME_SIZE-1); i++)
{
system[i] = system_string[i];
}
system[i] = 0;
for (i = 0; i< (NX_PPP_NAME_SIZE-1); i++)
{
secret[i] = secret_string[i];
}
secret[i] = 0;
return(NX_SUCCESS);
}
Create a PPP instance
UINT nx_ppp_create(
NX_PPP *ppp_ptr,
CHAR *name,
NX_IP *ip_ptr,
VOID *stack_memory_ptr,
ULONG stack_size,
UINT thread_priority,
NX_PACKET_POOL *pool_ptr,
void (*ppp_invalid_packet_handler)(NX_PACKET *packet_ptr),
void (*ppp_byte_send)(UCHAR byte));
This service creates a PPP instance for the specified NetX Duo IP instance. This function must be called prior to creating the NetX Duo IP instance.
Note: It is generally a good idea to create the NetX Duo IP thread at a higher priority than the PPP thread priority. Please refer to the nx_ip_create service for more information on specifying the IP thread priority.
Initialization, threads
/* Create "my_ppp" for IP instance "my_ip". */
status = nx_ppp_create(&my_ppp, "my PPP", &my_ip, stack_start, 1024, 2,
&my_pool, my_invalid_packet_handler, my_out_byte);
/* If status is NX_SUCCESS the PPP instance was successfully
created. */
Delete a PPP instance
UINT nx_ppp_delete(NX_PPP *ppp_ptr);
This service deletes the previously created PPP instance.
Threads
/* Delete PPP instance "my_ppp". */
status = nx_ppp_delete(&my_ppp);
/* If status is NX_SUCCESS the "my_ppp" was successfully deleted. */
Get DNS Server IP address
UINT nx_ppp_dns_address_get(
NX_PPP *ppp_ptr,
ULONG *dns_address_ptr);
This service retrieves the DNS IP address supplied by the peer in the IPCP handshake. If no IP address was supplied by the peer, an IP address of 0 is returned.
Initialization, threads, timers, ISRs
ULONG my_dns_address;
/* Get DNS Server address supplied by peer. */
status = nx_ppp_dns_address_get(&my_ppp, &my_dns_address);
/* If status is NX_SUCCESS the "my_dns_address" contains the DNS IP address –
if the peer supplied one. */
Get Secondary DNS Server IP address
UINT nx_ppp_secondary_dns_address_get(
NX_PPP *ppp_ptr,
ULONG *dns_address_ptr);
This service retrieves the secondary DNS IP address supplied by the peer in the IPCP handshake. If no IP address was supplied by the peer, an IP address of 0 is returned.
Initialization, threads, timers, ISRs
ULONG my_dns_address;
/* Get secondary DNS Server address supplied by peer. */
status = nx_ppp_secondary_dns_address_get(&my_ppp, &my_dns_address);
/* If status is NX_SUCCESS the "my_dns_address" contains the secondary DNS Server address – if the peer supplied one. */
Set primary DNS Server IP address
UINT nx_ppp_dns_address_set(
NX_PPP *ppp_ptr,
ULONG dns_address);
This service sets the DNS Server IP address. If the peer sends a DNS Server option request in the IPCP state, this host will provide the information.
Initialization, threads
ULONG my_dns_address = IP_ADDRESS(1,2,3,1);
/* Set DNS Server address. */
status = nx_ppp_dns_address_set(&my_ppp, my_dns_address);
/* If status is NX_SUCCESS the "my_dns_address" will be the DNS Server address provided if the peer requests one. */
Set secondary DNS Server IP address
UINT nx_ppp_secondary_dns_address_set(
NX_PPP *ppp_ptr,
ULONG dns_address);
This service sets the secondary DNS Server IP address. If the peer sends a secondary DNS Server option request in the IPCP state, this host will provide the information.
Initialization, threads
ULONG my_dns_address = IP_ADDRESS(1,2,3,1);
/* Set DNS Server address. */
status = nx_ppp_secondary_dns_address_set(&my_ppp, my_dns_address);
/* If status is NX_SUCCESS the "my_dns_address" will be the secondary DNS Server address provided if the peer requests one. */
Get IP interface index
UINT nx_ppp_interface_index_get(
NX_PPP *ppp_ptr,
UINT *index_ptr);
This service retrieves the IP interface index associated with this PPP instance. This is only useful when the PPP instance is not the primary interface of an IP instance.
Initialization, threads
ULONG my_index;
/* Get the interface index for this PPP instance. */
status = nx_ppp_interface_index_get(&my_ppp, &my_index);
/* If status is NX_SUCCESS the "my_index" contains the IP interface index for
this PPP instance. */
Assign IP addresses for IPCP
UINT nx_ppp_ip_address_assign(
NX_PPP *ppp_ptr,
ULONG local_ip_address,
ULONG peer_ip_address);
This service sets up the local and peer IP addresses for use in the Internet Protocol Control Protocol (IPCP. It should be called for the PPP instance that has valid IP addresses for itself and the other peer.
Initialization, threads
/* Set IP addresses for "my_ppp". */
status = nx_ppp_ip_address_assign(&my_ppp, IP_ADDRESS(256,2,2,187),
IP_ADDRESS(256,2,2,188));
/* If status is NX_SUCCESS the "my_ppp" has the IP addresses. */
Notify application on link down
UINT nx_ppp_link_down_notify(
NX_PPP *ppp_ptr,
VOID (*link_down_callback)(NX_PPP *ppp_ptr));
This service registers the application’s link down notification callback with the specified PPP instance. If non-NULL, the application’s link down callback function is called whenever the link goes down.
Initialization, threads, timers, ISRs
/* Register "my_link_down_callback" to be called whenever the PPP
link goes down. */
status = nx_ppp_link_down_notify(&my_ppp, my_link_down_callback);
/* If status is NX_SUCCESS the function "my_link_down_callback" has been
registered with this PPP instance. */
VOID my_link_down_callback(NX_PPP *ppp_ptr)
{
/* On link down, simply restart PPP. */
nx_ppp_restart(ppp_ptr);
}
Notify application on link up
UINT nx_ppp_link_up_notify(
NX_PPP *ppp_ptr,
VOID (*link_up_callback)(NX_PPP *ppp_ptr));
This service registers the application’s link up notification callback with the specified PPP instance. If non-NULL, the application’s link up callback function is called whenever the link comes up.
Initialization, threads, timers, ISRs
/* Register "my_link_up_callback" to be called whenever the PPP
link comes up. */
status = nx_ppp_link_up_notify(&my_ppp, my_link_up_callback);
/* If status is NX_SUCCESS the function "my_link_up_callback" has been
registered with this PPP instance. */
VOID my_link_up_callback(NX_PPP *ppp_ptr)
{
/* On link up, the application my want to start sending/receiving
UPD/TCP data. */
}
Notify application if authentication NAK received
UINT nx_ppp_nak_authentication_notify(
NX_PPP *ppp_ptr,
void (*nak_authentication_notify)(void));
This service registers the application’s authentication nak notification callback with the specified PPP instance. If non-NULL, this callback function is called whenever the PPP instance receives a NAK during authentication.
Initialization, threads, timers, ISRs
/* Register "my_nak_auth_callback" to be called whenever the PPP
receives a NAK during authentication. */
status = nx_ppp_nak_authentication_notify(&my_ppp, my_nak_auth_callback);
/* If status is NX_SUCCESS the function "my_nak_auth_callback" has been
registered with this PPP instance. */
VOID my_nak_auth_callback(NX_PPP *ppp_ptr)
{
/* Handle the situation of receiving an authentication NAK */
}
Enable PAP Authentication
UINT nx_ppp_pap_enable(
NX_PPP *ppp_ptr,
UINT (*generate_login)(CHAR *name, CHAR *password),
UINT (*verify_login)(CHAR *name, CHAR *password));
This service enables the Password Authentication Protocol (PAP) for the specified PPP instance. If the “verify_login” function pointer is specified, PAP is required by this PPP instance. Otherwise, PAP only responds to the peer’s PAP requirements as specified during LCP negotiation.
There are several data items referenced below in the required callback functions. The data item name is expected to be NULL-terminated string with a maximum size of NX_PPP_NAME_SIZE-1. The data item password is also expected to be a NULL-terminated string with a maximum size of NX_PPP_PASSWORD_SIZE-1.
Note: This function must be called after nx_ppp_create but before nx_ip_create or nx_ip_interface_attach.
Initialization, threads
CHAR name_string[] = "username";
CHAR password_string[] = "password";
/* Enable PAP for PPP instance "my_ppp". */
status = nx_ppp_pap_enable(&my_ppp, my_generate_login, my_verify_login);
/* If status is NX_SUCCESS the "my_ppp" now has PAP enabled. */
/* Define callback routines for PAP enable. */
UINT generate_login(CHAR *name, CHAR *password)
{
UINT i;
for (i = 0; i< (NX_PPP_NAME_SIZE-1); i++)
name[i] = name_string[i];
name[i] = 0;
for (i = 0; i< (NX_PPP_PASSWORD_SIZE-1); i++)
password[i] = password_string[i];
password_string[i] = 0;
return(NX_SUCCESS);
}
UINT verify_login(CHAR *name, CHAR *password)
{
/* Assume name and password are correct. Normally,
a comparison would be made here! */
printf("Name: %s, Password: %s\n", name, password);
return(NX_SUCCESS);
}
Send an LCP ping request
UINT nx_ppp_ping_request(
NX_PPP *ppp_ptr,
CHAR *data,
UINT data_size,
ULONG wait_option);
This service sends an LCP request and sets a flag that the PPP device is waiting for an echo response. The wait option is primarily for the nx_packet_allocate call. The service returns as soon as the request is sent. It does not wait for a response.
When a matching echo response is received, the PPP thread task will clear the flag. The PPP device must have completed the LCP part of the PPP negotiation.
This service is useful for PPP set ups where polling the hardware for link status may not be readily possible.
Application threads
CHAR buffer[] = "username";
UINT buffer_length = sizeof("username ") - 1;
/* Send an LCP ping request". */
status = nx_ppp_ping_request(&my_ppp, &buffer[0], buffer_length, 200);
/* If status is NX_SUCCESS the LCP echo request was successfully sent. Now wait to
receive a response. */
while(my_ppp.nx_ppp_lcp_echo_reply_id > 0)
{
tx_thread_sleep(100);
}
/* Got a valid reply! */
Send a raw ASCII string
UINT nx_ppp_raw_sting_send(
NX_PPP *ppp_ptr,
CHAR *string_ptr);
This service sends a non-PPP ASCII string directly out the PPP interface. It is typically used after PPP receives an non-PPP packet that contains modem control information.
Threads
/* Send "CLIENTSERVER" to "CLIENT" sent by Windows 98 before PPP is
initiated. */
status = nx_ppp_raw_string_send(&my_ppp, "CLIENTSERVER");
/* If status is NX_SUCCESS the raw string was successfully Sent via PPP. */
Restart PPP processing
UINT nx_ppp_restart(NX_PPP *ppp_ptr);
This service restarts the PPP processing. It is typically called when the link needs to be re-established either from a link down callback or by a non-PPP modem message indicating communication was lost.
Threads
/* Restart the PPP instance "my_ppp". */
status = nx_ppp_restart(&my_ppp);
/* If status is NX_SUCCESS the PPP instance has been restarted. */
Start PPP processing
UINT nx_ppp_start(NX_PPP *ppp_ptr);
This service starts the PPP processing. It is typically called after nx_ppp_stop() called.
Note: PPP automatically starts the PPP processing when the link is enabled.
Threads
/* Start the PPP instance "my_ppp". */
status = nx_ppp_start(&my_ppp);
/* If status is NX_SUCCESS the PPP instance has been started. */
Get current PPP status
UINT nx_ppp_status_get(
NX_PPP *ppp_ptr,
UINT *status_ptr);
This service gets the current status of the specified PPP instance.
Note: The status is only valid if the API returns NX_SUCCESS. In addition, if any of the *_FAILED status values are returned, PPP processing is effectively stopped until it is restarted again by the application.
Initialization, threads, timers, ISRs
UINT ppp_status;
UINT status;
/* Get the current status of PPP instance "my_ppp". */
status = nx_ppp_status_get(&my_ppp, &ppp_status);
/* If status is NX_SUCCESS the current internal PPP status is contained in
"ppp_status". */
Start PPP processing
UINT nx_ppp_stop(NX_PPP *ppp_ptr);
This service stops the PPP processing. User also can calls nx_ppp_start() to start the PPP processing if needed.
Threads
/* Stop the PPP instance "my_ppp". */
status = nx_ppp_stop(&my_ppp);
/* If status is NX_SUCCESS the PPP instance has been stopped. */
Receive PPP packet
UINT nx_ppp_packet_receive(
NX_PPP *ppp_ptr,
NX_PACKET *packet_ptr);
This service receives PPP packet.
Initialization, threads
/* Receive the PPP packet of PPP instance "my_ppp". */
status = nx_ppp_packet_receive(&my_ppp, packet_ptr);
/* If status is NX_SUCCESS the PPP packet has received. */
Set the PPP packet send function
UINT nx_ppp_packet_send_set(
NX_PPP *ppp_ptr,
VOID (*nx_ppp_packet_send)(NX_PACKET *packet_ptr));
This service sets the PPP packet send function.
Initialization, threads
/* Set the PPP packet send function of PPP instance "my_ppp". */
status = nx_ppp_packet_send_set(&my_ppp, nx_ppp_packet_send);
/* If status is NX_SUCCESS the PPP packet send function has set. */