git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-IoT-Libraries/abstractions/platform/include/platform/iot_network.h

   1 /*\r
   2  * Amazon FreeRTOS Platform V1.0.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  * http://aws.amazon.com/freertos\r
  23  * http://www.FreeRTOS.org\r
  24  */\r
  25 \r
  26 /**\r
  27  * @file iot_network.h\r
  28  * @brief Abstraction of network functions used by libraries in this SDK.\r
  29  */\r
  30 \r
  31 #ifndef IOT_NETWORK_H_\r
  32 #define IOT_NETWORK_H_\r
  33 \r
  34 /* Standard includes. */\r
  35 #include <stdbool.h>\r
  36 #include <stdint.h>\r
  37 #include <stdlib.h>\r
  38 \r
  39 /**\r
  40  * @ingroup platform_datatypes_enums\r
  41  * @brief Return codes for [network functions](@ref platform_network_functions).\r
  42  */\r
  43 typedef enum IotNetworkError\r
  44 {\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
  51 \r
  52 /**\r
  53  * @page platform_network_functions Networking\r
  54  * @brief Functions of the network abstraction component.\r
  55  *\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
  61  *\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
  71  */\r
  72 \r
  73 /**\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
  81  */\r
  82 \r
  83 /**\r
  84  * @brief Provide an asynchronous notification of incoming network data.\r
  85  *\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
  88  *\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
  92  */\r
  93 /* @[declare_platform_network_receivecallback] */\r
  94 typedef void ( * IotNetworkReceiveCallback_t )( void * pConnection,\r
  95                                                 void * pContext );\r
  96 /* @[declare_platform_network_receivecallback] */\r
  97 \r
  98 /**\r
  99  * @ingroup platform_datatypes_paramstructs\r
 100  * @brief Represents the functions of a network stack.\r
 101  *\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
 104  */\r
 105 typedef struct IotNetworkInterface\r
 106 {\r
 107     /**\r
 108      * @brief Create a new network connection.\r
 109      *\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
 116      * network stack.\r
 117      *\r
 118      * @return Any #IotNetworkError_t, as defined by the network stack.\r
 119      */\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
 125 \r
 126     /**\r
 127      * @brief Register an @ref platform_network_function_receivecallback.\r
 128      *\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
 132      * detached thread.\r
 133      *\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
 137      *\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
 141      *\r
 142      * @return Any #IotNetworkError_t, as defined by the network stack.\r
 143      *\r
 144      * @see platform_network_function_receivecallback\r
 145      */\r
 146     /* @[declare_platform_network_setreceivecallback] */\r
 147     IotNetworkError_t ( * setReceiveCallback )( void * pConnection,\r
 148                                                 IotNetworkReceiveCallback_t receiveCallback,\r
 149                                                 void * pContext );\r
 150     /* @[declare_platform_network_setreceivecallback] */\r
 151 \r
 152     /**\r
 153      * @brief Send data over a return connection.\r
 154      *\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
 158      *\r
 159      * @param[in] pConnection The connection used to send data, defined by the\r
 160      * network stack.\r
 161      * @param[in] pMessage The message to send.\r
 162      * @param[in] messageLength The length of `pMessage`.\r
 163      *\r
 164      * @return The number of bytes successfully sent, `0` on failure.\r
 165      */\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
 171 \r
 172     /**\r
 173      * @brief Block and wait for incoming network data.\r
 174      *\r
 175      * Wait for a message of size `bytesRequested` to arrive on the network and\r
 176      * place it in `pBuffer`.\r
 177      *\r
 178      * @param[in] pConnection The connection to wait on, defined by the network\r
 179      * stack.\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
 183      * least this size.\r
 184      *\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
 187      */\r
 188     /* @[declare_platform_network_receive] */\r
 189     size_t ( * receive )( void * pConnection,\r
 190                           uint8_t * pBuffer,\r
 191                           size_t bytesRequested );\r
 192     /* @[declare_platform_network_receive] */\r
 193 \r
 194     /**\r
 195      * @brief Close a network connection.\r
 196      *\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
 202      *\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
 205      *\r
 206      * @param[in] pConnection The network connection to close, defined by the\r
 207      * network stack.\r
 208      *\r
 209      * @return Any #IotNetworkError_t, as defined by the network stack.\r
 210      *\r
 211      * @note It must be safe to call this function on an already-closed connection.\r
 212      */\r
 213     /* @[declare_platform_network_close] */\r
 214     IotNetworkError_t ( * close )( void * pConnection );\r
 215     /* @[declare_platform_network_close] */\r
 216 \r
 217     /**\r
 218      * @brief Free resources used by a network connection.\r
 219      *\r
 220      * This function releases the resources of a closed connection. It should be\r
 221      * called after @ref platform_network_function_close.\r
 222      *\r
 223      * @param[in] pConnection The network connection to destroy, defined by\r
 224      * the network stack.\r
 225      *\r
 226      * @return Any #IotNetworkError_t, as defined by the network stack.\r
 227      *\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
 231      */\r
 232     /* @[declare_platform_network_destroy] */\r
 233     IotNetworkError_t ( * destroy )( void * pConnection );\r
 234     /* @[declare_platform_network_destroy] */\r
 235 } IotNetworkInterface_t;\r
 236 \r
 237 /**\r
 238  * @ingroup platform_datatypes_paramstructs\r
 239  * @brief Information on the remote server for connection setup.\r
 240  *\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
 243  * alternative.\r
 244  */\r
 245 typedef struct IotNetworkServerInfo\r
 246 {\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
 250 \r
 251 /**\r
 252  * @ingroup platform_datatypes_paramstructs\r
 253  * @brief Contains the credentials necessary for connection setup.\r
 254  *\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
 257  * alternative.\r
 258  */\r
 259 typedef struct IotNetworkCredentials\r
 260 {\r
 261     /**\r
 262      * @brief Set this to a non-NULL value to use ALPN.\r
 263      *\r
 264      * This string must be NULL-terminated.\r
 265      *\r
 266      * See [this link]\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
 269      */\r
 270     const char * pAlpnProtos;\r
 271 \r
 272     /**\r
 273      * @brief Set this to a non-zero value to use TLS max fragment length\r
 274      * negotiation (TLS MFLN).\r
 275      *\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
 278      */\r
 279     size_t maxFragmentLength;\r
 280 \r
 281     /**\r
 282      * @brief Disable server name indication (SNI) for a TLS session.\r
 283      */\r
 284     bool disableSni;\r
 285 \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
 293 \r
 294 #endif /* ifndef IOT_NETWORK_H_ */\r