Abstraction of network functions used by libraries in this SDK. More...

#include "iot_config.h"
#include <stdint.h>
#include <stdlib.h>
#include "types/iot_platform_types.h"

Data Structures
struct	IotNetworkInterface_t
	Represents the functions of a network stack. More...

struct	IotNetworkServerInfo
	Information on the remote server for connection setup. More...

struct	IotNetworkCredentials
	Contains the credentials necessary for connection setup. More...

Typedefs
typedef void(*	IotNetworkReceiveCallback_t) (IotNetworkConnection_t pConnection, void *pContext)
	Provide an asynchronous notification of incoming network data. More...

typedef void(*	IotNetworkCloseCallback_t) (IotNetworkConnection_t pConnection, IotNetworkCloseReason_t reason, void *pContext)
	Provide an asynchronous notification of network closing. More...

typedef IotNetworkError_t(*	IotNetworkCreate_t) (IotNetworkServerInfo_t pServerInfo, IotNetworkCredentials_t pCredentialInfo, IotNetworkConnection_t *pConnection)
	Create a new network connection. More...

typedef IotNetworkError_t(*	IotNetworkSetReceiveCallback_t) (IotNetworkConnection_t pConnection, IotNetworkReceiveCallback_t receiveCallback, void *pContext)
	Register an IotNetworkReceiveCallback_t. More...

typedef IotNetworkError_t(*	IotNetworkSetCloseCallback_t) (IotNetworkConnection_t pConnection, IotNetworkCloseCallback_t closeCallback, void *pContext)
	Register an IotNetworkReceiveCallback_t. More...

typedef size_t(*	IotNetworkSend_t) (IotNetworkConnection_t pConnection, const uint8_t *pMessage, size_t messageLength)
	Send data over a return connection. More...

typedef size_t(*	IotNetworkReceive_t) (IotNetworkConnection_t pConnection, uint8_t *pBuffer, size_t bytesRequested)
	Block and wait for incoming network data. More...

typedef IotNetworkError_t(*	IotNetworkClose_t) (IotNetworkConnection_t pConnection)
	Close a network connection. More...

typedef IotNetworkError_t(*	IotNetworkDestroy_t) (IotNetworkConnection_t pConnection)
	Free resources used by a network connection. More...

Enumerations
enum	IotNetworkError_t { IOT_NETWORK_SUCCESS = 0, IOT_NETWORK_FAILURE, IOT_NETWORK_BAD_PARAMETER, IOT_NETWORK_NO_MEMORY, IOT_NETWORK_SYSTEM_ERROR }
	Return codes for network functions. More...

enum	IotNetworkCloseReason_t { IOT_NETWORK_NOT_CLOSED = 0, IOT_NETWORK_SERVER_CLOSED, IOT_NETWORK_TRANSPORT_FAILURE, IOT_NETWORK_CLIENT_CLOSED, IOT_NETWORK_UNKNOWN_CLOSED }
	Disconnect reasons for the network close callback. More...

Detailed Description

Abstraction of network functions used by libraries in this SDK.

Typedef Documentation

◆ IotNetworkReceiveCallback_t

typedef void( * IotNetworkReceiveCallback_t) (IotNetworkConnection_t pConnection, void *pContext)

Provide an asynchronous notification of incoming network data.

A function with this signature may be set with IotNetworkInterface_t::setReceiveCallback to be invoked when data is available on the network.

Parameters

[in]	pConnection	The connection on which data is available, defined by the network stack.
[in]	pContext	The third argument passed to IotNetworkInterface_t::setReceiveCallback.

◆ IotNetworkCloseCallback_t

typedef void( * IotNetworkCloseCallback_t) (IotNetworkConnection_t pConnection, IotNetworkCloseReason_t reason, void *pContext)

Provide an asynchronous notification of network closing.

A function with this signature may be set with IotNetworkInterface_t::setCloseCallback to be invoked when the network connection is closed.

Parameters

[in]	pConnection	The connection that was closed, defined by the network stack.
[in]	reason	The reason the connection was closed
[in]	pContext	The third argument passed to IotNetworkInterface_t::setCloseCallback.

◆ IotNetworkCreate_t

typedef IotNetworkError_t( * IotNetworkCreate_t) (IotNetworkServerInfo_t pServerInfo, IotNetworkCredentials_t pCredentialInfo, IotNetworkConnection_t *pConnection)

Create a new network connection.

This function allocates resources and establishes a new network connection.

Parameters

[in]	pServerInfo	Represents information needed to set up the new connection, defined by the network stack.
[in]	pCredentialInfo	Represents information needed to secure the new connection, defined by the network stack.
[out]	pConnection	Set to represent a new connection, defined by the network stack.

Returns: Any IotNetworkError_t, as defined by the network stack.

◆ IotNetworkSetReceiveCallback_t

typedef IotNetworkError_t( * IotNetworkSetReceiveCallback_t) (IotNetworkConnection_t pConnection, IotNetworkReceiveCallback_t receiveCallback, void *pContext)

Register an IotNetworkReceiveCallback_t.

Sets an IotNetworkReceiveCallback_t to be called asynchronously when data arrives on the network. The network stack should invoke this function "as if" it were the thread routine of a detached thread.

Each network connection may only have one receive callback at any time. IotNetworkInterface_t::close is expected to remove any active receive callbacks.

Parameters

[in]	pConnection	The connection to associate with the receive callback.
[in]	receiveCallback	The function to invoke for incoming network data.
[in]	pContext	A value to pass as the first parameter to the receive callback.

Returns: Any IotNetworkError_t, as defined by the network stack.

See also: platform_network_function_receivecallback

◆ IotNetworkSetCloseCallback_t

typedef IotNetworkError_t( * IotNetworkSetCloseCallback_t) (IotNetworkConnection_t pConnection, IotNetworkCloseCallback_t closeCallback, void *pContext)

Register an IotNetworkReceiveCallback_t.

Sets an IotNetworkReceiveCallback_t to be called asynchronously when the network connection closes. The network stack should invoke this function "as if" it were the thread routine of a detached thread.

Each network connection may only have one close callback at any time. IotNetworkInterface_t::close is expected to remove any active close callbacks.

Parameters

[in]	pConnection	The connection to associate with the close callback.
[in]	receiveCallback	The function to invoke for incoming network close events.
[in]	pContext	A value to pass as the first parameter to the close callback.

Returns: Any IotNetworkError_t, as defined by the network stack.

See also: platform_network_function_closecallback

◆ IotNetworkSend_t

typedef size_t( * IotNetworkSend_t) (IotNetworkConnection_t pConnection, const uint8_t *pMessage, size_t messageLength)

Send data over a return connection.

Attempts to transmit messageLength bytes of pMessage across the connection represented by pConnection. Returns the number of bytes actually sent, 0 on failure.

Parameters

[in]	pConnection	The connection used to send data, defined by the network stack.
[in]	pMessage	The message to send.
[in]	messageLength	The length of `pMessage`.

Returns: The number of bytes successfully sent, 0 on failure.

◆ IotNetworkReceive_t

typedef size_t( * IotNetworkReceive_t) (IotNetworkConnection_t pConnection, uint8_t *pBuffer, size_t bytesRequested)

Block and wait for incoming network data.

Wait for a message of size bytesRequested to arrive on the network and place it in pBuffer.

Parameters

[in]	pConnection	The connection to wait on, defined by the network stack.
[out]	pBuffer	Where to place the incoming network data. This buffer must be at least `bytesRequested` in size.
[in]	bytesRequested	How many bytes to wait for. `pBuffer` must be at least this size.

Returns: The number of bytes successfully received. This should be bytesRequested when successful. Any other value may indicate an error.

◆ IotNetworkClose_t

typedef IotNetworkError_t( * IotNetworkClose_t) (IotNetworkConnection_t pConnection)

Close a network connection.

This function closes the connection, but does not release the resources used by the connection. This allows calls to other networking functions to return an error and handle a closed connection without the risk of crashing. Once it can be guaranteed that pConnection will no longer be used, the connection can be destroyed with IotNetworkInterface_t::destroy.

In addition to closing the connection, this function should also remove any active receive callback.

Parameters

[in] pConnection The network connection to close, defined by the network stack.

Returns: Any IotNetworkError_t, as defined by the network stack.

Note: It must be safe to call this function on an already-closed connection.

◆ IotNetworkDestroy_t

typedef IotNetworkError_t( * IotNetworkDestroy_t) (IotNetworkConnection_t pConnection)

Free resources used by a network connection.

This function releases the resources of a closed connection. It should be called after IotNetworkInterface_t::close.

Parameters

[in] pConnection The network connection to destroy, defined by the network stack.

Returns: Any IotNetworkError_t, as defined by the network stack.

Attention: No function should be called on the network connection after calling this function. This function must be safe to call from a receive callback.

Data Structures

Typedefs

Enumerations

Detailed Description

Typedef Documentation

◆ IotNetworkReceiveCallback_t

◆ IotNetworkCloseCallback_t

◆ IotNetworkCreate_t

◆ IotNetworkSetReceiveCallback_t

◆ IotNetworkSetCloseCallback_t

◆ IotNetworkSend_t

◆ IotNetworkReceive_t

◆ IotNetworkClose_t

◆ IotNetworkDestroy_t