This chapter contains a description of all NetX Duo Web HTTP services (listed below) in alphabetical order.
Note: 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_web_http_client_connect
Open a plaintext socket to an HTTP server for custom requests
UINT nx_web_http_client_connect(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS *server_ip,
UINT server_port,
ULONG wait_option);
This method is for plaintext HTTP.
This service opens a plaintext TCP socket to an HTTP server but does not send any requests. Requests are created with nx_web_http_client_request_initialize and sent using nx_web_http_client_request_send. Custom HTTP headers may be added to the request using nx_web_http_client_request_header_add.
Use of this service enables an application to add any number of custom headers to the request. This allows for customized HTTP requests intended for specific applications.
Note: The nx_web_http_client__start methods are provided for convenience (e.g. *nx_web_http_client_get_start) and handle the request generation and socket connection. You can use those services instead of nx_web_http_client_connect and the related routines if you do not need custom HTTP headers in your requests.
Threads
NXD_ADDRESS server_ip_addr;
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
nx_web_http_client_connect(&my_client, &server_ip_address,
NX_WEB_HTTP_SERVER_PORT, NX_WAIT_FOREVER);
/* Create a new GET request on the HTTP client instance. */
nx_web_http_client_request_initialize(&my_client,
NX_WEB_HTTP_METHOD_GET,
"https://192.168.1.150/test.txt ", "host.com",
0, /* Used by PUT and POST only */
NX_FALSE,
NX_NULL, /* username */
NX_NULL, /* password */
NX_WAIT_FOREVER);
/* Add a custom header to the GET request we just created. */
status = nx_web_http_client_request_header_add(&my_client, "Server", 6,
"NetX Web HTTPS Server", 21, NX_WAIT_FOREVER);
/* Start the GET operation to get a response from the HTTPS server. */
status = nx_web_http_client_request_send(&my_client, 1000);
/* At this point, we need to handle the response from the server by repeatedly
calling *nx_web_http_client_response_body_get* until the entire response is retrieved. */
get_status = NX_SUCCESS;
while(get_status != NX_WEB_HTTP_GET_DONE)
{
get_status = nx_web_http_client_response_body_get(&my_client, &receive_packet,
NX_WAIT_FOREVER);
/* Process response packets… */
}
Create an HTTP Client Instance
UINT nx_web_http_client_create(
NX_WEB_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. The Client instance can be used for either HTTP or HTTPS. See the services nx_web_http_client_connect and nx_web_http_client_secure_connect for more information on starting an HTTP or HTTPS instance. Also refer to the API for *nx_web_http_client_get_, *nx_web_http_client_put_, *nx_web_http_client_post_** for simple invocations of GET, PUT, and POST methods.
Initialization, Threads
/* Create the HTTP Client instance "my_client" on "ip_0". */
status = nx_web_http_client_create(&my_client, "my client", &ip_0, &pool_0, 8192);
/* If status is NX_SUCCESS an HTTP Client instance was successfully
created. */
Delete an HTTP Client Instance
UINT nx_web_http_client_delete(NX_WEB_HTTP_CLIENT *client_ptr);
This service deletes a previously created HTTP Client instance.
Threads
/* Delete the HTTP Client instance "my_client." */
status = nx_web_http_client_delete(&my_client);
/* If status is NX_SUCCESS an HTTP Client instance was successfully
deleted. */
Start a plaintext HTTP DELETE request
UINT nx_web_http_client_delete_start(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS ip_address,
UINT server_port, CHAR *resource,
CHAR *host, CHAR *username,
CHAR *password,
ULONG wait_option);
This method is for plaintext HTTP.
This service attempts to send a DELETE request for the resource specified by “resource” pointer on the previously created HTTP Client instance. If this routine returns NX_SUCCESS, the application can then call nx_web_http_client_response_body_get to retrieve the server’s response.
Note that 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.htm if the HTTP Server indicates it supports referring GET requests.
This API is deprecated. Developers are encouraged to use nx_web_http_client_delete_start_extended.
Threads
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
/* Start the DELETE operation on the HTTP Client "my_client." */
status = nx_web_http_client_delete_start(&my_client, &server_ip_address,
NX_WEB_HTTP_SERVER_PORT, "/TEST.HTM",
"host.com", "myname", "mypassword",
1000);
/* If status is NX_SUCCESS, the DELETE request for TEST.HTM is started and is so
far successful. The client must now call *nx_web_http_client_response_body_get*
to retrieve the response from the server. */
Start a plaintext HTTP DELETE request
UINT nx_web_http_client_delete_start_extended(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS ip_address,
UINT server_port,
CHAR *resource,
UINT resource_length,
CHAR *host,
UINT host_length,
CHAR *username,
UINT username_length,
CHAR *password,
UINT password_length,
ULONG wait_option);
This method is for plaintext HTTP.
This service attempts to send a DELETE request for the resource specified by “resource” pointer on the previously created HTTP Client instance. If this routine returns NX_SUCCESS, the application can then call nx_web_http_client_response_body_get to retrieve the server’s response.
Note that 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.htm if the HTTP Server indicates it supports referring GET requests.
The strings of resource, host, username and password must be NULL-terminated, and length of each string matches the length specified in the argument list.
This service replaces nx_web_http_client_delete_start . This version requires callers to supply length information to the function.
Threads
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
/* Start the DELETE operation on the HTTP Client "my_client." */
status = nx_web_http_client_delete_start_extended(&my_client,
&server_ip_address,
NX_WEB_HTTP_SERVER_PORT, "/TEST.HTM",
sizeof("/TEST.HTM") – 1,
"host.com", sizeof("host.com") – 1,
"myname", sizeof("myname") – 1,
"mypassword", sizeof("mypassword") – 1,
1000);
/* If status is NX_SUCCESS, the DELETE request for TEST.HTM is started and is so
far successful. The client must now call *nx_web_http_client_response_body_get*
to retrieve the response from the server. */
Start an encrypted HTTPS DELETE request
UINT nx_web_http_client_delete_secure_start(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS ip_address,
UINT server_port,
CHAR *resource,
CHAR *host,
CHAR *username,
CHAR *password,
UINT (*tls_setup)(
NX_WEB_HTTP_CLIENT *client_ptr,
NX_SECURE_TLS_SESSION *tls_session),
ULONG wait_option);
This method is for TLS-secured HTTPS.
This service attempts to send a DELETE request for the resource specified by “resource” pointer on the previously created HTTP Client instance. If this routine returns NX_SUCCESS, the application can then call nx_web_http_client_response_body_get to retrieve the server’s response.
Note that 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.htm if the HTTP Server indicates it supports referring GET requests.
This service is deprecated. Developers are encouraged to use nx_web_http_client_delete_secure_start_extended.
Threads
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
/* Start the DELETE operation on the HTTP Client "my_client." */
status = nx_web_http_client_delete_secure_start(&my_client, &server_ip_addr,
NX_WEB_HTTPS_SERVER_PORT, "/TEST.HTM",
"host.com", "myname", "mypassword", my_tls_setup_function, 1000);
/* If status is NX_SUCCESS, the DELETE request for TEST.HTM is started and is so
far successful. The client must now call *nx_web_http_client_response_body_get*
to retrieve the server's response. */
Start an encrypted HTTPS DELETE request
UINT nx_web_http_client_delete_secure_start_extended(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS ip_address,
UINT server_port,
CHAR *resource,
UINT resource_length,
CHAR *host,
UINT host_length,
CHAR *username,
UINT username_length,
CHAR *password,
UINT password_length,
UINT (*tls_setup)(
NX_WEB_HTTP_CLIENT *client_ptr,
NX_SECURE_TLS_SESSION *tls_session),
ULONG wait_option);
This method is for TLS-secured HTTPS.
This service attempts to send a DELETE request for the resource specified by “resource” pointer on the previously created HTTP Client instance. If this routine returns NX_SUCCESS, the application can then call nx_web_http_client_response_body_get to retrieve the server’s response.
Note that 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.htm if the HTTP Server indicates it supports referring GET requests.
The strings of resource, host, username and password must be NULL-terminated and length of each string matches the length specified in the argument list.
This service replaces nx_web_http_client_delete_secure_start. This version requires callers to supply length information to the function.
Threads
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
/* Start the DELETE operation on the HTTP Client "my_client." */
status = nx_web_http_client_delete_secure_start_extended(&my_client,
&server_ip_addr,
NX_WEB_HTTPS_SERVER_PORT, "/TEST.HTM", sizeof("/TEST.HTM") – 1,
"host.com", sizeof("host.com") – 1,
"myname", sizeof("myname") – 1,
"mypassword", sizeof("mypassword") – 1, my_tls_setup_function, 1000);
/* If status is NX_SUCCESS, the DELETE request for TEST.HTM is started and is so
far successful. The client must now call *nx_web_http_client_response_body_get*
to retrieve the server's response. */
Start a plaintext HTTP GET request
UINT nx_web_http_client_get_start(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS ip_address,
UINT server_port,
CHAR *resource,
CHAR *host, CHAR *username,
CHAR *password,
ULONG wait_option);
This method is for plaintext HTTP.
This service attempts to GET 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_web_http_client_response_body_get to retrieve packets of data corresponding to the requested resource content.
Note that 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.htm if the HTTP Server indicates it supports referring GET requests.
This service is deprecated. Developers are encouraged to use nx_web_http_client_get_start_extended.
Threads
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
/* Start the GET operation on the HTTP Client "my_client." */
status = nx_web_http_client_get_start(&my_client, &server_ip_addr,
NX_WEB_HTTP_SERVER_PORT, "/TEST.HTM",
"host.com", "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_web_http_client_response_body_get*
multiple times to retrieve the content associated with TEST.HTM. */
Start a plaintext HTTP GET request
UINT nx_web_http_client_get_start_extended(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS ip_address,
UINT server_port,
CHAR *resource,
UINT resource_length,
CHAR *host,
UINT host_length,
CHAR *username,
UINT username_length,
CHAR *password,
UINT password_length,
ULONG wait_option);
This method is for plaintext HTTP.
This service attempts to GET 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_web_http_client_response_body_get to retrieve packets of data corresponding to the requested resource content.
Note that 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.htm if the HTTP Server indicates it supports referring GET requests.
The strings of resource, host, username and password must be NULL-terminated, and length of each string matches the length specified in the argument list.
This service replaces nx_web_http_client_get_start. This version requires callers to supply length information to the function.
Threads
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
/* Start the GET operation on the HTTP Client "my_client." */
status = nx_web_http_client_get_start_extended(&my_client, &server_ip_addr,
NX_WEB_HTTP_SERVER_PORT, "/TEST.HTM",
sizeof("/TEST.HTM") – 1,
"host.com", sizeof("host.com") – 1,
"myname", sizeof("myname") – 1,
"mypassword", sizeof("mypassword") – 1,
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_web_http_client_response_body_get*
multiple times to retrieve the content associated with TEST.HTM. */
Start an encrypted HTTPS GET request
UINT nx_web_http_client_get_secure_start(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS ip_address,
UINT server_port,
CHAR *resource,
CHAR *host,
CHAR *username,
CHAR *password,
UINT (*tls_setup)(
NX_WEB_HTTP_CLIENT *client_ptr,
NX_SECURE_TLS_SESSION *tls_session),
ULONG wait_option);
This method is for TLS-secured HTTPS.
This service attempts to GET 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_web_http_client_response_body_get to retrieve packets of data corresponding to the requested resource content.
Note that 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.htm if the HTTP Server indicates it supports referring GET requests.
This service is deprecated. Developers are encouraged to use nx_web_http_client_get_secure_start_extended.
Threads
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
/* Start the GET operation on the HTTP Client "my_client." */
status = nx_web_http_client_get_secure_start(&my_client, &server_ip_addr,
NX_WEB_HTTPS_SERVER_PORT, "/TEST.HTM",
"host.com", "myname", "mypassword",
my_tls_setup_function, 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_web_http_client_response_body_get* multiple times to
retrieve the content associated with TEST.HTM. */
Start an encrypted HTTPS GET request
UINT nx_web_http_client_get_secure_start_extended(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS ip_address,
UINT server_port,
CHAR *resource,
UINT resource_length,
CHAR *host,
UINT host_length,
CHAR *username,
UINT username_length,
CHAR *password,
UINT password_length,
UINT (*tls_setup)(
NX_WEB_HTTP_CLIENT *client_ptr,
NX_SECURE_TLS_SESSION *tls_session),
ULONG wait_option);
This method is for TLS-secured HTTPS.
This service attempts to GET 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_web_http_client_response_body_get to retrieve packets of data corresponding to the requested resource content.
Note that 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.htm if the HTTP Server indicates it supports referring GET requests.
The strings of resource, host, username and password must be NULL-terminated, and length of each string matches the length specified in the argument list.
This service replaces nx_web_http_client_secure_start. This version requires callers to supply length information to the function.
Threads
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
/* Start the GET operation on the HTTP Client "my_client." */
status = nx_web_http_client_get_secure_start_extended(&my_client,
&server_ip_addr, NX_WEB_HTTPS_SERVER_PORT,
"/TEST.HTM", sizeof("/TEST.HTM") – 1,
"host.com", sizeof("host.com") – 1,
"myname", sizeof("myname") – 1,
"mypassword", sizeof("mypassword") – 1,
my_tls_setup_function, 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_web_http_client_response_body_get* multiple times to retrieve
the content associated with TEST.HTM. */
Start a plaintext HTTP HEAD request
UINT nx_web_http_client_head_start(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS ip_address,
UINT server_port,
CHAR *resource,
CHAR *host, CHAR *username,
CHAR *password,
ULONG wait_option);
This method is for plaintext HTTP.
This service attempts to retrieve the HEAD metadata for the resource specified by “resource” pointer on the previously created HTTP Client instance. If this routine returns NX_SUCCESS, the application can then call nx_web_http_client_response_body_get to retrieve the response.
Note that 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.htm if the HTTP Server indicates it supports referring GET requests.
This service is deprecated. Developers are encouraged to use nx_web_http_client_head_start_extended.
Threads
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
/* Start the HEAD operation on the HTTP Client "my_client." */
status = nx_web_http_client_head_start(&my_client, &server_ip_addr,
NX_WEB_HTTP_SERVER_PORT, "/TEST.HTM",
"host.com", "myname", "mypassword",
1000);
/* If status is NX_SUCCESS, the HEAD request for TEST.HTM is started and is so
far successful. The client must now call *nx_web_http_client_response_body_get*
to retrieve the response from the server. */
Start a plaintext HTTP HEAD request
UINT nx_web_http_client_head_start_extended(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS ip_address,
UINT server_port, CHAR *resource,
UINT resource_length,
CHAR *host,
UINT host_length,
CHAR *username,
UINT username_length,
CHAR *password,
UINT password_length,
ULONG wait_option);
This method is for plaintext HTTP.
This service attempts to retrieve the HEAD metadata for the resource specified by “resource” pointer on the previously created HTTP Client instance. If this routine returns NX_SUCCESS, the application can then call nx_web_http_client_response_body_get to retrieve the response.
Note that 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.htm if the HTTP Server indicates it supports referring GET requests.
The strings of resource, host, username and password must be NULL-terminated and length of each string matches the length specified in the argument list.
This service replaces nx_web_http_client_head_start. This version requires callers to supply length information to the function.
Threads
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
/* Start the HEAD operation on the HTTP Client "my_client." */
status = nx_web_http_client_head_start_extended(&my_client,
&server_ip_addr, NX_WEB_HTTPS_SERVER_PORT,
"/TEST.HTM", sizeof("/TEST.HTM") – 1,
"host.com", sizeof("host.com") – 1,
"myname", sizeof("myname") – 1,
"mypassword", sizeof("mypassword") – 1,
1000);
/* If status is NX_SUCCESS, the HEAD request for TEST.HTM is started and is so
far successful. The client must now call *nx_web_http_client_response_body_get*
to retrieve the response from the server. */
Start an encrypted HTTPS HEAD request
UINT nx_web_http_client_head_secure_start(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS ip_address,
UINT server_port,
CHAR *resource,
CHAR *host,
CHAR *username,
CHAR *password,
UINT (*tls_setup)(
NX_WEB_HTTP_CLIENT *client_ptr,
NX_SECURE_TLS_SESSION *tls_session),
ULONG wait_option);
This method is for TLS-secured HTTPS.
This service attempts to retrieve the HEAD metadata for the resource specified by “resource” pointer on the previously created HTTP Client instance. If this routine returns NX_SUCCESS, the application can then call nx_web_http_client_response_body_get to retrieve the server’s response corresponding to the requested resource content.
Note that 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.htm if the HTTP Server indicates it supports referring GET requests.
This service is deprecated. Developers are encouraged to use nx_web_http_client_head_secure_start_extended.
Threads
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
/* Start the HEAD operation on the HTTP Client "my_client." */
status = nx_web_http_client_head_secure_start(&my_client, &server_ip_addr,
NX_WEB_HTTPS_SERVER_PORT, "/TEST.HTM",
"host.com", "myname", "mypassword",
my_tls_setup_function, 1000);
/* If status is NX_SUCCESS, the HEAD request for TEST.HTM is started and is so
far successful. The client must now call *nx_web_http_client_response_body_get*
to retrieve the server's response. */
Start an encrypted HTTPS HEAD request
UINT nx_web_http_client_head_secure_start(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS ip_address,
UINT server_port,
CHAR *resource,
UINT resource_length,
CHAR *host,
UINT host_length,
CHAR *username,
UINT username_length,
CHAR *password,
UINT password_length,
UINT (*tls_setup)(
NX_WEB_HTTP_CLIENT *client_ptr,
NX_SECURE_TLS_SESSION *tls_session),
ULONG wait_option);
This method is for TLS-secured HTTPS.
This service attempts to retrieve the HEAD metadata for the resource specified by “resource” pointer on the previously created HTTP Client instance. If this routine returns NX_SUCCESS, the application can then call nx_web_http_client_response_body_get to retrieve the server’s response corresponding to the requested resource content.
Note that 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.htm if the HTTP Server indicates it supports referring GET requests.
The strings of resource, host, username and password must be NULL-terminated and length of each string matches the length specified in the argument list.
This service replaces nx_web_http_client_head_secure_start. This version requires callers to supply length information to the function.
Threads
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
/* Start the HEAD operation on the HTTP Client "my_client." */
status = nx_web_http_client_head_secure_start_extended(&my_client,
&server_ip_addr, NX_WEB_HTTPS_SERVER_PORT,
"/TEST.HTM", sizeof("/TEST.HTM") – 1,
"host.com", sizeof("host.com") – 1,
"myname", sizeof("myname") – 1,
"mypassword", sizeof("mypassword") – 1,
my_tls_setup_function, 1000);
/* If status is NX_SUCCESS, the HEAD request for TEST.HTM is started and is so
far successful. The client must now call *nx_web_http_client_response_body_get*
to retrieve the server's response. */
Allocate a HTTP(S) packet
UINT nx_web_http_client_request_packet_allocate(
NX_WEB_HTTP_CLIENT *client_ptr,
NX_PACKET **packet_ptr,
ULONG wait_option);
This service attempts to allocates a packet for Client HTTP(S).
Threads
/* Allocate a packet for HTTP(S) Client and suspend for a maximum of 5 timer
ticks if the pool is empty. */
status = nx_web_http_client_request_packet_allocate(&my_client, &packet_ptr, 5);
/* If status is NX_SUCCESS, the newly allocated packet pointer is found in the
variable packet_ptr. */
Start an HTTP POST request
UINT nx_web_http_client_post_start(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS ip_address,
UINT server_port,
CHAR *resource,
CHAR *host,
CHAR *username,
CHAR *password,
ULONG total_bytes,
ULONG wait_option);
This method is for plaintext HTTP.
This service attempts to send a POST request with the specified resource to the HTTP Server at the supplied IP address and port. If this routine is successful, the application code should make successive calls to the nx_web_http_client_put_packet routine to send the resource contents to the HTTP Server.
Note that 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.htm if the HTTP Server indicates it supports referring PUT requests.
This service is deprecated. Developers are encouraged to use nx_web_http_client_post_start_extended.
Threads
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
/* Start an HTTP POST to post the 20-byte resource "/TEST.HTM" to the HTTP Server
at IP address 1.2.3.5. */
status = nx_web_http_client_post_start(&my_client, &server_ip_addr,
NX_WEB_HTTP_SERVER_PORT, "/TEST.HTM",
"host.com", "myname", "mypassword", 20,
NX_WAIT_FOREVER);
/* If status is NX_SUCCESS, the POST operation for TEST.HTM has successfully been
started. */
Start an HTTP POST request
UINT nx_web_http_client_post_start_extended(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS ip_address,
UINT server_port,
CHAR *resource,
UINT resource_length,
CHAR *host,
UINT host_length,
CHAR *username,
UINT username_length,
CHAR *password,
UINT password_length,
ULONG total_bytes,
ULONG wait_option);
This method is for plaintext HTTP.
This service attempts to send a POST request with the specified resource to the HTTP Server at the supplied IP address and port. If this routine is successful, the application code should make successive calls to the nx_web_http_client_put_packet routine to send the resource contents to the HTTP Server.
Note that 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.htm if the HTTP Server indicates it supports referring PUT requests.
The strings of resource, host, username and password must be NULL-terminated and length of each string matches the length specified in the argument list.
This service replaces nx_web_http_client_post_start . This version requires callers to supply length information to the function.
Threads
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
/* Start an HTTP POST to post the 20-byte resource "/TEST.HTM" to the HTTP Server
at IP address 1.2.3.5. */
status = nx_web_http_client_post_start_extended(&my_client,
&server_ip_addr, NX_WEB_HTTPS_SERVER_PORT,
"/TEST.HTM", sizeof("/TEST.HTM") – 1,
"host.com", sizeof("host.com") – 1,
"myname", sizeof("myname") – 1,
"mypassword", sizeof("mypassword") – 1, 20,
NX_WAIT_FOREVER);
/* If status is NX_SUCCESS, the POST operation for TEST.HTM has successfully been
started. */
Start an encrypted HTTPS POST request
UINT nx_web_http_client_post_secure_start(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS ip_address,
UINT server_port,
CHAR *resource,
CHAR *host,
CHAR *username,
CHAR *password,
ULONG total_bytes,
UINT (*tls_setup)(
NX_WEB_HTTP_CLIENT *client_ptr,
NX_SECURE_TLS_SESSION *tls_session),
ULONG wait_option);
This method is for TLS-secured HTTPS.
This service attempts to send a POST request with the specified resource to the HTTPS Server at the supplied IP address and port. If this routine is successful, the application code should make successive calls to the nx_web_http_client_put_packet routine to send the resource contents to the HTTP Server.
Note that 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.htm if the HTTP Server indicates it supports referring PUT requests.
This service is deprecated. Developers are encouraged to use nx_web_http_client_post_secure_start_extended.
Threads
/* Start an HTTP PUT to place the 20-byte resource "/TEST.HTM" on the HTTPS Server
at IP address 1.2.3.5. */
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
status = nx_web_http_client_put_secure_start(&my_client, &server_ip_addr,
NX_WEB_HTTPS_SERVER_PORT, "/TEST.HTM",
"host.com", "myname", "mypassword", 20,
tls_setup, NX_WAIT_FOREVER);
/* If status is NX_SUCCESS, the POST operation for TEST.HTM has successfully been
started. */
Start an encrypted HTTPS POST request
UINT nx_web_http_client_post_secure_start_extended(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS ip_address,
UINT server_port, CHAR *resource,
UINT resource_length,
CHAR *host,
UINT host_length,
CHAR *username,
UINT username_length,
CHAR *password,
UINT password_length,
ULONG total_bytes,
UINT (*tls_setup)(
NX_WEB_HTTP_CLIENT *client_ptr,
NX_SECURE_TLS_SESSION *tls_session),
ULONG wait_option);
This method is for TLS-secured HTTPS.
This service attempts to send a POST request with the specified resource to the HTTPS Server at the supplied IP address and port. If this routine is successful, the application code should make successive calls to the nx_web_http_client_put_packet routine to send the resource contents to the HTTP Server.
Note that 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.htm if the HTTP Server indicates it supports referring PUT requests.
The strings of resource, host, username and password must be NULL-terminated and length of each string matches the length specified in the argument list.
This service replaces nx_web_http_client_post_secure_start . This version requires callers to supply length information to the function.
Threads
/* Start an HTTP PUT to place the 20-byte resource "/TEST.HTM" on the HTTPS Server
at IP address 1.2.3.5. */
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
status = nx_web_http_client_put_secure_start_extended(&my_client,
&server_ip_addr, NX_WEB_HTTPS_SERVER_PORT,
"/TEST.HTM", sizeof("/TEST.HTM") – 1,
"host.com", sizeof("host.com") – 1,
"myname", sizeof("myname") – 1,
"mypassword", sizeof("mypassword") – 1, 20,
tls_setup, NX_WAIT_FOREVER);
/* If status is NX_SUCCESS, the POST operation for TEST.HTM has successfully been
started. */
Start an HTTP PUT request
UINT nx_web_http_client_put_start(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS ip_address,
UINT server_port,
CHAR *resource,
CHAR *host,
CHAR *username,
CHAR *password,
ULONG total_bytes,
ULONG wait_option);
This method is for plaintext HTTP.
This service attempts to send a PUT request with the specified resource to the HTTP Server at the supplied IP address and port. If this routine is successful, the application code should make successive calls to the nx_web_http_client_put_packet routine to send the resource contents to the HTTP Server.
Note that 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.htm if the HTTP Server indicates it supports referring PUT requests.
This service is deprecated. Developers are encouraged to use nx_web_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. */
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
status = nx_web_http_client_put_start(&my_client, &server_ip_addr,
NX_WEB_HTTP_SERVER_PORT, "/TEST.HTM",
"host.com", "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
UINT nx_web_http_client_put_start(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS ip_address,
UINT server_port,
CHAR *resource,
UINT resource_length,
CHAR *host,
UINT host_length,
CHAR *username,
UINT username_length,
CHAR *password,
UINT password_length,
ULONG total_bytes,
ULONG wait_option);
This method is for plaintext HTTP.
This service attempts to send a PUT request with the specified resource to the HTTP Server at the supplied IP address and port. If this routine is successful, the application code should make successive calls to the nx_web_http_client_put_packet routine to send the resource contents to the HTTP Server.
Note that 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.htm if the HTTP Server indicates it supports referring PUT requests.
The strings of resource, host, username and password must be NULL-terminated and length of each string matches the length specified in the argument list.
This service replaces nx_web_http_client_put_start . This version requires callers to supply length information to the function.
Threads
/* Start an HTTP PUT to place the 20-byte resource "/TEST.HTM" on the HTTP Server
at IP address 1.2.3.5. */
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
status = nx_web_http_client_put_start_extended(&my_client,
&server_ip_addr, NX_WEB_HTTPS_SERVER_PORT,
"/TEST.HTM", sizeof("/TEST.HTM") – 1,
"host.com", sizeof("host.com") – 1,
"myname", sizeof("myname") – 1,
"mypassword", sizeof("mypassword") – 1, 20,
NX_WAIT_FOREVER);
/* If status is NX_SUCCESS, the PUT operation for TEST.HTM has successfully been
started. */
Start an encrypted HTTPS PUT request
UINT nx_web_http_client_put_secure_start(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS ip_address,
UINT server_port,
CHAR *resource,
CHAR *host,
CHAR *username,
CHAR *password,
ULONG total_bytes,
UINT (*tls_setup)(
NX_WEB_HTTP_CLIENT *client_ptr,
NX_SECURE_TLS_SESSION *tls_session),
ULONG wait_option);
This method is for TLS-secured HTTPS.
This service attempts to send a PUT request with the specified resource to the HTTPS Server at the supplied IP address and port. If this routine is successful, the application code should make successive calls to the nx_web_http_client_put_packet routine to send the resource contents to the HTTP Server.
Note that 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.htm if the HTTP Server indicates it supports referring PUT requests.
This service is deprecated. Developers are encouraged to use nx_web_http_client_put_secure_start_extended.
Threads
/* Start an HTTP PUT to place the 20-byte resource "/TEST.HTM" on the HTTPS Server
at IP address 1.2.3.5. */
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
status = nx_web_http_client_put_secure_start(&my_client, &server_ip_addr,
NX_WEB_HTTPS_SERVER_PORT, "/TEST.HTM",
"host.com", "myname", "mypassword", 20,
tls_setup, NX_WAIT_FOREVER);
/* If status is NX_SUCCESS, the PUT operation for TEST.HTM has successfully been
started. */
Start an encrypted HTTPS PUT request
UINT nx_web_http_client_put_secure_start(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS ip_address,
UINT server_port,
CHAR *resource,
UINT resource_length,
CHAR *host,
UINT host_length,
CHAR *username,
UINT username_length,
CHAR *password,
UINT password_length,
ULONG total_bytes,
UINT (*tls_setup)(
NX_WEB_HTTP_CLIENT *client_ptr,
NX_SECURE_TLS_SESSION *tls_session),
ULONG wait_option);
This method is for TLS-secured HTTPS.
This service attempts to send a PUT request with the specified resource to the HTTPS Server at the supplied IP address and port. If this routine is successful, the application code should make successive calls to the nx_web_http_client_put_packet routine to send the resource contents to the HTTP Server.
Note that 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.htm if the HTTP Server indicates it supports referring PUT requests.
The strings of resource, host, username and password must be NULL-terminated and length of each string matches the length specified in the argument list.
This service replaces nx_web_http_client_put_secure_start. This version requires callers to supply length information to the function.
Threads
/* Start an HTTP PUT to place the 20-byte resource "/TEST.HTM" on the HTTPS Server
at IP address 1.2.3.5. */
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
status = nx_web_http_client_put_secure_start_extended(&my_client,
&server_ip_addr, NX_WEB_HTTPS_SERVER_PORT,
"/TEST.HTM", sizeof("/TEST.HTM") – 1,
"host.com", sizeof("host.com") – 1,
"myname", sizeof("myname") – 1,
"mypassword", sizeof("mypassword") – 1, 20,
tls_setup, NX_WAIT_FOREVER);
/* If status is NX_SUCCESS, the PUT operation for TEST.HTM has successfully been
started. */
Send next resource data packet
UINT nx_web_http_client_put_packet(
NX_WEB_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 for both PUT and POST operations. Note that this routine should be called repetitively until the combined length of the packets sent equals the “total_bytes” specified in the previous nx_web_http_client_put_start or nx_web_http_client_post_start call (or their corresponding secure versions).
This service also checks for a response from the server in case there was a problem establishing the HTTP (or HTTPS) connection.
Threads
/* Send a 20-byte packet representing the content of the resource
"/TEST.HTM" to the HTTP Server. */
status = nx_web_http_client_put_packet(&client_ptr, packet_ptr, NX_WAIT_FOREVER);
/* If status is NX_SUCCESS, the 20-byte resource contents of TEST.HTM has
successfully been sent. */
Set chunked transfer for HTTP(S) request
UINT nx_web_http_client_request_chunked_set(
NX_WEB_HTTP_CLIENT *client_ptr,
UINT chunk_size,
NX_PACKET *packet_ptr);
This service uses chunked transfer coding to send a custom HTTP(S) request to the server specified in the nx_web_http_client_connect or nx_web_http_client_secure_connect call which has previously established the socket connection to the remote host.
Note: If the application uses chunked transfer coding to send a request data packet, it must call this service after calling nx_web_http_client_request_packet_allocate, and before call nx_web_http_client_request_packet_send .
Threads
/* Connect to a remote HTTPS server. */
nx_web_http_client_secure_connect(&my_client, IP_ADDRESS(1,2,3,5),
NX_WEB_HTTPS_SERVER_PORT, tls_setup_callback,
NX_WAIT_FOREVER);
/* Create a PUT request on the HTTP client instance. */
nx_web_http_client_request_initialize(&my_client,
NX_WEB_HTTP_METHOD_PUT,
"https://192.168.1.150/test.txt ", "host.com",
0, /* Used by PUT and POST only */
NX_TRUE,
NX_NULL, /* username */
NX_NULL, /* password */
NX_WAIT_FOREVER);
/* Start the PUT operation. */
nx_web_http_client_request_send(&my_client, 1000);
/* Create a new data packet request on the HTTP(S) client instance. */
nx_web_http_client_request_packet_allocate(&my_client,
&my_packet,
NX_WAIT_FOREVER);
/* Set the chunked transfer. */
status = nx_web_http_client_request_chunked_set(&my_client, 128, my_packet);
/* At this point, user can fill the data into my_packet. */
nx_packet_data_append(my_packet, data_ptr, data_size,
packet_pool, NX_WAIT_FOREVER);
/* Send data packet request to server. */
nx_web_http_client_request_packet_send(&my_client, my_packet,
0, NX_WAIT_FOREVER);
Add a custom header to a custom HTTP request
UINT nx_web_http_client_request_header_add(
NX_WEB_HTTP_CLIENT *client_ptr,
CHAR *field_name,
UINT name_length,
CHAR *field_value,
UINT value_length,
UINT wait_option);
This service adds a custom header (in the form of a field name and value) to a custom HTTP request created with nx_web_http_client_request_initialize.
Use of this service enables an application to add any number of custom headers to the request. This allows for customized HTTP requests intended for specific applications.
Note: The nx_web_http_client_*_start methods are provided for convenience. These functions all use this routine internally (along with nx_web_http_client_request_initialize) to create and send HTTP requests.
Threads
/* Connect to a remote HTTPS server. */
nx_web_http_client_secure_connect(&my_client, IP_ADDRESS(1,2,3,5),
NX_WEB_HTTPS_SERVER_PORT, tls_setup_callback,
NX_WAIT_FOREVER);
/* Create a new GET request on the HTTP client instance. */
nx_web_http_client_request_initialize(&my_client,
NX_WEB_HTTP_METHOD_GET,
"https://192.168.1.150/test.txt ", "host.com",
0, /* Used by PUT and POST only */
NX_FALSE,
NX_NULL, /* username */
NX_NULL, /* password */
NX_WAIT_FOREVER);
/* Add a custom header to the GET request we just created. */
status = nx_web_http_client_request_header_add(&my_client, "Server", 6,
"NetX Web HTTPS Server", 21, NX_WAIT_FOREVER);
/* Start the GET operation to get a response from the HTTPS server. */
status = nx_web_http_client_request_send(&my_client, 1000);
/* At this point, we need to handle the response from the server
by repeatedly calling *nx_web_http_client_response_body_get*
until the entire response is retrieved. */
get_status = NX_SUCCESS;
while(get_status != NX_WEB_HTTP_GET_DONE)
{
get_status = nx_web_http_client_response_body_get(&my_client, &receive_packet,
NX_WAIT_FOREVER);
/* Process response packets… */
}
Initialize a custom HTTP request
UINT nx_web_http_client_request_initialize(
NX_WEB_HTTP_CLIENT *client_ptr,
UINT method, CHAR *resource,
CHAR *host,
UINT input_size,
UINT transfer_encoding_trunked,
CHAR *username,
CHAR *password,
UINT wait_option);
This service creates a custom HTTP request and associates it with the HTTP Client instance. Unlike the simpler nx_web_http_client_get_start (along with the methods for PUT, POST, and the associated secure versions of those API), the custom request is not sent until the nx_web_http_client_request_send service is called.
Use of this service enables an application to add any number of custom headers to the request using the nx_web_http_client_request_header_add service. This allows for customized HTTP requests intended for specific applications.
Note: The nx_web_http_client_*_start methods are provided for convenience. These functions all use this routine internally (along with nx_web_http_client_request_send) to create and send HTTP requests.
This service is deprecated. Developers are encouraged to use nx_web_http_client_request_initialize_extended.
Threads
/* Connect to a remote HTTPS server. */
nx_web_http_client_secure_connect(&my_client, IP_ADDRESS(1,2,3,5),
NX_WEB_HTTPS_SERVER_PORT, tls_setup_callback,
NX_WAIT_FOREVER);
/* Create a new GET request on the HTTP client instance. */
nx_web_http_client_request_initialize(&my_client,
NX_WEB_HTTP_METHOD_GET,
"test.txt ", "host.com",
0, /* Used by PUT and POST only */
NX_FALSE,
NX_NULL, /* username */
NX_NULL, /* password */
NX_WAIT_FOREVER);
/* Start the GET operation to get a response from the HTTPS server. */
status = nx_web_http_client_request_send(&my_client, 1000);
/* At this point, we need to handle the response from the server by repeatedly
calling *nx_web_http_client_response_body_get* until the entire response is retrieved. */
get_status = NX_SUCCESS;
while(get_status != NX_WEB_HTTP_GET_DONE)
{
get_status = nx_web_http_client_response_body_get(&my_client, &receive_packet,
NX_WAIT_FOREVER);
/* Process response packets… */
}
Initialize a custom HTTP request
UINT nx_web_http_client_request_initialize_extended(
NX_WEB_HTTP_CLIENT *client_ptr,
UINT method,
CHAR *resource,
UINT resource_length,
CHAR *host,
UINT host_length,
UINT input_size,
UINT transfer_encoding_trunked,
CHAR *username,
UINT username_length,
CHAR *password,
UINT password_length,
UINT wait_option);
This service creates a custom HTTP request and associates it with the HTTP Client instance. Unlike the simpler nx_web_http_client_get_start (along with the methods for PUT, POST, and the associated secure versions of those API), the custom request is not sent until the nx_web_http_client_request_send service is called.
Use of this service enables an application to add any number of custom headers to the request using the nx_web_http_client_request_header_add service. This allows for customized HTTP requests intended for specific applications.
Note: The nx_web_http_client_*_start methods are provided for convenience. These functions all use this routine internally (along with nx_web_http_client_request_send) to create and send HTTP requests.
The strings of resource, host, username and password must be NULL-terminated and length of each string matches the length specified in the argument list.
This service replaces nx_web_http_client_request_initialize. This version requires callers to supply length information to the function.
Threads
/* Connect to a remote HTTPS server. */
nx_web_http_client_secure_connect(&my_client, IP_ADDRESS(1,2,3,5),
NX_WEB_HTTPS_SERVER_PORT, tls_setup_callback,
NX_WAIT_FOREVER);
/* Create a new GET request on the HTTP client instance. */
nx_web_http_client_request_initialize_extended(&my_client,
NX_WEB_HTTP_METHOD_GET,
"test.txt ", sizeof("test.txt ") – 1,
"host.com", sizeof("host.com") – 1,
0, /* Used by PUT and POST only */
NX_FALSE,
NX_NULL, /* username */
0,
NX_NULL, /* password */
0,
NX_WAIT_FOREVER);
/* Start the GET operation to get a response from the HTTPS server. */
status = nx_web_http_client_request_send(&my_client, 1000);
/* At this point, we need to handle the response from the server by repeatedly
calling *nx_web_http_client_response_body_get* until the entire response is retrieved. */
get_status = NX_SUCCESS;
while(get_status != NX_WEB_HTTP_GET_DONE)
{
get_status = nx_web_http_client_response_body_get(&my_client, &receive_packet,
NX_WAIT_FOREVER);
/* Process response packets… */
}
Send HTTP(S) request data packet to remote server
UINT nx_web_http_client_request_packet_send(
NX_WEB_HTTP_CLIENT *client_ptr,
NX_PACKET *packet_ptr,
UINT more_date,
ULONG wait_option);
This service sends a custom HTTP(S) request data packet created with nx_web_http_client_request_packet_allocate to the server specified in the nx_web_http_client_connect or nx_web_http_client_secure_connect() call which has previously established the socket connection to the remote host.
Threads
/* Connect to a remote HTTPS server. */
nx_web_http_client_secure_connect(&my_client, IP_ADDRESS(1,2,3,5),
NX_WEB_HTTPS_SERVER_PORT, tls_setup_callback,
NX_WAIT_FOREVER);
/* Create a PUT request on the HTTP client instance. */
nx_web_http_client_request_initialize(&my_client,
NX_WEB_HTTP_METHOD_PUT,
"https://192.168.1.150/test.txt ", "host.com",
128, /* Used by PUT and POST only */
NX_FALSE,
NX_NULL, /* username */
NX_NULL, /* password */
NX_WAIT_FOREVER);
/* Start the PUT operation. */
nx_web_http_client_request_send(&my_client, 1000);
/* Create a new data packet request on the HTTP(S) client instance. */
nx_web_http_client_request_packet_allocate(&my_client,
&my_packet,
NX_WAIT_FOREVER);
/* At this point, user can fill the data into my_packet. */
nx_packet_data_append(my_packet, data_ptr, data_size,
packet_pool, NX_WAIT_FOREVER);
/* Send data packet request to server. */
status = nx_web_http_client_request_packet_send(&my_client,
my_packet,
0,
NX_WAIT_FOREVER);
Send a custom HTTP request
UINT nx_web_http_client_request_send(
NX_WEB_HTTP_CLIENT *client_ptr,
UINT wait_option);
This service sends a custom HTTP request created with nx_web_http_client_request_initialize to the server specified in the nx_web_http_client_connect or nx_web_http_client_secure_connect both of which have previously established the socket connection to the remote host.
Use of this service enables an application to add any number of custom headers to the request using the nx_web_http_client_request_header_add service. This allows for customized HTTP requests intended for specific applications.
Note: The nx_web_http_client_*_start methods are provided for convenience. These functions all use this routine internally (along with nx_web_http_client_request_initialize) to create and send HTTP requests.
Threads
/* Connect to a remote HTTPS server. */
nx_web_http_client_secure_connect(&my_client, IP_ADDRESS(1,2,3,5),
NX_WEB_HTTPS_SERVER_PORT, tls_setup_callback,
NX_WAIT_FOREVER);
/* Create a new GET request on the HTTP client instance. */
nx_web_http_client_request_initialize(&my_client,
NX_WEB_HTTP_METHOD_GET,
"https://192.168.1.150/test.txt ", "host.com",
0, /* Used by PUT and POST only */
NX_FALSE,
NX_NULL, /* username */
NX_NULL, /* password */
NX_WAIT_FOREVER);
/* Start the GET operation to get a response from the HTTPS server. */
status = nx_web_http_client_request_send(&my_client, 1000);
/* At this point, we need to handle the response from the server by
repeatedly calling *nx_web_http_client_response_body_get* until
the entire response is retrieved. */
get_status = NX_SUCCESS;
while(get_status != NX_WEB_HTTP_GET_DONE)
{
get_status = nx_web_http_client_response_body_get(&my_client, &receive_packet,
NX_WAIT_FOREVER);
/* Process response packets… */
}
Get next resource data packet
UINT nx_web_http_client_response_body_get(
NX_WEB_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 request. Successive calls to this routine should be made until the return status of NX_WEB_HTTP_GET_DONE is received.
Threads
/* Get the next packet of resource content on the HTTP Client "my_client."
Note that the nx_web_http_client_get_start routine must have been called
previously. */
status = nx_web_http_client_response_body_get(&my_client, &next_packet, 1000);
/* If status is NX_SUCCESS, the next packet of content is pointed to
by "next_packet". */
Set callback to invoke when processing HTTP headers
UINT nx_web_http_client_response_header_callback_set(
NX_WEB_HTTP_CLIENT *client_ptr,
VOID (*callback_function)(
NX_WEB_HTTP_CLIENT *client_ptr,
CHAR *field_name,
UINT field_name_length,
CHAR *field_value,
UINT field_value_length));
This service assigns a callback that will be invoked whenever NetX Duo Web HTTP Client processes an HTTP header in an incoming response from a remote HTTP server. The callback is invoked once for each header in the response as it is processed. The callback allows an HTTP Client application to access each of the headers in the HTTP server response to take any desired actions beyond the basic processing that NetX Duo Web HTTP Client does.
client_ptr: Pointer to HTTP Client control block.
callback_function: Callback invoked during response header processing. The callback is invoked with the field name and value as strings (and their lengths). For example, the header “Content-Length: 100” would cause the function to be invoked with “Content-Length” for field_name and the string “100” for field_value.
Threads
/* Setup a callback to print out header information as it is processed. */
VOID http_response_callback(NX_WEB_HTTP_CLIENT *client_ptr, CHAR *field_name,
UINT field_name_length, CHAR *field_value,
UINT field_value_length)
{
CHAR name[100];
CHAR value[100];
memset(name, 0, sizeof(name));
memset(value, 0, sizeof(value));
strncpy(name, field_name, field_name_length);
strncpy(value, field_value, field_value_length);
printf("Received header: \n");
printf("\tField name: %s (%d bytes)\n", name, field_name_length);
printf("\tValue: %s (%d bytes)\n\n", value, field_value_length);
}
/* Assign the callback to the HTTP client instance. */
nx_web_http_client_response_header_callback_set(&my_client,
http_response_callback);
/* Start a GET operation to get a response from the HTTP server. */
status = nx_web_http_client_get_start(&my_client, IP_ADDRESS(1,2,3,5),
NX_WEB_HTTP_SERVER_PORT, "/TEST.HTM",
"myname", "mypassword", 1000);
/* When the HTTP server returns a response to the GET request, NetX Web HTTP
Client will invoke the http_response_callback function for each header
processed in the HTTP response. */
Open a TLS session to an HTTPS server for custom requests
UINT nx_web_http_client_secure_connect(
NX_WEB_HTTP_CLIENT *client_ptr,
NXD_ADDRESS *server_ip,
UINT server_port,
UINT (*tls_setup)(
NX_WEB_HTTP_CLIENT *client_ptr,
NX_SECURE_TLS_SESSION *tls),
ULONG wait_option);
This method is for TLS-secured HTTPS.
This service opens a secured TLS session to an HTTPS server but does not send any requests. Requests are created with nx_web_http_client_request_initialize and sent using nx_web_http_client_request_send. Custom HTTP headers may be added to the request using nx_web_http_client_request_header_add.
Use of this service enables an application to add any number of custom headers to the request. This allows for customized HTTP requests intended for specific applications.
Note: The nx_web_http_client_*_start methods are provided for convenience. These functions all use this routine internally (along with nx_web_http_client_request_initialize) to create and send HTTP requests.
Threads
/* Connect to a remote HTTPS server. */
/* Connect to a remote HTTP server. */
server_ip_addr.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_addr.nxd_ip_address.v4 = IP_ADDRESS(1,2,3,5);
nx_web_http_client_secure_connect(&my_client, &server_ip_addr,
NX_WEB_HTTPS_SERVER_PORT, tls_setup_callback,
NX_WAIT_FOREVER);
/* Create a new GET request on the HTTP client instance. */
nx_web_http_client_request_initialize(&my_client,
NX_WEB_HTTP_METHOD_GET,
"https://192.168.1.150/test.txt ", "host.com",
0, /* Used by PUT and POST only */
NX_FALSE,
NX_NULL, /* username */
NX_NULL, /* password */
NX_WAIT_FOREVER);
/* Add a custom header to the GET request we just created. */
status = nx_web_http_client_request_header_add(&my_client, "Server", 6,
"NetX Web HTTPS Server", 21, NX_WAIT_FOREVER);
/* Start the GET operation to get a response from the HTTPS server. */
status = nx_web_http_client_request_send(&my_client, 1000);
/* At this point, we need to handle the response from the server by repeatedly
calling *nx_web_http_client_response_body_get* until the entire response is retrieved. */
get_status = NX_SUCCESS;
while(get_status != NX_WEB_HTTP_GET_DONE)
{
get_status = nx_web_http_client_response_body_get(&my_client, &receive_packet,
NX_WAIT_FOREVER);
/* Process response packets… */
}
Set the callback to retrieve URL max age and date
UINT nx_web_http_server_cache_info_callback_set(
NX_WEB_HTTP_SERVER *server_ptr,
UINT (*cache_info_get)(CHAR *resource,
UINT *max_age,
NX_WEB_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_WEB_HTTP_SERVER my_server;
UINT cache_info_get(CHAR *resource, UINT *max_age,
NX_WEB_HTTP_SERVER_DATE *last_modified);
/* After my_server is created with nx_web_http_server_create and before the HTTP
server is set by nx_web_http_server_start, set the cache info callback: */
status = nx_web_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_web_http_server_callback_data_send(
NX_WEB_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 that 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_WEB_HTTP_CALLBACK_COMPLETED.
Threads
UINT my_request_notify(NX_WEB_HTTP_SERVER *server_ptr, UINT request_type,
CHAR *resource, NX_PACKET *packet_ptr)
{
/* Look for the test resource! */
if ((request_type == NX_WEB_HTTP_SERVER_GET_REQUEST) &&
(strcmp(resource, "/test.htm") == 0))
{
/* Found it, override the GET processing by sending the resource
contents directly. */
nx_web_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_web_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_WEB_HTTP_CALLBACK_COMPLETED);
}
return(NX_SUCCESS);
}
Create a response header in a callback function
UINT nx_web_http_server_callback_generate_response_header(
NX_WEB_HTTP_SERVER *server_ptr,
NX_PACKET **packet_pptr,
CHAR *status_code,
UINT content_length,
CHAR *content_type,
CHAR* additional_header);
This service is used in the HTTP(S) server callback routine (defined by the application) to generate an HTTP response header. The server callback routine is invoked when the HTTP server responds to Client GET, PUT and DELETE requests which require an HTTP response. This function takes the response information from the application and generates the appropriate response header. See the service nx_web_http_server_create for more information on the server request callback routine.
This API is deprecated. Developers are encouraged to use nx_web_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_web_http_server_create*,
creates a response to the received Client request. */
UINT my_request_notify(NX_WEB_HTTP_SERVER *server_ptr, UINT request_type,
CHAR *resource, NX_PACKET *recv_packet_ptr)
{
NX_PACKET *resp_packet_ptr;
ULONG string_length;
CHAR temp_string[30];
ULONG length = 0;
length = strlen(&demotestbuffer[0]);
/* Derive the client request type from the client request. */
nx_web_http_server_type_extract(server_ptr,
server_ptr -> nx_web_http_server_request_resource,
temp_string, sizeof(temp_string), &string_length);
/* Null terminate the string. */
temp_string[string_length] = 0;
/* Now build a response header with server status is OK and no additional header info. */
status = nx_web_http_server_callback_generate_response_header(http_server_ptr,
&resp_packet_ptr, NX_WEB_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],
strlen(&demotestbuffer[0]), server_ptr >>
nx_web_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_web_http_server_callback_packet_send(
&(server_ptr -> nx_web_http_server_socket),
resp_packet_ptr);
if (status != NX_SUCCESS)
{
nx_packet_release(resp_packet_ptr);
return status;
}
/* Let HTTP server know the response has been sent. */
return(NX_WEB_HTTP_CALLBACK_COMPLETED);
}
Create a response header in a callback function
UINT nx_web_http_server_callback_generate_response_header_extended(
NX_WEB_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 is used in the HTTP(S) server callback routine (defined by the application) to generate an HTTP response header. The server callback routine is invoked when the HTTP server responds to Client GET, PUT and DELETE requests which require an HTTP response. This function takes the response information from the application and generates the appropriate response header. See the service nx_web_http_server_create for more information on the server request callback routine.
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_web_http_server_create*,
creates a response to the received Client request. */
UINT my_request_notify(NX_WEB_HTTP_SERVER *server_ptr, UINT request_type,
CHAR *resource, NX_PACKET *recv_packet_ptr)
{
NX_PACKET *resp_packet_ptr;
ULONG string_length;
CHAR temp_string[30];
ULONG length = 0;
length = strlen(&demotestbuffer[0]);
/* Derive the client request type from the client request. */
nx_web_http_server_type_extract(server_ptr,
server_ptr -> nx_web_http_server_request_resource,
temp_string, sizeof(temp_string), &string_length);
/* Null terminate the string. */
temp_string[string_length] = 0;
/* Now build a response header with server status is OK and no additional header info. */
status = nx_web_http_server_callback_generate_response_header_extended(http_server_ptr,
&resp_packet_ptr, NX_WEB_HTTP_STATUS_OK,
sizeof(NX_WEB_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],
strlen(&demotestbuffer[0]), server_ptr >>
nx_web_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_web_http_server_callback_packet_send(
&(server_ptr -> nx_web_http_server_socket),
resp_packet_ptr);
if (status != NX_SUCCESS)
{
nx_packet_release(resp_packet_ptr);
return status;
}
/* Let HTTP server know the response has been sent. */
return(NX_WEB_HTTP_CALLBACK_COMPLETED);
}
Send an HTTP packet from callback function
UINT nx_web_http_server_callback_packet_send(
NX_WEB_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_WEB_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_WEB_HTTP_CALLBACK_COMPLETED.
See nx_web_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_web_http_server_callback_packet_send(server_ptr, packet_ptr);
if (status != NX_SUCCESS)
{
nx_packet_release(packet_ptr);
}
return(NX_WEB_HTTP_CALLBACK_COMPLETED);
Send response from callback function
UINT nx_web_http_server_callback_response_send(
NX_WEB_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 that if this function is used, the callback routine must return the status of NX_WEB_HTTP_CALLBACK_COMPLETED.
This service is deprecated. Developers are encouraged to use nx_web_http_server_callback_response_send_extended.
Threads
UINT my_request_notify(NX_WEB_HTTP_SERVER *server_ptr, UINT request_type,
CHAR *resource, NX_PACKET *packet_ptr)
{
/* Look for the test resource! */
if ((request_type == NX_WEB_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_web_http_server_callback_response_send(server_ptr,
"HTTP/1.0 404 ",
"NetX HTTP Server unable to find file: ",
resource);
/* Return completion status. */
return(NX_WEB_HTTP_CALLBACK_COMPLETED);
}
return(NX_SUCCESS);
}
Send response from callback function
UINT nx_web_http_server_callback_response_send_extended(
NX_WEB_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 that if this function is used, the callback routine must return the status of NX_WEB_HTTP_CALLBACK_COMPLETED.
The strings of header, information and additional_info must be NULL-terminated and length of each string matches the length specified in the argument list.
This service replaces nx_web_http_server_callback_response_send. This version requires callers to supply length information to the function.
Threads
UINT my_request_notify(NX_WEB_HTTP_SERVER *server_ptr, UINT request_type,
CHAR *resource, NX_PACKET *packet_ptr)
{
/* Look for the test resource! */
if ((request_type == NX_WEB_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_web_http_server_callback_response_send_extended(server_ptr,
"HTTP/1.0 404 ",
sizeof("HTTP/1.0 404 ") – 1,
"NetX HTTP Server unable to find file: ",
sizeof("NetX HTTP Server unable to find file: ") – 1,
resource, strlen(resource));
/* Return completion status. */
return(NX_WEB_HTTP_CALLBACK_COMPLETED);
}
return(NX_SUCCESS);
}
Get content from the request
UINT nx_web_http_server_content_get(
NX_WEB_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_web_http_server_create).
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_web_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_web_http_server_content_get_extended(
NX_WEB_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_web_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_web_http_server_create).
This service replaces nx_web_http_server_content_get. This version requires callers to supply length information to the function.
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_web_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/supports Content Length of zero value
UINT nx_web_http_server_content_length_get(
NX_PACKET *packet_ptr,
UINT *content_length);
This service attempts to retrieve the HTTP content length in the supplied packet. 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_web_http_server_create).
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_web_http_server_content_length_get(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_web_http_server_create(NX_WEB_HTTP_SERVER *http_server_ptr,
CHAR *http_server_name, NX_IP *ip_ptr, UINT server_port,
FX_MEDIA *media_ptr, VOID *stack_ptr, ULONG stack_size,
NX_PACKET_POOL *pool_ptr,
UINT (*authentication_check)(NX_WEB_HTTP_SERVER *server_ptr,
UINT request_type, CHAR *resource, CHAR **name,
CHAR **password, CHAR **realm),
UINT (*request_notify)(NX_WEB_HTTP_SERVER *server_ptr,
UINT 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.
This service is used to create both plaintext HTTP servers and TLS-secured HTTPS servers. To enable HTTPS using TLS, see the service nx_web_http_server_secure_configure.
Initialization, Threads
/* Create an HTTP Server instance called "my_server." */
status = nx_web_http_server_create(&my_server, "my server", &ip_0,
NX_WEB_HTTPS_SERVER_PORT, &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_web_http_server_delete(NX_WEB_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_web_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_web_http_server_get_entity_content(
NX_WEB_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, the 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 that NX_WEB_HTTP_MULTIPART_ENABLE must be enabled to use this service. Also note that the application should not release the packet pointed to by packet_pptr. This is done internally by the HTTP server.
See nx_web_http_server_get_entity_header for more details.
Threads
NX_WEB_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_web_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_web_http_server_get_entity_header(
NX_WEB_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 that NX_WEB_HTTP_MULTIPART_ENABLE must be enabled to use this service. Note also that the application should not release the packet pointed to by packet_pptr.
Threads
/* Buffer to hold data we are extracting from the request. */
UCHAR buffer[1440];
/* *my_request_notify* is the application request notify callback
registered with the HTTP server in *nx_web_http_server_create*,
creates a response to the received Client request. */
UINT my_request_notify(NX_WEB_HTTP_SERVER *server_ptr, UINT request_type,
CHAR *resource, NX_PACKET *packet_ptr)
{
UINT offset, length;
NX_PACKET *response_pkt;
/* Process multipart data. */
if(request_type == NX_WEB_HTTP_SERVER_POST_REQUEST)
{
/* Get the content header. */
while(nx_web_http_server_get_entity_header(server_ptr, &packet_ptr, buffer,
sizeof(buffer)) == NX_SUCCESS)
{
/* Header obtained successfully. Get the content data location. */
while(nx_web_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_web_http_server_callback_generate_response_header(server_ptr,
&response_pkt, NX_WEB_HTTP_STATUS_OK, 800, "text/html",
"Server: NetX WEB HTTP 5.10\r\n");
if(status == NX_SUCCESS)
{
if(nx_web_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_WEB_HTTP_CALLBACK_COMPLETED);
}
Set the callback to obtain GMT date and time
UINT nx_web_http_server_gmt_callback_set(
NX_WEB_HTTP_SERVER *server_ptr,
VOID (*gmt_get)(NX_WEB_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_WEB_HTTP_SERVER my_server;
VOID get_gmt(NX_WEB_HTTP_SERVER_DATE *now);
/* After the HTTP server is created by calling nx_web_http_server_create,
and before starting HTTP services when nx_web_http_server_start is called,
set the GMT retrieve callback: */
status = nx_web_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 handle invalid user/password
UINT nx_web_http_server_invalid_userpassword_notify_set(
NX_WEB_HTTP_SERVER *http_server_ptr,
UINT (*invalid_username_password_callback)(
CHAR *resource,
ULONG 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_WEB_HTTP_SERVER my_server;
VOID invalid_username_password_callback(NX_CHAR *resource,
ULONG client_address,
UINT request_type);
/* After the HTTP server is created by calling nx_web_http_server_create,
and before starting HTTP services when nx_web_http_server_start is called,
set the invalid username password callback: */
status = nx_web_http_server_invalid_userpassword_notify_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_web_http_server_mime_maps_additional_set(
NX_WEB_HTTP_SERVER *server_ptr,
NX_WEB_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 the NetX Duo Web HTTP Server. See nx_web_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_web_http_server_type_get_extended to parse the file type.
Initialization, Threads
/* my_server is an NX_WEB_HTTP_SERVER previously created. */
static NX_WEB_HTTP_SERVER_MIME_MAP my_mime_maps[] =
{
{"abc", "yourtype/abc"},
{"xyz", "mytype/xyz"},
};
status = nx_web_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." */
Allocate an HTTP(S) packet
UINT nx_web_http_server_response_packet_allocate(
NX_WEB_HTTP_SERVER *server_ptr,
NX_PACKET **packet_ptr,
ULONG wait_option);
This service attempts to allocates a packet for the HTTP(S) server.
Note that if a subsequent NetX Duo or HTTP Server API using this packet as input fails, such as nx_packet_data_append or **nx_web_http_server_callback_packet_send, the application is responsible for releasing the packet. **
Threads
/* Allocate a packet for HTTP(S) Server and suspend for a maximum of 5 timer
ticks if the pool is empty. */
status = nx_web_http_server_response_packet_allocate(&my_client, &packet_ptr, 5);
/* If status is NX_SUCCESS, the newly allocated packet pointer is found in the
variable packet_ptr. */
Extract content length and set pointer to start of data
UINT nx_web_http_server_packet_content_find(
NX_WEB_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_WEB_HTTP_SERVER_TIMEOUT_RECEIVE wait option.
Note this should not be called before calling nx_web_http_server_get_entity_header because it modifies the packet 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_web_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_web_http_server_packet_get(NX_WEB_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_WEB_HTTP_SERVER_TIMEOUT_RECEIVE.
Note that if successful the application is responsible for releasing the packet.
Threads
/* The HTTP server pointed to by server_ptr is previously created and started. */
UINT content_length;
NX_PACKET *recv_packet_ptr;
status = nx_web_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_web_http_server_param_get(
NX_PACKET *packet_ptr,
UINT param_number,
CHAR *param_ptr,
UINT *param_size,
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_WEB_HTTP_NOT_FOUND. This routine should be called from the application’s request notify callback specified during HTTP Server creation (nx_web_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_web_http_server_param_get(request_packet_ptr, 0, param_destination,
¶m_size, 30);
/* If status equals NX_SUCCESS, the NULL-terminated first parameter can be found
in "param_destination" and the size of that string can be found
in the variable "param_size." */
Get query from the request
UINT nx_web_http_server_query_get(
NX_PACKET *packet_ptr,
UINT query_number,
CHAR *query_ptr,
CHAR *query_size,
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_WEB_HTTP_NOT_FOUND. This routine should be called from the application’s request notify callback specified during HTTP Server creation (nx_web_http_server_create).
area.
Threads
/* Assuming we are in the application's request notify callback
routine, get the first query of the HTTP Client request. */
status = nx_web_http_server_query_get(request_packet_ptr, 0,
query_destination, &query_size, 30);
/* If status equals NX_SUCCESS, the NULL-terminated first query can be found
in "query_destination" and the length of that string can be found in the
variable "query_size". */
Set chunked transfer for HTTP(S) response
UINT nx_web_http_server_response_chunked_set(
NX_WEB_HTTP_SERVER *server_ptr,
UINT chunk_size,
NX_PACKET *packet_ptr);
This service uses chunked transfer coding to send a custom HTTP(S) response data packet created with nx_web_http_server_response_packet_allocate to the client.
Note: If the application uses chunked transfer coding to send a response data packet, it must call this service after calling nx_web_http_server_response_packet_allocate, and before calling nx_web_http_server_callback_packet_send.
Threads
/* Generate HTTP header. */
nx_web_http_server_callback_generate_response_header(server_ptr,
&response_pkt, NX_WEB_HTTP_STATUS_OK, 0, "text/html",
"Transfer-Encoding: chunked\r\n");
/* Create a new data packet response on the HTTP(S) Server instance. */
nx_web_http_server_response_packet_allocate(&my_server, &my_packet, NX_WAIT_FOREVER);
/* Set the chunked transfer. */
status = nx_web_http_server_response_chunked_set(&my_server, 128, my_packet)
/* At this point, user can fill the data into my_packet. */
nx_packet_data_append(my_packet, data_ptr, data_size,
packet_pool, NX_WAIT_FOREVER);
/* Send data packet response to client. */
nx_web_http_server_callback_packet_send(&my_server, my_packet);
Configure an HTTP Server to use TLS for secure HTTPS
UINT nx_web_http_server_secure_configure(
NX_WEB_HTTP_SERVER *http_server_ptr,
const NX_SECURE_TLS_CRYPTO *crypto_table,
VOID *metadata_buffer,
ULONG metadata_size,
UCHAR* packet_buffer,
UINT packet_buffer_size,
NX_SECURE_X509_CERT *identity_certificate,
NX_SECURE_X509_CERT *trusted_certificates[],
UINT trusted_certs_num,
NX_SECURE_X509_CERT *remote_certificates[],
UINT remote_certs_num,
UCHAR *remote_certificate_buffer,
UINT remote_cert_buffer_size);
This service configures a previously created NetX Duo Web HTTP server instance to use TLS for secure HTTPS communications. The parameters are used to configure all the possible TLS sessions with identical state so that each incoming HTTPS Client experiences consistent behavior. The number of TLS sessions is controlled using the macro NX_WEB_HTTP_SESSION_MAX.
The cryptographic routine table (ciphersuite table) is shared between all TLS sessions as it just contains function pointers.
The metadata and packet reassembly buffers are each divided equally between all TLS sessions. If the buffer size is not evenly divisible by the number of sessions the remainder will be unused.
The passed-in identity certificate is used by all sessions. During TLS operation the server identity certificate is only read from so copies are not needed for each session.
The trusted certificates are added to each TLS session in the HTTPS Server. These are used for Client certificate authentication which is automatically enabled when remote certificate space is provided.
The remote certificate array and buffer is shared by default between all TLS sessions. The remote certificates are used for Client certificate authentication which is automatically enabled when the remote certificate count is nonzero. Due to the buffer being shared some sessions may block during certificate validation.
To disable client certificate authentication, pass NX_NULL for the remote_certificates parameter and a value of 0 for the remote_certs_num parameter.
Return values will include any TLS error codes resulting from issues in the configuration of the TLS sessions.
Initialization, Threads
/* Create the HTTPS Server. */
status = nx_web_http_server_create(&my_server, "My HTTP Server",
&ip_0, &ram_disk, &server_stack, sizeof(server_stack),
&pool_0, authentication_check, server_request_callback);
/* Initialize device certificate (used for all sessions in HTTPS server). */
nx_secure_x509_certificate_initialize(&certificate, device_cert_der,
device_cert_der_len, NX_NULL, 0,
device_cert_key_der, device_cert_key_der_len,
NX_SECURE_X509_KEY_TYPE_RSA_PKCS1_DER);
/* Setup TLS session for the HTTPS server.
Note that since the remote_certs_num parameter is 0,
no trusted certificates are needed, and Client certificate authentication is disabled. */
status = nx_web_http_server_secure_configure(&my_server, &nx_crypto_tls_ciphers,
crypto_metadata,
sizeof(crypto_metadata),
tls_packet_buffer, sizeof(tls_packet_buffer),
&certificate, NX_NULL, 0, NX_NULL, 0, NX_NULL, 0);
/* Start an HTTPS Server with TLS. */
status = nx_web_http_server_start(&my_server);
/* If status equals NX_SUCCESS, the HTTP Server has been started. */
Start the HTTP Server
UINT nx_web_http_server_start(NX_WEB_HTTP_SERVER *http_server_ptr);
This service starts a previously created HTTP or HTTPS Server instance.
HTTPS servers share the same API as HTTP. To enable HTTPS using TLS on an HTTP server, see the service nx_web_http_server_secure_configure.
Initialization, Threads
/* Start the HTTP Server instance "my_server." */
status = nx_web_http_server_start(&my_server);
/* If status equals NX_SUCCESS, the HTTP Server has been started. */
Stop the HTTP Server
UINT nx_web_http_server_stop(NX_WEB_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_web_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_web_http_server_type_get(
NX_WEB_HTTP_SERVER *http_server_ptr,
CHAR *name, CHAR *http_type_string,
UINT *string_size);
Note: This service is deprecated. Users are encouraged to use the service nx_web_http_server_type_get_extended.
This service extracts the HTTP request type in the buffer http_type_string and its length in string_size 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 Web HTTP Server are:
If supplied, it will also search a user defined set of additional MIME maps. See nx_web_http_server_mime_maps_additional_set for more details on user defined maps.
Application
/* my_server is a previously created HTTP server, which starts accepting client
requests when *nx_web_http_server_start* is called */
CHAR temp_string[20];
UINT string_length;
/* Extract the HTTP type. */
string_length = nx_web_http_server_type_get(&my_server_ptr,
my_server.nx_web_http_server_request_resource, temp_string);
/* If string_length is non zero, the HTTP string is extracted. */
For a more detailed example, see the description for
*nx_web_http_server_callback_generate_response_header.*
Extract file type from Client HTTP request
UINT nx_web_http_server_type_get_extended(
NX_WEB_HTTP_SERVER *http_server_ptr,
CHAR *name, UINT name_length,
CHAR *http_type_string,
UINT http_type_string_max_size,
UINT *string_size);
This service extracts the HTTP request type in the buffer http_type_string and its length in string_size 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 Web HTTP Server are:
If supplied, it will also search a user defined set of additional MIME maps. See nx_web_http_server_mime_maps_additional_set for more details on user defined maps.
This service replaces nx_web_http_server_type_get. This version requires callers to supply length information to the function.
length.
Application
/* my_server is a previously created HTTP server, which starts accepting client
requests when *nx_web_http_server_start* is called */
CHAR temp_string[20];
UINT string_length;
UINT ret;
/* Extract the HTTP type. */
ret = nx_web_http_server_type_get_extended(&my_server_ptr,
my_server.nx_web_http_server_request_resource,
strlen(my_server.nx_web_http_server_request_resource),
temp_string,sizeof(temp_string), &string_length);
/* If string_length is non zero, the HTTP string is extracted. */
For a more detailed example, see the description for
*nx_web_http_server_callback_generate_response_header.*
Set digest authenticate callback function
UINT nx_web_http_server_digest_authenticate_notify_set(
NX_WEB_HTTP_SERVER *http_server_ptr,
UINT (*digest_authenticate_callback)(
NX_WEB_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_WEB_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_WEB_HTTP_SERVER my_server;
/* After the HTTP server is created by calling nx_web_http_server_create, and
before starting HTTP services when nx_web_http_server_start is called, set the digest authenticate callback: */
status = nx_web_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 digest authenticate callback function
UINT nx_web_http_server_digest_authenticate_notify_set(
NX_WEB_HTTP_SERVER *http_server_ptr,
UINT (*authentication_check_extended)(
NX_WEB_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 invoked when authenticate check is performed.
Application
UINT authenticate_check_callback(NX_WEB_HTTP_SERVER *server_ptr,
UINT request_type,
CHAR *name_ptr, UCHAR *resource, UCHAR **name,
UINT *name_length, UCHAR **password,
UINT *password_length, UCHAR **realm,
UINT *realm_length)
{
*name = "name";
*name_length = 4;
*password = "password";
*password_length = 8;
*realm = "realm";
*realm_length = 5;
return(NX_SUCCESS);
}
NX_WEB_HTTP_SERVER my_server;
/* After the HTTP server is created by calling nx_web_http_server_create, and
before starting HTTP services when nx_web_http_server_start is called, set the authenticate check callback: */
status = nx_web_http_digest_authenticate_check_set (&my_server,
authenticate_check_callback);
/* If status equals NX_SUCCESS, the authenticate_check_callback function
will be called when the HTTP server performs authenticate check. */