This chapter contains a description of all NetX Duo HTTP services (listed below) in alphabetical order except for the ‘NetX’ (IPv4 only) equivalent of the same service are paired together).
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.
Create a PPPoE Client instance
UINT nx_http_client_create(
NX_HTTP_CLIENT *client_ptr,
CHAR *client_name,
NX_IP *ip_ptr,
NX_PACKET_POOL *pool_ptr,
ULONG window_size);
This service creates an HTTP Client instance on the specified IP instance.
Initialization, Threads
/* Create the HTTP Client instance "my_client" on "ip_0". */
status = nx_http_client_create(&my_client, "my client", &ip_0, &pool_0, 100);
/* If status is NX_SUCCESS an HTTP Client instance was successfully created. */
Delete an HTTP Client Instance
UINT nx_http_client_delete(NX_HTTP_CLIENT *client_ptr);
This service deletes a previously created HTTP Client instance.
Threads
/* Delete the HTTP Client instance "my_client." */
status = nx_http_client_delete(&my_client);
/* If status is NX_SUCCESS an HTTP Client instance was successfully deleted. */
Start an HTTP GET request over IPv4
UINT nx_http_client_get_start(
NX_HTTP_CLIENT *client_ptr,
ULONG ip_address,
CHAR *resource,
CHAR *input_ptr,
UINT input_size,
CHAR *username,
CHAR *password,
ULONG wait_option);
This service attempts to create and send a GET request with the resource specified by “resource” pointer on the previously created HTTP Client instance. If this routine returns NX_SUCCESS, the application can then make multiple calls to nx_http_client_get_packet to retrieve packets of data corresponding to the requested resource content.
Note: The resource string can refer to a local file e.g.
"/index.htm"or it can refer to another URL e.g.http://abc.website.com/index.htmif the HTTP Server indicates it supports referring GET requests.
This service works only over IPv4 network. For applications that need to connect to IPv6 network, nxd_http_client_get_start_extended should be used.
This service is deprecated. Developers are encouraged to migrate to nx_http_client_get_start_extended or nxd_http_client_get_start_extended.
input_ptr.Threads
/* Start the GET operation on the HTTP Client "my_client." */
status = nx_http_client_get_start(&my_client, IP_ADDRESS(1,2,3,5), "/TEST.HTM",
NX_NULL, 0, "myname", "mypassword", 1000);
/* If status is NX_SUCCESS, the GET request for TEST.HTM is started and is so
far successful. The client must now call nx_http_client_get_packet multiple
times to retrieve the content associated with TEST.HTM. */
#define POST_MESSAGE "Add this data to the message content"
/* Start the POST operation on the HTTP Client "my_client." */
status = nx_http_client_get_start(&my_client, IP_ADDRESS(1,2,3,5), "/TEST.HTM",
POST_MESSAGE, sizeof(POST_MESSAGE),
"myname", "mypassword", 1000);
/* If status is NX_SUCCESS, the POST_MESSAGE is added to the message in the POST request
for TEST.HTM and successfully sent. */
Start an HTTP GET request over IPv4
UINT nx_http_client_get_start_extended(
NX_HTTP_CLIENT *client_ptr,
ULONG ip_address,
CHAR *resource,
UINT resource_length,
CHAR *input_ptr,
UINT input_size,
CHAR *username,
UINT username_length,
CHAR *password,
UINT password_length,
ULONG wait_option);
This service attempts to create and send a GET request with the resource specified by “resource” pointer on the previously created HTTP Client instance. If this routine returns NX_SUCCESS, the application can then make multiple calls to nx_http_client_get_packet to retrieve packets of data corresponding to the requested resource content.
Note: The resource string can refer to a local file e.g.
"/index.htm"or it can refer to another URL e.g.http://abc.website.com/index.htmif the HTTP Server indicates it supports referring GET requests.
This service works only over IPv4 network. For applications that need to connect to IPv6 network, nxd_http_client_get_start_extended should be used.
This service replaces nx_http_client_get_start. It requires caller to specify the length of the resource, username and password.
input_ptr.Threads
/* If status is NX_SUCCESS, the GET request for TEST.HTM is started and is so
far successful. The client must now call nx_http_client_get_packet multiple
times to retrieve the content associated with TEST.HTM. */
#define POST_MESSAGE "Add this data to the message content"
/* Start the POST operation on the HTTP Client "my_client." */
status = nx_http_client_get_start_extended(&my_client, IP_ADDRESS(1,2,3,5), "/TEST.HTM",
9, POST_MESSAGE, sizeof(POST_MESSAGE),
"myname", 6, "mypassword", 10, 1000);
/* If status is NX_SUCCESS, the POST_MESSAGE is added to the message in the POST request
for TEST.HTM and successfully sent. */
Send an HTTP GET request (IPv4 or IPv6)
UINT nxd_http_client_get_start(
NX_HTTP_CLIENT *client_ptr,
NXD_ADDRESS *server_ip,
CHAR *resource,
CHAR *input_ptr,
UINT input_size,
CHAR *username,
CHAR *password,
ULONG wait_option);
This service attempts to create and send a GET request with the resource specified by resource pointer on the previously created HTTP Client instance. It can be used to connect to IPv4 or IPv6 network. If this routine returns NX_SUCCESS, the application can then make multiple calls to nx_http_client_get_packet to retrieve packets of data corresponding to the requested resource content.
Note: The resource string can refer to a local file e.g.
"/index.htm"or it can refer to another URL e.g.http://abc.website.com/index.htmif the HTTP Server indicates it supports referring GET requests.
This service is deprecated. Developers are encouraged to migrate to nxd_http_client_get_start_extended.
input_ptr.Threads
NXD_ADDRESS server_ip_address;
/* for an IPv4 address, define as follows: */
server_ip_address.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_address.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,4);
/* for an IPv6 address, define as follows: */
server_ip_address.nxd_ip_version = NX_IP_VERSION_V6;
server_ip_address.nxd_ip_address.v6[0] = 0x20010db8;
server_ip_address.nxd_ip_address.v6[1] = 0x0;
server_ip_address.nxd_ip_address.v6[2] = 0xf101;
server_ip_address.nxd_ip_address.v6[3] = 0x106;
/* Start the GET operation on the HTTP Client "my_client." */
status = nxd_http_client_get_start(&my_client, server_ip_address, "/TEST.HTM",
NX_NULL, 0, "myname", "mypassword", 1000);
/* If status is NX_SUCCESS, the GET request for TEST.HTM is started and is so
far successful. The client must now call nx_http_client_get_packet multiple
times to retrieve the content associated with TEST.HTM. */
Send an HTTP GET request (IPv4 or IPv6)
UINT nxd_http_client_get_start_extended(
NX_HTTP_CLIENT *client_ptr,
NXD_ADDRESS *server_ip,
CHAR *resource,
UINT resource_length,
CHAR *input_ptr,
UINT input_size,
CHAR *username,
UINT username_length,
CHAR *password,
UINT password_length,
ULONG wait_option);
This service attempts to create and send a GET request with the resource specified by “resource” pointer on the previously created HTTP Client instance. It can be used to connect to IPv4 or IPv6 network. If this routine returns NX_SUCCESS, the application can then make multiple calls to nx_http_client_get_packet to retrieve packets of data corresponding to the requested resource content.
Note: The resource string can refer to a local file e.g.
"/index.htm"or it can refer to another URL e.g.http://abc.website.com/index.htmif the HTTP Server indicates it supports referring GET requests.
This service replaces nxd_http_client_get_start. It requires caller to specify the length of the resource, username and password.
input_ptr.Selecting TX_WAIT_FOREVER causes the calling thread to suspend indefinitely until the HTTP Server responds to the request.
Selecting a numeric value (0x1-0xFFFFFFFE) specifies the maximum number of timer-ticks to stay suspended while waiting for the HTTP Server response.
Threads
NXD_ADDRESS server_ip_address;
/* for an IPv4 address, define as follows: */
server_ip_address.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_address.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,4);
/* for an IPv6 address, define as follows: */
server_ip_address.nxd_ip_version = NX_IP_VERSION_V6;
server_ip_address.nxd_ip_address.v6[0] = 0x20010db8;
server_ip_address.nxd_ip_address.v6[1] = 0x0;
server_ip_address.nxd_ip_address.v6[2] = 0xf101;
server_ip_address.nxd_ip_address.v6[3] = 0x106;
/* Start the GET operation on the HTTP Client "my_client." */
status = nxd_http_client_get_start_extended(&my_client, server_ip_address,
"/TEST.HTM", 9, NX_NULL, 0, "myname",
6, "mypassword", 10, 1000);
/* If status is NX_SUCCESS, the GET request for TEST.HTM is started and is so
far successful. The client must now call nx_http_client_get_packet multiple
times to retrieve the content associated with TEST.HTM. */
Get next resource data packet
UINT nx_http_client_get_packet(
NX_HTTP_CLIENT *client_ptr,
NX_PACKET **packet_ptr,
ULONG wait_option);
This service retrieves the next packet of content of the resource requested by the previous nx_http_client_get_start call. Successive calls to this routine should be made until the return status of NX_HTTP_GET_DONE is received.
Threads
/* Get the next packet of resource content on the HTTP Client "my_client."
Note that the nx_http_client_get_start routine must have been called
previously. */
status = nx_http_client_get_packet(&my_client, &next_packet, 1000);
/* If status is NX_SUCCESS, the next packet of content is pointed to
by "next_packet". */
Start an HTTP PUT request over IPv4
UINT nx_http_client_put_start(
NX_HTTP_CLIENT *client_ptr,
ULONG ip_address,
CHAR *resource,
CHAR *username,
CHAR *password,
ULONG total_bytes,
ULONG wait_option);
This service attempts to send a PUT request with the specified resource to the HTTP Server at the supplied IP address. If this routine is successful, the application code should make successive calls to the nx_http_client_put_packet routine to actually send the resource contents to the HTTP Server.
Note: The resource string can refer to a local file e.g.
"/index.htm"or it can refer to another URL e.g.http://abc.website.com/index.htmif the HTTP Server indicates it supports referring PUT requests.
This service is deprecated. Developers are encouraged to migrate to nxd_http_client_put_start_extended.
Threads
/* Start an HTTP PUT to place the 20-byte resource "/TEST.HTM" on the HTTP Server
at IP address 1.2.3.5. */
status = nx_http_client_put_start(&my_client, IP_ADDRESS(1, 2, 3, 5),
"/TEST.HTM", "myname", "mypassword", 20, NX_WAIT_FOREVER);
/* If status is NX_SUCCESS, the PUT operation for TEST.HTM has successfully been
started. */
Start an HTTP PUT request over IPv4
UINT nx_http_client_put_start_extended(
NX_HTTP_CLIENT *client_ptr,
ULONG ip_address,
CHAR *resource,
UINT resource_length,
CHAR *username,
UINT username_length,
CHAR *password,
UINT password_length,
ULONG total_bytes,
ULONG wait_option);
This service attempts to send a PUT request with the specified resource to the HTTP Server at the supplied IP address. If this routine is successful, the application code should make successive calls to the nx_http_client_put_packet routine to actually send the resource contents to the HTTP Server.
Note: The resource string can refer to a local file e.g.
"/index.htm"or it can refer to another URL e.g.http://abc.website.com/index.htmif the HTTP Server indicates it supports referring PUT requests.
This service replaces nx_http_client_put_start. It requires caller to specify the length of the resource, username and password.
Threads
/* Start an HTTP PUT to place the 20-byte resource "/TEST.HTM" on the HTTP Server
at IP address 1.2.3.5. */
status = nx_http_client_put_start_extended(&my_client, IP_ADDRESS(1, 2, 3, 5),
"/TEST.HTM", 9, "myname", 6, "mypassword", 10, 20, NX_WAIT_FOREVER);
/* If status is NX_SUCCESS, the PUT operation for TEST.HTM has successfully been
started. */
Start an HTTP PUT request (IPv4 or IPv6)
UINT nxd_http_client_put_start(
NX_HTTP_CLIENT *client_ptr,
NXD_ADDRESS *server_ip,
CHAR *resource,
CHAR *username,
CHAR *password,
ULONG total_bytes,
ULONG wait_option);
This service attempts to PUT (send) the specified resource on the HTTP Server at the supplied IP address over IPv6. If this routine is successful, the application code should make successive calls to the nx_http_client_put_packet routine to actually send the resource contents to the HTTP Server.
Note: The resource string can refer to a local file e.g.
"/index.htm"or it can refer to another URL e.g.http://abc.website.com/index.htmif the HTTP Server indicates it supports referring PUT requests.
This service is deprecated. Developers are encouraged to migrate to nxd_http_client_put_start_extended.
Threads
NXD_ADDRESS server_ip_address;
/* for an IPv4 address, define as follows: */
server_ip_address.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_address.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,4);
/* for an IPv6 address, define as follows: */
server_ip_address.nxd_ip_version = NX_IP_VERSION_V6;
server_ip_address.nxd_ip_address.v6[0] = 0x20010db8;
server_ip_address.nxd_ip_address.v6[1] = 0x0;
server_ip_address.nxd_ip_address.v6[2] = 0xf101;
server_ip_address.nxd_ip_address.v6[3] = 0x106;
/* Start an HTTP PUT to place the 20-byte resource Client_test.HTM" on the HTTPv6
Server. */
status = nxd_http_client_put_start(&my_client, &server_ip_address,
"/client_test.htm", "name", "password", 103, 50);
/* If status is NX_SUCCESS, the PUT operation for Client_test.HTM has successfully
been started. */
Start an HTTP PUT request (IPv4 or IPv6)
UINT nxd_http_client_put_start_extended(
NX_HTTP_CLIENT *client_ptr,
NXD_ADDRESS *server_ip,
CHAR *resource,
UINT resource_length,
CHAR *username,
UINT username_length,
CHAR *password,
UINT password_length,
ULONG total_bytes,
ULONG wait_option);
This service attempts to PUT (send) the specified resource on the HTTP Server at the supplied IP address over IPv6. If this routine is successful, the application code should make successive calls to the nx_http_client_put_packet routine to actually send the resource contents to the HTTP Server.
Note: The resource string can refer to a local file e.g.
"/index.htm"or it can refer to another URL e.g.http://abc.website.com/index.htmif the HTTP Server indicates it supports referring PUT requests.
This service replaces nxd_http_client_put_start. It requires caller to specify the length of the resource, username and password.
Threads
NXD_ADDRESS server_ip_address;
/* for an IPv4 address, define as follows: */
server_ip_address.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_address.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,4);
/* for an IPv6 address, define as follows: */
server_ip_address.nxd_ip_version = NX_IP_VERSION_V6;
server_ip_address.nxd_ip_address.v6[0] = 0x20010db8;
server_ip_address.nxd_ip_address.v6[1] = 0x0;
server_ip_address.nxd_ip_address.v6[2] = 0xf101;
server_ip_address.nxd_ip_address.v6[3] = 0x106;
/* Start an HTTP PUT to place the 20-byte resource Client_test.HTM" on the HTTPv6
Server. */
status = nxd_http_client_put_start_extended(&my_client, &server_ip_address,
"/client_test.htm", 16, "name", 4, "password", 8, 103, 50);
/* If status is NX_SUCCESS, the PUT operation for Client_test.HTM has successfully
been started. */
Send next resource data packet
UINT nx_http_client_put_packet(
NX_HTTP_CLIENT *client_ptr,
NX_PACKET *packet_ptr,
ULONG wait_option);
This service attempts to send the next packet of resource content to the HTTP Server.
Note: This routine should be called repetitively until the combined length of the packets sent equals the “total_bytes” specified in the previous nx_http_client_put_start call.
Threads
/* Send a 20-byte packet representing the content of the resource
"/TEST.HTM" to the HTTP Server. */
status = nx_http_client_put_packet(NX_HTTP_CLIENT *client_ptr, NX_PACKET *packet_ptr, ULONG wait_option);
/* If status is NX_SUCCESS, the 20-byte resource contents of TEST.HTM has
successfully been sent. */
Set the connection port to the Server
UINT nx_http_client_set_connect_port(
NX_HTTP_CLIENT *client_ptr,
UINT port);
This service changes the connect port when connecting to the HTTP Server to the specified port at runtime. Otherwise the connect port defaults to 80. This must be called before nx_http_client_get_start and nx_http_client_put_start e.g. when the HTTP Client connects with the Server.
Threads, Initialization
NX_HTTP_CLIENT *client_ptr;
/* Change the connect port to 114. */
status = nx_http_client_set_connect_port(client_ptr, 114);
/* If status is NX_SUCCESS, the connect port is successfully changed. */
Set the callback to retrieve URL max age and date
UINT nx_http_server_cache_info_callback_set(
NX_HTTP_SERVER *server_ptr,
UINT (*cache_info_get)(
CHAR *resource,
UINT *max_age,
NX_HTTP_SERVER_DATE *date));
This service sets the callback service invoked to obtain the maximum age and last modified date of the specified resource.
Initialization
NX_HTTP_SERVER my_server;
UINT cache_info_get(CHAR *resource, UINT *max_age,
NX_HTTP_SERVER_DATE *last_modified);
/* After my_server is created with nx_http_server_create and before the HTTP
server is set by nx_http_server_start, set the cache info callback: */
status = nx_http_server_cache_info_callback_set(&my_server, cache_info_get);
/* If status is NX_SUCCESS, the callback was successfully sent. */
Send data from callback function
UINT nx_http_server_callback_data_send(
NX_HTTP_SERVER *server_ptr,
VOID *data_ptr,
ULONG data_length);
This service sends the data in the supplied packet from the application’s callback routine. This is typically used to send dynamic data associated with GET/POST requests.
Note: If this function is used, the callback routine is responsible for sending the entire response in the proper format. In addition, the callback routine must return the status of NX_HTTP_CALLBACK_COMPLETED.
Threads
UINT my_request_notify(NX_HTTP_SERVER *server_ptr, UINT request_type,
CHAR *resource, NX_PACKET *packet_ptr)
{
/* Look for the test resource! */
if ((request_type == NX_HTTP_SERVER_GET_REQUEST) &&
(strcmp(resource, "/test.htm") == 0))
{
/* Found it, override the GET processing by sending the resource
contents directly. */
nx_http_server_callback_data_send(server_ptr,
"HTTP/1.0 200 \r\nContent-Length:
103\r\nContent-Type: text/html\r\n\r\n",
63);
nx_http_server_callback_data_send(server_ptr, "<HTML>\r\n<HEAD><TITLE>NetX
HTTP Test </TITLE></HEAD>\r\n
<BODY>\r\n<H1>NetX Test Page
</H1>\r\n</BODY>\r\n</HTML>\r\n", 103);
/* Return completion status. */
return(NX_HTTP_CALLBACK_COMPLETED);
}
return(NX_SUCCESS);
}
Create a response header in a callback function
UINT nx_http_server_callback_generate_response_header(
NX_HTTP_SERVER *server_ptr,
NX_PACKET **packet_pptr,
CHAR *status_code,
UINT content_length,
CHAR *content_type,
CHAR* additional_header);
This service calls the internal function _nx_http_server_generate_response_header when the HTTP server responds to Client get, put and delete requests. It is intended for use in HTTP server callback functions when the HTTP server application is designing its response to the Client.
This service is deprecated. Developers are encouraged to migrate to nxd_http_server_callback_generate_response_header_extended.
Threads
CHAR demotestbuffer[] = "<html>\r\n\r\n<head>\r\n\r\n<title>Main \
Window</title>\r\n</head>\r\n\r\n<body>Test message\r\n \ </body>\r\n</html>\r\n";
/* my_request_notify is the application request notify callback registered with
the HTTP server in nx_http_server_create, creates a response to the received
Client request. */
UINT my_request_notify(NX_HTTP_SERVER *server_ptr, UINT request_type,
CHAR *resource, NX_PACKET *recv_packet_ptr)
{
NX_PACKET *sresp_packet_ptr;
ULONG string_length;
CHAR temp_string[30];
ULONG length = 0;
length = sizeof(demotestbuffer) - 1;
/* Derive the client request type from the client request. */
string_length = (ULONG) nx_http_server_type_retrieve(server_ptr, server_ptr ->
nx_http_server_request_resource, temp_string,
sizeof(temp_string));
/* Null terminate the string. */
temp_string[temp] = 0;
/* Now build a response header with server status is OK and no additional header
info. */
status = nx_http_server_callback_generate_response_header(http_server_ptr,
&resp_packet_ptr, NX_HTTP_STATUS_OK,
length, temp_string, NX_NULL);
/* If status is NX_SUCCESS, the header was successfully appended. */
/* Now add data to the packet. */
status = nx_packet_data_append(resp_packet_ptr, &demotestbuffer[0],
length, server_ptr ->
nx_http_server_packet_pool_ptr, NX_WAIT_FOREVER);
if (status != NX_SUCCESS)
{
nx_packet_release(resp_packet_ptr);
return status;
}
/* Now send the packet! */
status = nx_tcp_socket_send(&(server_ptr -> nx_http_server_socket),
resp_packet_ptr, NX_HTTP_SERVER_TIMEOUT_SEND);
if (status != NX_SUCCESS)
{
nx_packet_release(resp_packet_ptr);
return status;
}
/* Let HTTP server know the response has been sent. */
return NX_HTTP_CALLBACK_COMPLETED;
}
Create a response header in a callback function
UINT nx_http_server_callback_generate_response_header_extended(
NX_HTTP_SERVER *server_ptr,
NX_PACKET **packet_pptr,
CHAR *status_code,
UINT status_code_length,
UINT content_length,
CHAR *content_type,
UINT content_type_length,
CHAR *additional_header,
UINT additional_header_length);
This service calls the internal function _nx_http_server_generate_response_header when the HTTP server responds to Client get, put and delete requests. It is intended for use in HTTP server callback functions when the HTTP server application is designing its response to the Client.
This service replaces nx_http_server_callback_generate_response_header. This version supplies additional length information to the callback function.
Threads
CHAR demotestbuffer[] = "<html>\r\n\r\n<head>\r\n\r\n<title>Main \
Window</title>\r\n</head>\r\n\r\n<body>Test message\r\n \ </body>\r\n</html>\r\n";
/* my_request_notify is the application request notify callback registered with
the HTTP server in nx_http_server_create, creates a response to the received
Client request. */
UINT my_request_notify(NX_HTTP_SERVER *server_ptr, UINT request_type,
CHAR *resource, NX_PACKET *recv_packet_ptr)
{
NX_PACKET *sresp_packet_ptr;
ULONG string_length;
CHAR temp_string[30];
ULONG length = 0;
length = sizeof(demotestbuffer) - 1;
/* Derive the client request type from the client request. */
string_length = (ULONG) nx_http_server_type_retrieve(server_ptr, server_ptr ->
nx_http_server_request_resource, temp_string,
sizeof(temp_string));
/* Null terminate the string. */
temp_string[temp] = 0;
/* Now build a response header with server status is OK and no additional header
info. */
status = nx_http_server_callback_generate_response_header_extended(
http_server_ptr, &resp_packet_ptr, NX_HTTP_STATUS_OK,
sizeof(NX_HTTP_STATUS_OK) - 1, length,
temp_string, string_length, NX_NULL, 0);
/* If status is NX_SUCCESS, the header was successfully appended. */
/* Now add data to the packet. */
status = nx_packet_data_append(resp_packet_ptr, &demotestbuffer[0],
length, server_ptr ->
nx_http_server_packet_pool_ptr, NX_WAIT_FOREVER);
if (status != NX_SUCCESS)
{
nx_packet_release(resp_packet_ptr);
return status;
}
/* Now send the packet! */
status = nx_tcp_socket_send(&(server_ptr -> nx_http_server_socket),
resp_packet_ptr, NX_HTTP_SERVER_TIMEOUT_SEND);
if (status != NX_SUCCESS)
{
nx_packet_release(resp_packet_ptr);
return status;
}
/* Let HTTP server know the response has been sent. */
return NX_HTTP_CALLBACK_COMPLETED;
}
Send an HTTP packet from callback function
UINT nx_http_server_callback_packet_send(
NX_HTTP_SERVER *server_ptr,
NX_PACKET *packet_ptr);
This service sends a complete HTTP server response from an HTTP callback. HTTP server will send the packet with the NX_HTTP_SERVER _TIMEOUT_SEND. The HTTP header and data must be appended to the packet. If the return status indicates an error, the HTTP application must release the packet.
The callback should return NX_HTTP_CALLBACK_COMPLETED.
See nx_http_server_callback_generate_response_header for a more detailed example.
Threads
/* The packet is appended with HTTP header and data and is ready to send to the
Client directly. */
status = nx_http_server_callback_response_send(server_ptr, packet_ptr);
if (status != NX_SUCCESS)
{
nx_packet_release(packet_ptr);
}
return(NX_HTTP_CALLBACK_COMPLETED);
Send response from callback function
UINT nx_http_server_callback_response_send(
NX_HTTP_SERVER *server_ptr,
CHAR *header,
CHAR *information,
CHAR additional_info);
This service sends the supplied response information from the application’s callback routine. This is typically used to send custom responses associated with GET/POST requests.
Note: If this function is used, the callback routine must return the status of NX_HTTP_CALLBACK_COMPLETED.
This service is deprecated. Developers are encouraged to migrate to nxd_http_server_callback_response_send_extended.
Threads
UINT my_request_notify(NX_HTTP_SERVER *server_ptr, UINT request_type,
CHAR *resource, NX_PACKET *packet_ptr)
{
/* Look for the test resource! */
if ((request_type == NX_HTTP_SERVER_GET_REQUEST) &&
(strcmp(resource, "/test.htm") == 0))
{
/* In this example, we will complete the GET processing with
a resource not found response. */
nx_http_server_callback_response_send(server_ptr,
"HTTP/1.0 404 ",
"NetX HTTP Server unable to find
file: ", resource);
/* Return completion status. */
return(NX_HTTP_CALLBACK_COMPLETED);
}
return(NX_SUCCESS);
}
Send response from callback function
UINT nx_http_server_callback_response_send_extended(
NX_HTTP_SERVER *server_ptr,
CHAR *header,
UINT header_length,
CHAR *information,
UINT information_length,
CHAR *additional_info,
UINT additional_info_length);
This service sends the supplied response information from the application’s callback routine. This is typically used to send custom responses associated with GET/POST requests.
Note: If this function is used, the callback routine must return the status of NX_HTTP_CALLBACK_COMPLETED.
This service replaces nx_http_server_callback_response_send. This version takes additional length information as arguments.
Threads
UINT my_request_notify(NX_HTTP_SERVER *server_ptr, UINT request_type,
CHAR *resource, NX_PACKET *packet_ptr)
{
/* Look for the test resource! */
if ((request_type == NX_HTTP_SERVER_GET_REQUEST) &&
(strcmp(resource, "/test.htm") == 0))
{
/* In this example, we will complete the GET processing with
a resource not found response. */
nx_http_server_callback_response_send_extended(
server_ptr,
"HTTP/1.0 404 ", 12,
"NetX HTTP Server unable to find
file: ", 38, resource, 9);
/* Return completion status. */
return(NX_HTTP_CALLBACK_COMPLETED);
}
return(NX_SUCCESS);
}
Get content from the request
UINT nx_http_server_content_get(
NX_HTTP_SERVER *server_ptr,
NX_PACKET *packet_ptr,
ULONG byte_offset,
CHAR *destination_ptr,
UINT destination_size,
UINT *actual_size);
This service attempts to retrieve the specified amount of content from the POST or PUT HTTP Client request. It should be called from the application’s request notify callback specified during HTTP Server creation (nx_http_server_create).
This service is deprecated. Developers are encouraged to migrate to nx_http_server_content_get_extended.
Threads
/* Assuming we are in the application's request notify callback
routine, retrieve up to 100 bytes of content starting at offset
0. */
status = nx_http_server_content_get(&my_server, packet_ptr,
0, my_buffer, 100, &actual_size);
/* If status is NX_SUCCESS, "my_buffer" contains "actual_size" bytes of
request content. */
Get content from the request/supports zero length Content Length
UINT nx_http_server_content_get_extended(
NX_HTTP_SERVER *server_ptr,
NX_PACKET *packet_ptr,
ULONG byte_offset,
CHAR *destination_ptr,
UINT destination_size,
UINT *actual_size);
This service is almost identical to nx_http_server_content_get it attempts to retrieve the specified amount of content from the POST or PUT HTTP Client request. However it handles requests with Content Length of zero value (‘empty request’) as a valid request. It should be called from the application’s request notify callback specified during HTTP Server creation (nx_http_server_create).
This service replaces nx_http_server_content_get. This version requires caller to supply additional length information.
Threads
/* Assuming we are in the application's request notify callback
routine, retrieve up to 100 bytes of content starting at offset
0. */
status = nx_http_server_content_get_extended(&my_server, packet_ptr,
0, my_buffer, 100, &actual_size);
/* If status is NX_SUCCESS, "my_buffer" contains "actual_size" bytes of
request content. */
Get length of content in the request
UINT nx_http_server_content_length_get(NX_PACKET *packet_ptr);
This service attempts to retrieve the HTTP content length in the supplied packet. If there is no HTTP content, this routine returns a value of zero. It should be called from the application’s request notify callback specified during HTTP Server creation (nx_http_server_create).
This service is deprecated. Developers are encouraged to migrate to nx_http_server_content_length_get_extended.
Threads
/* Assuming we are in the application's request notify callback
routine, get the content length of the HTTP Client request. */
length = nx_http_server_content_length_get(packet_ptr);
/* The "length" variable now contains the length of the HTTP Client
request content area. */
Get length of content in the request/supports Content Length of zero value
UINT nx_http_server_content_length_get_extended(
NX_PACKET *packet_ptr,
UINT *content_length);
This service is similar to nx_http_server_content_length_get**; attempts to retrieve the HTTP content length in the supplied packet. However, the return value indicates successful completion status, and the actual length value is returned in the input pointer content_length. If there is no HTTP content/Content Length = 0, this routine still returns a successful completion status and the content_length input pointer points to a valid length (zero). It should be called from the application’s request notify callback specified during HTTP Server creation (nx_http_server_create**).
This service replaces nx_http_server_content_length_get.
Threads
/* Assuming we are in the application's request notify callback
routine, get the content length of the HTTP Client request. */
ULONG content_length;
status = nx_http_server_content_length_get_extended(packet_ptr, &content_length);
/* If the "status" variable indicates successful completion, the"length" variable
contains the length of the HTTP Client request content area. */
Create an HTTP Server instance
UINT nx_http_server_create(
NX_HTTP_SERVER *http_server_ptr,
CHAR *http_server_name,
NX_IP *ip_ptr,
FX_MEDIA *media_ptr,
VOID *stack_ptr,
ULONG stack_size,
NX_PACKET_POOL *pool_ptr,
UINT (*authentication_check)(
NX_HTTP_SERVER *server_ptr,
UINT request_type,
CHAR *resource,
CHAR **name,
CHAR **password,
CHAR **realm),
UINT (*request_notify)(
NX_HTTP_SERVER *server_ptr,
INT request_type,
CHAR *resource,
NX_PACKET *packet_ptr));
This service creates an HTTP Server instance, which runs in the context of its own ThreadX thread. The optional authentication_check and request_notify application callback routines give the application software control over the basic operations of the HTTP Server.
Initialization, Threads
/* Create an HTTP Server instance called "my_server." */
status = nx_http_server_create(&my_server, "my server", &ip_0, &ram_disk,
stack_ptr, stack_size, &pool_0,
my_authentication_check, my_request_notify);
/* If status equals NX_SUCCESS, the HTTP Server creation was successful. */
Delete an HTTP Server instance
UINT nx_http_server_delete(NX_HTTP_SERVER *http_server_ptr);
This service deletes a previously created HTTP Server instance.
Threads
/* Delete the HTTP Server instance called "my_server." */
status = nx_http_server_delete(&my_server);
/* If status equals NX_SUCCESS, the HTTP Server delete was successful. */
Retrieve the location and length of entity data
UINT nx_http_server_get_entity_content(
NX_HTTP_SERVER *server_ptr,
NX_PACKET **packet_pptr,
ULONG *available_offset,
ULONG *available_length);
This service determines the location of the start of data within the current multipart entity in the received Client messages, and the length of data not including the boundary string. Internally HTTP server updates its own offsets so that this function can be called again on the same Client datagram for messages with multiple entities. The packet pointer is updated to the next packet where the Client message is a multi-packet datagram.
Note: NX_HTTP_MULTIPART_ENABLE must be enabled to use this service.
See nx_http_server_get_entity_header for more details.
Threads
NX_HTTP_SERVER my_server;
UINT offset, length;
NX_PACKET *packet_ptr;
/* Inside the request notify callback, the HTTP server application first obtains
the entity header to determine details about the multipart data. If
successful, it then calls this service to get the location of entity data: */
status = nx_http_server_get_entity_content(&my_server, &packet_ptr, *offset,
&length);
/* If status equals NX_SUCCESS, offset and location determine the location of the
entity data. */
Retrieve the contents of entity header
UINT nx_http_server_get_entity_header(
NX_HTTP_SERVER *server_ptr,
NX_PACKET **packet_pptr,
UCHAR *entity_header_buffer,
ULONG buffer_size);
This service retrieves the entity header into the specified buffer. Internally HTTP Server updates its own pointers to locate the next multipart entity in a Client datagram with multiple entity headers. The packet pointer is updated to the next packet where the Client message is a multi-packet datagram.
Note: NX_HTTP_MULTIPART_ENABLE must be enabled to use this service.
Threads
/* my_request_notify is the application request notify callback registered with
the HTTP server in nx_http_server_create, creates a response to the received
Client request. */
UINT my_request_notify(NX_HTTP_SERVER *server_ptr, UINT request_type,
CHAR *resource, NX_PACKET *packet_ptr)
{
NX_PACKET *sresp_packet_ptr;
UINT offset, length;
NX_PACKET *response_pkt;
UCHAR buffer[1440];
/* Process multipart data. */
if(request_type == NX_HTTP_SERVER_POST_REQUEST)
{
/* Get the content header. */
while(nx_http_server_get_entity_header(server_ptr, &packet_ptr, buffer,
sizeof(buffer)) == NX_SUCCESS)
{
/* Header obtained successfully. Get the content data location. */
while(nx_http_server_get_entity_content(server_ptr, &packet_ptr, &offset,
&length) == NX_SUCCESS)
{
/* Write content data to buffer. */
nx_packet_data_extract_offset(packet_ptr, offset, buffer, length,
&length);
buffer[length] = 0;
}
}
/* Generate HTTP header. */
status = nx_http_server_callback_generate_response_header(server_ptr,
&response_pkt, NX_HTTP_STATUS_OK, 800, "text/html",
"Server: NetXDuo HTTP 5.3\r\n");
if(status == NX_SUCCESS)
{
if(nx_http_server_callback_packet_send(server_ptr, response_pkt) !=
NX_SUCCESS)
{
nx_packet_release(response_pkt);
}
}
}
else
{
/* Indicate we have not processed the response to client yet.*/
return(NX_SUCCESS);
}
/* Indicate the response to client is transmitted. */
return(NX_HTTP_CALLBACK_COMPLETED);
Set the callback to obtain GMT date and time
UINT nx_http_server_gmt_callback_set(
NX_HTTP_SERVER *server_ptr,
VOID (*gmt_get)(NX_HTTP_SERVER_DATE *date);
This service sets the callback to obtain GMT date and time with a previously created HTTP server. This service is invoked with the HTTP server is creating a header in HTTP server responses to the Client.
Threads
NX_HTTP_SERVER my_server;
VOID get_gmt(NX_HTTP_SERVER_DATE *now);
/* After the HTTP server is created by calling nx_http_server_create, and before
starting HTTP services when nx_http_server_start is called, set the GMT
retrieve callback: */
status = nx_http_server_gmt_callback_set(&my_server, gmt_get);
/* If status equals NX_SUCCESS, the gmt_get will be called to set the HTTP server
response header date. */
Set the callback to to handle invalid user/password
UINT nx_http_server_invalid_userpassword_notify_set(
NX_HTTP_SERVER *http_server_ptr,
UINT (*invalid_username_password_callback)
(CHAR *resource,
NXD_ADDRESS *client_address,
UINT request_type));
This service sets the callback invoked when an invalid username and password is received in a Client get, put or delete request, either by digest or basic authentication. The HTTP server must be previously created.
Threads
NX_HTTP_SERVER my_server;
VOID invalid_username_password_callback (NX_ CHAR *resource,
NXD_ADDRESS *client_address,
UINT request_type);
/* After the HTTP server is created by calling nx_http_server_create, and before
starting HTTP services when nx_http_server_start is called, set the invalid
username password callback: */
status = nx_http_server_gmt_callback_set(&my_server,
invalid_username_password_callback);
/* If status equals NX_SUCCESS, the invalid_username_password_callback function
will be called when the HTTP server receives an invalid username/password. */
Set additional MIME maps for HTML
UINT nx_http_server_mime_maps_additional_set(
NX_HTTP_SERVER *server_ptr,
NX_HTTP_SERVER_MIME_MAP *mime_maps,
UINT mime_maps_num);
This service allows the HTTP application developer to add additional MIME types from the default MIME types supplied by NetX Duo HTTP Server (see nx_http_server_get_type for list of defined types).
When a client request is received, e.g. a GET request, HTTP server parses the requested file type from the HTTP header using preferentially the additional MIME map set and if no match if found, it looks for a match in the default MIME map of the HTTP server. If no match is found, the MIME type defaults to “text/plain”.
If the request notify function is registered with the HTTP server, the request notify callback can call nx_http_server_type_retrieve to parse the file type.
Initialization, Threads
/* my_server is an NX_HTTP_SERVER previously created. */
NX_HTTP_SERVER_MIME_MAP my_mime_maps [2];
static NX_HTTP_SERVER_MIME_MAP my_mime_maps[] =
{
{"abc", "yourtype/abc"},
{"xyz", "mytype/xyz"},
};
status = nx_http_server_mime_maps_additional_set(&my_server,
&my_mime_maps[0], 2);
/* If status equals NX_SUCCESS, two additional MIME types are added to the HTTP
server MIME map set." */
Extract content length and set pointer to start of data
UINT nx_http_server_packet_content_find(
NX_HTTP_SERVER *server_ptr,
NX_PACKET **packet_ptr,
UINT *content_length);
This service extracts the content length from the HTTP header. It also updates the supplied packet as follows: the packet prepend pointer (start of location of packet buffer to write to) is set to the HTTP content (data) just passed the HTTP header.
If the beginning of content is not found in the current packet, the function waits for the next packet to be received using the NX_HTTP_SERVER_TIMEOUT_RECEIVE wait option.
Note: This should not be called before calling nx_http_server_get_entity_header because it modifies the prepend pointer past the entity header.
Threads
/* The HTTP server pointed to by server_ptr is previously created and started.
The server has received a Client request packet, recv_packet_ptr, and the packet
content find service is called from the request notify callback function
registered with the HTTP server. */
UINT content_length;
status = nx_http_server_packet_content_find(server_ptr, recv_packet_ptr,
&content_length);
/* If status equals NX_SUCCESS, the content length specifies the content length
and the packet pointer prepend pointer is set to the HTTP content (data). */
Receive the next HTTP packet
UINT nx_http_server_packet_get(
NX_HTTP_SERVER *server_ptr,
NX_PACKET **packet_ptr);
This service returns the next packet received on the HTTP server socket. The wait option to receive a packet is NX_HTTP_SERVER_TIMEOUT_RECEIVE.
Threads
/* The HTTP server pointed to by server_ptr is previously created and started. */
UINT content_length;
NX_PACKET *recv_packet_ptr;
status = nx_http_server_packet_get(server_ptr, &recv_packet_ptr);
/* If status equals NX_SUCCESS, a Client packet is obtained. */
Get parameter from the request
UINT nx_http_server_param_get(
NX_PACKET *packet_ptr,
UINT param_number, CHAR *param_ptr,
UINT max_param_size);
This service attempts to retrieve the specified HTTP URL parameter in the supplied request packet. If the requested HTTP parameter is not present, this routine returns a status of NX_HTTP_NOT_FOUND. This routine should be called from the application’s request notify callback specified during HTTP Server creation (nx_http_server_create).
Threads
/* Assuming we are in the application's request notify callback
routine, get the first parameter of the HTTP Client request. */
status = nx_http_server_param_get(request_packet_ptr, 0, param_destination,
30);
/* If status equals NX_SUCCESS, the NULL-terminated first parameter can be found
in "param_destination." */
Get query from the request
UINT nx_http_server_query_get(
NX_PACKET *packet_ptr,
UINT query_number,
CHAR *query_ptr,
UINT max_query_size);
This service attempts to retrieve the specified HTTP URL query in the supplied request packet. If the requested HTTP query is not present, this routine returns a status of NX_HTTP_NOT_FOUND. This routine should be called from the application’s request notify callback specified during HTTP Server creation (nx_http_server_create).
Threads
/* Assuming we are in the application's request notify callback
routine, get the first query of the HTTP Client request. */
status = nx_http_server_query_get(request_packet_ptr, 0, query_destination,
30);
/* If status equals NX_SUCCESS, the NULL-terminated first query can be found
in "query_destination." */
Start the HTTP Server
UINT nx_http_server_start(NX_HTTP_SERVER *http_server_ptr);
This service starts the previously create HTTP Server instance.
Initialization, Threads
/* Start the HTTP Server instance "my_server." */
status = nx_http_server_start(&my_server);
/* If status equals NX_SUCCESS, the HTTP Server has been started. */
Stop the HTTP Server
UINT nx_http_server_stop(NX_HTTP_SERVER *http_server_ptr);
This service stops the previously create HTTP Server instance. This routine should be called prior to deleting an HTTP Server instance.
Threads
/* Stop the HTTP Server instance "my_server." */
status = nx_http_server_stop(&my_server);
/* If status equals NX_SUCCESS, the HTTP Server has been stopped. */
Extract file type from Client HTTP request
UINT nx_http_server_type_get(
NX_HTTP_SERVER *http_server_ptr,
CHAR *name,
CHAR *http_type_string);
Note: This service is deprecated. Users are encouraged to use the service nx_http_server_type_retrieve.
This service extracts the HTTP request type in the buffer http_type_string and its length in the return value from the input buffer name, usually the URL. If no MIME map is found, it defaults to the “text/plain” type. Otherwise it compares the extracted type against the HTTP Server default MIME maps for a match. The default MIME maps in NetX Duo HTTP Server are:
If supplied, it will also search a user defined set of additional MIME maps. See nx_http_server_mime_maps_additional_set for more details on user defined maps.
This service is deprecated. Developers are encouraged to migrate to nx_http_server_type_get_extended.
Application
/* my_server is a previously created HTTP server, which starts accepting client
requests when nx_http_server_start is called*/
CHAR temp_string[20];
UINT string_length;
/* Extract the HTTP type. */
string_length = nx_http_server_type_get(&my_server_ptr,
my_server.nx_http_server_request_resource, temp_string);
/* If string_length is non zero, the HTTP string is extracted. */
Extract file type from Client HTTP request
UINT nx_http_server_type_get_extended(
NX_HTTP_SERVER *http_server_ptr,
CHAR *name, CHAR *http_type_string,
UINT http_type_string_max_size);
This service extracts the HTTP request type in the buffer http_type_string and its length in the return value from the input buffer name, usually the URL. If no MIME map is found, it defaults to the “text/plain” type. Otherwise it compares the extracted type against the HTTP Server default MIME maps for a match. The default MIME maps in NetX Duo HTTP Server are:
If supplied, it will also search a user defined set of additional MIME maps. See nx_http_server_mime_maps_additional_set for more details on user defined maps.
This service replaces nx_http_server_type_get. This version supplies additional length information.
Application
/* my_server is a previously created HTTP server, which starts accepting client
requests when nx_http_server_start is called*/
CHAR temp_string[20];
UINT string_length;
/* Get the length of request resource. */
if (_nx_utility_string_length_check(
my_server.nx_http_server_request_resource, &resource_length,
sizeof(my_server.nx_http_server_request_resource) - 1))
{
return;
}
/* Extract the HTTP type. */
string_length = nx_http_server_type_get_extended(&my_server,
my_server.nx_http_server_request_resource, resource_length,
temp_string, sizeof(temp_string));
/* If string_length is non zero, the HTTP string is extracted. */
For a more detailed example, see the description for nx_http_server_callback_generate_response_header.
Set digest authenticate callback function
UINT nx_http_server_digest_authenticate_notify_set(
NX_HTTP_SERVER *http_server_ptr,
UINT (*digest_authenticate_callback)(
NX_HTTP_SERVER *server_ptr,
CHAR *name_ptr,
CHAR *realm_ptr,
CHAR *password_ptr,
CHAR *method,
CHAR *authorization_uri,
CHAR *authorization_nc,
CHAR *authorization_cnonce));
This service sets the callback invoked when digest authenticate is performed.
Application
UINT digest_authenticate_callback(NX_HTTP_SERVER *server_ptr, CHAR *name_ptr,
CHAR *realm_ptr, CHAR *password_ptr, CHAR *method,
CHAR *authorization_uri, CHAR *authorization_nc,
CHAR *authorization_cnonce)
{
return(NX_SUCCESS);
}
NX_HTTP_SERVER my_server;
/* After the HTTP server is created by calling nx_http_server_create, and before
starting HTTP services when nx_http_server_start is called, set the digest authenticate callback: */
status = nx_http_server_digest_authenticate_notify_set (&my_server,
digest_authenticate_callback);
/* If status equals NX_SUCCESS, the digest_authenticate_callback function
will be called when the HTTP server performs digest authenticate. */
Set authentication checking callback function
UINT nx_http_server_authentication_check_set(
NX_HTTP_SERVER *http_server_ptr,
UINT (*authentication_check_extended)(
NX_HTTP_SERVER *server_ptr,
UINT request_type,
CHAR *resource,
CHAR **name,
UINT *name_length,
CHAR **password,
UINT *password_length,
CHAR **realm,
UINT *realm_length));
This service sets the callback function of authentication checking.
Application
static UINT authentication_check_extended(NX_HTTP_SERVER *server_ptr,
UINT request_type, CHAR *resource,
CHAR **name, UINT *name_length,
CHAR **password, UINT *password_length,
CHAR **realm, UINT *realm_length)
{
/* Just use a simple name, password, and realm for all
requests and resources. */
*name = "name";
*password = "password";
*realm = "NetX Duo HTTP demo";
*name_length = 4;
*password_length = 8;
*realm_length = 18;
/* Request basic authentication. */
return(NX_HTTP_BASIC_AUTHENTICATE);
}
NX_HTTP_SERVER my_server;
/* After the HTTP server is created by calling nx_http_server_create, and before
starting HTTP services when nx_http_server_start is called, set the
authentication checking callback: */
nx_http_server_authentication_check_set (&my_server,
authentication_check_extended);