iot_https_types.h File Reference

Types of the HTTPS Client library. More...

#include "iot_config.h"
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
#include "platform/iot_network.h"

Go to the source code of this file.

Data Structures
struct	IotHttpsClientCallbacks_t
	HTTPS Client library callbacks for asynchronous requests. More...
struct	IotHttpsUserBuffer_t
	User-provided buffer for storing the HTTPS headers and library internal context. More...
struct	IotHttpsSyncInfo_t
	HTTPS Client synchronous request information. More...
struct	IotHttpsAsyncInfo_t
	HTTPS Client asynchronous request information. More...
struct	IotHttpsConnectionInfo_t
	HTTP connection configuration. More...
struct	IotHttpsRequestInfo_t
	HTTP request configuration. More...
struct	IotHttpsResponseInfo_t
	HTTP request configuration. More...

Macros
#define	IOT_HTTPS_IS_NON_TLS_FLAG   ( 0x00000001 )
	Flag for IotHttpsConnectionInfo_t that disables TLS. More...
#define	IOT_HTTPS_DISABLE_SNI   ( 0x00000008 )
	Flag for IotHttpsConnectionInfo_t that disables Server Name Indication (SNI). More...
#define	IOT_HTTPS_CONNECTION_HANDLE_INITIALIZER   NULL
	Initializer for IotHttpsConnectionHandle_t.
#define	IOT_HTTPS_REQUEST_HANDLE_INITIALIZER   NULL
	Initializer for IotHttpsRequestHandle_t.
#define	IOT_HTTPS_RESPONSE_HANDLE_INITIALIZER   NULL
	Initializer for IotHttpsResponseHandle_t.
#define	IOT_HTTPS_USER_BUFFER_INITIALIZER   { 0 }
	Initializer for IotHttpsUserBuffer_t.
#define	IOT_HTTPS_SYNC_INFO_INITIALIZER   { 0 }
	Initializer for IotHttpsSyncInfo_t.
#define	IOT_HTTPS_ASYNC_INFO_INITIALIZER   { 0 }
	Initializer for IotHttpsAsyncInfo_t.
#define	IOT_HTTPS_CONNECTION_INFO_INITIALIZER   { 0 }
	Initializer for IotHttpsConnectionInfo_t.
#define	IOT_HTTPS_REQUEST_INFO_INITIALIZER   { 0 }
	Initializer for IotHttpsRequestInfo_t.
#define	IOT_HTTPS_RESPONSE_INFO_INITIALIZER   { 0 }
	Initializer for IotHttpsResponseInfo_t.
#define	IOT_HTTPS_NETWORK_INTERFACE_TYPE   const IotNetworkInterface_t *
	Type for the network interface containing the operations to send, receive, connect, and disconnect from the network.

Typedefs
typedef struct _httpsConnection *	IotHttpsConnectionHandle_t
	Opaque handle of an HTTP connection. More...
typedef struct _httpsRequest *	IotHttpsRequestHandle_t
	Opaque handle of an HTTP request. More...
typedef struct _httpsResponse *	IotHttpsResponseHandle_t
	Opaque handle of an HTTP response. More...

Enumerations
enum	IotHttpsReturnCode_t {   IOT_HTTPS_OK = 0, IOT_HTTPS_INVALID_PARAMETER = 101, IOT_HTTPS_INVALID_PAYLOAD = 102, IOT_HTTPS_MESSAGE_TOO_LARGE = 103,   IOT_HTTPS_OVERFLOW = 104, IOT_HTTPS_INSUFFICIENT_MEMORY = 105, IOT_HTTPS_QUEUE_FULL = 106, IOT_HTTPS_RETRY = 107,   IOT_HTTPS_NOT_FOUND = 108, IOT_HTTPS_MESSAGE_FINISHED = 109, IOT_HTTPS_INTERNAL_ERROR = 201, IOT_HTTPS_NETWORK_ERROR = 202,   IOT_HTTPS_CONNECTION_ERROR = 203, IOT_HTTPS_STREAM_ERROR = 204, IOT_HTTPS_AUTHENTICATION_ERROR = 205, IOT_HTTPS_TLS_ERROR = 206,   IOT_HTTPS_USER_CALLBACK_ERROR = 207, IOT_HTTPS_TIMEOUT_ERROR = 208, IOT_HTTPS_PROTOCOL_ERROR = 209, IOT_HTTPS_SEND_ABORT = 210,   IOT_HTTPS_RECEIVE_ABORT = 211, IOT_HTTPS_ASYNC_SCHEDULING_ERROR = 212, IOT_HTTPS_PARSING_ERROR = 213, IOT_HTTPS_FATAL = 901,   IOT_HTTPS_BUSY = 902, IOT_HTTPS_TRY_AGAIN = 903, IOT_HTTPS_DATA_EXIST = 904, IOT_HTTPS_NOT_SUPPORTED = 905 }
	Return codes of HTTPS Client functions. More...
enum	IotHttpsMethod_t { IOT_HTTPS_METHOD_GET = 0, IOT_HTTPS_METHOD_HEAD, IOT_HTTPS_METHOD_PUT, IOT_HTTPS_METHOD_POST }
	Types of HTTP methods. More...
enum	IotHttpsResponseStatus {   IOT_HTTPS_STATUS_CONTINUE = 100, IOT_HTTPS_STATUS_SWITCHING_PROTOCOLS, IOT_HTTPS_STATUS_OK = 200, IOT_HTTPS_STATUS_CREATED,   IOT_HTTPS_STATUS_ACCEPTED, IOT_HTTPS_STATUS_NON_AUTHORITIVE_INFORMATION, IOT_HTTPS_STATUS_NO_CONTENT, IOT_HTTPS_STATUS_RESET_CONTENT,   IOT_HTTPS_STATUS_PARTIAL_CONTENT, IOT_HTTPS_STATUS_MULTIPLE_CHOICES = 300, IOT_HTTPS_STATUS_MOVED_PERMANENTLY, IOT_HTTPS_STATUS_FOUND,   IOT_HTTPS_STATUS_SEE_OTHER, IOT_HTTPS_STATUS_NOT_MODIFIED, IOT_HTTPS_STATUS_USE_PROXY, IOT_HTTPS_STATUS_UNUSED,   IOT_HTTPS_STATUS_TEMPORARY_REDIRECT, IOT_HTTPS_STATUS_BAD_REQUEST = 400, IOT_HTTPS_STATUS_UNAUTHORIZED, IOT_HTTPS_STATUS_PAYMENT_REQUIRED,   IOT_HTTPS_STATUS_FORBIDDEN, IOT_HTTPS_STATUS_NOT_FOUND, IOT_HTTPS_STATUS_METHOD_NOT_ALLOWED, IOT_HTTPS_STATUS_NOT_ACCEPTABLE,   IOT_HTTPS_STATUS_PROXY_AUTHENTICATION_REQUIRED, IOT_HTTPS_STATUS_REQUEST_TIMEOUT, IOT_HTTPS_STATUS_CONFLICT, IOT_HTTPS_STATUS_GONE,   IOT_HTTPS_STATUS_LENGTH_REQUIRED, IOT_HTTPS_STATUS_PRECONDITION_FAILED, IOT_HTTPS_STATUS_REQUEST_ENTITY_TOO_LARGE, IOT_HTTPS_STATUS_REQUEST_URI_TOO_LONG,   IOT_HTTPS_STATUS_UNSUPPORTED_MEDIA_TYPE, IOT_HTTPS_STATUS_REQUEST_RANGE_NOT_SATISFIABLE, IOT_HTTPS_STATUS_EXPECTATION_FAILED, IOT_HTTPS_STATUS_INTERNAL_SERVER_ERROR = 500,   IOT_HTTPS_STATUS_NOT_IMPLEMENTED, IOT_HTTPS_STATUS_BAD_GATEWAY, IOT_HTTPS_STATUS_SERVICE_UNAVAILABLE, IOT_HTTPS_STATUS_GATEWAY_TIMEOUT,   IOT_HTTPS_STATUS_HTTP_VERSION_NOT_SUPPORTED }
	Types of standard HTTP Response status codes. More...

Variables
const uint32_t	requestUserBufferMinimumSize
	The minimum user buffer size for the HTTP request context and headers. More...
const uint32_t	responseUserBufferMinimumSize
	The minimum user buffer size for the HTTP response context and headers. More...
const uint32_t	connectionUserBufferMinimumSize
	The minimum user buffer size for the HTTP connection context and headers. More...

Detailed Description

Types of the HTTPS Client library.

Macro Definition Documentation

IOT_HTTPS_IS_NON_TLS_FLAG

#define IOT_HTTPS_IS_NON_TLS_FLAG   ( 0x00000001 )

Flag for IotHttpsConnectionInfo_t that disables TLS.

Set this bit in IotHttpsConnectionInfo_t.flags to disable use of TLS when the connection is created. This library creates secure connections by default.

IOT_HTTPS_DISABLE_SNI

#define IOT_HTTPS_DISABLE_SNI   ( 0x00000008 )

Flag for IotHttpsConnectionInfo_t that disables Server Name Indication (SNI).

Set this bit IotHttpsConnectionInfo_t.flags to disable SNI. SNI is enabled by default in this library. When SNI is enabled IotHttpsConnectionInfo_t.pAddress will be used for the server name verification.

Variable Documentation

requestUserBufferMinimumSize

const uint32_t requestUserBufferMinimumSize

extern

The minimum user buffer size for the HTTP request context and headers.

This helps to calculate the size of the buffer needed for IotHttpsRequestInfo_t.userBuffer.

This buffer size is calculated to fit the HTTP Request-Line and the default headers. It does not account for the length of the path in the Request-Line nor does it account for the length of the host name. It also does not account for extra headers that the application may add. These sizes need to be accounted for by the application when assigning a buffer.

A typical value for sizing the request user buffer for the request context is 512 bytes. See the example below.

uint8_t requestUserBuffer[512] = { 0 };
IotHttpsRequestInfo_t requestInfo = IOT_HTTPS_REQUEST_INFO_INITIALIZER;
requestInfo.userBuffer.pBuffer = requestUserBuffer;

By the application providing the memory for the internal context, no memory is needed to be allocated internally to the library for the internal context. The application has control over the memory allocation related to the request, response, and connection.

The minimum user buffer size for the HTTP request context and headers.

The request user buffer is configured in IotHttpsClientRequestInfo_t.userBuffer. This buffer stores the internal context of the request and then the request headers right after. The minimum size for the buffer is the total size of the internal request context, the HTTP formatted request line, the User-Agent header line, and the part of the Host header line.

responseUserBufferMinimumSize

const uint32_t responseUserBufferMinimumSize

extern

The minimum user buffer size for the HTTP response context and headers.

This helps to calculate the size of the buffer needed for IotHttpsResponseInfo_t.userBuffer.

The buffer size is calculated to fit the HTTP response context only. It does not account for the HTTP response status line. It does not account for any HTTP response headers. If the buffer assigned to IotHttpsResponseInfo_t.userBuffer is of this minimum size, then the response Status-Line and the response headers will not be stored. These sizes need to be accounted for by the application when assigning a buffer.

If the response Status-Line and response headers cannot fit into IotHttpsResponseInfo_t.userBuffer, then after a call to IotHttpsClient_SendSync, calls to IotHttpsClient_ReadResponseStatus, IotHttpsClient_ReadContentLength, and IotHttpsClient_ReadHeader will return a failure code.

A typical value for sizing the response user buffer for the response context is 512 bytes. See the example below.

uint8_t responseUserBuffer[512] = { 0 };
IotHttpsResponseInfo_t responseInfo = IOT_HTTPS_RESPONSE_INFO_INITIALIZER;
responseInfo.userBuffer.pBuffer = responseUserBuffer;

By the application providing the memory for the internal context, no memory is needed to be allocated internally to the library for the internal context. The application has control over the memory allocation related to the request, response, and connection.

The minimum user buffer size for the HTTP response context and headers.

The response user buffer is configured in IotHttpsClientRequestInfo_t.userBuffer. This buffer stores the internal context of the response and then the response headers right after. This minimum size is calculated for the case if no bytes from the HTTP response headers are to be stored.

connectionUserBufferMinimumSize

const uint32_t connectionUserBufferMinimumSize

extern

The minimum user buffer size for the HTTP connection context and headers.

This helps to calculate the size of the buffer needed for IotHttpsConnectionInfo_t.userBuffer.

The buffer size is calculated to fit the HTTP connection context only. The buffer assigned by the application must be at least this size.

A typical value for sizing the request user buffer for the connection context is 512 bytes. See the example below.

uint8_t connectionUserBuffer[512] = { 0 };
IotHttpsConnectionInfo_t connectionInfo = IOT_HTTPS_CONNECTION_INFO_INITIALIZER;
connectionInfo.userBuffer.pBuffer = connectionUserBuffer;

By the application providing the memory for the internal context, no memory is needed to be allocated internally to the library for the internal context. The application has control over the memory allocation related to the request, response, and connection.

The minimum user buffer size for the HTTP connection context and headers.

The connection user buffer is configured in IotHttpsConnectionInfo_t.userBuffer. This buffer stores the internal context of the connection.