http_client.h File Reference

HTTP client (HyperText Transfer Protocol) More...

#include "core/net.h"
#include "http/http_common.h"
#include "core/crypto.h"
#include "tls.h"
#include "encoding/base64.h"
#include "hash/hash_algorithms.h"

Go to the source code of this file.

Data Structures

struct  HttpClientAuthParams
 HTTP authentication parameters. More...
 
struct  _HttpClientContext
 HTTP client context. More...
 

Macros

#define HTTP_CLIENT_SUPPORT   ENABLED
 
#define HTTP_CLIENT_TLS_SUPPORT   DISABLED
 
#define HTTP_CLIENT_BASIC_AUTH_SUPPORT   DISABLED
 
#define HTTP_CLIENT_DIGEST_AUTH_SUPPORT   DISABLED
 
#define HTTP_CLIENT_MD5_SUPPORT   ENABLED
 
#define HTTP_CLIENT_SHA256_SUPPORT   DISABLED
 
#define HTTP_CLIENT_SHA512_256_SUPPORT   DISABLED
 
#define HTTP_CLIENT_DEFAULT_TIMEOUT   20000
 
#define HTTP_CLIENT_BUFFER_SIZE   2048
 
#define HTTP_CLIENT_TLS_TX_BUFFER_SIZE   2048
 
#define HTTP_CLIENT_TLS_RX_BUFFER_SIZE   16384
 
#define HTTP_CLIENT_MAX_METHOD_LEN   8
 
#define HTTP_CLIENT_MAX_USERNAME_LEN   32
 
#define HTTP_CLIENT_MAX_PASSWORD_LEN   32
 
#define HTTP_CLIENT_MAX_REALM_LEN   32
 
#define HTTP_CLIENT_MAX_NONCE_LEN   64
 
#define HTTP_CLIENT_CNONCE_SIZE   16
 
#define HTTP_CLIENT_MAX_OPAQUE_LEN   64
 
#define HTTP_CLIENT_AUTH_SUPPORT   ENABLED
 
#define HTTP_CLIENT_PRIVATE_CONTEXT
 
#define HttpClientContext   struct _HttpClientContext
 

Typedefs

typedef error_t(* HttpClientTlsInitCallback) (HttpClientContext *context, TlsContext *tlsContext)
 TLS initialization callback function. More...
 
typedef error_t(* HttpClientRandCallback) (uint8_t *data, size_t length)
 Random data generation callback function. More...
 

Enumerations

enum  HttpClientState { HTTP_CLIENT_STATE_DISCONNECTED = 0, HTTP_CLIENT_STATE_CONNECTING = 1, HTTP_CLIENT_STATE_CONNECTED = 2, HTTP_CLIENT_STATE_DISCONNECTING = 3 }
 HTTP client states. More...
 

Functions

error_t httpClientInit (HttpClientContext *context)
 Initialize HTTP client context. More...
 
error_t httpClientRegisterTlsInitCallback (HttpClientContext *context, HttpClientTlsInitCallback callback)
 Register TLS initialization callback function. More...
 
error_t httpClientRegisterRandCallback (HttpClientContext *context, HttpClientRandCallback callback)
 Register random data generation callback function. More...
 
error_t httpClientSetVersion (HttpClientContext *context, HttpVersion version)
 Set the HTTP protocol version to be used. More...
 
error_t httpClientSetTimeout (HttpClientContext *context, systime_t timeout)
 Set communication timeout. More...
 
error_t httpClientSetAuthInfo (HttpClientContext *context, const char_t *username, const char_t *password)
 Set authentication information. More...
 
error_t httpClientBindToInterface (HttpClientContext *context, NetInterface *interface)
 Bind the HTTP client to a particular network interface. More...
 
error_t httpClientConnect (HttpClientContext *context, const IpAddr *serverIpAddr, uint16_t serverPort)
 Establish a connection with the specified HTTP server. More...
 
error_t httpClientCreateRequest (HttpClientContext *context)
 Create a new HTTP request. More...
 
error_t httpClientSetMethod (HttpClientContext *context, const char_t *method)
 Set HTTP request method. More...
 
error_t httpClientSetUri (HttpClientContext *context, const char_t *uri)
 Set request URI. More...
 
error_t httpClientSetHost (HttpClientContext *context, const char_t *host, uint16_t port)
 Set the hostname and port number of the resource being requested. More...
 
error_t httpClientSetQueryString (HttpClientContext *context, const char_t *queryString)
 Set query string. More...
 
error_t httpClientAddQueryParam (HttpClientContext *context, const char_t *name, const char_t *value)
 Add a key/value pair to the query string. More...
 
error_t httpClientAddHeaderField (HttpClientContext *context, const char_t *name, const char_t *value)
 Add a header field to the HTTP request. More...
 
error_t httpClientFormatHeaderField (HttpClientContext *context, const char_t *name, const char_t *format,...)
 Format an HTTP header field. More...
 
error_t httpClientSetContentLength (HttpClientContext *context, size_t length)
 Set the length of the HTTP request body. More...
 
error_t httpClientWriteHeader (HttpClientContext *context)
 Write HTTP request header. More...
 
error_t httpClientWriteBody (HttpClientContext *context, const void *data, size_t length, size_t *written, uint_t flags)
 Write HTTP request body. More...
 
error_t httpClientWriteTrailer (HttpClientContext *context)
 Write HTTP trailer. More...
 
error_t httpClientReadHeader (HttpClientContext *context)
 Read HTTP response header. More...
 
uint_t httpClientGetStatus (HttpClientContext *context)
 Retrieve the HTTP status code of the response. More...
 
const char_thttpClientGetHeaderField (HttpClientContext *context, const char_t *name)
 Retrieve the value of the specified header field name. More...
 
error_t httpClientGetNextHeaderField (HttpClientContext *context, const char_t **name, const char_t **value)
 Iterate through the HTTP response header. More...
 
error_t httpClientReadBody (HttpClientContext *context, void *data, size_t size, size_t *received, uint_t flags)
 Read HTTP response body. More...
 
error_t httpClientReadTrailer (HttpClientContext *context)
 Read HTTP trailer. More...
 
error_t httpClientCloseBody (HttpClientContext *context)
 Close HTTP request or response body. More...
 
error_t httpClientDisconnect (HttpClientContext *context)
 Gracefully disconnect from the HTTP server. More...
 
error_t httpClientClose (HttpClientContext *context)
 Close the connection with the HTTP server. More...
 
void httpClientDeinit (HttpClientContext *context)
 Release HTTP client context. More...
 

Detailed Description

HTTP client (HyperText Transfer Protocol)

License

SPDX-License-Identifier: GPL-2.0-or-later

Copyright (C) 2010-2024 Oryx Embedded SARL. All rights reserved.

This file is part of CycloneTCP Open.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Author
Oryx Embedded SARL (www.oryx-embedded.com)
Version
2.4.4

Definition in file http_client.h.

Macro Definition Documentation

◆ HTTP_CLIENT_AUTH_SUPPORT

#define HTTP_CLIENT_AUTH_SUPPORT   ENABLED

Definition at line 166 of file http_client.h.

◆ HTTP_CLIENT_BASIC_AUTH_SUPPORT

#define HTTP_CLIENT_BASIC_AUTH_SUPPORT   DISABLED

Definition at line 54 of file http_client.h.

◆ HTTP_CLIENT_BUFFER_SIZE

#define HTTP_CLIENT_BUFFER_SIZE   2048

Definition at line 96 of file http_client.h.

◆ HTTP_CLIENT_CNONCE_SIZE

#define HTTP_CLIENT_CNONCE_SIZE   16

Definition at line 152 of file http_client.h.

◆ HTTP_CLIENT_DEFAULT_TIMEOUT

#define HTTP_CLIENT_DEFAULT_TIMEOUT   20000

Definition at line 89 of file http_client.h.

◆ HTTP_CLIENT_DIGEST_AUTH_SUPPORT

#define HTTP_CLIENT_DIGEST_AUTH_SUPPORT   DISABLED

Definition at line 61 of file http_client.h.

◆ HTTP_CLIENT_MAX_METHOD_LEN

#define HTTP_CLIENT_MAX_METHOD_LEN   8

Definition at line 117 of file http_client.h.

◆ HTTP_CLIENT_MAX_NONCE_LEN

#define HTTP_CLIENT_MAX_NONCE_LEN   64

Definition at line 145 of file http_client.h.

◆ HTTP_CLIENT_MAX_OPAQUE_LEN

#define HTTP_CLIENT_MAX_OPAQUE_LEN   64

Definition at line 159 of file http_client.h.

◆ HTTP_CLIENT_MAX_PASSWORD_LEN

#define HTTP_CLIENT_MAX_PASSWORD_LEN   32

Definition at line 131 of file http_client.h.

◆ HTTP_CLIENT_MAX_REALM_LEN

#define HTTP_CLIENT_MAX_REALM_LEN   32

Definition at line 138 of file http_client.h.

◆ HTTP_CLIENT_MAX_USERNAME_LEN

#define HTTP_CLIENT_MAX_USERNAME_LEN   32

Definition at line 124 of file http_client.h.

◆ HTTP_CLIENT_MD5_SUPPORT

#define HTTP_CLIENT_MD5_SUPPORT   ENABLED

Definition at line 68 of file http_client.h.

◆ HTTP_CLIENT_PRIVATE_CONTEXT

#define HTTP_CLIENT_PRIVATE_CONTEXT

Definition at line 175 of file http_client.h.

◆ HTTP_CLIENT_SHA256_SUPPORT

#define HTTP_CLIENT_SHA256_SUPPORT   DISABLED

Definition at line 75 of file http_client.h.

◆ HTTP_CLIENT_SHA512_256_SUPPORT

#define HTTP_CLIENT_SHA512_256_SUPPORT   DISABLED

Definition at line 82 of file http_client.h.

◆ HTTP_CLIENT_SUPPORT

#define HTTP_CLIENT_SUPPORT   ENABLED

Definition at line 40 of file http_client.h.

◆ HTTP_CLIENT_TLS_RX_BUFFER_SIZE

#define HTTP_CLIENT_TLS_RX_BUFFER_SIZE   16384

Definition at line 110 of file http_client.h.

◆ HTTP_CLIENT_TLS_SUPPORT

#define HTTP_CLIENT_TLS_SUPPORT   DISABLED

Definition at line 47 of file http_client.h.

◆ HTTP_CLIENT_TLS_TX_BUFFER_SIZE

#define HTTP_CLIENT_TLS_TX_BUFFER_SIZE   2048

Definition at line 103 of file http_client.h.

◆ HttpClientContext

#define HttpClientContext   struct _HttpClientContext

Definition at line 198 of file http_client.h.

Typedef Documentation

◆ HttpClientRandCallback

typedef error_t(* HttpClientRandCallback) (uint8_t *data, size_t length)

Random data generation callback function.

Definition at line 236 of file http_client.h.

◆ HttpClientTlsInitCallback

typedef error_t(* HttpClientTlsInitCallback) (HttpClientContext *context, TlsContext *tlsContext)

TLS initialization callback function.

Definition at line 226 of file http_client.h.

Enumeration Type Documentation

◆ HttpClientState

HTTP client states.

Enumerator
HTTP_CLIENT_STATE_DISCONNECTED 
HTTP_CLIENT_STATE_CONNECTING 
HTTP_CLIENT_STATE_CONNECTED 
HTTP_CLIENT_STATE_DISCONNECTING 

Definition at line 210 of file http_client.h.

Function Documentation

◆ httpClientAddHeaderField()

error_t httpClientAddHeaderField ( HttpClientContext context,
const char_t name,
const char_t value 
)

Add a header field to the HTTP request.

Parameters
[in]contextPointer to the HTTP client context
[in]nameNULL-terminated string that holds the header field name
[in]valueNULL-terminated string that holds the header field value
Returns
Error code

Definition at line 808 of file http_client.c.

◆ httpClientAddQueryParam()

error_t httpClientAddQueryParam ( HttpClientContext context,
const char_t name,
const char_t value 
)

Add a key/value pair to the query string.

Parameters
[in]contextPointer to the HTTP client context
[in]nameNULL-terminated string that holds the parameter name
[in]valueNULL-terminated string that holds the parameter value
Returns
Error code

Definition at line 691 of file http_client.c.

◆ httpClientBindToInterface()

error_t httpClientBindToInterface ( HttpClientContext context,
NetInterface interface 
)

Bind the HTTP client to a particular network interface.

Parameters
[in]contextPointer to the HTTP client context
[in]interfaceNetwork interface to be used
Returns
Error code

Definition at line 246 of file http_client.c.

◆ httpClientClose()

error_t httpClientClose ( HttpClientContext context)

Close the connection with the HTTP server.

Parameters
[in]contextPointer to the HTTP client context
Returns
Error code

Definition at line 2224 of file http_client.c.

◆ httpClientCloseBody()

error_t httpClientCloseBody ( HttpClientContext context)

Close HTTP request or response body.

Parameters
[in]contextPointer to the HTTP client context
Returns
Error code

Definition at line 2012 of file http_client.c.

◆ httpClientConnect()

error_t httpClientConnect ( HttpClientContext context,
const IpAddr serverIpAddr,
uint16_t  serverPort 
)

Establish a connection with the specified HTTP server.

Parameters
[in]contextPointer to the HTTP client context
[in]serverIpAddrIP address of the HTTP server to connect to
[in]serverPortPort number
Returns
Error code

Definition at line 269 of file http_client.c.

◆ httpClientCreateRequest()

error_t httpClientCreateRequest ( HttpClientContext context)

Create a new HTTP request.

Parameters
[in]contextPointer to the HTTP client context
Returns
Error code

Definition at line 365 of file http_client.c.

◆ httpClientDeinit()

void httpClientDeinit ( HttpClientContext context)

Release HTTP client context.

Parameters
[in]contextPointer to the HTTP client context

Definition at line 2245 of file http_client.c.

◆ httpClientDisconnect()

error_t httpClientDisconnect ( HttpClientContext context)

Gracefully disconnect from the HTTP server.

Parameters
[in]contextPointer to the HTTP client context
Returns
Error code

Definition at line 2149 of file http_client.c.

◆ httpClientFormatHeaderField()

error_t httpClientFormatHeaderField ( HttpClientContext context,
const char_t name,
const char_t format,
  ... 
)

Format an HTTP header field.

Parameters
[in]contextPointer to the HTTP client context
[in]nameNULL-terminated string that holds the header field name
[in]formatNULL-terminated string that that contains a format string
[in]...Optional arguments
Returns
Error code

Definition at line 890 of file http_client.c.

◆ httpClientGetHeaderField()

const char_t* httpClientGetHeaderField ( HttpClientContext context,
const char_t name 
)

Retrieve the value of the specified header field name.

Parameters
[in]contextPointer to the HTTP client context
[in]nameNULL-terminated string that specifies the header field name
Returns
Value of the header field

Definition at line 1539 of file http_client.c.

◆ httpClientGetNextHeaderField()

error_t httpClientGetNextHeaderField ( HttpClientContext context,
const char_t **  name,
const char_t **  value 
)

Iterate through the HTTP response header.

Parameters
[in]contextPointer to the HTTP client context
[out]nameNULL-terminated string that contains the name of the next header field
[out]valueNULL-terminated string that contains the value of the next header field
Returns
Error code

Definition at line 1598 of file http_client.c.

◆ httpClientGetStatus()

uint_t httpClientGetStatus ( HttpClientContext context)

Retrieve the HTTP status code of the response.

Parameters
[in]contextPointer to the HTTP client context
Returns
HTTP status code

Definition at line 1512 of file http_client.c.

◆ httpClientInit()

error_t httpClientInit ( HttpClientContext context)

Initialize HTTP client context.

Parameters
[in]contextPointer to the HTTP client context
Returns
Error code

Definition at line 66 of file http_client.c.

◆ httpClientReadBody()

error_t httpClientReadBody ( HttpClientContext context,
void *  data,
size_t  size,
size_t *  received,
uint_t  flags 
)

Read HTTP response body.

Parameters
[in]contextPointer to the HTTP client context
[out]dataBuffer where to store the incoming data
[in]sizeMaximum number of bytes that can be received
[out]receivedNumber of bytes that have been received
[in]flagsSet of flags that influences the behavior of this function
Returns
Error code

Definition at line 1646 of file http_client.c.

◆ httpClientReadHeader()

error_t httpClientReadHeader ( HttpClientContext context)

Read HTTP response header.

Parameters
[in]contextPointer to the HTTP client context
Returns
Error code

Definition at line 1372 of file http_client.c.

◆ httpClientReadTrailer()

error_t httpClientReadTrailer ( HttpClientContext context)

Read HTTP trailer.

Parameters
[in]contextPointer to the HTTP client context
Returns
Error code

Definition at line 1884 of file http_client.c.

◆ httpClientRegisterRandCallback()

error_t httpClientRegisterRandCallback ( HttpClientContext context,
HttpClientRandCallback  callback 
)

Register random data generation callback function.

Parameters
[in]contextPointer to the HTTP client context
[in]callbackRandom data generation callback function
Returns
Error code

Definition at line 135 of file http_client.c.

◆ httpClientRegisterTlsInitCallback()

error_t httpClientRegisterTlsInitCallback ( HttpClientContext context,
HttpClientTlsInitCallback  callback 
)

Register TLS initialization callback function.

Parameters
[in]contextPointer to the HTTP client context
[in]callbackTLS initialization callback function
Returns
Error code

Definition at line 111 of file http_client.c.

◆ httpClientSetAuthInfo()

error_t httpClientSetAuthInfo ( HttpClientContext context,
const char_t username,
const char_t password 
)

Set authentication information.

Parameters
[in]contextPointer to the HTTP client context
[in]usernameNULL-terminated string containing the user name to be used
[in]passwordNULL-terminated string containing the password to be used
Returns
Error code

Definition at line 209 of file http_client.c.

◆ httpClientSetContentLength()

error_t httpClientSetContentLength ( HttpClientContext context,
size_t  length 
)

Set the length of the HTTP request body.

Parameters
[in]contextPointer to the HTTP client context
[in]lengthLength of the HTTP request body, in bytes
Returns
Error code

Definition at line 987 of file http_client.c.

◆ httpClientSetHost()

error_t httpClientSetHost ( HttpClientContext context,
const char_t host,
uint16_t  port 
)

Set the hostname and port number of the resource being requested.

Parameters
[in]contextPointer to the HTTP client context
[in]hostNULL-terminated string containing the hostname
[in]portTCP port number
Returns
Error code

Definition at line 533 of file http_client.c.

◆ httpClientSetMethod()

error_t httpClientSetMethod ( HttpClientContext context,
const char_t method 
)

Set HTTP request method.

Parameters
[in]contextPointer to the HTTP client context
[in]methodNULL-terminating string containing the HTTP method
Returns
Error code

Definition at line 402 of file http_client.c.

◆ httpClientSetQueryString()

error_t httpClientSetQueryString ( HttpClientContext context,
const char_t queryString 
)

Set query string.

Parameters
[in]contextPointer to the HTTP client context
[in]queryStringNULL-terminated string that contains the query string
Returns
Error code

Definition at line 594 of file http_client.c.

◆ httpClientSetTimeout()

error_t httpClientSetTimeout ( HttpClientContext context,
systime_t  timeout 
)

Set communication timeout.

Parameters
[in]contextPointer to the HTTP client context
[in]timeoutTimeout value, in milliseconds
Returns
Error code

Definition at line 187 of file http_client.c.

◆ httpClientSetUri()

error_t httpClientSetUri ( HttpClientContext context,
const char_t uri 
)

Set request URI.

Parameters
[in]contextPointer to the HTTP client context
[in]uriNULL-terminated string that contains the resource name
Returns
Error code

Definition at line 462 of file http_client.c.

◆ httpClientSetVersion()

error_t httpClientSetVersion ( HttpClientContext context,
HttpVersion  version 
)

Set the HTTP protocol version to be used.

Parameters
[in]contextPointer to the HTTP client context
[in]versionHTTP protocol version (1.0 or 1.1)
Returns
Error code

Definition at line 162 of file http_client.c.

◆ httpClientWriteBody()

error_t httpClientWriteBody ( HttpClientContext context,
const void *  data,
size_t  length,
size_t *  written,
uint_t  flags 
)

Write HTTP request body.

Parameters
[in]contextPointer to the HTTP client context
[in]dataPointer to the buffer containing the data to be transmitted
[in]lengthNumber of data bytes to send
[out]writtenActual number of bytes written (optional parameter)
[in]flagsSet of flags that influences the behavior of this function
Returns
Error code

Definition at line 1137 of file http_client.c.

◆ httpClientWriteHeader()

error_t httpClientWriteHeader ( HttpClientContext context)

Write HTTP request header.

Parameters
[in]contextPointer to the HTTP client context
Returns
Error code

Definition at line 1014 of file http_client.c.

◆ httpClientWriteTrailer()

error_t httpClientWriteTrailer ( HttpClientContext context)

Write HTTP trailer.

Parameters
[in]contextPointer to the HTTP client context
Returns
Error code

Definition at line 1293 of file http_client.c.