HTTP/2 Client API. More...

Collaboration diagram for HTTP/2 Client:

Files
file	httpstd.c

file	httpstd.h
	Standard Definitions for HTTP Status Codes, Content Type and Fields.

Data Structures
struct	HTTP2Cli_Struct

struct	HTTP2Cli_Error
	HTTP/2 Error object. More...

struct	HTTP2Cli_Params
	HTTP/2 client instance config parameters. More...

Typedefs
typedef struct HTTP2Cli_Struct	HTTP2Cli_Struct
	HTTP/2 client object type. More...

typedef HTTP2Cli_Struct *	HTTP2Cli_Handle
	HTTP/2 client instance type. More...

typedef void(*	HTTP2Cli_responseDataFxn) (HTTP2Cli_Handle cli, uint32_t arg, uint32_t streamId, uint8_t *data, uint32_t len, bool endStream)
	HTTP2Cli callback function for handling data. More...

typedef void(*	HTTP2Cli_responseHeadersFxn) (HTTP2Cli_Handle cli, uint32_t arg, uint32_t streamId, uint16_t status, HTTP2Hdr_Field *headersList, uint32_t len, bool endStream)
	HTTP2Cli callback function for handling headers. More...

typedef struct HTTP2Cli_Error	HTTP2Cli_Error
	HTTP/2 Error object. More...

typedef struct HTTP2Cli_Params	HTTP2Cli_Params
	HTTP/2 client instance config parameters. More...

Functions
int	HTTP2Cli_connect (HTTP2Cli_Handle cli, const struct sockaddr *addr, int flags)
	Connect to the HTTP/2 Server. More...

void	HTTP2Cli_construct (HTTP2Cli_Struct cli, const HTTP2Cli_Params params)
	Initialize a new instance object inside the provided structure. More...

HTTP2Cli_Handle	HTTP2Cli_create (const HTTP2Cli_Params *params)
	Allocate and initialize a new instance object, and return it's handle. More...

void	HTTP2Cli_delete (HTTP2Cli_Handle *cli)
	Destroy and free this previously allocated instance object, and set the reference handle to NULL. More...

void	HTTP2Cli_destruct (HTTP2Cli_Struct *cli)
	Destroy the instance object inside the provided structure. More...

void	HTTP2Cli_disconnect (HTTP2Cli_Handle cli)
	Disconnect from the HTTP/2 server. More...

int	HTTP2Cli_getSocketError (HTTP2Cli_Handle cli)
	Get the error code from the socket/TLS layer. More...

int	HTTP2Cli_initSockAddr (const char uri, bool ipv6, struct sockaddr addr)
	Initialize the socket address structure for the given URI. More...

void	HTTP2Cli_Params_init (HTTP2Cli_Params *params)
	Initialize the config params with default values. More...

int	HTTP2Cli_processResponse (HTTP2Cli_Handle cli, uint32_t timeout_ms, HTTP2Cli_Error *error)
	Process the response from HTTP/2 server. More...

int	HTTP2Cli_sendRequest (HTTP2Cli_Handle cli, const char method, const char uri, HTTP2Hdr_Field additionalHeaders, uint8_t headersLen, uint8_t data, uint32_t dataLen, uint32_t *streamId)
	Make an HTTP/2 request to the server. More...

int	HTTP2Cli_sendRequestHeaders (HTTP2Cli_Handle cli, const char method, const char uri, HTTP2Hdr_Field additionalHeaders, uint8_t headersLen, bool endStream, uint32_t streamId)
	Send HTTP/2 request headers to the server. More...

int	HTTP2Cli_sendRequestData (HTTP2Cli_Handle cli, uint32_t streamId, uint8_t data, uint32_t dataLen, bool endStream)
	Send HTTP/2 data to the server. More...

int	HTTP2Cli_getSocket (HTTP2Cli_Handle cli)
	Get the handle to the underlying socket. More...

int	HTTP2Cli_sendPing (HTTP2Cli_Handle cli)
	Send a HTTP/2 PING to the HTTP/2 server. More...

HTTP/2 client Error Codes
#define	HTTP2Cli_ESOCKETFAIL (-101)
	Socket create failed. More...

#define	HTTP2Cli_ECONNECTFAIL (-102)
	TCP connection to the server failed. More...

#define	HTTP2Cli_ESENDFAIL (-103)
	Cannot send data to the server. More...

#define	HTTP2Cli_ERECVFAIL (-104)
	Cannot recieve data to the server. More...

#define	HTTP2Cli_ERECVTIMEOUT (-105)
	TCP connection timed out when waiting for data to arrive. More...

#define	HTTP2Cli_ETLSFAIL (-106)
	Failed to configure the socket with TLS parameters. More...

#define	HTTP2Cli_ESTREAMID (-107)
	No streams available on this connection. Close this connection and open a new connection. More...

#define	HTTP2Cli_EINSUFFICIENTHEAP (-108)
	Memory allocation failed due to insufficient system heap. More...

#define	HTTP2Cli_EPROTOCOL (-109)
	HTTP/2 protocol error caused by the server. Close this connection. More...

#define	HTTP2Cli_EFRAMESIZE (-110)
	HTTP/2 frame size error caused by the server. Close this connection. More...

#define	HTTP2Cli_EHEADERSLISTTOOBIG (-111)
	The size of headers is too big than the size that the server is ready to accept. More...

#define	HTTP2Cli_ERSTSTREAMRECV (-112)
	The server sent a RST Stream. Check HTTP2Cli_Error for error code. More...

#define	HTTP2Cli_EGOAWAYRECV (-113)
	The server sent a GO AWAY. Check HTTP2Cli_Error for error code. More...

#define	HTTP2Cli_EINVALIDREQUESTPARAMS (-114)
	Invalid request parameters input. More...

#define	HTTP2Cli_EHOSTNAMERESOLVE (-115)

#define	HTTP2Cli_EPINGPAYLOAD (-116)

Detailed Description

HTTP/2 Client API.

This module provides an HTTP client implementation of IETF standard for HTTP/2 - RFC 7540.

Macro Definition Documentation

§ HTTP2Cli_ESOCKETFAIL

#define HTTP2Cli_ESOCKETFAIL (-101)

Socket create failed.

See also: HTTP2Cli_getSocketError()

§ HTTP2Cli_ECONNECTFAIL

#define HTTP2Cli_ECONNECTFAIL (-102)

TCP connection to the server failed.

See also: HTTP2Cli_getSocketError()

§ HTTP2Cli_ESENDFAIL

#define HTTP2Cli_ESENDFAIL (-103)

Cannot send data to the server.

See also: HTTP2Cli_getSocketError()

§ HTTP2Cli_ERECVFAIL

#define HTTP2Cli_ERECVFAIL (-104)

Cannot recieve data to the server.

See also: HTTP2Cli_getSocketError()

§ HTTP2Cli_ERECVTIMEOUT

#define HTTP2Cli_ERECVTIMEOUT (-105)

TCP connection timed out when waiting for data to arrive.

§ HTTP2Cli_ETLSFAIL

#define HTTP2Cli_ETLSFAIL (-106)

Failed to configure the socket with TLS parameters.

See also: HTTP2Cli_getSocketError()

§ HTTP2Cli_ESTREAMID

#define HTTP2Cli_ESTREAMID (-107)

No streams available on this connection. Close this connection and open a new connection.

§ HTTP2Cli_EINSUFFICIENTHEAP

#define HTTP2Cli_EINSUFFICIENTHEAP (-108)

Memory allocation failed due to insufficient system heap.

§ HTTP2Cli_EPROTOCOL

#define HTTP2Cli_EPROTOCOL (-109)

HTTP/2 protocol error caused by the server. Close this connection.

§ HTTP2Cli_EFRAMESIZE

#define HTTP2Cli_EFRAMESIZE (-110)

HTTP/2 frame size error caused by the server. Close this connection.

§ HTTP2Cli_EHEADERSLISTTOOBIG

#define HTTP2Cli_EHEADERSLISTTOOBIG (-111)

The size of headers is too big than the size that the server is ready to accept.

§ HTTP2Cli_ERSTSTREAMRECV

#define HTTP2Cli_ERSTSTREAMRECV (-112)

The server sent a RST Stream. Check HTTP2Cli_Error for error code.

§ HTTP2Cli_EGOAWAYRECV

#define HTTP2Cli_EGOAWAYRECV (-113)

The server sent a GO AWAY. Check HTTP2Cli_Error for error code.

§ HTTP2Cli_EINVALIDREQUESTPARAMS

#define HTTP2Cli_EINVALIDREQUESTPARAMS (-114)

Invalid request parameters input.

§ HTTP2Cli_EHOSTNAMERESOLVE

#define HTTP2Cli_EHOSTNAMERESOLVE (-115)

§ HTTP2Cli_EPINGPAYLOAD

#define HTTP2Cli_EPINGPAYLOAD (-116)

Typedef Documentation

§ HTTP2Cli_Struct

typedef struct HTTP2Cli_Struct HTTP2Cli_Struct

HTTP/2 client object type.

§ HTTP2Cli_Handle

typedef HTTP2Cli_Struct* HTTP2Cli_Handle

HTTP/2 client instance type.

§ HTTP2Cli_responseDataFxn

typedef void(* HTTP2Cli_responseDataFxn) (HTTP2Cli_Handle cli, uint32_t arg, uint32_t streamId, uint8_t *data, uint32_t len, bool endStream)

HTTP2Cli callback function for handling data.

The HTTP2Cli_processResponse() function calls the registered data callback function when a data frame arrives from the HTTP/2 server. This function is called repeatedly till the end of data from the stream which is indicated by the endStream flag. The streamId can be used to match the request and the response.

Parameters

[in]	cli	Instance of the HTTP connection
[in]	arg	User supplied argument
[in]	streamId	Stream ID of the response
[in]	data	Response data buffer
[in]	dataLen	Length of the `data` buffer
[in]	endStream	Set if there is no more data in the stream

§ HTTP2Cli_responseHeadersFxn

typedef void(* HTTP2Cli_responseHeadersFxn) (HTTP2Cli_Handle cli, uint32_t arg, uint32_t streamId, uint16_t status, HTTP2Hdr_Field *headersList, uint32_t len, bool endStream)

HTTP2Cli callback function for handling headers.

The HTTP2Cli_processResponse() function calls the registered header callback function when a header frame arrives from the HTTP/2 server. This function is called repeatedly till the end of headers from the stream. If no data frames follow headers, the endStream flag will be set. The streamId can be used to match the request and the response.

Parameters

[in]	cli	Instance of the HTTP connection
[in]	arg	User supplied argument
[in]	streamId	Stream ID of the response
[in]	status	HTTP/2 response status code
[in]	headersList	List of HTTP/2 response headers
[in]	len	Length of the `headersList`
[in]	endStream	Set if there is no more data in the stream

§ HTTP2Cli_Error

typedef struct HTTP2Cli_Error HTTP2Cli_Error

HTTP/2 Error object.

§ HTTP2Cli_Params

typedef struct HTTP2Cli_Params HTTP2Cli_Params

HTTP/2 client instance config parameters.

Function Documentation

§ HTTP2Cli_connect()

int HTTP2Cli_connect	(	HTTP2Cli_Handle	cli,
		const struct sockaddr *	addr,
		int	flags
	)

Connect to the HTTP/2 Server.

Creates a secure TCP connection to the HTTP/2 Server and exchanges the HTTP/2 connection preface and settings.

Parameters

[in]	cli	Instance of an HTTP/2 client object
[in]	addr	IP address of the server
[in]	flags	Reserved for future use

Returns: 0 on success or error code on failure

§ HTTP2Cli_construct()

void HTTP2Cli_construct	(	HTTP2Cli_Struct *	cli,
		const HTTP2Cli_Params *	params
	)

Initialize a new instance object inside the provided structure.

Parameters

[in]	cli	Pointer to HTTP2Cli_Struct
[in]	params	Per-instance config parameters

§ HTTP2Cli_create()

HTTP2Cli_Handle HTTP2Cli_create ( const HTTP2Cli_Params * params )

Allocate and initialize a new instance object, and return it's handle.

Parameters

[in] params Per-instance config parameters

Returns: A new HTTP/2 client instance on success or NULL on failure

§ HTTP2Cli_delete()

void HTTP2Cli_delete ( HTTP2Cli_Handle * cli )

Destroy and free this previously allocated instance object, and set the reference handle to NULL.

Parameters

[in] cli Pointer to an HTTP/2 client instance

§ HTTP2Cli_destruct()

void HTTP2Cli_destruct ( HTTP2Cli_Struct * cli )

Destroy the instance object inside the provided structure.

Parameters

[in] cli Pointer to HTTP2Cli_Struct

§ HTTP2Cli_disconnect()

void HTTP2Cli_disconnect ( HTTP2Cli_Handle cli )

Disconnect from the HTTP/2 server.

Closes the secure TCP connection to the HTTP/2 server and destroys the HTTP/2 client instance object.

Parameters

[in] cli Instance of an HTTP/2 client object

§ HTTP2Cli_getSocketError()

int HTTP2Cli_getSocketError ( HTTP2Cli_Handle cli )

Get the error code from the socket/TLS layer.

This function can be used to get the underlying socket/TLS layer error code when the other HTTP2Cli APIs fail with connect/send/recv/tls errors.

Parameters

[in] cli Instance of an HTTP/2 client object

Returns: Error code from the socket/TLS layer or 0 when no error occured

§ HTTP2Cli_initSockAddr()

int HTTP2Cli_initSockAddr	(	const char *	uri,
		bool	ipv6,
		struct sockaddr *	addr
	)

Initialize the socket address structure for the given URI.

The supported URI format is:

[https://]host_name[:port_number][/request_uri]

For cases where port is not provided, the default port number is set.

Parameters

[in]	uri	A null terminated URI string
[in]	ipv6	Set if IPv6 address has to be retrieved for the given URI
[out]	addr	Pointer to the sockaddr structure to be filled with IP information.

Returns: 0 on success or error code on failure.

§ HTTP2Cli_Params_init()

void HTTP2Cli_Params_init ( HTTP2Cli_Params * params )

Initialize the config params with default values.

Parameters

[in] params Pointer to HTTP2Cli_Params

§ HTTP2Cli_processResponse()

int HTTP2Cli_processResponse	(	HTTP2Cli_Handle	cli,
		uint32_t	timeout_ms,
		HTTP2Cli_Error *	error
	)

Process the response from HTTP/2 server.

This function has to be called periodically to process the response/request from the server. The headers and data frames are processed and passed to to user supplied callback functions. The other frames are processed and appropriate response/ack are sent to the HTTP/2 server.

Remarks: It is important to call this function periodically as ack/pings have to be responded to within a resonable time.

Parameters

[in]	cli	Instance of an HTTP/2 client object
[in]	timeout_ms	Max time (in millisecs) allowed for function to return
[out]	error	Stream Id and error code returned by the server for stream errors (HTTP2Cli_ERSTSTREAMRECV) and connection errors (HTTP2Cli_EGOAWAYRECV) will be set in this object.

Returns: The received HTTP/2 frame type on success, or an error code on failure

§ HTTP2Cli_sendRequest()

int HTTP2Cli_sendRequest	(	HTTP2Cli_Handle	cli,
		const char *	method,
		const char *	uri,
		HTTP2Hdr_Field *	additionalHeaders,
		uint8_t	headersLen,
		uint8_t *	data,
		uint32_t	dataLen,
		uint32_t *	streamId
	)

Make an HTTP/2 request to the server.

Creates an HTTP/2 request based on the arguments: HTTP/2 method, URI, optional additional headers and optional data, and sends it to the HTTP/2 server.

This function by default sets-up ":method", ":path", ":scheme" and ":authority" headers for HTTP/2 request. Any additional headers can be sent through this function.

A stream is created for the HTTP/2 request and the ID will be returned in streamId. This ID can be used to determine the response for this request.

Parameters

[in]	cli	Instance of the HTTP/2 client object
[in]	method	HTTP/2 method (for ex: HTTPStd_GET)
[in]	uri	A NULL terminated URI string with format [https://]host_name[:port][/request_uri]
[in]	additionalHeaders	(Optional) Additional headers apart from the headers described above
[in]	headersLen	Length of the `additionalHeaders` array
[in]	data	(Optional) Application data
[in]	dataLen	Length of `data` buffer
[out]	streamId	An ID will be set for the stream created

Returns: 0 on success or an error code on failure

§ HTTP2Cli_sendRequestHeaders()

int HTTP2Cli_sendRequestHeaders	(	HTTP2Cli_Handle	cli,
		const char *	method,
		const char *	uri,
		HTTP2Hdr_Field *	additionalHeaders,
		uint8_t	headersLen,
		bool	endStream,
		uint32_t *	streamId
	)

Send HTTP/2 request headers to the server.

Creates an HTTP/2 request based on the arguments: HTTP/2 method, URI, and optional additional headers, and sends it to the HTTP/2 server.

This function is similar to HTTP2Cli_sendRequest() with the exception that only headers are sent to the server. It can be followed by a call to HTTP2Cli_sendRequestData() to send data if any.

This function by default sets-up ":method", ":path", ":scheme" and ":authority" headers for HTTP/2 request. Any additional headers can be sent through it.

A stream is created for the HTTP/2 request and the ID will be returned in streamId. This ID can be used to determine the response for this request.

Parameters

[in]	cli	Instance of the HTTP/2 client object
[in]	method	HTTP/2 method (for ex: HTTPStd_GET)
[in]	uri	A NULL terminated URI string with format [https://]host_name[:port][/request_uri]
[in]	additionalHeaders	(Optional) Additional headers apart from the headers described above
[in]	headersLen	Length of the `additionalHeaders` array
[in]	endStream	Set this to `true` if there is no data to send to the server.
[out]	streamId	An ID will be set for the stream created

Returns: 0 on success or an error code on failure

§ HTTP2Cli_sendRequestData()

int HTTP2Cli_sendRequestData	(	HTTP2Cli_Handle	cli,
		uint32_t *	streamId,
		uint8_t *	data,
		uint32_t	dataLen,
		bool	endStream
	)

Send HTTP/2 data to the server.

This function sends the input data in HTTP/2 data frames to the server. It can be called multiple times with the last data to be indicated by setting the 'endStream' flag.

Remarks: This function should be called only after a call to HTTP2Cli_sendRequestHeaders().

Parameters

[in]	cli	Instance of the HTTP/2 client object
[in]	streamId	Stream Id received from HTTP2Cli_sendRequestHeaders()
[in]	data	Application data
[in]	dataLen	Length of `data` buffer
[in]	endStream	Set this to `true` when sending the last data

Returns: 0 on success or an error code on failure

§ HTTP2Cli_getSocket()

int HTTP2Cli_getSocket ( HTTP2Cli_Handle cli )

Get the handle to the underlying socket.

Remarks: The socket handle should be only used for select(). Any other usage of this handle will result unknown HTTP/2 failures.

Parameters

[in] cli Instance of the HTTP/2 client object

Returns: Socket handle on success or 0 when socket is not created

§ HTTP2Cli_sendPing()

int HTTP2Cli_sendPing ( HTTP2Cli_Handle cli )

Send a HTTP/2 PING to the HTTP/2 server.

Remarks: The application should call HTTP2Cli_processResponse() to check for PING response from the server and it is responsible for timing the PING request.

Parameters

[in] cli Instance of the HTTP/2 client object

Returns: 0 on success or an error code on failure

Files

Data Structures

Typedefs

Functions

HTTP/2 client Error Codes

Detailed Description

Macro Definition Documentation

§ HTTP2Cli_ESOCKETFAIL

§ HTTP2Cli_ECONNECTFAIL

§ HTTP2Cli_ESENDFAIL

§ HTTP2Cli_ERECVFAIL

§ HTTP2Cli_ERECVTIMEOUT

§ HTTP2Cli_ETLSFAIL

§ HTTP2Cli_ESTREAMID

§ HTTP2Cli_EINSUFFICIENTHEAP

§ HTTP2Cli_EPROTOCOL

§ HTTP2Cli_EFRAMESIZE

§ HTTP2Cli_EHEADERSLISTTOOBIG

§ HTTP2Cli_ERSTSTREAMRECV

§ HTTP2Cli_EGOAWAYRECV

§ HTTP2Cli_EINVALIDREQUESTPARAMS

§ HTTP2Cli_EHOSTNAMERESOLVE

§ HTTP2Cli_EPINGPAYLOAD

Typedef Documentation

§ HTTP2Cli_Struct

§ HTTP2Cli_Handle

§ HTTP2Cli_responseDataFxn

§ HTTP2Cli_responseHeadersFxn

§ HTTP2Cli_Error

§ HTTP2Cli_Params

Function Documentation

§ HTTP2Cli_connect()

§ HTTP2Cli_construct()

§ HTTP2Cli_create()

§ HTTP2Cli_delete()

§ HTTP2Cli_destruct()

§ HTTP2Cli_disconnect()

§ HTTP2Cli_getSocketError()

§ HTTP2Cli_initSockAddr()

§ HTTP2Cli_Params_init()

§ HTTP2Cli_processResponse()

§ HTTP2Cli_sendRequest()

§ HTTP2Cli_sendRequestHeaders()

§ HTTP2Cli_sendRequestData()

§ HTTP2Cli_getSocket()

§ HTTP2Cli_sendPing()