git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/FreeRTOS-IoT-Libraries/c_sdk/standard/mqtt/include/iot_mqtt_serialize.h

   1 /*\r
   2  * IoT MQTT V2.1.0\r
   3  * Copyright (C) 2018 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_mqtt_serialize.h\r
  25  * @brief User-facing functions for serializing MQTT 3.1.1 packets. This header should\r
  26  * be included for building a single threaded light-weight MQTT client bypassing\r
  27  * stateful CSDK MQTT library.\r
  28  */\r
  29 \r
  30 #ifndef _IOT_MQTT_SERIALIZE_H_\r
  31 #define _IOT_MQTT_SERIALIZE_H_\r
  32 \r
  33 /* The config header is always included first. */\r
  34 #include "iot_config.h"\r
  35 \r
  36 /* MQTT types include. */\r
  37 #include "types/iot_mqtt_types.h"\r
  38 \r
  39 /*------------------------- MQTT library functions --------------------------*/\r
  40 \r
  41 /**\r
  42  * @functionspage{mqtt,MQTT library}\r
  43  * - @functionname{mqtt_function_getconnectpacketsize}\r
  44  * - @functionname{mqtt_function_serializeconnect}\r
  45  * - @functionname{mqtt_function_getsubscriptionpacketsize}\r
  46  * - @functionname{mqtt_function_serializesubscribe}\r
  47  * - @functionname{mqtt_function_serializeunsubscribe}\r
  48  * - @functionname{mqtt_function_getpublishpacketsize}\r
  49  * - @functionname{mqtt_function_serializepublish}\r
  50  * - @functionname{mqtt_function_serializedisconnect}\r
  51  * - @functionname{mqtt_function_serializepingreq}\r
  52  * - @functionname{mqtt_function_getincomingmqttpackettypeandlength}\r
  53  * - @functionname{mqtt_function_deserializeresponse}\r
  54  * - @functionname{mqtt_function_deserializepublish}\r
  55  */\r
  56 \r
  57 /**\r
  58  * @functionpage{IotMqtt_GetConnectPacketSize,mqtt,getconnectpacketsize}\r
  59  * @functionpage{IotMqtt_SerializeConnect,mqtt,serializeconnect}\r
  60  * @functionpage{IotMqtt_GetSubscriptionPacketSize,mqtt,getsubscriptionpacketsize}\r
  61  * @functionpage{IotMqtt_SerializeSubscribe,mqtt,serializesubscribe}\r
  62  * @functionpage{IotMqtt_SerializeUnsubscribe,mqtt,serializeunsubscribe}\r
  63  * @functionpage{IotMqtt_GetPublishPacketSize,mqtt,getpublishpacketsize}\r
  64  * @functionpage{IotMqtt_SerializePublish,mqtt,serializepublish}\r
  65  * @functionpage{IotMqtt_SerializeDisconnect,mqtt,serializedisconnect}\r
  66  * @functionpage{IotMqtt_SerializePingreq,mqtt,serializepingreq}\r
  67  * @functionpage{IotMqtt_GetIncomingMQTTPacketTypeAndLength,mqtt,getincomingmqttpackettypeandlength}\r
  68  * @functionpage{IotMqtt_DeserializeResponse,mqtt,deserializeresponse}\r
  69  * @functionpage{IotMqtt_DeserializePublish,mqtt,deserializepublish}\r
  70  */\r
  71 \r
  72 /**\r
  73  * @brief Calculate the size and "Remaining length" of a CONNECT packet generated\r
  74  * from the given parameters.\r
  75  *\r
  76  * @param[in] pConnectInfo User-provided CONNECT information struct.\r
  77  * @param[out] pRemainingLength Output for calculated "Remaining length" field.\r
  78  * @param[out] pPacketSize Output for calculated total packet size.\r
  79  *\r
  80  * @return IOT_MQTT_SUCCESS if the packet is within the length allowed by MQTT 3.1.1 spec;\r
  81  * IOT_MQTT_BAD_PARAMETER otherwise. If this function returns `IOT_MQTT_BAD_PARAMETER`,\r
  82  * the output parameters should be ignored.\r
  83  *\r
  84  * @note This call is part of serializer API used for implementing light-weight MQTT client.\r
  85  * \r
  86  * <b>Example</b>\r
  87  * @code{c}\r
  88  * // Example code below shows how IotMqtt_GetConnectPacketSize() should be used to calculate\r
  89  * // the size of connect request. \r
  90  *\r
  91  * IotMqttConnectInfo_t xConnectInfo;\r
  92  * size_t xRemainingLength = 0;\r
  93  * size_t xPacketSize = 0;\r
  94  * IotMqttError_t xResult;\r
  95  * \r
  96  * // start with everything set to zero\r
  97  * memset( ( void * ) &xConnectInfo, 0x00, sizeof( xConnectInfo ) );\r
  98  *      \r
  99  * // Initialize connection info, details are out of scope for this example.\r
 100  * _initializeConnectInfo( &xConnectInfo );\r
 101  * // Get size requirement for the connect packet \r
 102  * xResult = IotMqtt_GetConnectPacketSize( &xConnectInfo, &xRemainingLength, &xPacketSize );\r
 103  * IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );\r
 104  *\r
 105  *  // Application should allocate buffer with size == xPacketSize or use static buffer\r
 106  *  // with size >= xPacketSize to serialize connect request.\r
 107  * @endcode\r
 108  */\r
 109 /* @[declare_mqtt_getconnectpacketsize] */\r
 110 IotMqttError_t IotMqtt_GetConnectPacketSize( const IotMqttConnectInfo_t * pConnectInfo,\r
 111                                              size_t * pRemainingLength,\r
 112                                              size_t * pPacketSize );\r
 113 /* @[declare_mqtt_getconnectpacketsize] */\r
 114 \r
 115 /**\r
 116  * @brief Generate a CONNECT packet from the given parameters.\r
 117  *\r
 118  * @param[in] pConnectInfo User-provided CONNECT information.\r
 119  * @param[in] remainingLength remaining length of the packet to be serialized.\r
 120  * @param[in, out] pBuffer User provided buffer where the CONNECT packet is written.\r
 121  * @param[in] bufferSize Size of the buffer pointed to by pBuffer.\r
 122  *\r
 123  * @return #IOT_MQTT_SUCCESS or #IOT_MQTT_NO_MEMORY.\r
 124  *\r
 125  * @note pBuffer must be allocated by caller. Use @ref mqtt_function_getconnectpacketsize\r
 126  * to determine the required size.\r
 127  * @note This call is part of serializer API used for implementing light-weight MQTT client.\r
 128  * \r
 129  * <b>Example</b>\r
 130  * @code{c}\r
 131  * // Example code below shows how IotMqtt_SerializeConnect() should be used to serialize\r
 132  * // MQTT connect packet and send it to MQTT broker.\r
 133  * // Example uses static memory but dynamically allocated memory can be used as well.\r
 134  * // Get size requirement for the connect packet.\r
 135  * \r
 136  * #define mqttexampleSHARED_BUFFER_SIZE 100\r
 137  * static ucSharedBuffer[mqttexampleSHARED_BUFFER_SIZE];\r
 138  * void sendConnectPacket( int xMQTTSocket )\r
 139  * {\r
 140  *    IotMqttConnectInfo_t xConnectInfo;\r
 141  *    size_t xRemainingLength = 0;\r
 142  *    size_t xPacketSize = 0;\r
 143  *    IotMqttError_t xResult;\r
 144  *    size_t xSentBytes = 0;\r
 145  *    // Get size requirement for MQTT connect packet.\r
 146  *    xResult = IotMqtt_GetConnectPacketSize( &xConnectInfo, &xRemainingLength, &xPacketSize );\r
 147  *    IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );\r
 148  *    // Make sure the packet size is less than static buffer size\r
 149  *    IotMqtt_Assert( xPacketSize < mqttexampleSHARED_BUFFER_SIZE );\r
 150  *    // Serialize MQTT connect packet into provided buffer\r
 151  *    xResult = IotMqtt_SerializeConnect( &xConnectInfo, xRemainingLength, ucSharedBuffer, xPacketSize );\r
 152  *    IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS ); \r
 153  *    // xMQTTSocket here is posix socket created and connected to MQTT broker outside of this function.\r
 154  *    xSentBytes = send( xMQTTSocket, ( void * ) ucSharedBuffer, xPacketSize, 0 );\r
 155  *    IotMqtt_Assert( xSentBytes == xPacketSize );\r
 156  * }\r
 157  * @endcode\r
 158  */\r
 159 /* @[declare_mqtt_serializeconnect] */\r
 160 IotMqttError_t IotMqtt_SerializeConnect( const IotMqttConnectInfo_t * pConnectInfo,\r
 161                                          size_t remainingLength,\r
 162                                          uint8_t * pBuffer,\r
 163                                          size_t bufferSize );\r
 164 /* @[declare_mqtt_serializeconnect] */\r
 165 \r
 166 /**\r
 167  * @brief Calculate the size and "Remaining length" of a SUBSCRIBE or UNSUBSCRIBE\r
 168  * packet generated from the given parameters.\r
 169  *\r
 170  * @param[in] type Either IOT_MQTT_SUBSCRIBE or IOT_MQTT_UNSUBSCRIBE.\r
 171  * @param[in] pSubscriptionList User-provided array of subscriptions.\r
 172  * @param[in] subscriptionCount Size of `pSubscriptionList`.\r
 173  * @param[out] pRemainingLength Output for calculated "Remaining length" field.\r
 174  * @param[out] pPacketSize Output for calculated total packet size.\r
 175  *\r
 176  * @return IOT_MQTT_SUCCESS if the packet is within the length allowed by MQTT 3.1.1 spec;\r
 177  * IOT_MQTT_BAD_PARAMETER otherwise. If this function returns IOT_MQTT_BAD_PARAMETER,\r
 178  * the output parameters should be ignored.\r
 179  *\r
 180  * @note This call is part of serializer API used for implementing light-weight MQTT client.\r
 181  * \r
 182  * <b>Example</b>\r
 183  * @code{c}\r
 184  * // Example code below shows how IotMqtt_GetSubscriptionPacketSize() should be used to calculate\r
 185  * // the size of subscribe or unsubscribe request. \r
 186  *\r
 187  * IotMqttError_t xResult;\r
 188  * IotMqttSubscription_t xMQTTSubscription[ 1 ];\r
 189  * size_t xRemainingLength = 0;\r
 190  * size_t xPacketSize = 0;\r
 191  * \r
 192  * // Initialize Subscribe parameters. Details are out of scope for this example.\r
 193  * // It will involve setting QOS, topic filter  and topic filter length. \r
 194  *  _initializeSubscribe( xMQTTSubscription );\r
 195  *\r
 196  * xResult = IotMqtt_GetSubscriptionPacketSize( IOT_MQTT_SUBSCRIBE,\r
 197  *                                                                                               xMQTTSubscription,\r
 198  *                                                                                               sizeof( xMQTTSubscription ) / sizeof( IotMqttSubscription_t ),\r
 199  *                                                                                               &xRemainingLength, &xPacketSize );\r
 200  * IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );\r
 201  *\r
 202  * // Application should allocate buffer with size == xPacketSize or use static buffer\r
 203  * // with size >= xPacketSize to serialize connect request.\r
 204  * @endcode\r
 205  */\r
 206 /* @[declare_mqtt_getsubscriptionpacketsize] */\r
 207 IotMqttError_t IotMqtt_GetSubscriptionPacketSize( IotMqttOperationType_t type,\r
 208                                                   const IotMqttSubscription_t * pSubscriptionList,\r
 209                                                   size_t subscriptionCount,\r
 210                                                   size_t * pRemainingLength,\r
 211                                                   size_t * pPacketSize );\r
 212 /* @[declare_mqtt_getsubscriptionpacketsize] */\r
 213 \r
 214 /**\r
 215  * @brief Generate a SUBSCRIBE packet from the given parameters.\r
 216  *\r
 217  * @param[in] pSubscriptionList User-provided array of subscriptions.\r
 218  * @param[in] subscriptionCount Size of `pSubscriptionList`.\r
 219  * @param[in] remainingLength remaining length of the packet to be serialized.\r
 220  * @param[out] pPacketIdentifier The packet identifier generated for this SUBSCRIBE.\r
 221  * @param[in, out] pBuffer User provide buffer where the SUBSCRIBE packet is written.\r
 222  * @param[in] bufferSize Size of the buffer pointed to by pBuffer.\r
 223  *\r
 224  * @return #IOT_MQTT_SUCCESS or #IOT_MQTT_NO_MEMORY.\r
 225  *\r
 226  * @note pBuffer must be allocated by caller.\r
 227  * @note This call is part of serializer API used for implementing light-weight MQTT client.\r
 228  * <b>Example</b>\r
 229  * @code{c}\r
 230  * // Example code below shows how IotMqtt_SerializeSubscribe() should be used to serialize\r
 231  * // MQTT Subscribe packet and send it to MQTT broker.\r
 232  * // Example uses static memory, but dynamically allocated memory can be used as well.\r
 233  * // Get size requirement for the MQTT subscribe packet.\r
 234  * \r
 235  * #define mqttexampleSHARED_BUFFER_SIZE 100\r
 236  * static ucSharedBuffer[mqttexampleSHARED_BUFFER_SIZE];\r
 237  * void sendSubscribePacket( int xMQTTSocket )\r
 238  * {\r
 239  *    IotMqttSubscription_t xMQTTSubscription[ 1 ];\r
 240  *    size_t xRemainingLength = 0;\r
 241  *    size_t xPacketSize = 0;\r
 242  *    IotMqttError_t xResult;\r
 243  *    size_t xSentBytes = 0;\r
 244  *  \r
 245  *    // Initialize Subscribe parameters. Details are out of scope for this example.\r
 246  *    // It will involve setting QOS, topic filter  and topic filter length. \r
 247  *    _initializeSubscribe( xMQTTSubscription );\r
 248  *    // Get size requirement for MQTT Subscribe packet.\r
 249  *    xResult = IotMqtt_GetSubscriptionPacketSize( IOT_MQTT_SUBSCRIBE,\r
 250  *                                                                                               xMQTTSubscription,\r
 251  *                                                                                               sizeof( xMQTTSubscription ) / sizeof( IotMqttSubscription_t ),\r
 252  *                                                                                               &xRemainingLength, &xPacketSize );\r
 253  *    IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );\r
 254  *    // Make sure the packet size is less than static buffer size.\r
 255  *    IotMqtt_Assert( xPacketSize < mqttexampleSHARED_BUFFER_SIZE );\r
 256  * \r
 257  *    // Serialize subscribe into statically allocated ucSharedBuffer.\r
 258  *         xResult = IotMqtt_SerializeSubscribe( xMQTTSubscription, \r
 259  *                                                                                sizeof( xMQTTSubscription ) / sizeof( IotMqttSubscription_t ),\r
 260  *                                                                                xRemainingLength,\r
 261  *                                                                                &usPacketIdentifier,\r
 262  *                                                                                ucSharedBuffer,\r
 263  *                                                                                xPacketSize );\r
 264  *    IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS ); \r
 265  *    // xMQTTSocket here is posix socket created and connected to MQTT broker outside of this function.\r
 266  *    xSentBytes = send( xMQTTSocket, ( void * ) ucSharedBuffer, xPacketSize, 0 );\r
 267  *    IotMqtt_Assert( xSentBytes == xPacketSize );\r
 268  * }\r
 269  * @endcode\r
 270  */\r
 271 /* @[declare_mqtt_serializesubscribe] */\r
 272 IotMqttError_t IotMqtt_SerializeSubscribe( const IotMqttSubscription_t * pSubscriptionList,\r
 273                                            size_t subscriptionCount,\r
 274                                            size_t remainingLength,\r
 275                                            uint16_t * pPacketIdentifier,\r
 276                                            uint8_t * pBuffer,\r
 277                                            size_t bufferSize );\r
 278 /* @[declare_mqtt_serializesubscribe] */\r
 279 \r
 280 /**\r
 281  * @brief Generate a UNSUBSCRIBE packet from the given parameters.\r
 282  *\r
 283  * @param[in] pSubscriptionList User-provided array of subscriptions to remove.\r
 284  * @param[in] subscriptionCount Size of `pSubscriptionList`.\r
 285  * @param[in] remainingLength remaining length of the packet to be serialized.\r
 286  * @param[out] pPacketIdentifier The packet identifier generated for this UNSUBSCRIBE.\r
 287  * @param[in, out] pBuffer User provide buffer where the UNSUBSCRIBE packet is written.\r
 288  * @param[in] bufferSize Size of the buffer pointed to by pBuffer.\r
 289  *\r
 290  * @return #IOT_MQTT_SUCCESS or #IOT_MQTT_NO_MEMORY.\r
 291  *\r
 292  * @note pBuffer must be allocated by caller.\r
 293  * @note This call is part of serializer API used for implementing light-weight MQTT client.\r
 294  * \r
 295  * <b>Example</b>\r
 296  * @code{c}\r
 297  * // Example code below shows how IotMqtt_SerializeUnsubscribe() should be used to serialize\r
 298  * // MQTT unsubscribe packet and send it to MQTT broker.\r
 299  * // Example uses static memory, but dynamically allocated memory can be used as well.\r
 300  * // Get size requirement for the Unsubscribe packet.\r
 301  * \r
 302  * #define mqttexampleSHARED_BUFFER_SIZE 100\r
 303  * static ucSharedBuffer[mqttexampleSHARED_BUFFER_SIZE];\r
 304  * void sendUnsubscribePacket( int xMQTTSocket )\r
 305  * {\r
 306  *    // Following example shows one topic example.\r
 307  *    IotMqttSubscription_t xMQTTSubscription[ 1 ];\r
 308  *    size_t xRemainingLength = 0;\r
 309  *    size_t xPacketSize = 0;\r
 310  *    IotMqttError_t xResult;\r
 311  *    size_t xSentBytes = 0;\r
 312  *    // Get size requirement for MQTT unsubscribe packet.\r
 313  *    xResult = IotMqtt_GetSubscriptionPacketSize( IOT_MQTT_UNSUBSCRIBE,\r
 314  *                                                                                               xMQTTSubscription,\r
 315  *                                                                                               sizeof( xMQTTSubscription ) / sizeof( IotMqttSubscription_t ),\r
 316  *                                                                                               &xRemainingLength, &xPacketSize );\r
 317  *    IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );\r
 318  *    // Make sure the packet size is less than static buffer size.\r
 319  *    IotMqtt_Assert( xPacketSize < mqttexampleSHARED_BUFFER_SIZE );\r
 320  *    // Serialize subscribe into statically allocated ucSharedBuffer.\r
 321  *         xResult = IotMqtt_SerializeUnsubscribe( xMQTTSubscription, \r
 322  *                                                                                sizeof( xMQTTSubscription ) / sizeof( IotMqttSubscription_t ),\r
 323  *                                                                                xRemainingLength,\r
 324  *                                                                                &usPacketIdentifier,\r
 325  *                                                                                ucSharedBuffer,\r
 326  *                                                                                xPacketSize );\r
 327  *    IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS ); \r
 328  *    // xMQTTSocket here is posix socket created and connected to MQTT broker outside of this function.\r
 329  *    xSentBytes = send( xMQTTSocket, ( void * ) ucSharedBuffer, xPacketSize, 0 );\r
 330  *    IotMqtt_Assert( xSentBytes == xPacketSize );\r
 331  * }\r
 332  * @endcode\r
 333  */\r
 334 /* @[declare_mqtt_serializeunsubscribe] */\r
 335 IotMqttError_t IotMqtt_SerializeUnsubscribe( const IotMqttSubscription_t * pSubscriptionList,\r
 336                                              size_t subscriptionCount,\r
 337                                              size_t remainingLength,\r
 338                                              uint16_t * pPacketIdentifier,\r
 339                                              uint8_t * pBuffer,\r
 340                                              size_t bufferSize );\r
 341 /* @[declare_mqtt_serializeunsubscribe] */\r
 342 \r
 343 /**\r
 344  * @brief Calculate the size and "Remaining length" of a PUBLISH packet generated\r
 345  * from the given parameters.\r
 346  *\r
 347  * @param[in] pPublishInfo User-provided PUBLISH information struct.\r
 348  * @param[out] pRemainingLength Output for calculated "Remaining length" field.\r
 349  * @param[out] pPacketSize Output for calculated total packet size.\r
 350  *\r
 351  * @return IOT_MQTT_SUCCESS if the packet is within the length allowed by MQTT 3.1.1 spec;\r
 352  * IOT_MQTT_BAD_PARAMETER otherwise. If this function returns IOT_MQTT_BAD_PARAMETER,\r
 353  * the output parameters should be ignored.\r
 354  *\r
 355  * @note This call is part of serializer API used for implementing light-weight MQTT client.\r
 356  * \r
 357  * <b>Example</b>\r
 358  * @code{c}\r
 359  * // Example code below shows how IotMqtt_GetPublishPacketSize() should be used to calculate\r
 360  * // the size of MQTT publish request. \r
 361  *\r
 362  * IotMqttError_t xResult;\r
 363  * IotMqttPublishInfo_t xMQTTPublishInfo;\r
 364  * size_t xRemainingLength = 0;\r
 365  * size_t xPacketSize = 0;\r
 366  * \r
 367  * // Initialize Publish parameters. Details are out of scope for this example.\r
 368  * // It will involve setting QOS, topic filter, topic filter length, payload\r
 369  * // payload length\r
 370  *  _initializePublish( &xMQTTPublishInfo );\r
 371  *\r
 372  * // Find out length of Publish packet size.\r
 373  * xResult = IotMqtt_GetPublishPacketSize( &xMQTTPublishInfo, &xRemainingLength, &xPacketSize );\r
 374  * IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );\r
 375  *\r
 376  * // Application should allocate buffer with size == xPacketSize or use static buffer\r
 377  * // with size >= xPacketSize to serialize connect request.\r
 378  * @endcode\r
 379  */\r
 380 /* @[declare_mqtt_getpublishpacketsize] */\r
 381 IotMqttError_t IotMqtt_GetPublishPacketSize( IotMqttPublishInfo_t * pPublishInfo,\r
 382                                              size_t * pRemainingLength,\r
 383                                              size_t * pPacketSize );\r
 384 /* @[declare_mqtt_getpublishpacketsize] */\r
 385 \r
 386 /**\r
 387  * @brief Generate a PUBLISH packet from the given parameters.\r
 388  *\r
 389  * @param[in] pPublishInfo User-provided PUBLISH information.\r
 390  * @param[in] remainingLength remaining length of the packet to be serialized.\r
 391  * @param[out] pPacketIdentifier The packet identifier generated for this PUBLISH.\r
 392  * @param[out] pPacketIdentifierHigh Where the high byte of the packet identifier\r
 393  * is written.\r
 394  * @param[in, out] pBuffer User provide buffer where the PUBLISH packet is written.\r
 395  * @param[in] bufferSize Size of the buffer pointed to by pBuffer.\r
 396  *\r
 397  * @return #IOT_MQTT_SUCCESS or #IOT_MQTT_BAD_PARAMETER.\r
 398  *\r
 399  * @note pBuffer must be allocated by caller.\r
 400  * @note This call is part of serializer API used for implementing light-weight MQTT client.\r
 401  *\r
 402  * <b>Example</b>\r
 403  * @code{c}\r
 404  * // Example code below shows how IotMqtt_SerializePublish() should be used to serialize\r
 405  * // MQTT Publish packet and send it to broker.\r
 406  * // Example uses static memory, but dynamically allocated memory can be used as well.\r
 407  * \r
 408  * #define mqttexampleSHARED_BUFFER_SIZE 100\r
 409  * static ucSharedBuffer[mqttexampleSHARED_BUFFER_SIZE];\r
 410  * void sendUnsubscribePacket( int xMQTTSocket )\r
 411  * {\r
 412  *    IotMqttError_t xResult;\r
 413  *    IotMqttPublishInfo_t xMQTTPublishInfo;\r
 414  *    size_t xRemainingLength = 0;\r
 415  *    size_t xPacketSize = 0;\r
 416  *    size_t xSentBytes = 0;\r
 417  *    uint16_t usPacketIdentifier;\r
 418  *    uint8_t * pusPacketIdentifierHigh;\r
 419  *\r
 420  *    // Initialize Publish parameters. Details are out of scope for this example.\r
 421  *    // It will involve setting QOS, topic filter, topic filter length, payload\r
 422  *    // payload length.\r
 423  *    _initializePublish( &xMQTTPublishInfo );\r
 424  *\r
 425  *    // Find out length of Publish packet size.\r
 426  *    xResult = IotMqtt_GetPublishPacketSize( &xMQTTPublishInfo, &xRemainingLength, &xPacketSize );\r
 427  *    IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );\r
 428  *    // Make sure the packet size is less than static buffer size\r
 429  *        IotMqtt_Assert( xPacketSize < mqttexampleSHARED_BUFFER_SIZE );\r
 430  * \r
 431  *    xResult = IotMqtt_SerializePublish( &xMQTTPublishInfo,\r
 432  *                                                                              xRemainingLength,\r
 433  *                                                                              &usPacketIdentifier,\r
 434  *                                                                              &pusPacketIdentifierHigh,\r
 435  *                                                                              ucSharedBuffer,\r
 436  *                                                                              xPacketSize );\r
 437  *    IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS ); \r
 438  * \r
 439  *    // xMQTTSocket here is posix socket created and connected to MQTT broker outside of this function.\r
 440  *    xSentBytes = send( xMQTTSocket, ( void * ) ucSharedBuffer, xPacketSize, 0 );\r
 441  *    IotMqtt_Assert( xSentBytes == xPacketSize );\r
 442  * }\r
 443  * @endcode\r
 444  */\r
 445 /* @[declare_mqtt_serializepublish] */\r
 446 IotMqttError_t IotMqtt_SerializePublish( IotMqttPublishInfo_t * pPublishInfo,\r
 447                                          size_t remainingLength,\r
 448                                          uint16_t * pPacketIdentifier,\r
 449                                          uint8_t ** pPacketIdentifierHigh,\r
 450                                          uint8_t * pBuffer,\r
 451                                          size_t bufferSize );\r
 452 /* @[declare_mqtt_serializepublish] */\r
 453 \r
 454 /**\r
 455  * @brief Generate a DISCONNECT packet\r
 456  *\r
 457  * @param[in, out] pBuffer User provide buffer where the DISCONNECT packet is written.\r
 458  * @param[in] bufferSize Size of the buffer pointed to by pBuffer.\r
 459  *\r
 460  * @return  returns #IOT_MQTT_SUCCESS or #IOT_MQTT_BAD_PARAMETER\r
 461  *\r
 462  * @note This call is part of serializer API used for implementing light-weight MQTT client.\r
 463  * \r
 464  * <b>Example</b>\r
 465  * @code{c}\r
 466  * // Example below shows how IotMqtt_SerializeDisconnect() should be used.\r
 467  * \r
 468  * #define mqttexampleSHARED_BUFFER_SIZE 100\r
 469  * static ucSharedBuffer[mqttexampleSHARED_BUFFER_SIZE];\r
 470  * void sendDisconnectRequest( int xMQTTSocket )\r
 471  * {\r
 472  *     size_t xSentBytes = 0;\r
 473  * \r
 474  *    // Disconnect is fixed length packet, therefore there is no need to calculate the size,\r
 475  *    // just makes sure static buffer can accommodate disconnect request.\r
 476  *    IotMqtt_Assert( MQTT_PACKET_DISCONNECT_SIZE <= mqttexampleSHARED_BUFFER_SIZE );\r
 477  *\r
 478  *    // Serialize Disconnect packet into static buffer (dynamically allocated buffer can be used as well)\r
 479  *    xResult = IotMqtt_SerializeDisconnect( ucSharedBuffer, MQTT_PACKET_DISCONNECT_SIZE );\r
 480  *    IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );\r
 481  *\r
 482  *    // xMQTTSocket here is posix socket created and connected to MQTT broker outside of this function.\r
 483  *    xSentByte = send( xMQTTSocket, ( void * ) ucSharedBuffer, MQTT_PACKET_DISCONNECT_SIZE, 0 );\r
 484  *    IotMqtt_Assert( xSentByte == MQTT_PACKET_DISCONNECT_SIZE );\r
 485  * }\r
 486  *      \r
 487  * @endcode\r
 488  */\r
 489 /* @[declare_mqtt_serializedisconnect] */\r
 490 IotMqttError_t IotMqtt_SerializeDisconnect( uint8_t * pBuffer,\r
 491                                             size_t bufferSize );\r
 492 /* @[declare_mqtt_serializedisconnect] */\r
 493 \r
 494 /**\r
 495  * @brief Generate a PINGREQ packet.\r
 496  *\r
 497  * @param[in, out] pBuffer User provide buffer where the PINGREQ packet is written.\r
 498  * @param[in] bufferSize Size of the buffer pointed to by pBuffer.\r
 499  *\r
 500  * @return #IOT_MQTT_SUCCESS or #IOT_MQTT_BAD_PARAMETER.\r
 501  * \r
 502  * @note This call is part of serializer API used for implementing light-weight MQTT client.\r
 503  * \r
 504  * <b>Example</b>\r
 505  * @code{c}\r
 506  * // Example below shows how IotMqtt_SerializePingReq() should be used.\r
 507  * \r
 508  * #define mqttexampleSHARED_BUFFER_SIZE 100\r
 509  * static ucSharedBuffer[mqttexampleSHARED_BUFFER_SIZE];\r
 510  * void sendPingRequest( int xMQTTSocket )\r
 511  * {\r
 512  *    size_t xSentBytes = 0;\r
 513  * \r
 514  *    // PingReq is fixed length packet, therefore there is no need to calculate the size,\r
 515  *    // just makes sure static buffer can accommodate Ping request.\r
 516  *    IotMqtt_Assert( MQTT_PACKET_PINGREQ_SIZE <= mqttexampleSHARED_BUFFER_SIZE );\r
 517  *\r
 518  *    xResult = IotMqtt_SerializePingreq( ucSharedBuffer, MQTT_PACKET_PINGREQ_SIZE );\r
 519  *    IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );\r
 520  *    \r
 521  *    // xMQTTSocket here is posix socket created and connected to MQTT broker outside of this function.\r
 522  *    xSentByte = send( xMQTTSocket, ( void * ) ucSharedBuffer, MQTT_PACKET_DISCONNECT_SIZE, 0 );\r
 523  *    IotMqtt_Assert( xSentByte ==  MQTT_PACKET_PINGREQ_SIZE); \r
 524  * }\r
 525  * @endcode\r
 526  */\r
 527 /* @[declare_mqtt_serializepingreq] */\r
 528 IotMqttError_t IotMqtt_SerializePingreq( uint8_t * pBuffer,\r
 529                                          size_t bufferSize );\r
 530 /* @[declare_mqtt_serializepingreq] */\r
 531 \r
 532 /**\r
 533  * @brief Extract MQTT packet type and length from incoming packet\r
 534  *\r
 535  * @param[in, out] pIncomingPacket Pointer to IotMqttPacketInfo_t structure\r
 536  * where type, remaining length and packet identifier are stored.\r
 537  * @param[in] getNextByte Pointer to platform specific function  which is used\r
 538  * to extract type and length from incoming received stream (see example ).\r
 539  * @param[in] pNetworkConnection Pointer to platform specific network connection\r
 540  * which is used by getNextByte to receive network data\r
 541  *\r
 542  * @return #IOT_MQTT_SUCCESS on successful extraction of type and length,\r
 543  * #IOT_MQTT_BAD_RESPONSE on failure.\r
 544  *\r
 545  * @note This call is part of serializer API used for implementing light-weight MQTT client.\r
 546  *\r
 547  * <b>Example</b>\r
 548  * @code{c}\r
 549  * // Example code below shows how to implement getNetxByte function with posix sockets.\r
 550  * // Note: IotMqttGetNextByte_t typedef IotMqttError_t (* IotMqttGetNextByte_t)( void * pNetworkContext,\r
 551  * //                                              uint8_t * pNextByte );\r
 552  * // Note: It is assumed that socket is already created and connected,\r
 553  *\r
 554  * IotMqttError_t getNextByte( void * pContext,\r
 555  *                           uint8_t * pNextByte )\r
 556  * {\r
 557  *      int socket = ( int ) ( *pvContext );\r
 558  *      int receivedBytes;\r
 559  *      IotMqttError_t result;\r
 560  *\r
 561  *      receivedBytes = recv( socket, ( void * ) pNextByte, sizeof( uint8_t ), 0 );\r
 562  *\r
 563  *      if( receivedBytes == sizeof( uint8_t ) )\r
 564  *      {\r
 565  *          result = IOT_MQTT_SUCCESS;\r
 566  *      }\r
 567  *      else\r
 568  *      {\r
 569  *          result = IOT_MQTT_TIMEOUT;\r
 570  *      }\r
 571  *\r
 572  *       return result;\r
 573  * }\r
 574  * \r
 575  * // Example below shows how IotMqtt_GetIncomingMQTTPacketTypeAndLength() is used to extract type\r
 576  * // and length from incoming ping response.\r
 577  * // xMQTTSocket here is posix socket created and connected to MQTT broker outside of this function.\r
 578  * void getTypeAndLengthFromIncomingMQTTPingResponse( int xMQTTSocket )\r
 579  * {\r
 580  *    IotMqttPacketInfo_t xIncomingPacket;\r
 581  *    IotMqttError_t xResult = IotMqtt_GetIncomingMQTTPacketTypeAndLength( &xIncomingPacket, getNextByte, ( void * ) xMQTTSocket );\r
 582  *        IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );\r
 583  *    IotMqtt_Assert( xIncomingPacket.type == MQTT_PACKET_TYPE_PINGRESP );\r
 584  * }\r
 585  * @endcode\r
 586  *\r
 587  */\r
 588 /* @[declare_mqtt_getincomingmqttpackettypeandlength] */\r
 589 IotMqttError_t IotMqtt_GetIncomingMQTTPacketTypeAndLength( IotMqttPacketInfo_t * pIncomingPacket,\r
 590                                                            IotMqttGetNextByte_t getNextByte,\r
 591                                                            void * pNetworkConnection );\r
 592 /* @[declare_mqtt_getincomingmqttpackettypeandlength] */\r
 593 \r
 594 /**\r
 595  * @brief Deserialize incoming publish packet.\r
 596  *\r
 597  * @param[in, out] pMqttPacket The caller of this API sets type, remainingLength and pRemainingData.\r
 598  * On success, packetIdentifier and pubInfo will be set by the function.\r
 599  *\r
 600  * @return One of the following:\r
 601  * - #IOT_MQTT_SUCCESS\r
 602  * - #IOT_MQTT_BAD_RESPONSE\r
 603  * - #IOT_MQTT_SERVER_REFUSED\r
 604  *\r
 605  * @note This call is part of serializer API used for implementing light-weight MQTT client.\r
 606  * \r
 607  * <b>Example</b>\r
 608  * @code{c}\r
 609  * // Example below shows how IotMqtt_DeserializePublish() used to extract contents of incoming \r
 610  * // Publish.  xMQTTSocket here is posix socket created and connected to MQTT broker outside of this function.\r
 611  * void processIncomingPublish( int xMQTTSocket )\r
 612  * {\r
 613  *    IotMqttError_t xResult;\r
 614  *    IotMqttPacketInfo_t xIncomingPacket;\r
 615  *\r
 616  *        xResult = IotMqtt_GetIncomingMQTTPacketTypeAndLength( &xIncomingPacket, getNextByte, ( void * ) xMQTTSocket );\r
 617  *        IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );\r
 618  *        IotMqtt_Assert( ( xIncomingPacket.type & 0xf0 ) == MQTT_PACKET_TYPE_PUBLISH );\r
 619  *        IotMqtt_Assert( xIncomingPacket.remainingLength <= mqttexampleSHARED_BUFFER_SIZE );\r
 620  *\r
 621  *        // Receive the remaining bytes.\r
 622  *        if( recv( xMQTTSocket, ( void * ) ucSharedBuffer, xIncomingPacket.remainingLength, 0 ) ==  xIncomingPacket.remainingLength )\r
 623  *        {\r
 624  *              xIncomingPacket.pRemainingData = ucSharedBuffer;\r
 625  *\r
 626  *              if( IotMqtt_DeserializePublish( &xIncomingPacket ) != IOT_MQTT_SUCCESS )\r
 627  *              {\r
 628  *                      xResult = IOT_MQTT_BAD_RESPONSE;\r
 629  *              }\r
 630  *              else\r
 631  *              {\r
 632  *                      // Process incoming Publish.\r
 633  *                      IotLogInfo( "Incoming QOS : %d\n", xIncomingPacket.pubInfo.qos );\r
 634  *                      IotLogInfo( "Incoming Publish Topic Name: %.*s\n", xIncomingPacket.pubInfo.topicNameLength, xIncomingPacket.pubInfo.pTopicName );\r
 635  *                      IotLogInfo( "Incoming Publish Message : %.*s\n", xIncomingPacket.pubInfo.payloadLength, xIncomingPacket.pubInfo.pPayload  );\r
 636  *              }\r
 637  *        }\r
 638  *        else\r
 639  *        {\r
 640  *              xResult = IOT_MQTT_NETWORK_ERROR;\r
 641  *        }\r
 642  *\r
 643  *      IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );\r
 644  * }\r
 645  * @endcode\r
 646  */\r
 647 /* @[declare_mqtt_deserializepublish] */\r
 648 IotMqttError_t IotMqtt_DeserializePublish( IotMqttPacketInfo_t * pMqttPacket );\r
 649 /* @[declare_mqtt_deserializepublish] */\r
 650 \r
 651 /**\r
 652  * @brief Deserialize incoming ack packets.\r
 653  *\r
 654  * @param[in, out] pMqttPacket The caller of this API sets type, remainingLength and pRemainingData.\r
 655  * On success, packetIdentifier will be set.\r
 656  *\r
 657  * @return One of the following:\r
 658  * - #IOT_MQTT_SUCCESS\r
 659  * - #IOT_MQTT_BAD_RESPONSE\r
 660  * - #IOT_MQTT_SERVER_REFUSED\r
 661  *\r
 662  * @note This call is part of serializer API used for implementing light-weight MQTT client.\r
 663  * \r
 664  * <b>Example</b>\r
 665  * @code{c}\r
 666  * // Example below shows how  IotMqtt_DeserializeResponse() is used to process unsubscribe ack.\r
 667  * // xMQTTSocket here is posix socket created and connected to MQTT broker outside of this function.\r
 668  * void processUnsubscribeAck( int xMQTTSocket )\r
 669  * {\r
 670  *      IotMqttError_t xResult;\r
 671  *      IotMqttPacketInfo_t xIncomingPacket;\r
 672  * \r
 673  *              xResult = IotMqtt_GetIncomingMQTTPacketTypeAndLength( &xIncomingPacket, getNextByte, ( void * ) xMQTTSocket );\r
 674  *              IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );\r
 675  *              IotMqtt_Assert( xIncomingPacket.type == MQTT_PACKET_TYPE_UNSUBACK );\r
 676  *              IotMqtt_Assert( xIncomingPacket.remainingLength <= sizeof( ucSharedBuffer ) );\r
 677  *\r
 678  *              // Receive the remaining bytes.\r
 679  *              if( recv( xMQTTSocket, ( void * ) ucSharedBuffer, xIncomingPacket.remainingLength, 0 ) == xIncomingPacket.remainingLength )\r
 680  *              {\r
 681  *                      xIncomingPacket.pRemainingData = ucSharedBuffer;\r
 682  *\r
 683  *                      if( IotMqtt_DeserializeResponse( &xIncomingPacket ) != IOT_MQTT_SUCCESS )\r
 684  *                      {\r
 685  *                              xResult = IOT_MQTT_BAD_RESPONSE;\r
 686  *                      }\r
 687  *              }\r
 688  *              else\r
 689  *              {\r
 690  *                      xResult = IOT_MQTT_NETWORK_ERROR;\r
 691  *              }\r
 692  *      IotMqtt_Assert( xResult == IOT_MQTT_SUCCESS );\r
 693  * }\r
 694  * @endcode\r
 695  */\r
 696 /* @[declare_mqtt_deserializeresponse] */\r
 697 IotMqttError_t IotMqtt_DeserializeResponse( IotMqttPacketInfo_t * pMqttPacket );\r
 698 /* @[declare_mqtt_deserializeresponse] */\r
 699 \r
 700 \r
 701 \r
 702 #endif /* ifndef IOT_MQTT_SERIALIZE_H_ */\r