Azure SDK for Embedded C
Data Structures | Enumerations | Functions
az_http.h File Reference

This header defines the types and functions your application uses to leverage HTTP request and response functionality. More...

#include <azure/core/az_config.h>
#include <azure/core/az_context.h>
#include <azure/core/az_result.h>
#include <azure/core/az_span.h>
#include <stdbool.h>
#include <stdint.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_policy_retry_options
 Allows you to customize the retry policy used by SDK clients whenever they perform an I/O operation. More...
 
struct  az_http_response
 Allows you to parse an HTTP response's status line, headers, and body. More...
 
struct  az_http_response_status_line
 Represents the result of making an HTTP request. An application obtains this initialized structure by calling az_http_response_get_status_line(). More...
 

Enumerations

enum  az_http_status_code {
  AZ_HTTP_STATUS_CODE_NONE = 0, AZ_HTTP_STATUS_CODE_CONTINUE = 100, AZ_HTTP_STATUS_CODE_SWITCHING_PROTOCOLS = 101, AZ_HTTP_STATUS_CODE_PROCESSING = 102,
  AZ_HTTP_STATUS_CODE_EARLY_HINTS = 103, AZ_HTTP_STATUS_CODE_OK = 200, AZ_HTTP_STATUS_CODE_CREATED = 201, AZ_HTTP_STATUS_CODE_ACCEPTED = 202,
  AZ_HTTP_STATUS_CODE_NON_AUTHORITATIVE_INFORMATION = 203, AZ_HTTP_STATUS_CODE_NO_CONTENT = 204, AZ_HTTP_STATUS_CODE_RESET_CONTENT = 205, AZ_HTTP_STATUS_CODE_PARTIAL_CONTENT = 206,
  AZ_HTTP_STATUS_CODE_MULTI_STATUS = 207, AZ_HTTP_STATUS_CODE_ALREADY_REPORTED = 208, AZ_HTTP_STATUS_CODE_IM_USED = 226, AZ_HTTP_STATUS_CODE_MULTIPLE_CHOICES = 300,
  AZ_HTTP_STATUS_CODE_MOVED_PERMANENTLY = 301, AZ_HTTP_STATUS_CODE_FOUND = 302, AZ_HTTP_STATUS_CODE_SEE_OTHER = 303, AZ_HTTP_STATUS_CODE_NOT_MODIFIED = 304,
  AZ_HTTP_STATUS_CODE_USE_PROXY = 305, AZ_HTTP_STATUS_CODE_TEMPORARY_REDIRECT = 307, AZ_HTTP_STATUS_CODE_PERMANENT_REDIRECT = 308, AZ_HTTP_STATUS_CODE_BAD_REQUEST = 400,
  AZ_HTTP_STATUS_CODE_UNAUTHORIZED = 401, AZ_HTTP_STATUS_CODE_PAYMENT_REQUIRED = 402, AZ_HTTP_STATUS_CODE_FORBIDDEN = 403, AZ_HTTP_STATUS_CODE_NOT_FOUND = 404,
  AZ_HTTP_STATUS_CODE_METHOD_NOT_ALLOWED = 405, AZ_HTTP_STATUS_CODE_NOT_ACCEPTABLE = 406, AZ_HTTP_STATUS_CODE_PROXY_AUTHENTICATION_REQUIRED = 407, AZ_HTTP_STATUS_CODE_REQUEST_TIMEOUT = 408,
  AZ_HTTP_STATUS_CODE_CONFLICT = 409, AZ_HTTP_STATUS_CODE_GONE = 410, AZ_HTTP_STATUS_CODE_LENGTH_REQUIRED = 411, AZ_HTTP_STATUS_CODE_PRECONDITION_FAILED = 412,
  AZ_HTTP_STATUS_CODE_PAYLOAD_TOO_LARGE = 413, AZ_HTTP_STATUS_CODE_URI_TOO_LONG = 414, AZ_HTTP_STATUS_CODE_UNSUPPORTED_MEDIA_TYPE = 415, AZ_HTTP_STATUS_CODE_RANGE_NOT_SATISFIABLE = 416,
  AZ_HTTP_STATUS_CODE_EXPECTATION_FAILED = 417, AZ_HTTP_STATUS_CODE_MISDIRECTED_REQUEST = 421, AZ_HTTP_STATUS_CODE_UNPROCESSABLE_ENTITY = 422, AZ_HTTP_STATUS_CODE_LOCKED = 423,
  AZ_HTTP_STATUS_CODE_FAILED_DEPENDENCY = 424, AZ_HTTP_STATUS_CODE_TOO_EARLY = 425, AZ_HTTP_STATUS_CODE_UPGRADE_REQUIRED = 426, AZ_HTTP_STATUS_CODE_PRECONDITION_REQUIRED = 428,
  AZ_HTTP_STATUS_CODE_TOO_MANY_REQUESTS = 429, AZ_HTTP_STATUS_CODE_REQUEST_HEADER_FIELDS_TOO_LARGE = 431, AZ_HTTP_STATUS_CODE_UNAVAILABLE_FOR_LEGAL_REASONS = 451, AZ_HTTP_STATUS_CODE_INTERNAL_SERVER_ERROR = 500,
  AZ_HTTP_STATUS_CODE_NOT_IMPLEMENTED = 501, AZ_HTTP_STATUS_CODE_BAD_GATEWAY = 502, AZ_HTTP_STATUS_CODE_SERVICE_UNAVAILABLE = 503, AZ_HTTP_STATUS_CODE_GATEWAY_TIMEOUT = 504,
  AZ_HTTP_STATUS_CODE_HTTP_VERSION_NOT_SUPPORTED = 505, AZ_HTTP_STATUS_CODE_VARIANT_ALSO_NEGOTIATES = 506, AZ_HTTP_STATUS_CODE_INSUFFICIENT_STORAGE = 507, AZ_HTTP_STATUS_CODE_LOOP_DETECTED = 508,
  AZ_HTTP_STATUS_CODE_NOT_EXTENDED = 510, AZ_HTTP_STATUS_CODE_NETWORK_AUTHENTICATION_REQUIRED = 511
}
 Defines the possible HTTP status codes. More...
 

Functions

AZ_NODISCARD AZ_INLINE az_result az_http_response_init (az_http_response *out_response, az_span buffer)
 Initializes an az_http_response instance over a byte buffer (span) which will be filled with the HTTP response data as it comes in from the network. More...
 
AZ_NODISCARD az_result az_http_response_get_status_line (az_http_response *ref_response, az_http_response_status_line *out_status_line)
 Returns the az_http_response_status_line information within an HTTP response. More...
 
AZ_INLINE AZ_NODISCARD az_http_status_code az_http_response_get_status_code (az_http_response *ref_response)
 Returns the az_http_status_code information from an HTTP response. More...
 
AZ_NODISCARD az_result az_http_response_get_next_header (az_http_response *ref_response, az_span *out_name, az_span *out_value)
 Returns the next HTTP response header. More...
 
AZ_NODISCARD az_result az_http_response_get_body (az_http_response *ref_response, az_span *out_body)
 Returns a span over the HTTP body within an HTTP response. More...
 

Detailed Description

This header defines the types and functions your application uses to leverage HTTP request and response functionality.

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.

Enumeration Type Documentation

◆ az_http_status_code

Defines the possible HTTP status codes.

Enumerator
AZ_HTTP_STATUS_CODE_NONE 

No HTTP status code.

AZ_HTTP_STATUS_CODE_CONTINUE 

HTTP 100 Continue.

AZ_HTTP_STATUS_CODE_SWITCHING_PROTOCOLS 

HTTP 101 Switching Protocols.

AZ_HTTP_STATUS_CODE_PROCESSING 

HTTP 102 Processing.

AZ_HTTP_STATUS_CODE_EARLY_HINTS 

HTTP 103 Early Hints.

AZ_HTTP_STATUS_CODE_OK 

HTTP 200 OK.

AZ_HTTP_STATUS_CODE_CREATED 

HTTP 201 Created.

AZ_HTTP_STATUS_CODE_ACCEPTED 

HTTP 202 Accepted.

AZ_HTTP_STATUS_CODE_NON_AUTHORITATIVE_INFORMATION 

HTTP 203 Non-Authoritative Information.

AZ_HTTP_STATUS_CODE_NO_CONTENT 

HTTP 204 No Content.

AZ_HTTP_STATUS_CODE_RESET_CONTENT 

HTTP 205 Rest Content.

AZ_HTTP_STATUS_CODE_PARTIAL_CONTENT 

HTTP 206 Partial Content.

AZ_HTTP_STATUS_CODE_MULTI_STATUS 

HTTP 207 Multi-Status.

AZ_HTTP_STATUS_CODE_ALREADY_REPORTED 

HTTP 208 Already Reported.

AZ_HTTP_STATUS_CODE_IM_USED 

HTTP 226 IM Used.

AZ_HTTP_STATUS_CODE_MULTIPLE_CHOICES 

HTTP 300 Multiple Choices.

AZ_HTTP_STATUS_CODE_MOVED_PERMANENTLY 

HTTP 301 Moved Permanently.

AZ_HTTP_STATUS_CODE_FOUND 

HTTP 302 Found.

AZ_HTTP_STATUS_CODE_SEE_OTHER 

HTTP 303 See Other.

AZ_HTTP_STATUS_CODE_NOT_MODIFIED 

HTTP 304 Not Modified.

AZ_HTTP_STATUS_CODE_USE_PROXY 

HTTP 305 Use Proxy.

AZ_HTTP_STATUS_CODE_TEMPORARY_REDIRECT 

HTTP 307 Temporary Redirect.

AZ_HTTP_STATUS_CODE_PERMANENT_REDIRECT 

HTTP 308 Permanent Redirect.

AZ_HTTP_STATUS_CODE_BAD_REQUEST 

HTTP 400 Bad Request.

AZ_HTTP_STATUS_CODE_UNAUTHORIZED 

HTTP 401 Unauthorized.

AZ_HTTP_STATUS_CODE_PAYMENT_REQUIRED 

HTTP 402 Payment Required.

AZ_HTTP_STATUS_CODE_FORBIDDEN 

HTTP 403 Forbidden.

AZ_HTTP_STATUS_CODE_NOT_FOUND 

HTTP 404 Not Found.

AZ_HTTP_STATUS_CODE_METHOD_NOT_ALLOWED 

HTTP 405 Method Not Allowed.

AZ_HTTP_STATUS_CODE_NOT_ACCEPTABLE 

HTTP 406 Not Acceptable.

AZ_HTTP_STATUS_CODE_PROXY_AUTHENTICATION_REQUIRED 

HTTP 407 Proxy Authentication Required.

AZ_HTTP_STATUS_CODE_REQUEST_TIMEOUT 

HTTP 408 Request Timeout.

AZ_HTTP_STATUS_CODE_CONFLICT 

HTTP 409 Conflict.

AZ_HTTP_STATUS_CODE_GONE 

HTTP 410 Gone.

AZ_HTTP_STATUS_CODE_LENGTH_REQUIRED 

HTTP 411 Length Required.

AZ_HTTP_STATUS_CODE_PRECONDITION_FAILED 

HTTP 412 Precondition Failed.

AZ_HTTP_STATUS_CODE_PAYLOAD_TOO_LARGE 

HTTP 413 Payload Too Large.

AZ_HTTP_STATUS_CODE_URI_TOO_LONG 

HTTP 414 URI Too Long.

AZ_HTTP_STATUS_CODE_UNSUPPORTED_MEDIA_TYPE 

HTTP 415 Unsupported Media Type.

AZ_HTTP_STATUS_CODE_RANGE_NOT_SATISFIABLE 

HTTP 416 Range Not Satisfiable.

AZ_HTTP_STATUS_CODE_EXPECTATION_FAILED 

HTTP 417 Expectation Failed.

AZ_HTTP_STATUS_CODE_MISDIRECTED_REQUEST 

HTTP 421 Misdirected Request.

AZ_HTTP_STATUS_CODE_UNPROCESSABLE_ENTITY 

HTTP 422 Unprocessable Entity.

AZ_HTTP_STATUS_CODE_LOCKED 

HTTP 423 Locked.

AZ_HTTP_STATUS_CODE_FAILED_DEPENDENCY 

HTTP 424 Failed Dependency.

AZ_HTTP_STATUS_CODE_TOO_EARLY 

HTTP 425 Too Early.

AZ_HTTP_STATUS_CODE_UPGRADE_REQUIRED 

HTTP 426 Upgrade Required.

AZ_HTTP_STATUS_CODE_PRECONDITION_REQUIRED 

HTTP 428 Precondition Required.

AZ_HTTP_STATUS_CODE_TOO_MANY_REQUESTS 

HTTP 429 Too Many Requests.

AZ_HTTP_STATUS_CODE_REQUEST_HEADER_FIELDS_TOO_LARGE 

HTTP 431 Request Header Fields Too Large.

AZ_HTTP_STATUS_CODE_UNAVAILABLE_FOR_LEGAL_REASONS 

HTTP 451 Unavailable For Legal Reasons.

AZ_HTTP_STATUS_CODE_INTERNAL_SERVER_ERROR 

HTTP 500 Internal Server Error.

AZ_HTTP_STATUS_CODE_NOT_IMPLEMENTED 

HTTP 501 Not Implemented.

AZ_HTTP_STATUS_CODE_BAD_GATEWAY 

HTTP 502 Bad Gateway.

AZ_HTTP_STATUS_CODE_SERVICE_UNAVAILABLE 

HTTP 503 Unavailable.

AZ_HTTP_STATUS_CODE_GATEWAY_TIMEOUT 

HTTP 504 Gateway Timeout.

AZ_HTTP_STATUS_CODE_HTTP_VERSION_NOT_SUPPORTED 

HTTP 505 HTTP Version Not Supported.

AZ_HTTP_STATUS_CODE_VARIANT_ALSO_NEGOTIATES 

HTTP 506 Variant Also Negotiates.

AZ_HTTP_STATUS_CODE_INSUFFICIENT_STORAGE 

HTTP 507 Insufficient Storage.

AZ_HTTP_STATUS_CODE_LOOP_DETECTED 

HTTP 508 Loop Detected.

AZ_HTTP_STATUS_CODE_NOT_EXTENDED 

HTTP 510 Not Extended.

AZ_HTTP_STATUS_CODE_NETWORK_AUTHENTICATION_REQUIRED 

HTTP 511 Network Authentication Required.

Function Documentation

◆ az_http_response_get_body()

AZ_NODISCARD az_result az_http_response_get_body ( az_http_response ref_response,
az_span out_body 
)

Returns a span over the HTTP body within an HTTP response.

Parameters
[in,out]ref_responseA pointer to an az_http_response instance.
[out]out_bodyA pointer to an az_span to receive the HTTP response's body.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKAn az_span over the response body was returned.
otherError while trying to read and parse body.

◆ az_http_response_get_next_header()

AZ_NODISCARD az_result az_http_response_get_next_header ( az_http_response ref_response,
az_span out_name,
az_span out_value 
)

Returns the next HTTP response header.

When called right after az_http_response_get_status_line(), or after az_http_response_get_status_code(), this function returns the first header. When called after calling az_http_response_get_next_header(), this function returns the next header.

If called after parsing HTTP body or before parsing status line, this function will return AZ_ERROR_HTTP_INVALID_STATE.

Parameters
[in,out]ref_responseA pointer to an az_http_response instance.
[out]out_nameA pointer to an az_span to receive the header's name.
[out]out_valueA pointer to an az_span to receive the header's value.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKA header was returned.
AZ_ERROR_HTTP_END_OF_HEADERSThere are no more headers within the HTTP response payload.
AZ_ERROR_HTTP_CORRUPT_RESPONSE_HEADERThe HTTP response contains an unexpected invalid character or is incomplete.
AZ_ERROR_HTTP_INVALID_STATEThe az_http_response instance is in an invalid state. Consider calling az_http_response_get_status_line() to reset its state.

◆ az_http_response_get_status_code()

AZ_INLINE AZ_NODISCARD az_http_status_code az_http_response_get_status_code ( az_http_response ref_response)

Returns the az_http_status_code information from an HTTP response.

Invokes az_http_response_get_status_line(), so it advances the reading position accordingly.

Remarks
Use this function when HTTP Reason Phrase is not needed, and when it is not important for the invoking code to distinguish between AZ_HTTP_STATUS_CODE_NONE and any possible error when parsing an HTTP response.
Parameters
[in,out]ref_responseThe az_http_response with an HTTP response.
Returns
An HTTP status code.

◆ az_http_response_get_status_line()

AZ_NODISCARD az_result az_http_response_get_status_line ( az_http_response ref_response,
az_http_response_status_line out_status_line 
)

Returns the az_http_response_status_line information within an HTTP response.

Parameters
[in,out]ref_responseThe az_http_response with an HTTP response.
[out]out_status_lineThe pointer to an az_http_response_status_line structure to be filled in by this function.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKResponse status line was parsed to out_status_line.
otherHTTP response was not parsed.

◆ az_http_response_init()

AZ_NODISCARD AZ_INLINE az_result az_http_response_init ( az_http_response out_response,
az_span  buffer 
)

Initializes an az_http_response instance over a byte buffer (span) which will be filled with the HTTP response data as it comes in from the network.

Parameters
[out]out_responseThe pointer to an az_http_response instance which is to be initialized.
[in]bufferA span over the byte buffer that is to be filled with the HTTP response data. This buffer must be large enough to hold the entire response.
Returns
An az_result value indicating the result of the operation.
Return values
AZ_OKSuccess.
otherInitialization failed.