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

enum 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_response	A pointer to an az_http_response instance.
[out]	out_body	A 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_OK	An az_span over the response body was returned.
other	Error 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_response	A pointer to an az_http_response instance.
[out]	out_name	A pointer to an az_span to receive the header's name.
[out]	out_value	A 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_OK	A header was returned.
AZ_ERROR_HTTP_END_OF_HEADERS	There are no more headers within the HTTP response payload.
AZ_ERROR_HTTP_CORRUPT_RESPONSE_HEADER	The HTTP response contains an unexpected invalid character or is incomplete.
AZ_ERROR_HTTP_INVALID_STATE	The 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_response

The 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_response	The az_http_response with an HTTP response.
[out]	out_status_line	The 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_OK	Response status line was parsed to out_status_line.
other	HTTP 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_response	The pointer to an az_http_response instance which is to be initialized.
[in]	buffer	A 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_OK	Success.
other	Initialization failed.