Nigel Rantor / azure_c_shared_utility

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of azure_c_shared_utility by Azure IoT

Embed: (wiki syntax)

« Back to documentation index

httpheaders.h File Reference
Functions

httpheaders.h File Reference

This is a utility module that handles HTTP message-headers. More...

Go to the source code of this file.

Functions

 DEFINE_ENUM (HTTP_HEADERS_RESULT, HTTP_HEADERS_RESULT_VALUES)
 Enumeration specifying the status of calls to various APIs in this module.
 MOCKABLE_FUNCTION (, HTTP_HEADERS_HANDLE, HTTPHeaders_Alloc)
 Produces a HTTP_HANDLE that can later be used in subsequent calls to the module.
 MOCKABLE_FUNCTION (, void, HTTPHeaders_Free, HTTP_HEADERS_HANDLE, httpHeadersHandle)
 De-allocates the data structures allocated by previous API calls to the same handle.
 MOCKABLE_FUNCTION (, HTTP_HEADERS_RESULT, HTTPHeaders_AddHeaderNameValuePair, HTTP_HEADERS_HANDLE, httpHeadersHandle, const char *, name, const char *, value)
 Adds a header record from the name and value parameters.
 MOCKABLE_FUNCTION (, HTTP_HEADERS_RESULT, HTTPHeaders_ReplaceHeaderNameValuePair, HTTP_HEADERS_HANDLE, httpHeadersHandle, const char *, name, const char *, value)
 This API performs exactly the same as HTTPHeaders_AddHeaderNameValuePair except that if the header name already exists then the already existing value will be replaced as opposed to being concatenated to.
 MOCKABLE_FUNCTION (, const char *, HTTPHeaders_FindHeaderValue, HTTP_HEADERS_HANDLE, httpHeadersHandle, const char *, name)
 Retrieves the value for a previously stored name.
 MOCKABLE_FUNCTION (, HTTP_HEADERS_RESULT, HTTPHeaders_GetHeaderCount, HTTP_HEADERS_HANDLE, httpHeadersHandle, size_t *, headersCount)
 This API retrieves the number of stored headers.
 MOCKABLE_FUNCTION (, HTTP_HEADERS_RESULT, HTTPHeaders_GetHeader, HTTP_HEADERS_HANDLE, handle, size_t, index, char **, destination)
 This API retrieves the string name+": "+value for the header element at the given index.
 MOCKABLE_FUNCTION (, HTTP_HEADERS_HANDLE, HTTPHeaders_Clone, HTTP_HEADERS_HANDLE, handle)
 This API produces a clone of the handle parameter.

Detailed Description

This is a utility module that handles HTTP message-headers.

An application would use HTTPHeaders_Alloc to create a new set of HTTP headers. After getting the handle, the application would build in several headers by consecutive calls to HTTPHeaders_AddHeaderNameValuePair. When the headers are constructed, the application can retrieve the stored data by calling one of the following functions:

  • HTTPHeaders_FindHeaderValue - when the name of the header is known and it wants to know the value of that header
  • HTTPHeaders_GetHeaderCount - when the application needs to know the count of all the headers
  • HTTPHeaders_GetHeader - when the application needs to retrieve the name + ": " + value string based on an index.

Definition in file httpheaders.h.

Function Documentation

DEFINE_ENUM ( HTTP_HEADERS_RESULT  ,
HTTP_HEADERS_RESULT_VALUES   
)

Enumeration specifying the status of calls to various APIs in this module.

MOCKABLE_FUNCTION ( HTTP_HEADERS_HANDLE  ,
HTTPHeaders_Clone  ,
HTTP_HEADERS_HANDLE  ,
handle   
)

This API produces a clone of the handle parameter.

Parameters:
handleA valid HTTP_HEADERS_HANDLE value.

If handle is not NULL this function clones the content of the handle to a new handle and returns it.

Returns:
A HTTP_HEADERS_HANDLE containing a cloned copy of the contents of handle.
MOCKABLE_FUNCTION ( HTTP_HEADERS_RESULT  ,
HTTPHeaders_GetHeader  ,
HTTP_HEADERS_HANDLE  ,
handle  ,
size_t  ,
index  ,
char **  ,
destination   
)

This API retrieves the string name+": "+value for the header element at the given index.

Parameters:
handleA valid HTTP_HEADERS_HANDLE value.
indexZero-based index of the item in the headers collection.
destinationIf non-null, the header value is written into a new string a pointer to which is written into this parameters. It is the caller's responsibility to free this memory.
Returns:
Returns HTTP_HEADERS_OK when execution is successful or HTTP_HEADERS_ERROR when an error occurs.
MOCKABLE_FUNCTION ( HTTP_HEADERS_RESULT  ,
HTTPHeaders_GetHeaderCount  ,
HTTP_HEADERS_HANDLE  ,
httpHeadersHandle  ,
size_t *  ,
headersCount   
)

This API retrieves the number of stored headers.

Parameters:
httpHeadersHandleA valid HTTP_HEADERS_HANDLE value.
headersCountIf non-null, the API writes the number of into the memory pointed at by this parameter.
Returns:
Returns HTTP_HEADERS_OK when execution is successful or HTTP_HEADERS_ERROR when an error occurs.
MOCKABLE_FUNCTION ( const char *  ,
HTTPHeaders_FindHeaderValue  ,
HTTP_HEADERS_HANDLE  ,
httpHeadersHandle  ,
const char *  ,
name   
)

Retrieves the value for a previously stored name.

Parameters:
httpHeadersHandleA valid HTTP_HEADERS_HANDLE value.
nameThe name of the HTTP header to find.
Returns:
The return value points to a string that shall be strcmp equal to the original stored string.
MOCKABLE_FUNCTION ( HTTP_HEADERS_RESULT  ,
HTTPHeaders_ReplaceHeaderNameValuePair  ,
HTTP_HEADERS_HANDLE  ,
httpHeadersHandle  ,
const char *  ,
name  ,
const char *  ,
value   
)

This API performs exactly the same as HTTPHeaders_AddHeaderNameValuePair except that if the header name already exists then the already existing value will be replaced as opposed to being concatenated to.

Parameters:
httpHeadersHandleA valid HTTP_HEADERS_HANDLE value.
nameThe name of the HTTP header to add/replace. It is invalid for the name to include the ':' character or character codes outside the range 33-126.
valueThe value to be assigned to the header.
Returns:
Returns HTTP_HEADERS_OK when execution is successful or an error code from the HTTPAPIEX_RESULT enum.
MOCKABLE_FUNCTION ( HTTP_HEADERS_RESULT  ,
HTTPHeaders_AddHeaderNameValuePair  ,
HTTP_HEADERS_HANDLE  ,
httpHeadersHandle  ,
const char *  ,
name  ,
const char *  ,
value   
)

Adds a header record from the name and value parameters.

Parameters:
httpHeadersHandleA valid HTTP_HEADERS_HANDLE value.
nameThe name of the HTTP header to add. It is invalid for the name to include the ':' character or character codes outside the range 33-126.
valueThe value to be assigned to the header.

The function stores the name:value pair in such a way that when later retrieved by a call to HTTPHeaders_GetHeader it will return a string that is strcmp equal to name+": "+value. If the name already exists in the collection of headers, the function concatenates the new value after the existing value, separated by a comma and a space as in: old-value+", "+new-value.

Returns:
Returns HTTP_HEADERS_OK when execution is successful or an error code from the HTTPAPIEX_RESULT enum.
MOCKABLE_FUNCTION ( void  ,
HTTPHeaders_Free  ,
HTTP_HEADERS_HANDLE  ,
httpHeadersHandle   
)

De-allocates the data structures allocated by previous API calls to the same handle.

Parameters:
httpHeadersHandleA valid HTTP_HEADERS_HANDLE value.
MOCKABLE_FUNCTION ( HTTP_HEADERS_HANDLE  ,
HTTPHeaders_Alloc   
)

Produces a HTTP_HANDLE that can later be used in subsequent calls to the module.

This function returns NULL in case an error occurs. After successful execution HTTPHeaders_GetHeaderCount will report 0 existing headers.

Returns:
A HTTP_HEADERS_HANDLE representing the newly created collection of HTTP headers.
Generated on Tue Jul 12 2022 19:14:38 by  doxygen 1.7.2