Functions

group group_c_api_functions

C API provided by HTTP server library.

Functions

cy_rslt_t cy_http_server_network_init(void)

One-time initialization function for network sockets implementation.

It must be called once (and only once) before calling any other function in this library.

Returns

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

cy_rslt_t cy_http_server_network_deinit(void)

One-time deinitialization function for Secure Sockets implementation.

It should be called after destroying all network socket connections.

Returns

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

cy_rslt_t cy_http_server_create(cy_network_interface_t *interface, uint16_t port, uint16_t max_connection, cy_https_server_security_info_t *security_info, cy_http_server_t *server_handle)

Creates a HTTP server instance and initializes its members based on the supplied arguments.

Handle to the HTTP server instance is returned via the handle pointer supplied by the user on successful return. Handle to the HTTP server instance is used for server start, stop, and delete. This API function must be called before using any other HTTP Server API.

note

Refer code snippet Code Snippet 6: HTTP Server Start to understand how to initialize the 'interface' before calling this function.

Parameters
  • interface[in] : Pointer to the network interface information structure (included as part of cy_nw_helper.h). Used for server start.

  • port[in] : Port number on which the server listens for client connection requests. Usually port number 443 is used for the HTTPS server, and port number 80 is used for the HTTP server.

  • max_connection[in] : Maximum number of client connections that can be accepted.

  • security_info[in] : Security info containing the certificate, private key, and rootCA certificate. For a non-secured connection, this parameter should be NULL.

  • server_handle[out] : Pointer to store the HTTP sever handle allocated by this function on successful return.

Returns

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

cy_rslt_t cy_http_server_delete(cy_http_server_t server_handle)

Deletes the given HTTP server instance and resources allocated for the instance by the cy_http_server_create function.

Before calling this API function, the HTTP server associated with server_handle must be stopped.

Parameters

server_handle[in] : HTTP server handle

Returns

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

cy_rslt_t cy_http_server_start(cy_http_server_t server_handle)

Starts a HTTP server daemon (web server)

The web server implements HTTP 1.1 using a non-blocking architecture which allows multiple sockets to be served simultaneously. Web pages and other files can be served either dynamically from a function or from static data in memory or internal/external flash resources. Prior to calling this API, API cy_http_server_create must be called for creating HTTP{ server instance.

Parameters

server_handle[in] : HTTP server handle created using cy_http_server_create.

Returns

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

cy_rslt_t cy_http_server_stop(cy_http_server_t server_handle)

Stops a HTTP server daemon (web server) Before calling this API function, API cy_http_server_start must be called to start HTTP server.

Parameters

server_handle[in] : HTTP server handle created using cy_http_server_create.

Returns

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

cy_rslt_t cy_http_server_register_resource(cy_http_server_t server_handle, uint8_t *url, uint8_t *mime_type, cy_url_resource_type url_resource_type, void *resource_data)

Used to register a resource(static/dynamic) with the HTTP server.

All static resources must have been registered before calling cy_http_server_start.

Parameters
  • server_handle[in] : HTTP server handle created using cy_http_server_create.

  • url[in] : URL of the resource. The application should reserve memory for the URL.

  • mime_type[in] : MIME type of the resource. The application should reserve memory for the MIME type.

  • url_resource_type[in] : Content type of the resource.

  • resource_data[in] : Pointer to the static or dynamic resource type structure.

Returns

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

cy_rslt_t cy_http_server_response_stream_enable_chunked_transfer(cy_http_response_stream_t *stream)

Enables chunked transfer encoding on the HTTP stream.

Parameters

stream[in] : Pointer to the HTTP stream.

Returns

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes from Macros otherwise.

cy_rslt_t cy_http_server_response_stream_disable_chunked_transfer(cy_http_response_stream_t *stream)

Disables chunked transfer encoding on the HTTP stream.

Parameters

stream[in] : Pointer to the HTTP stream.

Returns

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes from Macros otherwise.

cy_rslt_t cy_http_server_response_stream_write_header(cy_http_response_stream_t *stream, cy_http_status_codes_t status_code, uint32_t content_length, cy_http_cache_t cache_type, cy_http_mime_type_t mime_type)

Writes HTTP header to the HTTP stream provided.

Parameters
  • stream[in] : Pointer to the HTTP stream.

  • status_code[in] : HTTP status code.

  • content_length[in] : HTTP content length to follow, in bytes.

  • cache_type[in] : HTTP cache type (enabled or disabled). In AnyCloud and Mbed frameworks, the caching feature is not supported; therefore, this parameter should be always CY_HTTP_CACHE_DISABLED.

  • mime_type[in] : HTTP MIME type.

Returns

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes from Macros otherwise.

cy_rslt_t cy_http_server_response_stream_write_payload(cy_http_response_stream_t *stream, const void *data, uint32_t length)

Writes data to the HTTP stream.

Parameters
  • stream[in] : HTTP stream to write the data into.

  • data[in] : data to write.

  • length[in] : data length in bytes.

Returns

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes from Macros otherwise.

cy_rslt_t cy_http_server_response_stream_write_resource(cy_http_response_stream_t *stream, const void *resource)

Writes resource to HTTP stream.

Currently not supported in AnyCloud and Mbed frameworks.

Parameters
  • stream[in] : HTTP stream to write the resource into.

  • resource[in] : Pointer to resource.

Returns

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes from Macros otherwise.

cy_rslt_t cy_http_server_response_stream_flush(cy_http_response_stream_t *stream)

Flushes the HTTP stream.

Parameters

stream[in] : HTTP stream to flush.

Returns

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes from Macros otherwise.

cy_rslt_t cy_http_server_response_stream_disconnect(cy_http_response_stream_t *stream)

Queues a disconnect request to the HTTP server.

Parameters

stream[in] : Pointer to the HTTP stream.

Returns

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes from Macros otherwise.

cy_rslt_t cy_http_server_response_stream_disconnect_all(cy_http_server_t server_handle)

Disconnects all the HTTP streams associated with the given server.

Parameters

server_handle[in] : HTTP server handle created using cy_http_server_create.

Returns

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes from Macros otherwise.

cy_rslt_t cy_http_server_get_query_parameter_value(const char *url_query, const char *parameter_key, char **parameter_value, uint32_t *value_length)

Searches for a parameter (key-value pair) in a URL query string and returns a pointer to the value.

Parameters
  • url_query[in] : NULL-terminated URL query string.

  • parameter_key[in] : NULL-terminated Key or name of the parameter to find in the URL query string.

  • parameter_value[out] : If the parameter with the given key is found, this pointer will point to the parameter value upon return; NULL otherwise.

  • value_length[out] : This variable will contain the length of the parameter value upon return; 0 otherwise.

Returns

cy_rslt_t : CY_RSLT_SUCCESS if found; CY_RSLT_NOT_FOUND otherwise.

cy_rslt_t cy_http_server_get_query_parameter_count(const char *url_query, uint32_t *count)

Returns the number of parameters found in the URL query string.

Parameters
  • url_query[in] : NULL terminated URL query string.

  • count[out] : Parameter count.

Returns

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes from Macros otherwise.

cy_rslt_t cy_http_server_match_query_parameter(const char *url_query, const char *parameter_key, const char *parameter_value)

Checks whether the given parameter key-value pair is present in the given URL query.

Parameters
  • url_query[in] : NULL-terminated URL query string.

  • parameter_key[in] : NULL-terminated key or name of the parameter to find in the URL query string.

  • parameter_value[out] : NULL-terminated value of the parameter to find in the URL query string.

Returns

cy_rslt_t : CY_RSLT_SUCCESS if matched; CY_RSLT_NOT_FOUND if matching parameter is not found.