Azure SDK for Embedded C
Data Structures | Typedefs | Functions
az_http_transport.h File Reference

Utilities to be used by HTTP transport policy implementations. More...

#include <azure/core/az_http.h>
#include <azure/core/az_span.h>
#include <azure/core/_az_cfg_prefix.h>
#include <azure/core/_az_cfg_suffix.h>

Go to the source code of this file.

Data Structures

struct  az_http_request
 Structure used to represent an HTTP request. It contains an HTTP method, URL, headers and body. It also contains another utility variables. More...
 

Typedefs

typedef az_span az_http_method
 A type representing an HTTP method (POST, PUT, GET, DELETE, etc.).
 

Functions

AZ_INLINE az_http_method az_http_method_get ()
 HTTP GET method name.
 
AZ_INLINE az_http_method az_http_method_head ()
 HTTP HEAD method name.
 
AZ_INLINE az_http_method az_http_method_post ()
 HTTP POST method name.
 
AZ_INLINE az_http_method az_http_method_put ()
 HTTP PUT method name.
 
AZ_INLINE az_http_method az_http_method_delete ()
 HTTP DELETE method name.
 
AZ_INLINE az_http_method az_http_method_patch ()
 HTTP PATCH method name.
 
AZ_NODISCARD az_result az_http_request_get_header (az_http_request const *request, int32_t index, az_span *out_name, az_span *out_value)
 Gets the HTTP header by index. More...
 
AZ_NODISCARD az_result az_http_request_get_method (az_http_request const *request, az_http_method *out_method)
 Get method of an HTTP request. More...
 
AZ_NODISCARD az_result az_http_request_get_url (az_http_request const *request, az_span *out_url)
 Get the URL from an HTTP request. More...
 
AZ_NODISCARD az_result az_http_request_get_body (az_http_request const *request, az_span *out_body)
 Get body from an HTTP request. More...
 
AZ_NODISCARD az_result az_http_response_append (az_http_response *ref_response, az_span source)
 This function is expected to be used by transport adapters like curl. Use it to write content from source to ref_response. More...
 
AZ_NODISCARD int32_t az_http_request_headers_count (az_http_request const *request)
 Returns the number of headers within the request. More...
 
AZ_NODISCARD az_result az_http_client_send_request (az_http_request const *request, az_http_response *ref_response)
 Sends an HTTP request through the wire and write the response into ref_response. More...
 

Detailed Description

Utilities to be used by HTTP transport policy implementations.

Note
You MUST NOT use any symbols (macros, functions, structures, enums, etc.) prefixed with an underscore ('_') directly in your application code. These symbols are part of Azure SDK's internal implementation; we do not document these symbols and they are subject to change in future versions of the SDK which would break your code.

Function Documentation

◆ az_http_client_send_request()

AZ_NODISCARD az_result az_http_client_send_request ( az_http_request const *  request,
az_http_response ref_response 
)

Sends an HTTP request through the wire and write the response into ref_response.

Parameters
[in]requestPoints to an az_http_request that contains the settings and data that is used to send the request through the wire.
[in,out]ref_responsePoints to an az_http_response where the response from the wire will be written.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKSuccess.
AZ_ERROR_HTTP_RESPONSE_OVERFLOWThere was an issue while trying to write into ref_response. It might mean that there was not enough space in ref_response to hold the entire response from the network.
AZ_ERROR_HTTP_RESPONSE_COULDNT_RESOLVE_HOSTThe URL from ref_request can't be resolved by the HTTP stack and the request was not sent.
AZ_ERROR_HTTP_ADAPTERAny other issue from the transport adapter layer.

◆ az_http_request_get_body()

AZ_NODISCARD az_result az_http_request_get_body ( az_http_request const *  request,
az_span out_body 
)

Get body from an HTTP request.

Remarks
This function is expected to be used by transport layer only.
Parameters
[in]requestThe HTTP request from which to get the body.
[out]out_bodyPointer to write the HTTP request body to.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKSuccess.
otherFailure.

◆ az_http_request_get_header()

AZ_NODISCARD az_result az_http_request_get_header ( az_http_request const *  request,
int32_t  index,
az_span out_name,
az_span out_value 
)

Gets the HTTP header by index.

Parameters
[in]requestHTTP request to get HTTP header from.
[in]indexIndex of the HTTP header to get.
[out]out_nameA pointer to an az_span to write the header's name.
[out]out_valueA pointer to an az_span to write the header's value.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKSuccess.
AZ_ERROR_ARGindex is out of range.

◆ az_http_request_get_method()

AZ_NODISCARD az_result az_http_request_get_method ( az_http_request const *  request,
az_http_method out_method 
)

Get method of an HTTP request.

Remarks
This function is expected to be used by transport layer only.
Parameters
[in]requestThe HTTP request from which to get the method.
[out]out_methodPointer to write the HTTP method to.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKSuccess.
otherFailure.

◆ az_http_request_get_url()

AZ_NODISCARD az_result az_http_request_get_url ( az_http_request const *  request,
az_span out_url 
)

Get the URL from an HTTP request.

Remarks
This function is expected to be used by transport layer only.
Parameters
[in]requestThe HTTP request from which to get the URL.
[out]out_urlPointer to write the HTTP URL to.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKSuccess.
otherFailure.

◆ az_http_request_headers_count()

AZ_NODISCARD int32_t az_http_request_headers_count ( az_http_request const *  request)

Returns the number of headers within the request.

Parameters
[in]requestPointer to an az_http_request to be used by this function.
Returns
Number of headers in the request.

◆ az_http_response_append()

AZ_NODISCARD az_result az_http_response_append ( az_http_response ref_response,
az_span  source 
)

This function is expected to be used by transport adapters like curl. Use it to write content from source to ref_response.

Remarks
The source can be an empty az_span. If so, nothing will be written.
Parameters
[in,out]ref_responsePointer to an az_http_response.
[in]sourceThis is an az_span with the content to be written into ref_response.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKSuccess.
AZ_ERROR_NOT_ENOUGH_SPACEThe response buffer is not big enough to contain the source content.