git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/FreeRTOS-IoT-Libraries/c_sdk/platform/iot_network.h

   1 /*\r
   2  * IoT Platform V1.1.0\r
   3  * Copyright (C) 2019 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  *\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
  11  *\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
  14  *\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
  21  */\r
  22 \r
  23 /**\r
  24  * @file iot_network.h\r
  25  * @brief Abstraction of network functions used by libraries in this SDK.\r
  26  */\r
  27 \r
  28 #ifndef IOT_NETWORK_H_\r
  29 #define IOT_NETWORK_H_\r
  30 \r
  31 /* The config header is always included first. */\r
  32 #include "iot_config.h"\r
  33 \r
  34 /* Standard includes. */\r
  35 #include <stdint.h>\r
  36 #include <stdlib.h>\r
  37 \r
  38 /**\r
  39  * @ingroup platform_datatypes_enums\r
  40  * @brief Return codes for [network functions](@ref platform_network_functions).\r
  41  */\r
  42 typedef enum IotNetworkError\r
  43 {\r
  44     IOT_NETWORK_SUCCESS = 0,   /**< Function successfully completed. */\r
  45     IOT_NETWORK_FAILURE,       /**< Generic failure not covered by other values. */\r
  46     IOT_NETWORK_BAD_PARAMETER, /**< At least one parameter was invalid. */\r
  47     IOT_NETWORK_NO_MEMORY,     /**< Memory allocation failed. */\r
  48     IOT_NETWORK_SYSTEM_ERROR   /**< An error occurred when calling a system API. */\r
  49 } IotNetworkError_t;\r
  50 \r
  51 /**\r
  52  * @page platform_network_functions Networking\r
  53  * @brief Functions of the network abstraction component.\r
  54  *\r
  55  * The network abstraction component does not declare functions, but uses function\r
  56  * pointers instead. This allows multiple network stacks to be used at the same time.\r
  57  * Libraries that require the network will request an #IotNetworkInterface_t\r
  58  * parameter. The members of the #IotNetworkInterface_t will be called whenever\r
  59  * the library interacts with the network.\r
  60  *\r
  61  * The following function pointers are associated with an #IotNetworkInterface_t.\r
  62  * Together, they represent a network stack.\r
  63  * - @functionname{platform_network_function_create}\r
  64  * - @functionname{platform_network_function_setreceivecallback}\r
  65  * - @functionname{platform_network_function_send}\r
  66  * - @functionname{platform_network_function_receive}\r
  67  * - @functionname{platform_network_function_close}\r
  68  * - @functionname{platform_network_function_destroy}\r
  69  * - @functionname{platform_network_function_receivecallback}\r
  70  */\r
  71 \r
  72 /**\r
  73  * @functionpage{IotNetworkInterface_t::create,platform_network,create}\r
  74  * @functionpage{IotNetworkInterface_t::setReceiveCallback,platform_network,setreceivecallback}\r
  75  * @functionpage{IotNetworkInterface_t::send,platform_network,send}\r
  76  * @functionpage{IotNetworkInterface_t::receive,platform_network,receive}\r
  77  * @functionpage{IotNetworkInterface_t::close,platform_network,close}\r
  78  * @functionpage{IotNetworkInterface_t::destroy,platform_network,destroy}\r
  79  * @functionpage{IotNetworkReceiveCallback_t,platform_network,receivecallback}\r
  80  */\r
  81 \r
  82 /**\r
  83  * @brief Provide an asynchronous notification of incoming network data.\r
  84  *\r
  85  * A function with this signature may be set with @ref platform_network_function_setreceivecallback\r
  86  * to be invoked when data is available on the network.\r
  87  *\r
  88  * @param[in] pConnection The connection on which data is available, defined by\r
  89  * the network stack.\r
  90  * @param[in] pContext The third argument passed to @ref platform_network_function_setreceivecallback.\r
  91  */\r
  92 /* @[declare_platform_network_receivecallback] */\r
  93 typedef void ( * IotNetworkReceiveCallback_t )( IotNetworkConnection_t pConnection,\r
  94                                                 void * pContext );\r
  95 /* @[declare_platform_network_receivecallback] */\r
  96 \r
  97 /**\r
  98  * @ingroup platform_datatypes_paramstructs\r
  99  * @brief Represents the functions of a network stack.\r
 100  *\r
 101  * Functions that match these signatures should be implemented against a system's\r
 102  * network stack. See the `platform` directory for existing implementations.\r
 103  */\r
 104 typedef struct IotNetworkInterface\r
 105 {\r
 106     /**\r
 107      * @brief Create a new network connection.\r
 108      *\r
 109      * This function allocates resources and establishes a new network connection.\r
 110      * @param[in] pServerInfo Represents information needed to set up the\r
 111      * new connection, defined by the network stack.\r
 112      * @param[in] pCredentialInfo Represents information needed to secure the\r
 113      * new connection, defined by the network stack.\r
 114      * @param[out] pConnection Set to represent a new connection, defined by the\r
 115      * network stack.\r
 116      *\r
 117      * @return Any #IotNetworkError_t, as defined by the network stack.\r
 118      */\r
 119     /* @[declare_platform_network_create] */\r
 120     IotNetworkError_t ( * create )( IotNetworkServerInfo_t pServerInfo,\r
 121                                     IotNetworkCredentials_t pCredentialInfo,\r
 122                                     IotNetworkConnection_t * pConnection );\r
 123     /* @[declare_platform_network_create] */\r
 124 \r
 125     /**\r
 126      * @brief Register an @ref platform_network_function_receivecallback.\r
 127      *\r
 128      * Sets an @ref platform_network_function_receivecallback to be called\r
 129      * asynchronously when data arrives on the network. The network stack\r
 130      * should invoke this function "as if" it were the thread routine of a\r
 131      * detached thread.\r
 132      *\r
 133      * Each network connection may only have one receive callback at any time.\r
 134      * @ref platform_network_function_close is expected to remove any active\r
 135      * receive callbacks.\r
 136      *\r
 137      * @param[in] pConnection The connection to associate with the receive callback.\r
 138      * @param[in] receiveCallback The function to invoke for incoming network data.\r
 139      * @param[in] pContext A value to pass as the first parameter to the receive callback.\r
 140      *\r
 141      * @return Any #IotNetworkError_t, as defined by the network stack.\r
 142      *\r
 143      * @see platform_network_function_receivecallback\r
 144      */\r
 145     /* @[declare_platform_network_setreceivecallback] */\r
 146     IotNetworkError_t ( * setReceiveCallback )( IotNetworkConnection_t pConnection,\r
 147                                                 IotNetworkReceiveCallback_t receiveCallback,\r
 148                                                 void * pContext );\r
 149     /* @[declare_platform_network_setreceivecallback] */\r
 150 \r
 151     /**\r
 152      * @brief Send data over a return connection.\r
 153      *\r
 154      * Attempts to transmit `messageLength` bytes of `pMessage` across the\r
 155      * connection represented by `pConnection`. Returns the number of bytes\r
 156      * actually sent, `0` on failure.\r
 157      *\r
 158      * @param[in] pConnection The connection used to send data, defined by the\r
 159      * network stack.\r
 160      * @param[in] pMessage The message to send.\r
 161      * @param[in] messageLength The length of `pMessage`.\r
 162      *\r
 163      * @return The number of bytes successfully sent, `0` on failure.\r
 164      */\r
 165     /* @[declare_platform_network_send] */\r
 166     size_t ( * send )( IotNetworkConnection_t pConnection,\r
 167                        const uint8_t * pMessage,\r
 168                        size_t messageLength );\r
 169     /* @[declare_platform_network_send] */\r
 170 \r
 171     /**\r
 172      * @brief Block and wait for incoming network data.\r
 173      *\r
 174      * Wait for a message of size `bytesRequested` to arrive on the network and\r
 175      * place it in `pBuffer`.\r
 176      *\r
 177      * @param[in] pConnection The connection to wait on, defined by the network\r
 178      * stack.\r
 179      * @param[out] pBuffer Where to place the incoming network data. This buffer\r
 180      * must be at least `bytesRequested` in size.\r
 181      * @param[in] bytesRequested How many bytes to wait for. `pBuffer` must be at\r
 182      * least this size.\r
 183      *\r
 184      * @return The number of bytes successfully received. This should be\r
 185      * `bytesRequested` when successful. Any other value may indicate an error.\r
 186      */\r
 187     /* @[declare_platform_network_receive] */\r
 188     size_t ( * receive )( IotNetworkConnection_t pConnection,\r
 189                           uint8_t * pBuffer,\r
 190                           size_t bytesRequested );\r
 191 \r
 192     /* @[declare_platform_network_receive] */\r
 193 \r
 194     /**\r
 195      * @brief Read incoming data available in the network buffers.\r
 196      *\r
 197      * Reads bytes available in the network buffers into `pBuffer`.\r
 198      * - If there is less data available than requested, it will return\r
 199      *   the available number of bytes.\r
 200      * - If there is more data available than requested, it will fill the\r
 201      *   whole `pBuffer`.\r
 202      * - If there is no data available, it will return 0.\r
 203      *\r
 204      * @param[in] pConnection The connection to receive data on, defined by\r
 205      * the network stack.\r
 206      * @param[out] pBuffer The buffer to place the incoming network data.\r
 207      * @param[in] bufferSize The size of `pBuffer`.\r
 208      *\r
 209      * @return The number of bytes successfully received.\r
 210      */\r
 211     /* @[declare_platform_network_receiveupto] */\r
 212     size_t ( * receiveUpto )( IotNetworkConnection_t pConnection,\r
 213                               uint8_t * pBuffer,\r
 214                               size_t bufferSize );\r
 215     /* @[declare_platform_network_receiveupto] */\r
 216 \r
 217 \r
 218     /**\r
 219      * @brief Close a network connection.\r
 220      *\r
 221      * This function closes the connection, but does not release the resources\r
 222      * used by the connection. This allows calls to other networking functions\r
 223      * to return an error and handle a closed connection without the risk of\r
 224      * crashing. Once it can be guaranteed that `pConnection` will no longer be\r
 225      * used, the connection can be destroyed with @ref platform_network_function_destroy.\r
 226      *\r
 227      * In addition to closing the connection, this function should also remove\r
 228      * any active [receive callback](@ref platform_network_function_receivecallback).\r
 229      *\r
 230      * @param[in] pConnection The network connection to close, defined by the\r
 231      * network stack.\r
 232      *\r
 233      * @return Any #IotNetworkError_t, as defined by the network stack.\r
 234      *\r
 235      * @note It must be safe to call this function on an already-closed connection.\r
 236      */\r
 237     /* @[declare_platform_network_close] */\r
 238     IotNetworkError_t ( * close )( IotNetworkConnection_t pConnection );\r
 239     /* @[declare_platform_network_close] */\r
 240 \r
 241     /**\r
 242      * @brief Free resources used by a network connection.\r
 243      *\r
 244      * This function releases the resources of a closed connection. It should be\r
 245      * called after @ref platform_network_function_close.\r
 246      *\r
 247      * @param[in] pConnection The network connection to destroy, defined by\r
 248      * the network stack.\r
 249      *\r
 250      * @return Any #IotNetworkError_t, as defined by the network stack.\r
 251      *\r
 252      * @attention No function should be called on the network connection after\r
 253      * calling this function. This function must be safe to call from a\r
 254      * [receive callback](@ref platform_network_function_receivecallback).\r
 255      */\r
 256     /* @[declare_platform_network_destroy] */\r
 257     IotNetworkError_t ( * destroy )( IotNetworkConnection_t pConnection );\r
 258     /* @[declare_platform_network_destroy] */\r
 259 } IotNetworkInterface_t;\r
 260 \r
 261 /**\r
 262  * @ingroup platform_datatypes_paramstructs\r
 263  * @brief Information on the remote server for connection setup.\r
 264  *\r
 265  * May be passed to #IotNetworkInterface_t.create as `pConnectionInfo`. This\r
 266  * structure contains commonly-used parameters, but may be replaced with an\r
 267  * alternative.\r
 268  */\r
 269 struct IotNetworkServerInfo\r
 270 {\r
 271     const char * pHostName; /**< @brief Server host name. Must be NULL-terminated. */\r
 272     uint16_t port;          /**< @brief Server port in host-order. */\r
 273 };\r
 274 \r
 275 /**\r
 276  * @ingroup platform_datatypes_paramstructs\r
 277  * @brief Contains the credentials necessary for connection setup.\r
 278  *\r
 279  * May be passed to #IotNetworkInterface_t.create as `pCredentialInfo`. This\r
 280  * structure contains commonly-used parameters, but may be replaced with an\r
 281  * alternative.\r
 282  */\r
 283 struct IotNetworkCredentials\r
 284 {\r
 285     /**\r
 286      * @brief Set this to a non-NULL value to use ALPN.\r
 287      *\r
 288      * This string must be NULL-terminated.\r
 289      *\r
 290      * See [this link]\r
 291      * (https://aws.amazon.com/blogs/iot/mqtt-with-tls-client-authentication-on-port-443-why-it-is-useful-and-how-it-works/)\r
 292      * for more information.\r
 293      */\r
 294     const char * pAlpnProtos;\r
 295 \r
 296     /**\r
 297      * @brief Set this to a non-zero value to use TLS max fragment length\r
 298      * negotiation (TLS MFLN).\r
 299      *\r
 300      * @note The network stack may have a minimum value for this parameter and\r
 301      * may return an error if this parameter is too small.\r
 302      */\r
 303     size_t maxFragmentLength;\r
 304 \r
 305     /**\r
 306      * @brief Disable server name indication (SNI) for a TLS session.\r
 307      */\r
 308     bool disableSni;\r
 309 \r
 310     const char * pRootCa;     /**< @brief String representing a trusted server root certificate. */\r
 311     size_t rootCaSize;        /**< @brief Size associated with #IotNetworkCredentials.pRootCa. */\r
 312     const char * pClientCert; /**< @brief String representing the client certificate. */\r
 313     size_t clientCertSize;    /**< @brief Size associated with #IotNetworkCredentials.pClientCert. */\r
 314     const char * pPrivateKey; /**< @brief String representing the client certificate's private key. */\r
 315     size_t privateKeySize;    /**< @brief Size associated with #IotNetworkCredentials.pPrivateKey. */\r
 316 };\r
 317 \r
 318 #endif /* ifndef IOT_NETWORK_H_ */\r