HTTP Client
HTTP client functions. More...
Modules | |
Types | |
HTTP client data types. | |
Functions | |
zos_result_t | zn_http_open_request (const zos_http_request_t *context, uint32_t *handle) |
Open a HTTP request stream. More... | |
zos_result_t | zn_http_get (const zos_http_request_t *context, uint32_t *handle) |
HTTP GET request stream. More... | |
zos_result_t | zn_http_post (const zos_http_request_t *context, uint32_t *handle) |
HTTP POST request stream. More... | |
zos_result_t | zn_http_add_header (uint32_t handle, const char *key, const char *value) |
Add HTTP header to request stream. More... | |
zos_result_t | zn_http_write (uint32_t handle, const void *data, uint32_t size, zos_bool_t auto_flush) |
Write data to a HTTP POST request stream. More... | |
zos_result_t | zn_http_read (uint32_t handle, void *data, uint32_t max_size, uint32_t *bytes_read_ptr) |
Read HTTP GET/POST response stream. More... | |
zos_result_t | zn_http_read_with_buffer (uint32_t handle, zos_buffer_t *buffer) |
Read HTTP stream data into buffer. More... | |
zos_result_t | zn_http_poll (uint32_t handle, uint32_t *bytes_available_ptr) |
Poll HTTP stream for more response data. More... | |
zos_result_t | zn_http_read_status (uint32_t handle, uint32_t *status_ptr) |
Complete HTTP request stream and return HTTP status code. More... | |
zos_result_t | zn_http_receive_response (uint32_t handle, zos_http_response_t *response) |
Receive the HTTP response headers. More... | |
zos_result_t | zn_http_receive_response_with_config (uint32_t handle, zos_http_response_t *response, const zos_http_response_config_t *config) |
Receive the HTTP response header with specified configuration. More... | |
void | zn_http_response_cleanup (zos_http_response_t *response) |
Cleanup a HTTP response. More... | |
zos_result_t | zn_http_close (uint32_t handle) |
Close HTTP request stream. More... | |
zos_result_t | zn_http_download (const zos_http_download_t *context) |
Download file from remote HTTP server to local file system. More... | |
zos_result_t | zn_http_upload (const zos_http_upload_t *context) |
Upload file from local file system to remote HTTP server. More... | |
Detailed Description
HTTP client functions.
Function Documentation
zos_result_t zn_http_add_header | ( | uint32_t | handle, |
const char * | key, |
||
const char * | value |
||
) |
Add HTTP header to request stream.
The HTTP request stream should have been previously opened with one of the following:
See ZentriOS Command API documentation: http_add_header.
- Parameters
-
[in] handle
Handle of opened HTTP request [in] key
HTTP request header key [in] value
HTTP request header value
- Returns
- zos_result_t return of API call
zos_result_t zn_http_close | ( | uint32_t | handle | ) |
Close HTTP request stream.
This closes an opened HTTP stream.
See ZentriOS Command API documentation: stream_close.
- Parameters
-
[in] handle
Handle of opened HTTP stream to close
- Returns
- zos_result_t return of API call
zos_result_t zn_http_download | ( | const zos_http_download_t * | context | ) |
Download file from remote HTTP server to local file system.
See ZentriOS Command API documentation: http_download.
- Parameters
-
[in] context
zos_http_download_t information about download
- Returns
- zos_result_t return of API call
zos_result_t zn_http_get | ( | const zos_http_request_t * | context, |
uint32_t * | handle |
||
) |
HTTP GET request stream.
This has the same functionality as zn_http_open_request() except a GET request is opened.
After the GET request is opened, zn_http_add_header() may be used to append additional headers to the request.
To receive the request response, use one the following:
Once the response is received use zn_http_read() to ready the response body.
Use zn_http_close() to close the HTTP stream.
See ZentriOS Command API documentation for additionality info: http_get.
- Parameters
-
[in] context
zos_http_request_t Information about the HTTP GET request [out] handle
Stream handle of HTTP GET request
- Returns
- zos_result_t return of API call
zos_result_t zn_http_open_request | ( | const zos_http_request_t * | context, |
uint32_t * | handle |
||
) |
Open a HTTP request stream.
This allows for opening a HTTP request specificed in zos_http_request_t. Once opened a handle is returned. The handle may be used with any of the following APIs:
- zn_http_add_header()
- zn_http_write()
- zn_http_read_status()
- zn_http_receive_response()
- zn_http_receive_response_with_config()
- zn_http_close()
- Note
- This API only opens the HTTP request with the server. The one following APIs should be used to receive the response:
Once the response is received use zn_http_read() to ready the response body. If zn_http_receive_response() or zn_http_receive_response_with_config() is used, then 'content_length' of zos_http_response_t contains the amount of data to be read. zn_http_poll() can also be used to determine the amount of data to be read.
Use zn_http_close() to close the HTTP stream.
- Parameters
-
[in] context
zos_http_request_t Information about the HTTP request [out] handle
Stream handle of HTTP request
- Returns
- zos_result_t return of API call
zos_result_t zn_http_poll | ( | uint32_t | handle, |
uint32_t * | bytes_available_ptr |
||
) |
Poll HTTP stream for more response data.
This read an open HTTP stream for more response body data.
The HTTP response should then have been previously received with one of the following:
- Parameters
-
[in] handle
Handle of opened HTTP request [out] bytes_available_ptr
Pointer to hold number of bytes available to read
- Returns
- zos_result_t return of API call
- Examples:
- nxp/nfc3d/cloud_rest.c.
zos_result_t zn_http_post | ( | const zos_http_request_t * | context, |
uint32_t * | handle |
||
) |
HTTP POST request stream.
This has the same functionality as zn_http_open_request() except a POST request is opened.
After the POST request is opened, zn_http_add_header() may be used to append additional headers to the request.
zn_http_write() is then used to send the HTTP POST data.
- Note
- If the 'content_length' member of zos_http_request_t is set to '-1', chunked encoding is used. This allows for arbitrary amounts of data to be sent to the server. If 'content_length' is greater than 0 then zn_http_write() should be issued as many times a necessary to write that specified amount of data.
Once all POST data is written, receive the request response using one the following:
Once the response is received use zn_http_read() to ready the response body.
Use zn_http_close() to close the HTTP stream.
This API provides similar functionality to the Command API function http_post.
- Note
- A complete example showing how to send data using an HTTP POST request with the Command API is available: Sending a POST Request
- Parameters
-
[in] context
zos_http_request_t Information about the HTTP POST request [out] handle
A handle for the request
- Returns
- The result of the POST request
zos_result_t zn_http_read | ( | uint32_t | handle, |
void * | data, |
||
uint32_t | max_size, |
||
uint32_t * | bytes_read_ptr |
||
) |
Read HTTP GET/POST response stream.
The HTTP request stream should have been previously opened with one of the following:
The HTTP response should then have been previously received with one of the following:
This reads the HTTP response body into the given buffer.
See ZentriOS Command API documentation: stream_read.
- Parameters
-
[in] handle
Handle of opened HTTP request [out] data
Buffer to hold read data [in] max_size
Maximum amount of bytes to read (i.e. size of given buffer) [out] bytes_read_ptr
Pointer to hold number of bytes actually read, use NULL if not used
- Returns
- zos_result_t return of API call
- Examples:
- basic/http_methods/http_get.c, and nxp/nfc3d/cloud_rest.c.
zos_result_t zn_http_read_status | ( | uint32_t | handle, |
uint32_t * | status_ptr |
||
) |
Complete HTTP request stream and return HTTP status code.
The completes a HTTP request and returns the HTTP response status code.
Use zn_http_read() to read the HTTP response body.
- Note
- The HTTP response headers are discarded with this API, use zn_http_receive_response() to receive the response headers.
See ZentriOS Command API documentation: http_read_status.
- Parameters
-
[in] handle
Handle of opened HTTP request [out] status_ptr
Pointer to hold HTTP status code
- Returns
- zos_result_t return of API call
zos_result_t zn_http_read_with_buffer | ( | uint32_t | handle, |
zos_buffer_t * | buffer |
||
) |
Read HTTP stream data into buffer.
See zn_read_with_buffer() for more information.
- Parameters
-
handle
Stream handle buffer
Buffer to specify how much data to read, then return how much data was read with pointer to data
- Returns
- zos_result_t result of api call
zos_result_t zn_http_receive_response | ( | uint32_t | handle, |
zos_http_response_t * | response |
||
) |
Receive the HTTP response headers.
This completes the HTTP request and returns the HTTP response zos_http_response_t.
- Note
- Only zos_http_basic_header_t headers are returned, use zn_http_receive_response_with_config() to return other headers.
- After calling this API use zn_http_read() to receive the HTTP response body.
- Parameters
-
[in] handle
Handle of opened HTTP request [out] response
zos_http_response_t To hold HTTP response
- Returns
- zos_result_t return of API call
zos_result_t zn_http_receive_response_with_config | ( | uint32_t | handle, |
zos_http_response_t * | response, |
||
const zos_http_response_config_t * | config |
||
) |
Receive the HTTP response header with specified configuration.
This completes the HTTP request and returns the HTTP response zos_http_response_t. How the response is returned is specified by the supplied zos_http_response_config_t
- Note
- After calling this API use zn_http_read() to receive the HTTP response body.
- Use zn_http_response_cleanup() to cleanup the HTTP response.
- Parameters
-
[in] handle
Handle of opened HTTP request [out] response
zos_http_response_t To hold HTTP response [in] config
zos_http_response_config_t Specifying how to return the response
- Returns
- zos_result_t return of API call
void zn_http_response_cleanup | ( | zos_http_response_t * | response | ) |
Cleanup a HTTP response.
This cleans up the zos_http_response_t returned by:
- Parameters
-
[in] response
zos_http_response_t to cleanup
zos_result_t zn_http_upload | ( | const zos_http_upload_t * | context | ) |
Upload file from local file system to remote HTTP server.
See ZentriOS Command API documentation: http_upload.
- Parameters
-
[in] context
zos_http_upload_t information about upload
- Returns
- zos_result_t return of API call
zos_result_t zn_http_write | ( | uint32_t | handle, |
const void * | data, |
||
uint32_t | size, |
||
zos_bool_t | auto_flush |
||
) |
Write data to a HTTP POST request stream.
The HTTP request stream should have been previously opened with one of the following:
See ZentriOS Command API documentation: stream_write.
- Parameters
-
[in] handle
Handle of opened HTTP POST request [in] data
Data to send to server [in] size
Size in bytes of data to send [in] auto_flush
ZOS_TRUE to only flush when internal buffer is full, ZOS_FALSE to send data immediately to server
- Returns
- zos_result_t return of API call
- Examples:
- nxp/nfc3d/cloud_rest.c.