HTTP Stream Reader

Data Structures
struct	M_http_reader_callbacks

Typedefs
typedef struct M_http_reader	M_http_reader_t
typedef M_http_error_t(*	M_http_reader_start_func) (M_http_message_type_t type, M_http_version_t version, M_http_method_t method, const char *uri, M_uint32 code, const char *reason, void *thunk)
typedef M_http_error_t(*	M_http_reader_header_full_func) (const char *key, const char *val, void *thunk)
typedef M_http_error_t(*	M_http_reader_header_func) (const char *key, const char *val, void *thunk)
typedef M_http_error_t(*	M_http_reader_header_done_func) (M_http_data_format_t format, void *thunk)
typedef M_http_error_t(*	M_http_reader_body_func) (const unsigned char *data, size_t len, void *thunk)
typedef M_http_error_t(*	M_http_reader_body_done_func) (void *thunk)
typedef M_http_error_t(*	M_http_reader_chunk_extensions_func) (const char *key, const char *val, size_t idx, void *thunk)
typedef M_http_error_t(*	M_http_reader_chunk_extensions_done_func) (size_t idx, void *thunk)
typedef M_http_error_t(*	M_http_reader_chunk_data_func) (const unsigned char *data, size_t len, size_t idx, void *thunk)
typedef M_http_error_t(*	M_http_reader_chunk_data_done_func) (size_t idx, void *thunk)
typedef M_http_error_t(*	M_http_reader_chunk_data_finished_func) (void *thunk)
typedef M_http_error_t(*	M_http_reader_multipart_preamble_func) (const unsigned char *data, size_t len, void *thunk)
typedef M_http_error_t(*	M_http_reader_multipart_preamble_done_func) (void *thunk)
typedef M_http_error_t(*	M_http_reader_multipart_header_full_func) (const char *key, const char *val, size_t idx, void *thunk)
typedef M_http_error_t(*	M_http_reader_multipart_header_func) (const char *key, const char *val, size_t idx, void *thunk)
typedef M_http_error_t(*	M_http_reader_multipart_header_done_func) (size_t idx, void *thunk)
typedef M_http_error_t(*	M_http_reader_multipart_data_func) (const unsigned char *data, size_t len, size_t idx, void *thunk)
typedef M_http_error_t(*	M_http_reader_multipart_data_done_func) (size_t idx, void *thunk)
typedef M_http_error_t(*	M_http_reader_multipart_data_finished_func) (void *thunk)
typedef M_http_error_t(*	M_http_reader_multipart_epilouge_func) (const unsigned char *data, size_t len, void *thunk)
typedef M_http_error_t(*	M_http_reader_multipart_epilouge_done_func) (void *thunk)
typedef M_http_error_t(*	M_http_reader_trailer_full_func) (const char *key, const char *val, void *thunk)
typedef M_http_error_t(*	M_http_reader_trailer_func) (const char *key, const char *val, void *thunk)
typedef M_http_error_t(*	M_http_reader_trailer_done_func) (void *thunk)

Enumerations
enum	M_http_reader_flags_t {   M_HTTP_READER_NONE = 0 ,   M_HTTP_READER_SKIP_START }

Functions
M_http_reader_t *	M_http_reader_create (struct M_http_reader_callbacks *cbs, M_uint32 flags, void *thunk)
void	M_http_reader_destroy (M_http_reader_t *httpr)
M_http_error_t	M_http_reader_read (M_http_reader_t *httpr, const unsigned char *data, size_t data_len, size_t *len_read)

Detailed Description

Stream reader used for parsing using callbacks. Very useful for large HTTP messages.

---

Data Structure Documentation

M_http_reader_callbacks

struct M_http_reader_callbacks

Callbacks for various stages of parsing.

Data Fields
M_http_reader_start_func	start_func
M_http_reader_header_full_func	header_full_func
M_http_reader_header_func	header_func
M_http_reader_header_done_func	header_done_func
M_http_reader_body_func	body_func
M_http_reader_body_done_func	body_done_func
M_http_reader_chunk_extensions_func	chunk_extensions_func
M_http_reader_chunk_extensions_done_func	chunk_extensions_done_func
M_http_reader_chunk_data_func	chunk_data_func
M_http_reader_chunk_data_done_func	chunk_data_done_func
M_http_reader_chunk_data_finished_func	chunk_data_finished_func
M_http_reader_multipart_preamble_func	multipart_preamble_func
M_http_reader_multipart_preamble_done_func	multipart_preamble_done_func
M_http_reader_multipart_header_full_func	multipart_header_full_func
M_http_reader_multipart_header_func	multipart_header_func
M_http_reader_multipart_header_done_func	multipart_header_done_func
M_http_reader_multipart_data_func	multipart_data_func
M_http_reader_multipart_data_done_func	multipart_data_done_func
M_http_reader_multipart_data_finished_func	multipart_data_finished_func
M_http_reader_multipart_epilouge_func	multipart_epilouge_func
M_http_reader_multipart_epilouge_done_func	multipart_epilouge_done_func
M_http_reader_trailer_full_func	trailer_full_func
M_http_reader_trailer_func	trailer_func
M_http_reader_trailer_done_func	trailer_done_func

Typedef Documentation

M_http_reader_t

typedef struct M_http_reader M_http_reader_t

M_http_reader_start_func

typedef M_http_error_t(* M_http_reader_start_func) (M_http_message_type_t type, M_http_version_t version, M_http_method_t method, const char *uri, M_uint32 code, const char *reason, void *thunk)

Function definition for the start line.

Parameters

[in]	type	Type of message.
[in]	version	HTTP version.
[in]	method	If request, method of request.
[in]	uri	If request, uri requested.
[in]	code	If response, numeric response code.
[in]	reason	If response, response reason.
[in]	thunk	Thunk.

Returns

Result

M_http_reader_header_full_func

typedef M_http_error_t(* M_http_reader_header_full_func) (const char *key, const char *val, void *thunk)

Function definition for reading full headers.

This will provide the full unparsed header. This is always called for every header. It may be called multiple times if a header appears multiple times. This is intended for informational use or if passing along data and not altering any headers in the process.

A header appearing multiple times here means it was present multiple times.

Parameters

[in]	key	Header key.
[in]	val	Header value.
[in]	thunk	Thunk.

Returns

Result

See also

M_http_reader_header_func

M_http_reader_header_func

typedef M_http_error_t(* M_http_reader_header_func) (const char *key, const char *val, void *thunk)

Function definition for reading headers as component parts.

This is the main header reading callback that should be used when parsing a message.

Headers are split if a header list. Keys will appear multiple times if values were in a list or if the header appears multiple times. The standard uses ',' as a list separator but some headers will use a semicolon ';'. Values with semicolon ';' separated parameters are split as well.

Will be called for headers that have a single part and are not split.

It is not possible to determine if a header was present multiple times vs being in list form.

Parameters

[in]	key	Header key.
[in]	val	Header value.
[in]	thunk	Thunk.

Returns

Result

See also

M_http_reader_header_full_func

M_http_reader_header_done_func

typedef M_http_error_t(* M_http_reader_header_done_func) (M_http_data_format_t format, void *thunk)

Function definition for header parsing completion.

Parameters

[in]	format	The format data was sent using.
[in]	thunk	Thunk.

Returns

Result

M_http_reader_body_func

typedef M_http_error_t(* M_http_reader_body_func) (const unsigned char *data, size_t len, void *thunk)

Function definition for reading body data.

Parameters

[in]	data	Data.
[in]	len	Length of data.
[in]	thunk	Thunk.

Returns

Result

M_http_reader_body_done_func

typedef M_http_error_t(* M_http_reader_body_done_func) (void *thunk)

Function definition for completion of body parsing.

This will only be called if the Content-Length header was specified.

Parameters

[in]

thunk

Thunk.

Returns

Result

M_http_reader_chunk_extensions_func

typedef M_http_error_t(* M_http_reader_chunk_extensions_func) (const char *key, const char *val, size_t idx, void *thunk)

Function definition for reading chunk extensions.

Extensions are not required to have values.

Parameters

[in]	key	Key.
[in]	val	Value.
[in]	idx	Chunk number the extension belongs to.
[in]	thunk	Thunk.

Returns

Result

M_http_reader_chunk_extensions_done_func

typedef M_http_error_t(* M_http_reader_chunk_extensions_done_func) (size_t idx, void *thunk)

Function definition for completion of chunk extension parsing.

Will only be called if there were chunk extensions.

Parameters

[in]	idx	Chunk number that had extensions.
[in]	thunk	Thunk.

Returns

Result

M_http_reader_chunk_data_func

typedef M_http_error_t(* M_http_reader_chunk_data_func) (const unsigned char *data, size_t len, size_t idx, void *thunk)

Function definition for reading chunk data.

Parameters

[in]	data	Data.
[in]	len	Length of data.
[in]	idx	Chunk number the data belongs to.
[in]	thunk	Thunk.

Returns

Result

M_http_reader_chunk_data_done_func

typedef M_http_error_t(* M_http_reader_chunk_data_done_func) (size_t idx, void *thunk)

Function definition for completion of chunk data.

Parameters

[in]	idx	Chunk number that has been completely processed.
[in]	thunk	Thunk.

Returns

Result

M_http_reader_chunk_data_finished_func

typedef M_http_error_t(* M_http_reader_chunk_data_finished_func) (void *thunk)

Function definition for completion of parsing all chunks.

Only called when data is chunked.

Parameters

[in]

thunk

Thunk.

Returns

Result

M_http_reader_multipart_preamble_func

typedef M_http_error_t(* M_http_reader_multipart_preamble_func) (const unsigned char *data, size_t len, void *thunk)

Function definition for reading multipart preamble.

Typically the preamble should be ignored if present.

Parameters

[in]	data	Data.
[in]	len	Length of data.
[in]	thunk	Thunk.

Returns

Result

M_http_reader_multipart_preamble_done_func

typedef M_http_error_t(* M_http_reader_multipart_preamble_done_func) (void *thunk)

Function definition for completion of multipart preamble parsing.

Only called if a preamble was present.

Parameters

[in]

thunk

Thunk.

Returns

Result

M_http_reader_multipart_header_full_func

typedef M_http_error_t(* M_http_reader_multipart_header_full_func) (const char *key, const char *val, size_t idx, void *thunk)

Function definition for reading full multi part headers.

This will provide the full unparsed header. This is always called for every header. It may be called multiple times if a header appears multiple times. This is intended for informational use or if passing along data and not altering any headers in the process.

A header appearing multiple times here means it was present multiple times.

Parameters

[in]	key	Header key.
[in]	val	Header value.
[in]	idx	Part number the header belongs to.
[in]	thunk	Thunk.

Returns

Result

See also

M_http_reader_header_func

M_http_reader_multipart_header_func

typedef M_http_error_t(* M_http_reader_multipart_header_func) (const char *key, const char *val, size_t idx, void *thunk)

Function definition for reading multipart part headers.

This is the main multi part header reading callback that should be used when parsing a message.

Headers are split if a header list. Keys will appear multiple times if values were in a list or if the header appears multiple times. The standard uses ',' as a list separator but some headers will use a semicolon ';'. Values with semicolon ';' separated parameters are split as well.

Will be called for headers that have a single part and are not split.

It is not possible to determine if a header was present multiple times vs being in list form.

Parameters

[in]	key	Key.
[in]	val	Value.
[in]	idx	Part number the header belongs to.
[in]	thunk	Thunk.

Returns

Result

M_http_reader_multipart_header_done_func

typedef M_http_error_t(* M_http_reader_multipart_header_done_func) (size_t idx, void *thunk)

Function definition for completion of multipart part header parsing.

Parameters

[in]	idx	Part number.
[in]	thunk	Thunk.

Returns

Result

M_http_reader_multipart_data_func

typedef M_http_error_t(* M_http_reader_multipart_data_func) (const unsigned char *data, size_t len, size_t idx, void *thunk)

Function definition for reading multipart part data.

Parameters

[in]	data	Data.
[in]	len	Length of data.
[in]	idx	Partnumber the data belongs to.
[in]	thunk	Thunk.

Returns

Result

M_http_reader_multipart_data_done_func

typedef M_http_error_t(* M_http_reader_multipart_data_done_func) (size_t idx, void *thunk)

Function definition for completion of multipart part data.

Parameters

[in]	idx	Chunk number that has been completely processed.
[in]	thunk	Thunk.

Returns

Result

M_http_reader_multipart_data_finished_func

typedef M_http_error_t(* M_http_reader_multipart_data_finished_func) (void *thunk)

Function definition for completion of parsing all multipart parts.

Only called when data is chunked.

Parameters

[in]

thunk

Thunk.

Returns

Result

M_http_reader_multipart_epilouge_func

typedef M_http_error_t(* M_http_reader_multipart_epilouge_func) (const unsigned char *data, size_t len, void *thunk)

Function definition for reading multipart epilogue.

Typically the epilogue should be ignored if present.

Parameters

[in]	data	Data.
[in]	len	Length of data.
[in]	thunk	Thunk.

Returns

Result

M_http_reader_multipart_epilouge_done_func

typedef M_http_error_t(* M_http_reader_multipart_epilouge_done_func) (void *thunk)

Function definition for completion of multipart epilogue parsing.

Only called if a epilogue was present.

Parameters

[in]

thunk

Thunk.

Returns

Result

M_http_reader_trailer_full_func

typedef M_http_error_t(* M_http_reader_trailer_full_func) (const char *key, const char *val, void *thunk)

Function definition for reading full trailer headers.

This will provide the full unparsed header. This is always called for every trailer header. It may be called multiple times if a header appears multiple times. This is intended for informational use or if passing along data and not altering any headers in the process.

A header appearing multiple times here means it was present multiple times.

Parameters

[in]	key	Header key.
[in]	val	Header value.
[in]	thunk	Thunk.

Returns

Result

See also

M_http_reader_header_func

M_http_reader_trailer_func

typedef M_http_error_t(* M_http_reader_trailer_func) (const char *key, const char *val, void *thunk)

Function definition for reading trailing headers.

This is the main trailer header reading callback that should be used when parsing a message.

Headers are split if a header list. Keys will appear multiple times if values were in a list or if the header appears multiple times. The standard uses ',' as a list separator but some headers will use a semicolon ';'. Values with semicolon ';' separated parameters are split as well.

Will be called for headers that have a single part and are not split.

It is not possible to determine if a header was present multiple times vs being in list form.

Parameters

[in]	key	Header key.
[in]	val	Header value.
[in]	thunk	Thunk.

Returns

Result

M_http_reader_trailer_done_func

typedef M_http_error_t(* M_http_reader_trailer_done_func) (void *thunk)

Function definition for trailing header parsing completion.

Only called if trailing headers were present.

Parameters

[in]

thunk

Thunk.

Returns

Result

Enumeration Type Documentation

M_http_reader_flags_t

enum M_http_reader_flags_t

Flags controlling reader behavior.

Enumerator
M_HTTP_READER_NONE	Default operation.
M_HTTP_READER_SKIP_START	Skip parsing start line. Data starts with headers.

Function Documentation

M_http_reader_create()

M_http_reader_t * M_http_reader_create	(	struct M_http_reader_callbacks *	cbs,
		M_uint32	flags,
		void *	thunk
	)

Create an http reader object.

Parameters

[in]	cbs	Callbacks for processing.
[in]	flags	Flags controlling behavior.
[in]	thunk	Thunk passed to callbacks.

Returns

Object.

M_http_reader_destroy()

void M_http_reader_destroy

(

M_http_reader_t *

httpr

)

Destroy an http object.

Parameters

[in]

httpr

Http reader object.

M_http_reader_read()

M_http_error_t M_http_reader_read	(	M_http_reader_t *	httpr,
		const unsigned char *	data,
		size_t	data_len,
		size_t *	len_read
	)

Parse http message from given data.

M_HTTP_ERROR_SUCCESS, and M_HTTP_ERROR_SUCCESS_MORE_POSSIBLE are both Success conditions. Data is valid and has been parsed. Remaining unread data in the buffer on M_HTTP_ERROR_SUCCESS indicates a possible additional message.

M_HTTP_ERROR_MOREDATA indicates valid data but an incomplete message. The parse should be run again starting where the last parse stopped. Until a known or possible full parse has completed.

The reader can only be used once per complete message.

Parameters

[in]	httpr	Http reader object.
[in]	data	Data to parse.
[in]	data_len	Length of data.
[out]	len_read	How much data was read.

Returns

Result.