http_client.c File Reference

HTTP client (HyperText Transfer Protocol) More...

#include <limits.h>
#include <stdarg.h>
#include "core/net.h"
#include "http/http_client.h"
#include "http/http_client_auth.h"
#include "http/http_client_transport.h"
#include "http/http_client_misc.h"
#include "str.h"
#include "debug.h"

Go to the source code of this file.

Macros

#define TRACE_LEVEL   HTTP_TRACE_LEVEL
 

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.

Description

The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypermedia information systems. Refer to the following RFCs for complete details:

  • RFC 1945: Hypertext Transfer Protocol - HTTP/1.0
  • RFC 2616: Hypertext Transfer Protocol - HTTP/1.1
  • RFC 2818: HTTP Over TLS
  • RFC 7230: Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing
  • RFC 7231: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
Author
Oryx Embedded SARL (www.oryx-embedded.com)
Version
2.4.0

Definition in file http_client.c.

Macro Definition Documentation

◆ TRACE_LEVEL

#define TRACE_LEVEL   HTTP_TRACE_LEVEL

Definition at line 43 of file http_client.c.

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.