--- /dev/null
+/*\r
+ * IoT Platform V1.1.0\r
+ * Copyright (C) 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.\r
+ *\r
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
+ * this software and associated documentation files (the "Software"), to deal in\r
+ * the Software without restriction, including without limitation the rights to\r
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
+ * the Software, and to permit persons to whom the Software is furnished to do so,\r
+ * subject to the following conditions:\r
+ *\r
+ * The above copyright notice and this permission notice shall be included in all\r
+ * copies or substantial portions of the Software.\r
+ *\r
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
+ */\r
+\r
+/**\r
+ * @file iot_network.h\r
+ * @brief Abstraction of network functions used by libraries in this SDK.\r
+ */\r
+\r
+#ifndef IOT_NETWORK_H_\r
+#define IOT_NETWORK_H_\r
+\r
+/* The config header is always included first. */\r
+#include "iot_config.h"\r
+\r
+/* Standard includes. */\r
+#include <stdint.h>\r
+#include <stdlib.h>\r
+\r
+/**\r
+ * @ingroup platform_datatypes_enums\r
+ * @brief Return codes for [network functions](@ref platform_network_functions).\r
+ */\r
+typedef enum IotNetworkError\r
+{\r
+ IOT_NETWORK_SUCCESS = 0, /**< Function successfully completed. */\r
+ IOT_NETWORK_FAILURE, /**< Generic failure not covered by other values. */\r
+ IOT_NETWORK_BAD_PARAMETER, /**< At least one parameter was invalid. */\r
+ IOT_NETWORK_NO_MEMORY, /**< Memory allocation failed. */\r
+ IOT_NETWORK_SYSTEM_ERROR /**< An error occurred when calling a system API. */\r
+} IotNetworkError_t;\r
+\r
+/**\r
+ * @page platform_network_functions Networking\r
+ * @brief Functions of the network abstraction component.\r
+ *\r
+ * The network abstraction component does not declare functions, but uses function\r
+ * pointers instead. This allows multiple network stacks to be used at the same time.\r
+ * Libraries that require the network will request an #IotNetworkInterface_t\r
+ * parameter. The members of the #IotNetworkInterface_t will be called whenever\r
+ * the library interacts with the network.\r
+ *\r
+ * The following function pointers are associated with an #IotNetworkInterface_t.\r
+ * Together, they represent a network stack.\r
+ * - @functionname{platform_network_function_create}\r
+ * - @functionname{platform_network_function_setreceivecallback}\r
+ * - @functionname{platform_network_function_send}\r
+ * - @functionname{platform_network_function_receive}\r
+ * - @functionname{platform_network_function_close}\r
+ * - @functionname{platform_network_function_destroy}\r
+ * - @functionname{platform_network_function_receivecallback}\r
+ */\r
+\r
+/**\r
+ * @functionpage{IotNetworkInterface_t::create,platform_network,create}\r
+ * @functionpage{IotNetworkInterface_t::setReceiveCallback,platform_network,setreceivecallback}\r
+ * @functionpage{IotNetworkInterface_t::send,platform_network,send}\r
+ * @functionpage{IotNetworkInterface_t::receive,platform_network,receive}\r
+ * @functionpage{IotNetworkInterface_t::close,platform_network,close}\r
+ * @functionpage{IotNetworkInterface_t::destroy,platform_network,destroy}\r
+ * @functionpage{IotNetworkReceiveCallback_t,platform_network,receivecallback}\r
+ */\r
+\r
+/**\r
+ * @brief Provide an asynchronous notification of incoming network data.\r
+ *\r
+ * A function with this signature may be set with @ref platform_network_function_setreceivecallback\r
+ * to be invoked when data is available on the network.\r
+ *\r
+ * @param[in] pConnection The connection on which data is available, defined by\r
+ * the network stack.\r
+ * @param[in] pContext The third argument passed to @ref platform_network_function_setreceivecallback.\r
+ */\r
+/* @[declare_platform_network_receivecallback] */\r
+typedef void ( * IotNetworkReceiveCallback_t )( IotNetworkConnection_t pConnection,\r
+ void * pContext );\r
+/* @[declare_platform_network_receivecallback] */\r
+\r
+/**\r
+ * @ingroup platform_datatypes_paramstructs\r
+ * @brief Represents the functions of a network stack.\r
+ *\r
+ * Functions that match these signatures should be implemented against a system's\r
+ * network stack. See the `platform` directory for existing implementations.\r
+ */\r
+typedef struct IotNetworkInterface\r
+{\r
+ /**\r
+ * @brief Create a new network connection.\r
+ *\r
+ * This function allocates resources and establishes a new network connection.\r
+ * @param[in] pServerInfo Represents information needed to set up the\r
+ * new connection, defined by the network stack.\r
+ * @param[in] pCredentialInfo Represents information needed to secure the\r
+ * new connection, defined by the network stack.\r
+ * @param[out] pConnection Set to represent a new connection, defined by the\r
+ * network stack.\r
+ *\r
+ * @return Any #IotNetworkError_t, as defined by the network stack.\r
+ */\r
+ /* @[declare_platform_network_create] */\r
+ IotNetworkError_t ( * create )( IotNetworkServerInfo_t pServerInfo,\r
+ IotNetworkCredentials_t pCredentialInfo,\r
+ IotNetworkConnection_t * pConnection );\r
+ /* @[declare_platform_network_create] */\r
+\r
+ /**\r
+ * @brief Register an @ref platform_network_function_receivecallback.\r
+ *\r
+ * Sets an @ref platform_network_function_receivecallback to be called\r
+ * asynchronously when data arrives on the network. The network stack\r
+ * should invoke this function "as if" it were the thread routine of a\r
+ * detached thread.\r
+ *\r
+ * Each network connection may only have one receive callback at any time.\r
+ * @ref platform_network_function_close is expected to remove any active\r
+ * receive callbacks.\r
+ *\r
+ * @param[in] pConnection The connection to associate with the receive callback.\r
+ * @param[in] receiveCallback The function to invoke for incoming network data.\r
+ * @param[in] pContext A value to pass as the first parameter to the receive callback.\r
+ *\r
+ * @return Any #IotNetworkError_t, as defined by the network stack.\r
+ *\r
+ * @see platform_network_function_receivecallback\r
+ */\r
+ /* @[declare_platform_network_setreceivecallback] */\r
+ IotNetworkError_t ( * setReceiveCallback )( IotNetworkConnection_t pConnection,\r
+ IotNetworkReceiveCallback_t receiveCallback,\r
+ void * pContext );\r
+ /* @[declare_platform_network_setreceivecallback] */\r
+\r
+ /**\r
+ * @brief Send data over a return connection.\r
+ *\r
+ * Attempts to transmit `messageLength` bytes of `pMessage` across the\r
+ * connection represented by `pConnection`. Returns the number of bytes\r
+ * actually sent, `0` on failure.\r
+ *\r
+ * @param[in] pConnection The connection used to send data, defined by the\r
+ * network stack.\r
+ * @param[in] pMessage The message to send.\r
+ * @param[in] messageLength The length of `pMessage`.\r
+ *\r
+ * @return The number of bytes successfully sent, `0` on failure.\r
+ */\r
+ /* @[declare_platform_network_send] */\r
+ size_t ( * send )( IotNetworkConnection_t pConnection,\r
+ const uint8_t * pMessage,\r
+ size_t messageLength );\r
+ /* @[declare_platform_network_send] */\r
+\r
+ /**\r
+ * @brief Block and wait for incoming network data.\r
+ *\r
+ * Wait for a message of size `bytesRequested` to arrive on the network and\r
+ * place it in `pBuffer`.\r
+ *\r
+ * @param[in] pConnection The connection to wait on, defined by the network\r
+ * stack.\r
+ * @param[out] pBuffer Where to place the incoming network data. This buffer\r
+ * must be at least `bytesRequested` in size.\r
+ * @param[in] bytesRequested How many bytes to wait for. `pBuffer` must be at\r
+ * least this size.\r
+ *\r
+ * @return The number of bytes successfully received. This should be\r
+ * `bytesRequested` when successful. Any other value may indicate an error.\r
+ */\r
+ /* @[declare_platform_network_receive] */\r
+ size_t ( * receive )( IotNetworkConnection_t pConnection,\r
+ uint8_t * pBuffer,\r
+ size_t bytesRequested );\r
+\r
+ /* @[declare_platform_network_receive] */\r
+\r
+ /**\r
+ * @brief Read incoming data available in the network buffers.\r
+ *\r
+ * Reads bytes available in the network buffers into `pBuffer`.\r
+ * - If there is less data available than requested, it will return\r
+ * the available number of bytes.\r
+ * - If there is more data available than requested, it will fill the\r
+ * whole `pBuffer`.\r
+ * - If there is no data available, it will return 0.\r
+ *\r
+ * @param[in] pConnection The connection to receive data on, defined by\r
+ * the network stack.\r
+ * @param[out] pBuffer The buffer to place the incoming network data.\r
+ * @param[in] bufferSize The size of `pBuffer`.\r
+ *\r
+ * @return The number of bytes successfully received.\r
+ */\r
+ /* @[declare_platform_network_receiveupto] */\r
+ size_t ( * receiveUpto )( IotNetworkConnection_t pConnection,\r
+ uint8_t * pBuffer,\r
+ size_t bufferSize );\r
+ /* @[declare_platform_network_receiveupto] */\r
+\r
+\r
+ /**\r
+ * @brief Close a network connection.\r
+ *\r
+ * This function closes the connection, but does not release the resources\r
+ * used by the connection. This allows calls to other networking functions\r
+ * to return an error and handle a closed connection without the risk of\r
+ * crashing. Once it can be guaranteed that `pConnection` will no longer be\r
+ * used, the connection can be destroyed with @ref platform_network_function_destroy.\r
+ *\r
+ * In addition to closing the connection, this function should also remove\r
+ * any active [receive callback](@ref platform_network_function_receivecallback).\r
+ *\r
+ * @param[in] pConnection The network connection to close, defined by the\r
+ * network stack.\r
+ *\r
+ * @return Any #IotNetworkError_t, as defined by the network stack.\r
+ *\r
+ * @note It must be safe to call this function on an already-closed connection.\r
+ */\r
+ /* @[declare_platform_network_close] */\r
+ IotNetworkError_t ( * close )( IotNetworkConnection_t pConnection );\r
+ /* @[declare_platform_network_close] */\r
+\r
+ /**\r
+ * @brief Free resources used by a network connection.\r
+ *\r
+ * This function releases the resources of a closed connection. It should be\r
+ * called after @ref platform_network_function_close.\r
+ *\r
+ * @param[in] pConnection The network connection to destroy, defined by\r
+ * the network stack.\r
+ *\r
+ * @return Any #IotNetworkError_t, as defined by the network stack.\r
+ *\r
+ * @attention No function should be called on the network connection after\r
+ * calling this function. This function must be safe to call from a\r
+ * [receive callback](@ref platform_network_function_receivecallback).\r
+ */\r
+ /* @[declare_platform_network_destroy] */\r
+ IotNetworkError_t ( * destroy )( IotNetworkConnection_t pConnection );\r
+ /* @[declare_platform_network_destroy] */\r
+} IotNetworkInterface_t;\r
+\r
+/**\r
+ * @ingroup platform_datatypes_paramstructs\r
+ * @brief Information on the remote server for connection setup.\r
+ *\r
+ * May be passed to #IotNetworkInterface_t.create as `pConnectionInfo`. This\r
+ * structure contains commonly-used parameters, but may be replaced with an\r
+ * alternative.\r
+ */\r
+struct IotNetworkServerInfo\r
+{\r
+ const char * pHostName; /**< @brief Server host name. Must be NULL-terminated. */\r
+ uint16_t port; /**< @brief Server port in host-order. */\r
+};\r
+\r
+/**\r
+ * @ingroup platform_datatypes_paramstructs\r
+ * @brief Contains the credentials necessary for connection setup.\r
+ *\r
+ * May be passed to #IotNetworkInterface_t.create as `pCredentialInfo`. This\r
+ * structure contains commonly-used parameters, but may be replaced with an\r
+ * alternative.\r
+ */\r
+struct IotNetworkCredentials\r
+{\r
+ /**\r
+ * @brief Set this to a non-NULL value to use ALPN.\r
+ *\r
+ * This string must be NULL-terminated.\r
+ *\r
+ * See [this link]\r
+ * (https://aws.amazon.com/blogs/iot/mqtt-with-tls-client-authentication-on-port-443-why-it-is-useful-and-how-it-works/)\r
+ * for more information.\r
+ */\r
+ const char * pAlpnProtos;\r
+\r
+ /**\r
+ * @brief Set this to a non-zero value to use TLS max fragment length\r
+ * negotiation (TLS MFLN).\r
+ *\r
+ * @note The network stack may have a minimum value for this parameter and\r
+ * may return an error if this parameter is too small.\r
+ */\r
+ size_t maxFragmentLength;\r
+\r
+ /**\r
+ * @brief Disable server name indication (SNI) for a TLS session.\r
+ */\r
+ bool disableSni;\r
+\r
+ const char * pRootCa; /**< @brief String representing a trusted server root certificate. */\r
+ size_t rootCaSize; /**< @brief Size associated with #IotNetworkCredentials.pRootCa. */\r
+ const char * pClientCert; /**< @brief String representing the client certificate. */\r
+ size_t clientCertSize; /**< @brief Size associated with #IotNetworkCredentials.pClientCert. */\r
+ const char * pPrivateKey; /**< @brief String representing the client certificate's private key. */\r
+ size_t privateKeySize; /**< @brief Size associated with #IotNetworkCredentials.pPrivateKey. */\r
+};\r
+\r
+#endif /* ifndef IOT_NETWORK_H_ */\r
projects / freertos / blobdiff