#include "esp_tls.h"
#include <nghttp2/nghttp2.h>

Classes
struct	sh2lib_handle
	Handle for working with sh2lib APIs. More...

struct	sh2lib_callbacks

Macros
#define	DATA_RECV_RST_STREAM 1

#define	DATA_RECV_FRAME_COMPLETE 2

#define	SH2LIB_MAKE_NV(NAME, VALUE, FLAGS)

Typedefs
typedef int(*	sh2lib_frame_data_header_cb_t) (struct sh2lib_handle handle, const char name, size_t namelen, const char *value, size_t valuelen, int flags)
	Function Prototype for data receive callback. More...

typedef int(*	sh2lib_frame_data_recv_cb_t) (struct sh2lib_handle handle, const char data, size_t len, int flags)

typedef int(*	sh2lib_putpost_data_cb_t) (struct sh2lib_handle handle, char data, size_t len, uint32_t *data_flags)
	Function Prototype for callback to send data in PUT/POST. More...

Functions
int	sh2lib_connect (struct sh2lib_handle hd, const char uri, mbedtls_x509_crt *cacerts)
	Connect to a URI using HTTP/2. More...

void	sh2lib_free (struct sh2lib_handle *hd)
	Free a sh2lib handle. More...

int	sh2lib_do_get (struct sh2lib_handle hd, const char path, sh2lib_callbacks *callbacks)
	Setup an HTTP GET request stream. More...

int	sh2lib_do_post (struct sh2lib_handle hd, const char path, sh2lib_callbacks *callbacks)
	Setup an HTTP POST request stream. More...

int	sh2lib_do_put (struct sh2lib_handle hd, const char path, sh2lib_callbacks *callbacks)
	Setup an HTTP PUT request stream. More...

int	sh2lib_execute (struct sh2lib_handle *hd)
	Execute send/receive on an HTTP/2 connection. More...

int	sh2lib_do_get_with_nv (struct sh2lib_handle hd, const nghttp2_nv nva, size_t nvlen, sh2lib_callbacks *callbacks)
	Setup an HTTP GET request stream with custom name-value pairs. More...

int	sh2lib_do_putpost_with_nv (struct sh2lib_handle hd, const nghttp2_nv nva, size_t nvlen, sh2lib_callbacks *callbacks)
	Setup an HTTP PUT/POST request stream with custom name-value pairs. More...

Macro Definition Documentation

◆ DATA_RECV_FRAME_COMPLETE

#define DATA_RECV_FRAME_COMPLETE 2

Flag indicating frame is completely received

◆ DATA_RECV_RST_STREAM

#define DATA_RECV_RST_STREAM 1

Flag indicating receive stream is reset

◆ SH2LIB_MAKE_NV

#define SH2LIB_MAKE_NV	(	NAME,
		VALUE,
		FLAGS
	)

Value:

{                                                                           \
    (uint8_t *)NAME, (uint8_t *)VALUE, strlen(NAME), strlen(VALUE), FLAGS     \
  }

Typedef Documentation

◆ sh2lib_frame_data_header_cb_t

typedef int(* sh2lib_frame_data_header_cb_t) (struct sh2lib_handle *handle, const char *name, size_t namelen, const char *value, size_t valuelen, int flags)

Function Prototype for data receive callback.

This function gets called whenever data is received on any stream. The function is also called for indicating events like frame receive complete, or end of stream. The function may get called multiple times as long as data is received on the stream.

Parameters

[in]	handle	Pointer to the sh2lib handle.
[in]	data	Pointer to a buffer that contains the data received.
[in]	len	The length of valid data stored at the 'data' pointer.
[in]	flags	Flags indicating whether the stream is reset (DATA_RECV_RST_STREAM) or this particularly frame is completely received DATA_RECV_FRAME_COMPLETE).

Returns: The function should return 0

◆ sh2lib_frame_data_recv_cb_t

typedef int(* sh2lib_frame_data_recv_cb_t) (struct sh2lib_handle *handle, const char *data, size_t len, int flags)

◆ sh2lib_putpost_data_cb_t

typedef int(* sh2lib_putpost_data_cb_t) (struct sh2lib_handle *handle, char *data, size_t len, uint32_t *data_flags)

Function Prototype for callback to send data in PUT/POST.

This function gets called whenever nghttp2 wishes to send data, like for PUT/POST requests to the server. The function keeps getting called until this function sets the flag NGHTTP2_DATA_FLAG_EOF to indicate end of data.

Parameters

[in]	handle	Pointer to the sh2lib handle.
[out]	data	Pointer to a buffer that should contain the data to send.
[in]	len	The maximum length of data that can be sent out by this function.
[out]	data_flags	Pointer to the data flags. The NGHTTP2_DATA_FLAG_EOF should be set in the data flags to indicate end of new data.

Returns: The function should return the number of valid bytes stored in the data pointer

Function Documentation

◆ sh2lib_connect()

int sh2lib_connect	(	struct sh2lib_handle *	hd,
		const char *	uri,
		mbedtls_x509_crt *	cacerts
	)

Connect to a URI using HTTP/2.

This API opens an HTTP/2 connection with the provided URI. If successful, the hd pointer is populated with a valid handle for subsequent communication.

Only 'https' URIs are supported.

Parameters

[out]	hd	Pointer to a variable of the type 'struct sh2lib_handle'.
[in]	uri	Pointer to the URI that should be connected to.

Returns

ESP_OK if the connection was successful
ESP_FAIL if the connection fails

◆ sh2lib_do_get()

int sh2lib_do_get	(	struct sh2lib_handle *	hd,
		const char *	path,
		sh2lib_callbacks *	callbacks
	)

Setup an HTTP GET request stream.

This API sets up an HTTP GET request to be sent out to the server. A new stream is created for handling the request. Once the request is setup, the API sh2lib_execute() must be called to actually perform the socket I/O with the server.

Parameters

[in]	hd	Pointer to a variable of the type 'struct sh2lib_handle'.
[in]	path	Pointer to the string that contains the resource to perform the HTTP GET operation on (for example, /users).
[in]	recv_cb	The callback function that should be called for processing the request's response

Returns

ESP_OK if request setup is successful
ESP_FAIL if the request setup fails

◆ sh2lib_do_get_with_nv()

int sh2lib_do_get_with_nv	(	struct sh2lib_handle *	hd,
		const nghttp2_nv *	nva,
		size_t	nvlen,
		sh2lib_callbacks *	callbacks
	)

Setup an HTTP GET request stream with custom name-value pairs.

For a simpler version of the API, please refer to sh2lib_do_get().

This API sets up an HTTP GET request to be sent out to the server. A new stream is created for handling the request. Once the request is setup, the API sh2lib_execute() must be called to actually perform the socket I/O with the server.

Please note that the following name value pairs MUST be a part of the request

name:value
":method":"GET"
":scheme":"https"
":path":<the-path-for-the-GET-operation> (for example, /users)

Parameters

[in]	hd	Pointer to a variable of the type 'struct sh2lib_handle'.
[in]	nva	An array of name-value pairs that should be part of the request.
[in]	nvlen	The number of elements in the array pointed to by 'nva'.
[in]	recv_cb	The callback function that should be called for processing the request's response

Returns

ESP_OK if request setup is successful
ESP_FAIL if the request setup fails

◆ sh2lib_do_post()

int sh2lib_do_post	(	struct sh2lib_handle *	hd,
		const char *	path,
		sh2lib_callbacks *	callbacks
	)

Setup an HTTP POST request stream.

This API sets up an HTTP POST request to be sent out to the server. A new stream is created for handling the request. Once the request is setup, the API sh2lib_execute() must be called to actually perform the socket I/O with the server.

Parameters

[in]	hd	Pointer to a variable of the type 'struct sh2lib_handle'.
[in]	path	Pointer to the string that contains the resource to perform the HTTP POST operation on (for example, /users).
[in]	send_cb	The callback function that should be called for sending data as part of this request.
[in]	recv_cb	The callback function that should be called for processing the request's response

Returns

ESP_OK if request setup is successful
ESP_FAIL if the request setup fails

◆ sh2lib_do_put()

int sh2lib_do_put	(	struct sh2lib_handle *	hd,
		const char *	path,
		sh2lib_callbacks *	callbacks
	)

Setup an HTTP PUT request stream.

This API sets up an HTTP PUT request to be sent out to the server. A new stream is created for handling the request. Once the request is setup, the API sh2lib_execute() must be called to actually perform the socket I/O with the server.

Parameters

[in]	hd	Pointer to a variable of the type 'struct sh2lib_handle'.
[in]	path	Pointer to the string that contains the resource to perform the HTTP PUT operation on (for example, /users).
[in]	send_cb	The callback function that should be called for sending data as part of this request.
[in]	recv_cb	The callback function that should be called for processing the request's response

Returns

ESP_OK if request setup is successful
ESP_FAIL if the request setup fails

◆ sh2lib_do_putpost_with_nv()

int sh2lib_do_putpost_with_nv	(	struct sh2lib_handle *	hd,
		const nghttp2_nv *	nva,
		size_t	nvlen,
		sh2lib_callbacks *	callbacks
	)

Setup an HTTP PUT/POST request stream with custom name-value pairs.

For a simpler version of the API, please refer to sh2lib_do_put() or sh2lib_do_post().

This API sets up an HTTP PUT/POST request to be sent out to the server. A new stream is created for handling the request. Once the request is setup, the API sh2lib_execute() must be called to actually perform the socket I/O with the server.

Please note that the following name value pairs MUST be a part of the request

name:value
":method":"PUT" (or POST)
":scheme":"https"
":path":<the-path-for-the-PUT-operation> (for example, /users)

Parameters

[in]	hd	Pointer to a variable of the type 'struct sh2lib_handle'.
[in]	nva	An array of name-value pairs that should be part of the request.
[in]	nvlen	The number of elements in the array pointed to by 'nva'.
[in]	send_cb	The callback function that should be called for sending data as part of this request.
[in]	recv_cb	The callback function that should be called for processing the request's response

Returns

ESP_OK if request setup is successful
ESP_FAIL if the request setup fails

◆ sh2lib_execute()

int sh2lib_execute ( struct sh2lib_handle * hd )

Execute send/receive on an HTTP/2 connection.

While the API sh2lib_do_get(), sh2lib_do_post() setup the requests to be initiated with the server, this API performs the actual data send/receive operations on the HTTP/2 connection. The callback functions are accordingly called during the processing of these requests.

Parameters

[in] hd Pointer to a variable of the type 'struct sh2lib_handle'

Returns

ESP_OK if the connection was successful
ESP_FAIL if the connection fails

◆ sh2lib_free()

void sh2lib_free ( struct sh2lib_handle * hd )

Free a sh2lib handle.

This API frees-up an sh2lib handle, thus closing any open connections that may be associated with this handle, and freeing up any resources.

Parameters

[in] hd Pointer to a variable of the type 'struct sh2lib_handle'.

Classes

Macros

Typedefs

Functions

Macro Definition Documentation

◆ DATA_RECV_FRAME_COMPLETE

◆ DATA_RECV_RST_STREAM

◆ SH2LIB_MAKE_NV

Typedef Documentation

◆ sh2lib_frame_data_header_cb_t

◆ sh2lib_frame_data_recv_cb_t

◆ sh2lib_putpost_data_cb_t

Function Documentation

◆ sh2lib_connect()

◆ sh2lib_do_get()

◆ sh2lib_do_get_with_nv()

◆ sh2lib_do_post()

◆ sh2lib_do_put()

◆ sh2lib_do_putpost_with_nv()

◆ sh2lib_execute()

◆ sh2lib_free()