core_http_client.h

Go to the documentation of this file.

/*
 * coreHTTP
 * Copyright (C) 2024 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
 *
 * SPDX-License-Identifier: MIT
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 * the Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
 
#ifndef CORE_HTTP_CLIENT_H_
#define CORE_HTTP_CLIENT_H_
 
#include <stdint.h>
#include <stddef.h>
 
/* *INDENT-OFF* */
#ifdef __cplusplus
    extern "C" {
#endif
/* *INDENT-ON* */
 
#define HTTP_LIBRARY_VERSION    "v3.1.2"
/* HTTP_DO_NOT_USE_CUSTOM_CONFIG allows building the HTTP Client library
 * without a config file. If a config file is provided, the
 * HTTP_DO_NOT_USE_CUSTOM_CONFIG macro must not be defined.
 */
#ifndef HTTP_DO_NOT_USE_CUSTOM_CONFIG
    #include "core_http_config.h"
#endif
 
/* Include config defaults header to get default values of configurations not
 * defined in core_http_config.h file. */
#include "core_http_config_defaults.h"
 
/* Transport interface include. */
#include "transport_interface.h"
 
/* Convenience macros for some HTTP request methods. */
 
#define HTTP_METHOD_GET     "GET"                       
#define HTTP_METHOD_PUT     "PUT"                       
#define HTTP_METHOD_POST    "POST"                      
#define HTTP_METHOD_HEAD    "HEAD"                      
#define HTTP_MAX_CONTENT_LENGTH_HEADER_LENGTH    sizeof( "Content-Length: 4294967295" ) - 1U
 
#define HTTP_SEND_DISABLE_CONTENT_LENGTH_FLAG    0x1U
 
#define HTTP_REQUEST_KEEP_ALIVE_FLAG       0x1U
 
#define HTTP_REQUEST_NO_USER_AGENT_FLAG    0x2U
 
#define HTTP_RESPONSE_CONNECTION_CLOSE_FLAG         0x1U
 
#define HTTP_RESPONSE_CONNECTION_KEEP_ALIVE_FLAG    0x2U
 
#define HTTP_RESPONSE_DO_NOT_PARSE_BODY_FLAG    0x1U
 
#define HTTP_RANGE_REQUEST_END_OF_FILE          -1
 
typedef enum HTTPStatus
{
    HTTPSuccess,
 
    HTTPInvalidParameter,
 
    HTTPNetworkError,
 
    HTTPPartialResponse,
 
    HTTPNoResponse,
 
    HTTPInsufficientMemory,
 
    HTTPSecurityAlertExtraneousResponseData,
 
    HTTPSecurityAlertInvalidChunkHeader,
 
    HTTPSecurityAlertInvalidProtocolVersion,
 
    HTTPSecurityAlertInvalidStatusCode,
 
    HTTPSecurityAlertInvalidCharacter,
 
    HTTPSecurityAlertInvalidContentLength,
 
    HTTPParserPaused,
 
    HTTPParserInternalError,
 
    HTTPHeaderNotFound,
 
    HTTPInvalidResponse
} HTTPStatus_t;
 
typedef struct HTTPRequestHeaders
{
    uint8_t * pBuffer;
    size_t bufferLen; 
    size_t headersLen;
} HTTPRequestHeaders_t;
 
typedef struct HTTPRequestInfo
{
    const char * pMethod;
    size_t methodLen; 
    const char * pPath;
    size_t pathLen; 
    const char * pHost;
    size_t hostLen; 
    uint32_t reqFlags;
} HTTPRequestInfo_t;
 
 
 
typedef struct HTTPClient_ResponseHeaderParsingCallback
{
    void ( * onHeaderCallback )( void * pContext,
                                 const char * fieldLoc,
                                 size_t fieldLen,
                                 const char * valueLoc,
                                 size_t valueLen,
                                 uint16_t statusCode );
 
    void * pContext;
} HTTPClient_ResponseHeaderParsingCallback_t;
 
typedef uint32_t (* HTTPClient_GetCurrentTimeFunc_t )( void );
 
typedef struct HTTPResponse
{
    uint8_t * pBuffer;
    size_t bufferLen; 
    HTTPClient_ResponseHeaderParsingCallback_t * pHeaderParsingCallback;
 
    HTTPClient_GetCurrentTimeFunc_t getTime;
 
    const uint8_t * pHeaders;
 
    size_t headersLen;
 
    const uint8_t * pBody;
 
    size_t bodyLen;
 
    /* Useful HTTP header values found. */
 
    uint16_t statusCode;
 
    size_t contentLength;
 
    size_t headerCount;
 
    uint8_t areHeadersComplete;
 
    uint32_t respOptionFlags;
 
    uint32_t respFlags;
} HTTPResponse_t;
 
/* @[declare_httpclient_initializerequestheaders] */
HTTPStatus_t HTTPClient_InitializeRequestHeaders( HTTPRequestHeaders_t * pRequestHeaders,
                                                  const HTTPRequestInfo_t * pRequestInfo );
/* @[declare_httpclient_initializerequestheaders] */
 
/* @[declare_httpclient_addheader] */
HTTPStatus_t HTTPClient_AddHeader( HTTPRequestHeaders_t * pRequestHeaders,
                                   const char * pField,
                                   size_t fieldLen,
                                   const char * pValue,
                                   size_t valueLen );
/* @[declare_httpclient_addheader] */
 
/* @[declare_httpclient_addrangeheader] */
HTTPStatus_t HTTPClient_AddRangeHeader( HTTPRequestHeaders_t * pRequestHeaders,
                                        int32_t rangeStartOrlastNbytes,
                                        int32_t rangeEnd );
/* @[declare_httpclient_addrangeheader] */
 
/* @[declare_httpclient_sendhttpheaders] */
HTTPStatus_t HTTPClient_SendHttpHeaders( const TransportInterface_t * pTransport,
                                         HTTPClient_GetCurrentTimeFunc_t getTimestampMs,
                                         HTTPRequestHeaders_t * pRequestHeaders,
                                         size_t reqBodyLen,
                                         uint32_t sendFlags );
/* @[declare_httpclient_sendhttpheaders] */
 
/* @[declare_httpclient_sendhttpdata] */
HTTPStatus_t HTTPClient_SendHttpData( const TransportInterface_t * pTransport,
                                      HTTPClient_GetCurrentTimeFunc_t getTimestampMs,
                                      const uint8_t * pData,
                                      size_t dataLen );
/* @[declare_httpclient_sendhttpdata] */
 
/* @[declare_httpclient_send] */
HTTPStatus_t HTTPClient_Send( const TransportInterface_t * pTransport,
                              HTTPRequestHeaders_t * pRequestHeaders,
                              const uint8_t * pRequestBodyBuf,
                              size_t reqBodyBufLen,
                              HTTPResponse_t * pResponse,
                              uint32_t sendFlags );
/* @[declare_httpclient_send] */
 
/* @[declare_httpclient_receiveandparsehttpresponse] */
HTTPStatus_t HTTPClient_ReceiveAndParseHttpResponse( const TransportInterface_t * pTransport,
                                                     HTTPResponse_t * pResponse,
                                                     const HTTPRequestHeaders_t * pRequestHeaders );
/* @[declare_httpclient_receiveandparsehttpresponse] */
 
/* @[declare_httpclient_readheader] */
HTTPStatus_t HTTPClient_ReadHeader( const HTTPResponse_t * pResponse,
                                    const char * pField,
                                    size_t fieldLen,
                                    const char ** pValueLoc,
                                    size_t * pValueLen );
/* @[declare_httpclient_readheader] */
 
/* @[declare_httpclient_strerror] */
const char * HTTPClient_strerror( HTTPStatus_t status );
/* @[declare_httpclient_strerror] */
 
/* *INDENT-OFF* */
#ifdef __cplusplus
    }
#endif
/* *INDENT-ON* */
 
#endif /* ifndef CORE_HTTP_CLIENT_H_ */