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_t * | httpClientGetHeaderField (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.
- 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
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
enum 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] context Pointer to the HTTP client context [in] name NULL-terminated string that holds the header field name [in] value NULL-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] context Pointer to the HTTP client context [in] name NULL-terminated string that holds the parameter name [in] value NULL-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] context Pointer to the HTTP client context [in] interface Network 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] context Pointer 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] context Pointer 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] context Pointer to the HTTP client context [in] serverIpAddr IP address of the HTTP server to connect to [in] serverPort Port 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] context Pointer 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] context Pointer 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] context Pointer 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] context Pointer to the HTTP client context [in] name NULL-terminated string that holds the header field name [in] format NULL-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] context Pointer to the HTTP client context [in] name NULL-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] context Pointer to the HTTP client context [out] name NULL-terminated string that contains the name of the next header field [out] value NULL-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] context Pointer 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] context Pointer 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] context Pointer to the HTTP client context [out] data Buffer where to store the incoming data [in] size Maximum number of bytes that can be received [out] received Number of bytes that have been received [in] flags Set 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] context Pointer 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] context Pointer 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] context Pointer to the HTTP client context [in] callback Random 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] context Pointer to the HTTP client context [in] callback TLS 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] context Pointer to the HTTP client context [in] username NULL-terminated string containing the user name to be used [in] password NULL-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] context Pointer to the HTTP client context [in] length Length 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] context Pointer to the HTTP client context [in] host NULL-terminated string containing the hostname [in] port TCP 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] context Pointer to the HTTP client context [in] method NULL-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] context Pointer to the HTTP client context [in] queryString NULL-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] context Pointer to the HTTP client context [in] timeout Timeout 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] context Pointer to the HTTP client context [in] uri NULL-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] context Pointer to the HTTP client context [in] version HTTP 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] context Pointer to the HTTP client context [in] data Pointer to the buffer containing the data to be transmitted [in] length Number of data bytes to send [out] written Actual number of bytes written (optional parameter) [in] flags Set 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] context Pointer 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] context Pointer to the HTTP client context
- Returns
- Error code
Definition at line 1293 of file http_client.c.