Add the Labs projects provided in the V10.2.1_191129 zip file.

[freertos] / FreeRTOS-Labs / Source / FreeRTOS-IoT-Libraries / c_sdk / standard / https / src / private / iot_https_internal.h

/*\r
 * Amazon FreeRTOS HTTPS Client 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
 * http://aws.amazon.com/freertos\r
 * http://www.FreeRTOS.org\r
 */\r
\r
#ifndef IOT_HTTPS_INTERNAL_H_\r
#define IOT_HTTPS_INTERNAL_H_\r
\r
/* The config header is always included first. */\r
#include "iot_config.h"\r
\r
/* Standard Includes. */\r
#include <string.h>\r
#include <stdbool.h>\r
#include <stdlib.h>\r
#include <stdio.h>\r
\r
/* Third party http-parser include. */\r
#include "http_parser.h"\r
\r
/* HTTPS Client library includes. */\r
#include "iot_https_client.h"\r
\r
/* Task pool include. */\r
#include "iot_taskpool_freertos.h"\r
\r
/* Linear containers (lists and queues) include. */\r
#include "iot_linear_containers.h"\r
\r
/* Types include. */\r
#include "types/iot_taskpool_types_freertos.h"\r
\r
/* Platform layer includes. */\r
#include "platform/iot_threads.h"\r
#include "platform/iot_network.h"\r
\r
/* Error handling include. */\r
#include "iot_error.h"\r
\r
/*-----------------------------------------------------------*/\r
\r
/* Convenience macros for handling errors in a standard way. */\r
\r
/**\r
 * @brief Every public API return an enumeration value with an underlying value of 0 in case of success.\r
 */\r
#define HTTPS_SUCCEEDED( x )                         ( ( x ) == IOT_HTTPS_OK )\r
\r
/**\r
 * @brief Every public API returns an enumeration value with an underlying value different than 0 in case of success.\r
 */\r
#define HTTPS_FAILED( x )                            ( ( x ) != IOT_HTTPS_OK )\r
\r
/**\r
 * @brief Declare the storage for the error status variable.\r
 */\r
#define HTTPS_FUNCTION_ENTRY( result )               IOT_FUNCTION_ENTRY( IotHttpsReturnCode_t, result )\r
\r
/**\r
 * @brief Jump to the cleanup area.\r
 */\r
#define HTTPS_GOTO_CLEANUP()                         IOT_GOTO_CLEANUP()\r
\r
/**\r
 * @brief Set error and leave.\r
 */\r
#define HTTPS_SET_AND_GOTO_CLEANUP( statusValue )    IOT_SET_AND_GOTO_CLEANUP( statusValue )\r
\r
/**\r
 * @brief Initialize error and declare start of cleanup area.\r
 */\r
#define HTTPS_FUNCTION_CLEANUP_BEGIN()               IOT_FUNCTION_CLEANUP_BEGIN()\r
\r
/**\r
 * @brief Initialize error and declare end of cleanup area.\r
 */\r
#define HTTPS_FUNCTION_CLEANUP_END()                 IOT_FUNCTION_CLEANUP_END()\r
\r
/**\r
 * @brief Create an empty cleanup area.\r
 */\r
#define HTTPS_FUNCTION_EXIT_NO_CLEANUP()             IOT_FUNCTION_EXIT_NO_CLEANUP()\r
\r
/**\r
 * @brief Exit if an argument is NULL.\r
 */\r
#define HTTPS_ON_NULL_ARG_GOTO_CLEANUP( ptr )                    \\r
    if( ( ptr == NULL ) )                                        \\r
    {                                                            \\r
        IotLogError( # ptr " was NULL." );                       \\r
        IOT_SET_AND_GOTO_CLEANUP( IOT_HTTPS_INVALID_PARAMETER ); \\r
    }\r
\r
/**\r
 * @brief Exit if an condition is false.\r
 */\r
#define HTTPS_ON_ARG_ERROR_GOTO_CLEANUP( expr )                  \\r
    if( ( expr ) == false )                                      \\r
    {                                                            \\r
        IotLogError( # expr " must be true." );                  \\r
        IOT_SET_AND_GOTO_CLEANUP( IOT_HTTPS_INVALID_PARAMETER ); \\r
    }\r
\r
/**\r
 * @brief Exit if an argument is false with a message.\r
 */\r
#define HTTPS_ON_ARG_ERROR_MSG_GOTO_CLEANUP( expr, statusValue, ... ) \\r
    if( ( expr ) == false )                                           \\r
    {                                                                 \\r
        IotLogError( __VA_ARGS__ );                                   \\r
        IOT_SET_AND_GOTO_CLEANUP( statusValue );                      \\r
    }\r
\r
/* Configure logs for HTTPS Client functions. */\r
#ifdef IOT_LOG_LEVEL_HTTPS\r
    #define LIBRARY_LOG_LEVEL        IOT_LOG_LEVEL_HTTPS\r
#else\r
    #ifdef IOT_LOG_LEVEL_GLOBAL\r
        #define LIBRARY_LOG_LEVEL    IOT_LOG_LEVEL_GLOBAL\r
    #else\r
        #define LIBRARY_LOG_LEVEL    IOT_LOG_NONE\r
    #endif\r
#endif\r
\r
#define LIBRARY_LOG_NAME    ( "HTTPS Client" )\r
#include "iot_logging_setup.h"\r
\r
/*\r
 * Provide default values for undefined memory allocation functions based on\r
 * the usage of dynamic memory allocation.\r
 */\r
#if IOT_STATIC_MEMORY_ONLY == 1\r
    #include "iot_static_memory.h"\r
#endif\r
\r
/**\r
 * @cond DOXYGEN_IGNORE\r
 * Doxygen should ignore this section.\r
 *\r
 * Provide default values for undefined configuration constants.\r
 */\r
#ifndef AWS_IOT_HTTPS_ENABLE_METRICS\r
    #define AWS_IOT_HTTPS_ENABLE_METRICS           ( 1 )\r
#endif\r
#ifndef IOT_HTTPS_USER_AGENT\r
    #define IOT_HTTPS_USER_AGENT                   "FreeRTOS"\r
#endif\r
#ifndef IOT_HTTPS_MAX_FLUSH_BUFFER_SIZE\r
    #define IOT_HTTPS_MAX_FLUSH_BUFFER_SIZE        ( 1024 )\r
#endif\r
#ifndef IOT_HTTPS_RESPONSE_WAIT_MS\r
    #define IOT_HTTPS_RESPONSE_WAIT_MS             ( 1000 )\r
#endif\r
#ifndef IOT_HTTPS_MAX_HOST_NAME_LENGTH\r
    #define IOT_HTTPS_MAX_HOST_NAME_LENGTH         ( 255 ) /* Per FQDN, the maximum host name length is 255 bytes. */\r
#endif\r
#ifndef IOT_HTTPS_MAX_ALPN_PROTOCOLS_LENGTH\r
    #define IOT_HTTPS_MAX_ALPN_PROTOCOLS_LENGTH    ( 255 ) /* The maximum alpn protocols length is chosen arbitrarily. */\r
#endif\r
\r
/** @endcond */\r
\r
/**\r
 * @brief The HTTP protocol version of this library is HTTP/1.1.\r
 */\r
#define HTTPS_PROTOCOL_VERSION                        "HTTP/1.1"\r
\r
/**\r
 * @brief An empty path for a NULL specified path in the request initialization configuration.\r
 */\r
#define HTTPS_EMPTY_PATH                              "/"\r
\r
/**\r
 * @brief HTTPS "CONNECT" method, defined as the longest string length method.\r
 */\r
#define HTTPS_CONNECT_METHOD                          "CONNECT"\r
\r
/*\r
 * Constants for the values of the HTTP "Connection" header field.\r
 *\r
 * This is used for writing headers automatically during the sending of the HTTP request.\r
 * "Connection: keep-alive\r\n" is written automatically for a persistent connection.\r
 * "Connection: close\r\n" is written automatically for a non-persistent connection.\r
 */\r
#define HTTPS_CONNECTION_KEEP_ALIVE_HEADER_VALUE      "keep-alive"\r
#define HTTPS_CONNECTION_CLOSE_HEADER_VALUE           "close"\r
\r
/**\r
 * Constants for HTTP header formatting.\r
 *\r
 * ": " separates and header field from the header value.\r
 */\r
#define HTTPS_HEADER_FIELD_SEPARATOR                  ": "\r
#define HTTPS_HEADER_FIELD_SEPARATOR_LENGTH           ( 2 )\r
#define COLON_CHARACTER                               ':'\r
#define SPACE_CHARACTER                               ' '\r
\r
/**\r
 * Constants for HTTP header formatting.\r
 *\r
 * "\r\n" Ends the header line.\r
 */\r
#define HTTPS_END_OF_HEADER_LINES_INDICATOR           "\r\n"\r
#define HTTPS_END_OF_HEADER_LINES_INDICATOR_LENGTH    ( 2 )\r
#define CARRIAGE_RETURN_CHARACTER                     '\r'\r
#define NEWLINE_CHARACTER                             '\n'\r
\r
/*\r
 * Constants for header fields added automatically during the request initialization.\r
 */\r
#define HTTPS_USER_AGENT_HEADER                       "User-Agent"\r
#define HTTPS_HOST_HEADER                             "Host"\r
\r
/*\r
 * Constants for the header fields added automatically during the sending of the HTTP request.\r
 */\r
#define HTTPS_CONTENT_LENGTH_HEADER                   "Content-Length"\r
#define HTTPS_CONNECTION_HEADER                       "Connection"\r
\r
/**\r
 * @brief The maximum Content-Length header line size.\r
 *\r
 * This is the length of header line string: "Content-Length: 4294967296\r\n". 4294967296 is 2^32. This number is chosen\r
 * because it is the maximum file size that can be represented in a 32 bit system.\r
 *\r
 * This is used to initialize a local array for the final headers to send.\r
 */\r
#define HTTPS_MAX_CONTENT_LENGTH_LINE_LENGTH          ( 26 )\r
\r
/**\r
 * @brief Macro for fast string length calculation of string macros.\r
 *\r
 * We subtract 1 to subtract the NULL terminating character.\r
 * We do not assume that the size of a character is a single byte or 8 bits with this calculation.\r
 */\r
#define FAST_MACRO_STRLEN( x )    ( ( sizeof( x ) / sizeof( char ) ) - 1 )\r
\r
/*-----------------------------------------------------------*/\r
\r
/**\r
 * @brief The state of the HTTP response parsing.\r
 *\r
 * This state notes what has been parsed in the HTTP response. As soon as any part of the HTTP response is received from\r
 * the network, it is sent to be parsed.\r
 *\r
 * The states move as follows:\r
 * PARSER_STATE_NONE --> PARSER_STATE_IN_HEADERS --> PARSER_STATE_HEADERS_COMPLETE --> PARSER_STATE_BODY_COMPLETE\r
 *\r
 * The parser callbacks are called in the following order:\r
 * 1. _httpParserOnMessageBeginCallback()\r
 * 2. _httpParserOnStatusCallback()\r
 * 3. _httpParserOnHeaderFieldCallback()\r
 * 4. _httpParserOnHeaderValueCallback()\r
 * 5. _httpParserOnHeadersCompleteCallback()\r
 * 6. _httpParserOnChunkHeaderCallback() (optional only if the response is chunked)\r
 * 7. _httpParserOnBodyCallback()\r
 * 8. _httpParserOnChunkCompleteCallback() (optional only if the response is chunked)\r
 * 9. _httpParserOnMessageCompleteCallback()\r
 *\r
 * Theses states are set in the parser callbacks and used outside the callbacks to determine action.\r
 *\r
 * PARSER_STATE_NONE is assigned to #_httpsResponse_t.parserState when the _httpsResponse_t.parserState is initialized\r
 * in @ref IotHttpsClient_InitializeRequest and before parsing a new respone message from the server.\r
 *\r
 * PARSER_STATE_IN_HEADERS is assigned at the start of the HTTP Response message. This occurs in the\r
 * _httpParserOnMessageBeginCallback(). HTTP headers are always first and there is always the response status line\r
 * and some headers in a response message according to RFC 2616.\r
 *\r
 * PARSER_STATE_HEADERS_COMPLETE is assigned when all of the headers are finished being parsed in the HTTP response\r
 * message. This occurs in the _httpParserOnHeadersCompleteCallback(). The state can end here if the response has no\r
 * body, like for a response to a HEAD request.\r
 * If this state is not reached after receiving headers from the network into the user configured header buffer and\r
 * running it through the parser, then we know that not all of the headers from the response could fit into the buffer.\r
 *\r
 * PARSER_STATE_IN_BODY is assigned each time the parser reaches HTTP response body. This occurs in the\r
 * _httpParserOnBodyCallback().\r
 *\r
 * PARSER_STATE_BODY_COMPLETE is assigned when the parser has finished with the whole HTTP response message. This\r
 * happens when _httpParserOnMessageCompleteCallback() is invoked.\r
 * If this state is not reached after receiving body from the network into the user configured body buffer and\r
 * running it through the parser, then we know that not all of the body from the response could fit into the buffer.\r
 */\r
typedef enum IotHttpsResponseParserState\r
{\r
    PARSER_STATE_NONE = 0,         /**< @brief The parser has not started so we are neither in the headers or the body. */\r
    PARSER_STATE_IN_HEADERS,       /**< @brief The parser is currently parsing the HTTP respone headers. */\r
    PARSER_STATE_HEADERS_COMPLETE, /**< @brief The parser has finished parsing the headers. */\r
    PARSER_STATE_IN_BODY,          /**< @brief The parser is currently parsing the HTTP response body. */\r
    PARSER_STATE_BODY_COMPLETE     /**< @brief The parser has completed parsing the HTTP response body. */\r
} IotHttpsResponseParserState_t;\r
\r
/**\r
 * @brief The state denoting which buffer (the header buffer or the body buffer) is currently being processed\r
 * and for what.\r
 *\r
 * This state is set outside of the parser callbacks and used inside the of parser callbacks to determine actions.\r
 *\r
 * The state moves as follows:\r
 * Receiving and parsing a response: PROCESSING_STATE_NONE --> PROCESSING_STATE_FILLING_HEADER_BUFFER --> PROCESSING_STATE_FILLING_BODY_BUFFER --> PROCESSING_STATE_FINISHED\r
 * Searching a response for headers: ((enter state)) --> PROCESSING_STATE_SEARCHING_HEADER_BUFFER --> ((enter state))\r
 *\r
 * PROCESSING_STATE_NONE is assigned when #_httpsResponse_t.bufferProcessingState is initialized in\r
 * @ref IotHttpsClient_InitializeRequest.\r
 *\r
 * PROCESSING_STATE_FILLING_HEADER_BUFFER is assigned at the start of receiving HTTP response headers from the network\r
 * into the header buffer, before processing the received headers with the parser.\r
 * This state is then used in the parser callbacks _httpParserOnStatusCallback(), _httpParserOnHeaderFieldCallback(),\r
 * _httpParserOnHeaderValueCallback(), and _httpParserOnHeadersCompleteCallback() to move the\r
 * #_httpsResponse_t.headersCur pointer along in the header buffer.\r
 * Since the server sends the HTTP response as a single continuous message, sometimes during receiving of the HTTP\r
 * headers we may receive part or all of the HTTP response body:\r
 * ((example header buffer))[headers headers headers headers body body body]\r
 * When parsing this header buffer the parser will execute _httpParserOnBodyCallback() in the\r
 * PROCESSING_STATE_FILLING_HEADER_BUFFER state. The state is used here, for an asynchronous response, to save where\r
 * and how much body is inside the of the header buffer. When a body buffer becomes available, the body in the header\r
 * buffer will be copied to the body buffer.\r
 *\r
 * PROCESSING_STATE_FILLING_BODY_BUFFER is assigned at the start of receiving the HTTP response body form the network\r
 * into the body buffer, before processing the received body with the parser.\r
 *\r
 * PROCESSING_STATE_FINISHED is assigned at the end of IotHttpsClient_SendSync() or at the end of\r
 * IotHttpsClient_SendAsync() when both the header and body buffer are finished being filled with network data and\r
 * parsed.\r
 *\r
 * PROCESSING_STATE_SEARCHING_HEADER_BUFFER is assigned in IotHttpsClient_ReadHeader() when searching for a header\r
 * in the header buffer.\r
 * This state is used in the parser callback _httpParserOnHeaderFieldCallback() to check if the current header field\r
 * parsed equals the header we are searching for. It is used in parser callback _httpParserOnHeaderValueCallback() to\r
 * return the header value if the corresponding field we are searching for was found. It is used in parser callback\r
 * _httpParserOnHeadersCompleteCallback() to stop parsing the header buffer if the header we are searching for was not\r
 * found.\r
 *\r
 * The header buffer is separate from the body buffer.\r
 * The header buffer is configured in #IotHttpRequestInfo_t.respUserBuff. The body buffer is configured in\r
 * #IotHttpRequestInfo_t.syncInfo->respData or as buffer provided asynchronously during the\r
 * #IotHttpsClientCallbacks_t.readReadyCallback() to call to @ref IotHttpsClient_ReadResponseBody().\r
 */\r
typedef enum IotHttpsResponseBufferState\r
{\r
    PROCESSING_STATE_NONE,                   /**< @brief There is no buffer processing currently. */\r
    PROCESSING_STATE_FILLING_HEADER_BUFFER,  /**< @brief The header buffer is being filled and parsed. */\r
    PROCESSING_STATE_FILLING_BODY_BUFFER,    /**< @brief The body buffer is being filled and parsed. */\r
    PROCESSING_STATE_FINISHED,               /**< @brief Filling and parsing of both buffers is finished. */\r
    PROCESSING_STATE_SEARCHING_HEADER_BUFFER /**< @brief The header buffer is being searched. */\r
} IotHttpsResponseBufferState_t;\r
\r
/*-----------------------------------------------------------*/\r
\r
/**\r
 * @brief Represents an HTTP connection.\r
 */\r
typedef struct _httpsConnection\r
{\r
    const IotNetworkInterface_t * pNetworkInterface; /**< @brief Network interface with calls for connect, disconnect, send, and receive. */\r
    IotNetworkConnection_t pNetworkConnection;       /**< @brief Pointer to the network connection to use pNetworkInterface calls on. */\r
    uint32_t timeout;                                /**< @brief Timeout for a connection and waiting for a response from the network. */\r
\r
    /**\r
     * @brief true if a connection was successful most recently on this context\r
     *\r
     * We have no way of knowing if the server closed the connection because that error is unique to the underlying TLS\r
     * layer. This is set to false initially, then set to true for a successful intentional call to connect.\r
     * Post connection, this is set to false only after an implicit disconnect with a non-persistent request, an implicit\r
     * disconnect with a network error, or an explicit disconnect with a call to @ref https_client_function_disconnect.\r
     */\r
    bool isConnected;\r
    bool isDestroyed;                           /**< @brief true if the connection is already destroyed and we should call anymore  */\r
    IotMutex_t connectionMutex;                 /**< @brief Mutex protecting operations on this entire connection context. */\r
    IotDeQueue_t reqQ;                          /**< @brief The queue for the requests that are not finished yet. */\r
    IotDeQueue_t respQ;                         /**< @brief The queue for the responses that are waiting to be processed. */\r
    IotTaskPoolJobStorage_t taskPoolJobStorage; /**< @brief An asynchronous operation requires storage for the task pool job. */\r
    IotTaskPoolJob_t taskPoolJob;               /**< @brief The task pool job identifier for an asynchronous request. */\r
} _httpsConnection_t;\r
\r
/**\r
 * @brief Third party library http-parser information.\r
 *\r
 * There are two separate structures for http_parser state information. This is so that the application can read\r
 * a header during it's readReadyCallback. The readReadyCallback could be invoked many times and the parser will\r
 * therefore be invoked many times for each response read from the network. In order to ensure that the state of\r
 * the parser remains intact whilst headers may be read, two structures holding the state are kept.\r
 */\r
typedef struct _httpParserInfo\r
{\r
    http_parser responseParser; /**< @brief http_parser state information for parsing the response. */\r
    size_t ( * parseFunc )( http_parser * parser,\r
                            const http_parser_settings * settings,\r
                            const char * data,\r
                            size_t len ); /**< @brief http_parser_execute function is to be plugged in here during initialization of the response. */\r
    http_parser readHeaderParser;         /**< @brief http_parser state information for parsing the header buffer for reading a header. */\r
} _httpParserInfo_t;\r
\r
/**\r
 * @brief Represents an HTTP response.\r
 */\r
typedef struct _httpsResponse\r
{\r
    IotLink_t link;                                      /**< @brief The link to insert the job in the connection's respQ. */\r
    uint8_t * pHeaders;                                  /**< @brief Pointer to the start of the headers buffer. */\r
    uint8_t * pHeadersEnd;                               /**< @brief Pointer to the end of the headers buffer. */\r
    uint8_t * pHeadersCur;                               /**< @brief Pointer to the next location to write in the headers buffer. */\r
    uint8_t * pBody;                                     /**< @brief Pointer to the start of the body buffer. */\r
    uint8_t * pBodyEnd;                                  /**< @brief Pointer to the end of the body buffer. */\r
    uint8_t * pBodyCur;                                  /**< @brief Pointer to the next location to write in the body buffer. */\r
    _httpParserInfo_t httpParserInfo;                    /**< @brief Third party http-parser information. */\r
    uint16_t status;                                     /**< @brief The HTTP response status code of this response. */\r
    IotHttpsMethod_t method;                             /**< @brief The method of the originating request. */\r
    IotHttpsResponseParserState_t parserState;           /**< @brief The current state of the parser. See IotHttpsResponseParserState_t documentation for more details. */\r
    IotHttpsResponseBufferState_t bufferProcessingState; /**< @brief Which buffer is currently being processed and for what. See IotHttpsResponseBufferState_t documentation. */\r
    char * pReadHeaderField;                             /**< @brief Header field that we want to read from the headers buffer when IotHttpsClient_ReadHeader() is called. */\r
    size_t readHeaderFieldLength;                        /**< @brief Length of pReadHeaderField */\r
    char * pReadHeaderValue;                             /**< @brief Header value that we read from the headers buffer when IotHttpsClient_ReadHeader() is called. */\r
    size_t readHeaderValueLength;                        /**< @brief Length of pReadHeaderValue. */\r
    bool foundHeaderField;                               /**< @brief State to use during parsing to let us know when we found the header field in the https-parser callbacks.\r
                                                          *          This is set to true when the header field is found in parser callback _httpParserOnHeaderFieldCallback().\r
                                                          *          On the following parser callback _httpParserOnHeaderValueCallback() we will store the value in pReadHeaderValue and then exit the parsing. */\r
    struct _httpsConnection * pHttpsConnection;          /**< @brief Connection associated with response. This is set during IotHttpsClient_SendAsync(). This is needed during the asynchronous workflow to receive data given the respHandle only in the callback. */\r
    bool isAsync;                                        /**< @brief This is set to true if this response is to be retrieved asynchronously. Set to false otherwise. */\r
    uint8_t * pBodyInHeaderBuf;                          /**< @brief Pointer to the start of body inside the header buffer for copying to a body buffer provided later by the asynchronous response process. */\r
    uint8_t * pBodyCurInHeaderBuf;                       /**< @brief Pointer to the next location to write body data during processing of the header buffer. This is necessary in case there is a chunk encoded HTTP response. */\r
    IotHttpsReturnCode_t bodyRxStatus;                   /**< @brief The status of network receiving the HTTPS body to be returned during the #IotHttpsClientCallbacks_t.readReadyCallback. */\r
    bool cancelled;                                      /**< @brief This is set to true to stop the request/response processing in the asynchronous request workflow. */\r
    IotSemaphore_t respFinishedSem;                      /**< @brief This is for synchronous response to post that is finished being received. It is better to use a task event signal, but that is not implemented yet in the iot_threads.h API. */\r
    IotHttpsReturnCode_t syncStatus;                     /**< @brief The status of the synchronous response. */\r
\r
    /**\r
     * @brief This is set to true to when the request is finished being sent on the network\r
     *\r
     * A request is not shared with multiple tasks, so only one task will update this. This is to let the let the\r
     * network receive callback know that the request is fully pushed out to the server. This is also to let the\r
     * disconnect know that the request is not using the network interface resources anymore.\r
     */\r
    bool reqFinishedSending;\r
    IotHttpsClientCallbacks_t * pCallbacks; /**< @brief Pointer to the asynchronous request callbacks. */\r
    void * pUserPrivData;                   /**< @brief User private data to hand back in the asynchronous callbacks for context. */\r
    bool isNonPersistent;                   /**< @brief Non-persistent flag to indicate closing the connection immediately after receiving the response. */\r
} _httpsResponse_t;\r
\r
/**\r
 * @brief Represents and HTTP request.\r
 */\r
typedef struct _httpsRequest\r
{\r
    IotLink_t link;                             /**< @brief The link to insert the job in the connection's reqQ. */\r
    uint8_t * pHeaders;                         /**< @brief Pointer to the start of the headers buffer. */\r
    uint8_t * pHeadersEnd;                      /**< @brief Pointer to the end of the headers buffer. */\r
    uint8_t * pHeadersCur;                      /**< @brief Pointer to the next location to write in the headers buffer. */\r
    uint8_t * pBody;                            /**< @brief Pointer to the start of the body buffer. */\r
    uint32_t bodyLength;                        /**< @brief Length of request body buffer. */\r
    IotHttpsMethod_t method;                    /**< @brief The method of the originating request. */\r
    IotHttpsConnectionInfo_t * pConnInfo;       /**< @brief Connection info associated with this request. For an implicit connection. */\r
    struct _httpsResponse * pHttpsResponse;     /**< @brief Response associated with request. This is initialized during IotHttpsClient_InitializeRequest(), then returned to the application in IotHttpsClient_SendAsync() and IotHttpsClient_SendSync(). */\r
    struct _httpsConnection * pHttpsConnection; /**< @brief Connection associated with request. This is set during IotHttpsClient_SendAsync(). It is needed for the asynchronous workflow to use to send data given the reqHandle only in the callback. */\r
    bool isNonPersistent;                       /**< @brief Non-persistent flag to indicate closing the connection immediately after receiving the response. */\r
    bool isAsync;                               /**< @brief This is set to true if this request is to be sent asynchronously. Set to false otherwise. */\r
    void * pUserPrivData;                       /**< @brief User private data to hand back in the asynchronous callbacks for context. */\r
    IotHttpsClientCallbacks_t * pCallbacks;     /**< @brief Pointer to the asynchronous request callbacks. */\r
    bool cancelled;                             /**< @brief Set this to true to stop the response processing in the asynchronous workflow. */\r
    IotHttpsReturnCode_t bodyTxStatus;          /**< @brief The status of network sending the HTTPS body to be returned during the #IotHttpsClientCallbacks_t.writeCallback. */\r
    bool scheduled;                             /**< @brief Set to true when this request has already been scheduled to the task pool. */\r
} _httpsRequest_t;\r
\r
/*-----------------------------------------------------------*/\r
\r
/**\r
 * @brief A map of the method enum to strings\r
 *\r
 * These are in order to the HTTP request method enums defined in IotHttpsMethod_t.\r
 */\r
static const char * _pHttpsMethodStrings[] = {\r
    "GET",\r
    "HEAD",\r
    "PUT",\r
    "POST"\r
};\r
\r
#endif /* IOT_HTTPS_INTERNAL_H_ */\r