IotNetworkInterface_t Struct Reference

Represents the functions of a network stack. More...

#include <iot_network.h>

Data Fields
IotNetworkError_t(*	create )(void *pConnectionInfo, void *pCredentialInfo, void **pConnection)
	Create a new network connection. More...
IotNetworkError_t(*	setReceiveCallback )(void *pConnection, IotNetworkReceiveCallback_t receiveCallback, void *pContext)
	Register an IotNetworkReceiveCallback_t. More...
size_t(*	send )(void *pConnection, const uint8_t *pMessage, size_t messageLength)
	Send data over a return connection. More...
size_t(*	receive )(void *pConnection, uint8_t *pBuffer, size_t bytesRequested)
	Block and wait for incoming network data. More...
size_t(*	receiveUpto )(void *pConnection, uint8_t *pBuffer, size_t bufferSize)
	Read incoming data available in the network buffers. More...
IotNetworkError_t(*	close )(void *pConnection)
	Close a network connection. More...
IotNetworkError_t(*	destroy )(void *pConnection)
	Free resources used by a network connection. More...

Detailed Description

Represents the functions of a network stack.

Functions that match these signatures should be implemented against a system's network stack. See the platform directory for existing implementations.

Field Documentation

create

IotNetworkError_t( * IotNetworkInterface_t::create) (void *pConnectionInfo, void *pCredentialInfo, void **pConnection)

Create a new network connection.

This function allocates resources and establishes a new network connection.

Parameters

[in]	pConnectionInfo	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.

setReceiveCallback

IotNetworkError_t( * IotNetworkInterface_t::setReceiveCallback) (void *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

send

size_t( * IotNetworkInterface_t::send) (void *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.

receive

size_t( * IotNetworkInterface_t::receive) (void *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 MUST be bytesRequested when successful. Any other value may indicate an error.

receiveUpto

size_t( * IotNetworkInterface_t::receiveUpto) (void *pConnection, uint8_t *pBuffer, size_t bufferSize)

Read incoming data available in the network buffers.

Reads bytes available in the network buffers into pBuffer.

• If there is less data available than requested, it will return the available number of bytes.
• If there is more data available than requested, it will fill the whole pBuffer.
• If there is no data available, it will return 0.

Parameters

[in]	pConnection	The connection to receive data on, defined by the network stack.
[out]	pBuffer	The buffer to place the incoming network data.
[in]	bufferSize	The size of pBuffer.

Returns

The number of bytes successfully received.

close

IotNetworkError_t( * IotNetworkInterface_t::close) (void *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.

destroy

IotNetworkError_t( * IotNetworkInterface_t::destroy) (void *pConnection)

Free resources used by a network connection.

This function releases the resources of a closed connection. It MUST 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 MAY be called on the network connection after calling this function. This function MUST be safe to call from a receive callback.

---

The documentation for this struct was generated from the following file:

• iot_network.h