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, void *param) |
| 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, void *param) |
| 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 | httpClientSetAllowedAuthModes (HttpClientContext *context, uint_t allowedAuthModes) |
| Set allowed HTTP authentication modes. 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-2025 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.5.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, void *param) |
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 859 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 742 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 297 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 2277 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 2065 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 320 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 416 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 2298 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 2202 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 941 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 1592 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 1651 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 1565 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 1699 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 1425 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 1937 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 144 of file http_client.c.
◆ httpClientRegisterTlsInitCallback()
| error_t httpClientRegisterTlsInitCallback | ( | HttpClientContext * | context, |
| HttpClientTlsInitCallback | callback, | ||
| void * | param | ||
| ) |
Register TLS initialization callback function.
- Parameters
-
[in] context Pointer to the HTTP client context [in] callback TLS initialization callback function [in] param An opaque pointer passed to the callback function
- Returns
- Error code
Definition at line 118 of file http_client.c.
◆ httpClientSetAllowedAuthModes()
| error_t httpClientSetAllowedAuthModes | ( | HttpClientContext * | context, |
| uint_t | allowedAuthModes | ||
| ) |
Set allowed HTTP authentication modes.
- Parameters
-
[in] context Pointer to the HTTP client context [in] allowedAuthModes Logic OR of allowed HTTP authentication schemes
- Returns
- Error code
Definition at line 218 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 253 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 1038 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 584 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 453 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 645 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 196 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 513 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 171 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 1188 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 1065 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 1346 of file http_client.c.
