2 * Amazon FreeRTOS Platform V1.0.0
\r
3 * Copyright (C) 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
\r
5 * Permission is hereby granted, free of charge, to any person obtaining a copy of
\r
6 * this software and associated documentation files (the "Software"), to deal in
\r
7 * the Software without restriction, including without limitation the rights to
\r
8 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
\r
9 * the Software, and to permit persons to whom the Software is furnished to do so,
\r
10 * subject to the following conditions:
\r
12 * The above copyright notice and this permission notice shall be included in all
\r
13 * copies or substantial portions of the Software.
\r
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
\r
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
\r
17 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
\r
18 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
\r
19 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
\r
20 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
\r
22 * http://aws.amazon.com/freertos
\r
23 * http://www.FreeRTOS.org
\r
27 * @file iot_network.h
\r
28 * @brief Abstraction of network functions used by libraries in this SDK.
\r
31 #ifndef IOT_NETWORK_H_
\r
32 #define IOT_NETWORK_H_
\r
34 /* Standard includes. */
\r
35 #include <stdbool.h>
\r
40 * @ingroup platform_datatypes_enums
\r
41 * @brief Return codes for [network functions](@ref platform_network_functions).
\r
43 typedef enum IotNetworkError
\r
45 IOT_NETWORK_SUCCESS = 0, /**< Function successfully completed. */
\r
46 IOT_NETWORK_FAILURE, /**< Generic failure not covered by other values. */
\r
47 IOT_NETWORK_BAD_PARAMETER, /**< At least one parameter was invalid. */
\r
48 IOT_NETWORK_NO_MEMORY, /**< Memory allocation failed. */
\r
49 IOT_NETWORK_SYSTEM_ERROR /**< An error occurred when calling a system API. */
\r
50 } IotNetworkError_t;
\r
53 * @page platform_network_functions Networking
\r
54 * @brief Functions of the network abstraction component.
\r
56 * The network abstraction component does not declare functions, but uses function
\r
57 * pointers instead. This allows multiple network stacks to be used at the same time.
\r
58 * Libraries that require the network will request an #IotNetworkInterface_t
\r
59 * parameter. The members of the #IotNetworkInterface_t will be called whenever
\r
60 * the library interacts with the network.
\r
62 * The following function pointers are associated with an #IotNetworkInterface_t.
\r
63 * Together, they represent a network stack.
\r
64 * - @functionname{platform_network_function_create}
\r
65 * - @functionname{platform_network_function_setreceivecallback}
\r
66 * - @functionname{platform_network_function_send}
\r
67 * - @functionname{platform_network_function_receive}
\r
68 * - @functionname{platform_network_function_close}
\r
69 * - @functionname{platform_network_function_destroy}
\r
70 * - @functionname{platform_network_function_receivecallback}
\r
74 * @functionpage{IotNetworkInterface_t::create,platform_network,create}
\r
75 * @functionpage{IotNetworkInterface_t::setReceiveCallback,platform_network,setreceivecallback}
\r
76 * @functionpage{IotNetworkInterface_t::send,platform_network,send}
\r
77 * @functionpage{IotNetworkInterface_t::receive,platform_network,receive}
\r
78 * @functionpage{IotNetworkInterface_t::close,platform_network,close}
\r
79 * @functionpage{IotNetworkInterface_t::destroy,platform_network,destroy}
\r
80 * @functionpage{IotNetworkReceiveCallback_t,platform_network,receivecallback}
\r
84 * @brief Provide an asynchronous notification of incoming network data.
\r
86 * A function with this signature may be set with @ref platform_network_function_setreceivecallback
\r
87 * to be invoked when data is available on the network.
\r
89 * @param[in] pConnection The connection on which data is available, defined by
\r
90 * the network stack.
\r
91 * @param[in] pContext The third argument passed to @ref platform_network_function_setreceivecallback.
\r
93 /* @[declare_platform_network_receivecallback] */
\r
94 typedef void ( * IotNetworkReceiveCallback_t )( void * pConnection,
\r
96 /* @[declare_platform_network_receivecallback] */
\r
99 * @ingroup platform_datatypes_paramstructs
\r
100 * @brief Represents the functions of a network stack.
\r
102 * Functions that match these signatures should be implemented against a system's
\r
103 * network stack. See the `platform` directory for existing implementations.
\r
105 typedef struct IotNetworkInterface
\r
108 * @brief Create a new network connection.
\r
110 * This function allocates resources and establishes a new network connection.
\r
111 * @param[in] pConnectionInfo Represents information needed to set up the
\r
112 * new connection, defined by the network stack.
\r
113 * @param[in] pCredentialInfo Represents information needed to secure the
\r
114 * new connection, defined by the network stack.
\r
115 * @param[out] pConnection Set to represent a new connection, defined by the
\r
118 * @return Any #IotNetworkError_t, as defined by the network stack.
\r
120 /* @[declare_platform_network_create] */
\r
121 IotNetworkError_t ( * create )( void * pConnectionInfo,
\r
122 void * pCredentialInfo,
\r
123 void ** pConnection );
\r
124 /* @[declare_platform_network_create] */
\r
127 * @brief Register an @ref platform_network_function_receivecallback.
\r
129 * Sets an @ref platform_network_function_receivecallback to be called
\r
130 * asynchronously when data arrives on the network. The network stack
\r
131 * should invoke this function "as if" it were the thread routine of a
\r
134 * Each network connection may only have one receive callback at any time.
\r
135 * @ref platform_network_function_close is expected to remove any active
\r
136 * receive callbacks.
\r
138 * @param[in] pConnection The connection to associate with the receive callback.
\r
139 * @param[in] receiveCallback The function to invoke for incoming network data.
\r
140 * @param[in] pContext A value to pass as the first parameter to the receive callback.
\r
142 * @return Any #IotNetworkError_t, as defined by the network stack.
\r
144 * @see platform_network_function_receivecallback
\r
146 /* @[declare_platform_network_setreceivecallback] */
\r
147 IotNetworkError_t ( * setReceiveCallback )( void * pConnection,
\r
148 IotNetworkReceiveCallback_t receiveCallback,
\r
150 /* @[declare_platform_network_setreceivecallback] */
\r
153 * @brief Send data over a return connection.
\r
155 * Attempts to transmit `messageLength` bytes of `pMessage` across the
\r
156 * connection represented by `pConnection`. Returns the number of bytes
\r
157 * actually sent, `0` on failure.
\r
159 * @param[in] pConnection The connection used to send data, defined by the
\r
161 * @param[in] pMessage The message to send.
\r
162 * @param[in] messageLength The length of `pMessage`.
\r
164 * @return The number of bytes successfully sent, `0` on failure.
\r
166 /* @[declare_platform_network_send] */
\r
167 size_t ( * send )( void * pConnection,
\r
168 const uint8_t * pMessage,
\r
169 size_t messageLength );
\r
170 /* @[declare_platform_network_send] */
\r
173 * @brief Block and wait for incoming network data.
\r
175 * Wait for a message of size `bytesRequested` to arrive on the network and
\r
176 * place it in `pBuffer`.
\r
178 * @param[in] pConnection The connection to wait on, defined by the network
\r
180 * @param[out] pBuffer Where to place the incoming network data. This buffer
\r
181 * must be at least `bytesRequested` in size.
\r
182 * @param[in] bytesRequested How many bytes to wait for. `pBuffer` must be at
\r
185 * @return The number of bytes successfully received. This should be
\r
186 * `bytesRequested` when successful. Any other value may indicate an error.
\r
188 /* @[declare_platform_network_receive] */
\r
189 size_t ( * receive )( void * pConnection,
\r
191 size_t bytesRequested );
\r
192 /* @[declare_platform_network_receive] */
\r
195 * @brief Close a network connection.
\r
197 * This function closes the connection, but does not release the resources
\r
198 * used by the connection. This allows calls to other networking functions
\r
199 * to return an error and handle a closed connection without the risk of
\r
200 * crashing. Once it can be guaranteed that `pConnection` will no longer be
\r
201 * used, the connection can be destroyed with @ref platform_network_function_destroy.
\r
203 * In addition to closing the connection, this function should also remove
\r
204 * any active [receive callback](@ref platform_network_function_receivecallback).
\r
206 * @param[in] pConnection The network connection to close, defined by the
\r
209 * @return Any #IotNetworkError_t, as defined by the network stack.
\r
211 * @note It must be safe to call this function on an already-closed connection.
\r
213 /* @[declare_platform_network_close] */
\r
214 IotNetworkError_t ( * close )( void * pConnection );
\r
215 /* @[declare_platform_network_close] */
\r
218 * @brief Free resources used by a network connection.
\r
220 * This function releases the resources of a closed connection. It should be
\r
221 * called after @ref platform_network_function_close.
\r
223 * @param[in] pConnection The network connection to destroy, defined by
\r
224 * the network stack.
\r
226 * @return Any #IotNetworkError_t, as defined by the network stack.
\r
228 * @attention No function should be called on the network connection after
\r
229 * calling this function. This function must be safe to call from a
\r
230 * [receive callback](@ref platform_network_function_receivecallback).
\r
232 /* @[declare_platform_network_destroy] */
\r
233 IotNetworkError_t ( * destroy )( void * pConnection );
\r
234 /* @[declare_platform_network_destroy] */
\r
235 } IotNetworkInterface_t;
\r
238 * @ingroup platform_datatypes_paramstructs
\r
239 * @brief Information on the remote server for connection setup.
\r
241 * May be passed to #IotNetworkInterface_t.create as `pConnectionInfo`. This
\r
242 * structure contains commonly-used parameters, but may be replaced with an
\r
245 typedef struct IotNetworkServerInfo
\r
247 const char * pHostName; /**< @brief Server host name. Must be NULL-terminated. */
\r
248 uint16_t port; /**< @brief Server port in host-order. */
\r
249 } IotNetworkServerInfo_t;
\r
252 * @ingroup platform_datatypes_paramstructs
\r
253 * @brief Contains the credentials necessary for connection setup.
\r
255 * May be passed to #IotNetworkInterface_t.create as `pCredentialInfo`. This
\r
256 * structure contains commonly-used parameters, but may be replaced with an
\r
259 typedef struct IotNetworkCredentials
\r
262 * @brief Set this to a non-NULL value to use ALPN.
\r
264 * This string must be NULL-terminated.
\r
267 * (https://aws.amazon.com/blogs/iot/mqtt-with-tls-client-authentication-on-port-443-why-it-is-useful-and-how-it-works/)
\r
268 * for more information.
\r
270 const char * pAlpnProtos;
\r
273 * @brief Set this to a non-zero value to use TLS max fragment length
\r
274 * negotiation (TLS MFLN).
\r
276 * @note The network stack may have a minimum value for this parameter and
\r
277 * may return an error if this parameter is too small.
\r
279 size_t maxFragmentLength;
\r
282 * @brief Disable server name indication (SNI) for a TLS session.
\r
286 const char * pRootCa; /**< @brief String representing a trusted server root certificate. */
\r
287 size_t rootCaSize; /**< @brief Size associated with #IotNetworkCredentials_t.pRootCa. */
\r
288 const char * pClientCert; /**< @brief String representing the client certificate. */
\r
289 size_t clientCertSize; /**< @brief Size associated with #IotNetworkCredentials_t.pClientCert. */
\r
290 const char * pPrivateKey; /**< @brief String representing the client certificate's private key. */
\r
291 size_t privateKeySize; /**< @brief Size associated with #IotNetworkCredentials_t.pPrivateKey. */
\r
292 } IotNetworkCredentials_t;
\r
294 #endif /* ifndef IOT_NETWORK_H_ */
\r