HTTP request module header file. More...

#include "http_definitions.h"
#include "string_array.h"

Include dependency graph for http_request.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	http_request_t
	HTTP Request Handle. More...

Macros
#define	BOUNDARY_SIGN_LENGTH 2

#define	BOUNDARY_SIGN "--"

#define	COLON_FORMAT_LENGTH 2

#define	BOUNDARY_LENGTH 22

#define	BOUNDARY_CHARACTER_COUNT 62

#define	GROWTH_FACTOR 1.5

#define	CONTENT_TYPE_LINE_LENGTH 65

#define	CONTENT_TYPE_HEADER_LENGTH 14

#define	CONTENT_ID_HEADER_LENGTH 12

#define	NEW_LINE_LENGTH 2

#define	NEW_LINE "\r\n"

#define	BOUNDARY_LINE_LENGTH (BOUNDARY_SIGN_LENGTH + BOUNDARY_LENGTH + NEW_LINE_LENGTH)

#define	HTTP_REQUEST_RESIZE_ENABLED MCL_TRUE

#define	HTTP_REQUEST_RESIZE_DISABLED MCL_FALSE

Typedefs
typedef mcl_size_t(*	payload_copy_callback_t) (void destination, void source, mcl_size_t size, void *user_context)

Enumerations
enum	E_MCL_HTTP_METHOD { MCL_HTTP_GET, MCL_HTTP_HEAD, MCL_HTTP_POST, MCL_HTTP_PUT, MCL_HTTP_DELETE, MCL_HTTP_CONNECT, MCL_HTTP_OPTIONS, MCL_HTTP_TRACE }
	HTTP Method Types. More...

Functions
E_MCL_ERROR_CODE	http_request_initialize (E_MCL_HTTP_METHOD method, string_t uri, mcl_size_t header_size, mcl_size_t payload_size, mcl_bool_t resize_enabled, string_t user_agent, mcl_size_t max_http_payload_size, http_request_t **http_request)
	HTTP Request Initializer. More...

E_MCL_ERROR_CODE	http_request_add_header (http_request_t http_request, string_t header_name, string_t *header_value)
	To be used to add an HTTP header to the request with it's value. More...

E_MCL_ERROR_CODE	http_request_add_single (http_request_t http_request, string_t content_type, string_t content_id, string_t meta_string)
	To be used to add a single to the HTTP Request. More...

E_MCL_ERROR_CODE	http_request_add_tuple (http_request_t http_request, string_t meta, string_t meta_content_type, payload_copy_callback_t payload_copy_callback, void user_context, void payload, mcl_size_t payload_size, string_t payload_content_type)
	To be used to add a tuple to the HTTP Request. More...

E_MCL_ERROR_CODE	http_request_start_tuple (http_request_t *http_request)
	To start a new tuple structure inside the http request body. More...

E_MCL_ERROR_CODE	http_request_start_tuple_sub_section (http_request_t http_request, string_t content_type, string_t content_id, string_t *sub_boundary)
	To start a sub tuple section inside of the http request body. More...

E_MCL_ERROR_CODE	http_request_end_tuple_sub_section (http_request_t http_request, string_t sub_boundary)
	To end a sub tuple section previously started with `http_request_start_tuple_sub_section()`. More...

E_MCL_ERROR_CODE	http_request_add_raw_data (http_request_t http_request, payload_copy_callback_t copy_callback, void user_context, void data, mcl_size_t data_size, mcl_size_t actual_written_size)
	To add raw data into an http_request. More...

mcl_size_t	http_request_get_available_space_for_tuple (http_request_t *http_request)
	To be used to get the available space left in the request buffer in order to add a tuple. More...

mcl_size_t	http_request_get_available_space_for_raw_data (http_request_t *http_request)
	To be used to get the available space left in the request buffer in order to add a raw data. More...

mcl_size_t	http_request_get_available_space_for_single (http_request_t *http_request)
	To be used to get the available space left in the request buffer in order to add a single. More...

E_MCL_ERROR_CODE	http_request_finalize (http_request_t *http_request)
	Adds closing boundary to the payload and resizes the payload buffer to release unused memory space. More...

void	http_request_destroy (http_request_t **http_request)
	To destroy the HTTP Request Handler. More...

Detailed Description

HTTP request module header file.

Copyright: Copyright (C) 2016 Siemens Aktiengesellschaft.
All rights reserved.

Date: Jun 28, 2016 HTTP request messages are built with this module. It has the abilities like adding headers and adding boundaries automatically when inserting a single or tuple. Manages the multipart/mixed message structure.

Definition in file http_request.h.

Macro Definition Documentation

#define BOUNDARY_CHARACTER_COUNT 62

Definition at line 32 of file http_request.h.

Referenced by _generate_random_boundary().

#define BOUNDARY_LENGTH 22

Definition at line 31 of file http_request.h.

Referenced by _generate_random_boundary(), and http_request_finalize().

#define BOUNDARY_LINE_LENGTH (BOUNDARY_SIGN_LENGTH + BOUNDARY_LENGTH + NEW_LINE_LENGTH)

Definition at line 51 of file http_request.h.

Referenced by _add_boundary(), and http_request_end_tuple_sub_section().

#define BOUNDARY_SIGN "--"

Definition at line 25 of file http_request.h.

Referenced by http_request_finalize().

#define BOUNDARY_SIGN_LENGTH 2

Definition at line 24 of file http_request.h.

Referenced by _add_boundary(), and http_request_finalize().

#define COLON_FORMAT_LENGTH 2

Definition at line 28 of file http_request.h.

#define CONTENT_ID_HEADER_LENGTH 12

Definition at line 43 of file http_request.h.

Referenced by http_request_add_single().

#define CONTENT_TYPE_HEADER_LENGTH 14

Definition at line 40 of file http_request.h.

Referenced by http_request_add_single(), http_request_add_tuple(), and http_request_start_tuple_sub_section().

#define CONTENT_TYPE_LINE_LENGTH 65

Definition at line 37 of file http_request.h.

Referenced by http_request_add_tuple(), and http_request_start_tuple_sub_section().

#define GROWTH_FACTOR 1.5

Definition at line 34 of file http_request.h.

Referenced by _resize_payload_buffer_if_necessary().

#define HTTP_REQUEST_RESIZE_DISABLED MCL_FALSE

Definition at line 55 of file http_request.h.

Referenced by http_processor_stream().

#define HTTP_REQUEST_RESIZE_ENABLED MCL_TRUE

Definition at line 54 of file http_request.h.

Referenced by http_processor_exchange(), http_processor_get_access_token(), and http_processor_register().

#define NEW_LINE "\r\n"

Definition at line 47 of file http_request.h.

Referenced by _add_blank_line().

#define NEW_LINE_LENGTH 2

Definition at line 46 of file http_request.h.

Referenced by _add_blank_line(), http_request_add_single(), http_request_add_tuple(), and http_request_start_tuple_sub_section().

Typedef Documentation

typedef mcl_size_t(* payload_copy_callback_t) (void *destination, void *source, mcl_size_t size, void *user_context)

Definition at line 93 of file http_request.h.

Enumeration Type Documentation

enum E_MCL_HTTP_METHOD

HTTP Method Types.

Used when initializing http_request_t struct to specifying the http method of the request.

Enumerator
MCL_HTTP_GET	Http get method.
MCL_HTTP_HEAD	Http head method.
MCL_HTTP_POST	Http post method.
MCL_HTTP_PUT	Http put method.
MCL_HTTP_DELETE	Http delete method.
MCL_HTTP_CONNECT	Http connect method.
MCL_HTTP_OPTIONS	Http options method.
MCL_HTTP_TRACE	Http trace method.

Definition at line 62 of file http_request.h.

Function Documentation

E_MCL_ERROR_CODE http_request_add_header	(	http_request_t *	http_request,
		string_t *	header_name,
		string_t *	header_value
	)

To be used to add an HTTP header to the request with it's value.

Parameters

[in]	http_request	HTTP Request handle to be used.
[in]	header_name	Header name.
[in]	header_value	Header value.

Returns

MCL_OK in case of success.
MCL_OUT_OF_MEMORY in case there is not enough memory in the system to proceed.
MCL_FAIL in case of an internal error in MCL.

Definition at line 131 of file http_request.c.

References ASSERT_CODE_MESSAGE, ASSERT_STATEMENT_CODE_MESSAGE, http_request_t::boundary, string_t::buffer, CONTENT_TYPE_MULTIPART_MIXED, content_type_values, DEBUG_ENTRY, DEBUG_LEAVE, http_request_t::header, HTTP_HEADER_CONTENT_TYPE, http_header_names, string_t::length, MCL_NULL, MCL_OK, MCL_TRUE, string_array_add(), string_compare(), string_destroy(), string_initialize_new(), and string_util_snprintf().

Referenced by _add_authentication_header_to_request(), _exchange_initialize_http_request_headers(), _process_registration_response_rsa_3072(), http_processor_exchange(), http_processor_get_access_token(), http_processor_register(), http_processor_stream(), and http_request_initialize().

Here is the call graph for this function:

Here is the caller graph for this function:

E_MCL_ERROR_CODE http_request_add_raw_data	(	http_request_t *	http_request,
		payload_copy_callback_t	copy_callback,
		void *	user_context,
		void *	data,
		mcl_size_t	data_size,
		mcl_size_t *	actual_written_size
	)

To add raw data into an http_request.

To accommodate server format needs, caller must make sure that the format is suitable. Usually called between start and end tuple sections.

Parameters

[in]	http_request	HTTP Request Handle to be used.
[in]	copy_callback	Callback function to be used to copy the payload to `http_request`.
[in]	user_context	User context pointer to pass to the callback function.
[in]	data	Data to be added. Should be something that the callback can operate on. It will be passed to callback function.
[in]	data_size	Size of the data.
[out]	actual_written_size	Actually written data size.

Returns

MCL_OK in case of success.
MCL_OUT_OF_MEMORY in case there is not enough memory in the system to proceed.
MCL_HTTP_REQUEST_NO_MORE_SPACE in case http_request has no more space for adding new content.
MCL_FAIL in case of an internal error in MCL.

Definition at line 407 of file http_request.c.

References _add_payload(), _resize_payload_buffer_if_necessary(), ASSERT_CODE_MESSAGE, DEBUG_ENTRY, DEBUG_LEAVE, MCL_FALSE, MCL_NULL, MCL_OK, and http_request_t::payload_offset.

Referenced by _exchange_add_current_data_to_request_by_streaming().

Here is the call graph for this function:

Here is the caller graph for this function:

E_MCL_ERROR_CODE http_request_add_single	(	http_request_t *	http_request,
		string_t *	content_type,
		string_t *	content_id,
		string_t *	meta_string
	)

To be used to add a single to the HTTP Request.

Please refer to the MindConnect API Specification document for the detailed information on Singles.

With this function; a new meta section will be added in the HTTP Request message body without opening a multipart/related section and the given meta string will be inserted in this meta section.

Note: Content-Type header should be included in the received meta string.

Parameters

[in]	http_request	HTTP Request Handle to be used.
[in]	content_type	HTTP Content Type for this single. Sample : "application/vnd.siemens.mindsphere.meta+json".
[in]	content_id	A unique random id string containing 36 chars.
[in]	meta_string	The pre-generated meta string to add.

Returns

MCL_OK in case of success.
MCL_OUT_OF_MEMORY in case there is not enough memory in the system to proceed.
MCL_HTTP_REQUEST_NO_MORE_SPACE in case http_request has no more space for adding new content.
MCL_FAIL in case of an internal error in MCL.

Definition at line 172 of file http_request.c.

References _add_blank_line(), _add_boundary(), _add_content_info(), _add_meta(), _resize_payload_buffer_if_necessary(), ASSERT_CODE_MESSAGE, http_request_t::boundary, string_t::buffer, CONTENT_ID_HEADER_LENGTH, CONTENT_TYPE_HEADER_LENGTH, DEBUG_ENTRY, DEBUG_LEAVE, HTTP_HEADER_CONTENT_ID, HTTP_HEADER_CONTENT_TYPE, http_header_names, string_t::length, MCL_FALSE, MCL_NULL, MCL_NULL_CHAR_SIZE, MCL_OK, MCL_OPEN_BOUNDARY, NEW_LINE_LENGTH, http_request_t::payload, and http_request_t::payload_offset.

Here is the call graph for this function:

E_MCL_ERROR_CODE http_request_add_tuple	(	http_request_t *	http_request,
		string_t *	meta,
		string_t *	meta_content_type,
		payload_copy_callback_t	payload_copy_callback,
		void *	user_context,
		void *	payload,
		mcl_size_t	payload_size,
		string_t *	payload_content_type
	)

To be used to add a tuple to the HTTP Request.

Please refer to the MindConnect API Specification document for the detailed information on tuples.

With this function; a new multipart/related section will be opened in the HTTP Request message body. The received meta string will be inserted in the fist section and the payload to the second section. The boundary id will be generated for this section and managed.

Note: Content-Type header should be included in the received meta and payload strings.

Parameters

[in]	http_request	HTTP Request Handle to be used.
[in]	meta	Meta string to be added.
[in]	meta_content_type	HTTP Content Type header for meta section of the tuple. Sample : "application/vnd.siemens.mindsphere.meta+json".
[in]	payload_copy_callback	Callback function to be used to copy the payload to `http_request`.
[in]	user_context	User context pointer to pass to the callback function.
[in]	payload	Payload string to be added.
[in]	payload_size	Size of the payload string to be added.
[in]	payload_content_type	HTTP Content Type header for the payload section of the tuple. Sample : "application/octet-stream ".

Returns

MCL_OK in case of success.
MCL_OUT_OF_MEMORY in case there is not enough memory in the system to proceed.
MCL_HTTP_REQUEST_NO_MORE_SPACE in case http_request has no more space for adding new content.
MCL_FAIL in case of an internal error in MCL.

Definition at line 214 of file http_request.c.

References _add_blank_line(), _add_boundary(), _add_content_info(), _add_meta(), _add_payload(), _generate_random_boundary(), _resize_payload_buffer_if_necessary(), ASSERT_CODE_MESSAGE, ASSERT_STATEMENT_CODE_MESSAGE, http_request_t::boundary, string_t::buffer, CONTENT_TYPE_HEADER_LENGTH, CONTENT_TYPE_LINE_LENGTH, CONTENT_TYPE_MULTIPART_RELATED, content_type_values, DEBUG_ENTRY, DEBUG_LEAVE, HTTP_HEADER_CONTENT_TYPE, http_header_names, string_t::length, MCL_CLOSE_BOUNDARY, MCL_FALSE, MCL_NULL, MCL_OK, MCL_OPEN_BOUNDARY, NEW_LINE_LENGTH, OVERHEAD_FOR_TUPLE, http_request_t::payload, http_request_t::payload_offset, and string_destroy().

Referenced by _exchange_add_current_data_to_request().

Here is the call graph for this function:

Here is the caller graph for this function:

void http_request_destroy ( http_request_t ** http_request )

To destroy the HTTP Request Handler.

Will release the resources of HTTP Request. After destroy operation, handler shouldn't be used.

Parameters

[in] http_request HTTP Request handle to be freed.

Definition at line 497 of file http_request.c.

References DEBUG_ENTRY, DEBUG_LEAVE, MCL_DEBUG, MCL_FREE, MCL_NULL, string_array_destroy(), and string_destroy().

Referenced by http_processor_exchange(), http_processor_get_access_token(), http_processor_register(), http_processor_stream(), and http_request_initialize().

Here is the call graph for this function:

Here is the caller graph for this function:

E_MCL_ERROR_CODE http_request_end_tuple_sub_section	(	http_request_t *	http_request,
		string_t *	sub_boundary
	)

To end a sub tuple section previously started with http_request_start_tuple_sub_section().

Parameters

[in]	http_request	HTTP Request Handle to be used
[in]	sub_boundary	The sub boundary to be used for this tuple section.

Returns

MCL_OK in case of success.
MCL_OUT_OF_MEMORY in case there is not enough memory in the system to proceed.
MCL_HTTP_REQUEST_NO_MORE_SPACE in case http_request has no more space for adding new content.
MCL_FAIL in case of an internal error in MCL.

Definition at line 382 of file http_request.c.

References _add_boundary(), _resize_payload_buffer_if_necessary(), ASSERT_CODE_MESSAGE, BOUNDARY_LINE_LENGTH, string_t::buffer, DEBUG_ENTRY, DEBUG_LEAVE, MCL_CLOSE_BOUNDARY, MCL_FALSE, MCL_NULL_CHAR_SIZE, MCL_OK, http_request_t::payload, and http_request_t::payload_offset.

Referenced by _exchange_add_current_data_to_request_by_streaming().

Here is the call graph for this function:

Here is the caller graph for this function:

E_MCL_ERROR_CODE http_request_finalize ( http_request_t * http_request )

Adds closing boundary to the payload and resizes the payload buffer to release unused memory space.

Parameters

[in] http_request HTTP Request Handle to be used.

Returns

MCL_OK in case of success.
MCL_OUT_OF_MEMORY in case there is not enough memory in the system to proceed.
MCL_HTTP_REQUEST_NO_MORE_SPACE in case http_request has no more space for adding new content.
MCL_FAIL in case of an internal error in MCL.

Definition at line 469 of file http_request.c.

References _resize_payload_buffer_if_necessary(), ASSERT_CODE_MESSAGE, http_request_t::boundary, BOUNDARY_LENGTH, BOUNDARY_SIGN, BOUNDARY_SIGN_LENGTH, string_t::buffer, DEBUG_ENTRY, DEBUG_LEAVE, MCL_HTTP_REQUEST_FINALIZE_FAILED, MCL_OK, MCL_TRUE, http_request_t::payload, http_request_t::payload_offset, and string_util_memcpy().

Referenced by _exchange_finalize_http_request().

Here is the call graph for this function:

Here is the caller graph for this function:

mcl_size_t http_request_get_available_space_for_raw_data ( http_request_t * http_request )

To be used to get the available space left in the request buffer in order to add a raw data.

Differently than other get available space functions, this one doesn't calculate the overhead.

Parameters

[in] http_request HTTP Request Handle to be used.

Returns: Returns the available size.

Definition at line 438 of file http_request.c.

References _get_available_space(), DEBUG_ENTRY, and DEBUG_LEAVE.

Referenced by _exchange_add_current_data_to_request_by_streaming().

Here is the call graph for this function:

Here is the caller graph for this function:

mcl_size_t http_request_get_available_space_for_single ( http_request_t * http_request )

To be used to get the available space left in the request buffer in order to add a single.

Please refer to the MindConnect API Specification document for the detailed information on singles. Returns the free available space after deducting the necessary overhead for the single add operation.

Parameters

[in] http_request HTTP Request Handle to be used.

Returns: Returns the available size.

Definition at line 458 of file http_request.c.

References _get_available_space(), DEBUG_ENTRY, and DEBUG_LEAVE.

Here is the call graph for this function:

mcl_size_t http_request_get_available_space_for_tuple ( http_request_t * http_request )

To be used to get the available space left in the request buffer in order to add a tuple.

Please refer to the MindConnect API Specification document for the detailed information on tuples.

Parameters

[in] http_request HTTP Request Handle to be used.

Returns: Returns the free available space after deducting the necessary overhead for the tuple add operation.

Definition at line 448 of file http_request.c.

References _get_available_space(), DEBUG_ENTRY, DEBUG_LEAVE, and OVERHEAD_FOR_TUPLE.

Here is the call graph for this function:

E_MCL_ERROR_CODE http_request_initialize	(	E_MCL_HTTP_METHOD	method,
		string_t *	uri,
		mcl_size_t	header_size,
		mcl_size_t	payload_size,
		mcl_bool_t	resize_enabled,
		string_t *	user_agent,
		mcl_size_t	max_http_payload_size,
		http_request_t **	http_request
	)

HTTP Request Initializer.

Creates, initializes and returns a http_request_t. Owner is responsible of calling http_request_destroy() when the job is done.

Parameters

[in]	method	HTTP method for this request.
[in]	uri	HTTP Request URI. Should be started with the root.
[in]	header_size	Required memory space for the header string.
[in]	payload_size	Required memory space for the payload string.
[in]	resize_enabled	Indicates that the http_request should resize its buffer in case necessary. Give this as MCL_FALSE in case the buffer is static.
[in]	user_agent	Value of HTTP header User-Agent for this request.
[in]	max_http_payload_size	Maximum payload size for one http request.
[out]	http_request	The newly initialized HTTP request.

Returns

MCL_OK in case of success.
MCL_OUT_OF_MEMORY in case there is not enough memory in the system to proceed.
MCL_FAIL in case of an internal error in MCL.

Definition at line 79 of file http_request.c.

References _generate_random_boundary(), ASSERT_CODE_MESSAGE, ASSERT_STATEMENT_CODE_MESSAGE, DEBUG_ENTRY, DEBUG_LEAVE, http_header_names, HTTP_HEADER_USER_AGENT, http_request_add_header(), http_request_destroy(), MCL_FALSE, MCL_MALLOC, MCL_NEW, MCL_NULL, MCL_OK, MCL_OUT_OF_MEMORY, string_array_initialize(), and string_initialize().

Referenced by http_processor_exchange(), http_processor_get_access_token(), http_processor_register(), and http_processor_stream().

Here is the call graph for this function:

Here is the caller graph for this function:

E_MCL_ERROR_CODE http_request_start_tuple ( http_request_t * http_request )

To start a new tuple structure inside the http request body.

Caller should pay attention for the status of the http request body. It is the callers responsibility to maintain integrity.

Parameters

http_request HTTP Request Handle to be used.

Returns

MCL_OK in case of success.
MCL_OUT_OF_MEMORY in case there is not enough memory in the system to proceed.
MCL_HTTP_REQUEST_NO_MORE_SPACE in case http_request has no more space for adding new content.
MCL_FAIL in case of an internal error in MCL.

Definition at line 294 of file http_request.c.

References _add_boundary(), _resize_payload_buffer_if_necessary(), ASSERT_CODE_MESSAGE, http_request_t::boundary, string_t::buffer, DEBUG_ENTRY, DEBUG_LEAVE, MCL_FALSE, MCL_OK, MCL_OPEN_BOUNDARY, OVERHEAD_FOR_BOUNDARY, http_request_t::payload, and http_request_t::payload_offset.

Referenced by _exchange_add_current_data_to_request_by_streaming().

Here is the call graph for this function:

Here is the caller graph for this function:

E_MCL_ERROR_CODE http_request_start_tuple_sub_section	(	http_request_t *	http_request,
		string_t *	content_type,
		string_t *	content_id,
		string_t **	sub_boundary
	)

To start a sub tuple section inside of the http request body.

To accommodate tuple needs two sub sections must be started consequently. One is for meta and one is for payload. It is the callers responsibility to maintain integrity.

Parameters

[in]	http_request	HTTP Request Handle to be used.
[in]	content_type	HTTP Content Type header for this section of the tuple. Sample : "application/vnd.siemens.mindsphere.meta+json".
[in]	content_id	A unique random id.
[out]	sub_boundary	The sub boundary to be used for this tuple section. If a value for this param is not provided ( as NULL ), it will be created and returned to the caller to be used in consecutive calls.

Returns

MCL_OK in case of success.
MCL_OUT_OF_MEMORY in case there is not enough memory in the system to proceed.
MCL_HTTP_REQUEST_NO_MORE_SPACE in case http_request has no more space for adding new content.
MCL_FAIL in case of an internal error in MCL.

Definition at line 321 of file http_request.c.

References _add_blank_line(), _add_boundary(), _add_content_info(), _generate_random_boundary(), _resize_payload_buffer_if_necessary(), ASSERT_CODE_MESSAGE, string_t::buffer, CONTENT_TYPE_HEADER_LENGTH, CONTENT_TYPE_LINE_LENGTH, CONTENT_TYPE_MULTIPART_RELATED, content_type_values, DEBUG_ENTRY, DEBUG_LEAVE, HTTP_HEADER_CONTENT_TYPE, http_header_names, string_t::length, MCL_FALSE, MCL_NULL, MCL_OK, MCL_OPEN_BOUNDARY, NEW_LINE_LENGTH, http_request_t::payload, and http_request_t::payload_offset.

Referenced by _exchange_add_current_data_to_request_by_streaming().

Here is the call graph for this function:

Here is the caller graph for this function:

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation