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.

Return

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.

Return

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.

Return

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

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

Parameters
  • [in] port: : 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.

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

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

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

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.

Return

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

Parameters
  • [in] server_handle: : HTTP server handle

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.

Return

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

Parameters

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.

Return

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

Parameters

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.

Return

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

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

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

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

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

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

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.

Return

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

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

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.

Return

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

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

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.

Return

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

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

  • [in] status_code: : HTTP status code.

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

  • [in] cache_type: : 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.

  • [in] mime_type: : HTTP MIME type.

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.

Return

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

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

  • [in] data: : data to write.

  • [in] length: : data length in bytes.

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.

Return

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

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

  • [in] resource: : Pointer to resource.

cy_rslt_t cy_http_server_response_stream_flush(cy_http_response_stream_t *stream)

Flushes the HTTP stream.

Return

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

Parameters
  • [in] stream: : HTTP stream to flush.

cy_rslt_t cy_http_server_response_stream_disconnect(cy_http_response_stream_t *stream)

Queues a disconnect request to the HTTP server.

Return

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

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

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.

Return

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

Parameters

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.

Return

cy_rslt_t : CY_RSLT_SUCCESS if found; CY_RSLT_NOT_FOUND otherwise.

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

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

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

  • [out] value_length: : This variable will contain the length of the parameter value upon return; 0 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.

Return

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

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

  • [out] count: : Parameter count.

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.

Return

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

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

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

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