Azure SDK for Embedded C
az_http.h
Go to the documentation of this file.
1 // Copyright (c) Microsoft Corporation. All rights reserved.
2 // SPDX-License-Identifier: MIT
3 
16 #ifndef _az_HTTP_H
17 #define _az_HTTP_H
18 
19 #include <azure/core/az_config.h>
20 #include <azure/core/az_context.h>
21 #include <azure/core/az_result.h>
22 #include <azure/core/az_span.h>
23 
24 #include <stdbool.h>
25 #include <stdint.h>
26 
27 #include <azure/core/_az_cfg_prefix.h>
28 
32 typedef enum
33 {
36 
37  // === 1xx (information) Status Codes: ===
42 
43  // === 2xx (successful) Status Codes: ===
48  = 203,
55 
56  // === 3xx (redirection) Status Codes: ===
65 
66  // === 4xx (client error) Status Codes: ===
75  = 407,
95  = 431,
97  = 451,
98 
99  // === 5xx (server error) Status Codes: ===
111  = 511,
113 
122 typedef struct
123 {
126 
129 
131  int32_t max_retries;
133 
134 typedef enum
135 {
136  _az_HTTP_RESPONSE_KIND_STATUS_LINE = 0,
137  _az_HTTP_RESPONSE_KIND_HEADER = 1,
138  _az_HTTP_RESPONSE_KIND_BODY = 2,
139  _az_HTTP_RESPONSE_KIND_EOF = 3,
140 } _az_http_response_kind;
141 
150 typedef struct
151 {
152  struct
153  {
154  az_span http_response;
155  int32_t written;
156  struct
157  {
158  az_span remaining; // the remaining un-parsed portion of the original http_response.
159  _az_http_response_kind next_kind;
160  // After parsing an element, next_kind refers to the next expected element
161  } parser;
162  } _internal;
164 
177 AZ_NODISCARD AZ_INLINE az_result
179 {
180  *out_response = (az_http_response){
181  ._internal = {
182  .http_response = buffer,
183  .written = 0,
184  .parser = {
185  .remaining = AZ_SPAN_EMPTY,
186  .next_kind = _az_HTTP_RESPONSE_KIND_STATUS_LINE,
187  },
188  },
189  };
190 
191  return AZ_OK;
192 }
193 
200 // Member order is optimized for alignment.
201 typedef struct
202 {
205  uint8_t major_version;
206  uint8_t minor_version;
208 
221  az_http_response* ref_response,
222  az_http_response_status_line* out_status_line);
223 
237 AZ_INLINE AZ_NODISCARD az_http_status_code
239 {
240  az_http_response_status_line status_line = { 0 };
241  return az_result_failed(az_http_response_get_status_line(ref_response, &status_line))
243  : status_line.status_code;
244 }
245 
270  az_http_response* ref_response,
271  az_span* out_name,
272  az_span* out_value);
273 
284 AZ_NODISCARD az_result az_http_response_get_body(az_http_response* ref_response, az_span* out_body);
285 
286 #include <azure/core/_az_cfg_suffix.h>
287 
288 #endif // _az_HTTP_H
AZ_HTTP_STATUS_CODE_NOT_ACCEPTABLE
@ AZ_HTTP_STATUS_CODE_NOT_ACCEPTABLE
HTTP 406 Not Acceptable.
Definition: az_http.h:73
AZ_HTTP_STATUS_CODE_GATEWAY_TIMEOUT
@ AZ_HTTP_STATUS_CODE_GATEWAY_TIMEOUT
HTTP 504 Gateway Timeout.
Definition: az_http.h:104
az_result.h
Definition of az_result and helper functions.
AZ_HTTP_STATUS_CODE_PRECONDITION_REQUIRED
@ AZ_HTTP_STATUS_CODE_PRECONDITION_REQUIRED
HTTP 428 Precondition Required.
Definition: az_http.h:92
AZ_HTTP_STATUS_CODE_UNPROCESSABLE_ENTITY
@ AZ_HTTP_STATUS_CODE_UNPROCESSABLE_ENTITY
HTTP 422 Unprocessable Entity.
Definition: az_http.h:87
AZ_HTTP_STATUS_CODE_ALREADY_REPORTED
@ AZ_HTTP_STATUS_CODE_ALREADY_REPORTED
HTTP 208 Already Reported.
Definition: az_http.h:53
az_http_status_code
az_http_status_code
Defines the possible HTTP status codes.
Definition: az_http.h:33
AZ_HTTP_STATUS_CODE_VARIANT_ALSO_NEGOTIATES
@ AZ_HTTP_STATUS_CODE_VARIANT_ALSO_NEGOTIATES
HTTP 506 Variant Also Negotiates.
Definition: az_http.h:106
AZ_HTTP_STATUS_CODE_IM_USED
@ AZ_HTTP_STATUS_CODE_IM_USED
HTTP 226 IM Used.
Definition: az_http.h:54
AZ_HTTP_STATUS_CODE_MULTI_STATUS
@ AZ_HTTP_STATUS_CODE_MULTI_STATUS
HTTP 207 Multi-Status.
Definition: az_http.h:52
AZ_HTTP_STATUS_CODE_PARTIAL_CONTENT
@ AZ_HTTP_STATUS_CODE_PARTIAL_CONTENT
HTTP 206 Partial Content.
Definition: az_http.h:51
AZ_HTTP_STATUS_CODE_URI_TOO_LONG
@ AZ_HTTP_STATUS_CODE_URI_TOO_LONG
HTTP 414 URI Too Long.
Definition: az_http.h:82
AZ_HTTP_STATUS_CODE_REQUEST_HEADER_FIELDS_TOO_LARGE
@ AZ_HTTP_STATUS_CODE_REQUEST_HEADER_FIELDS_TOO_LARGE
HTTP 431 Request Header Fields Too Large.
Definition: az_http.h:94
AZ_HTTP_STATUS_CODE_NO_CONTENT
@ AZ_HTTP_STATUS_CODE_NO_CONTENT
HTTP 204 No Content.
Definition: az_http.h:49
AZ_HTTP_STATUS_CODE_UPGRADE_REQUIRED
@ AZ_HTTP_STATUS_CODE_UPGRADE_REQUIRED
HTTP 426 Upgrade Required.
Definition: az_http.h:91
AZ_HTTP_STATUS_CODE_MOVED_PERMANENTLY
@ AZ_HTTP_STATUS_CODE_MOVED_PERMANENTLY
HTTP 301 Moved Permanently.
Definition: az_http.h:58
az_result
int32_t az_result
The type represents the various success and error conditions.
Definition: az_result.h:46
AZ_HTTP_STATUS_CODE_FAILED_DEPENDENCY
@ AZ_HTTP_STATUS_CODE_FAILED_DEPENDENCY
HTTP 424 Failed Dependency.
Definition: az_http.h:89
AZ_HTTP_STATUS_CODE_PAYMENT_REQUIRED
@ AZ_HTTP_STATUS_CODE_PAYMENT_REQUIRED
HTTP 402 Payment Required.
Definition: az_http.h:69
AZ_HTTP_STATUS_CODE_MISDIRECTED_REQUEST
@ AZ_HTTP_STATUS_CODE_MISDIRECTED_REQUEST
HTTP 421 Misdirected Request.
Definition: az_http.h:86
AZ_HTTP_STATUS_CODE_HTTP_VERSION_NOT_SUPPORTED
@ AZ_HTTP_STATUS_CODE_HTTP_VERSION_NOT_SUPPORTED
HTTP 505 HTTP Version Not Supported.
Definition: az_http.h:105
AZ_HTTP_STATUS_CODE_UNSUPPORTED_MEDIA_TYPE
@ AZ_HTTP_STATUS_CODE_UNSUPPORTED_MEDIA_TYPE
HTTP 415 Unsupported Media Type.
Definition: az_http.h:83
AZ_HTTP_STATUS_CODE_PAYLOAD_TOO_LARGE
@ AZ_HTTP_STATUS_CODE_PAYLOAD_TOO_LARGE
HTTP 413 Payload Too Large.
Definition: az_http.h:81
AZ_SPAN_EMPTY
#define AZ_SPAN_EMPTY
An empty az_span.
Definition: az_span.h:95
AZ_HTTP_STATUS_CODE_FORBIDDEN
@ AZ_HTTP_STATUS_CODE_FORBIDDEN
HTTP 403 Forbidden.
Definition: az_http.h:70
az_http_policy_retry_options::retry_delay_msec
int32_t retry_delay_msec
The minimum time, in milliseconds, to wait before a retry.
Definition: az_http.h:125
az_http_policy_retry_options::max_retry_delay_msec
int32_t max_retry_delay_msec
The maximum time, in milliseconds, to wait before a retry.
Definition: az_http.h:128
AZ_HTTP_STATUS_CODE_FOUND
@ AZ_HTTP_STATUS_CODE_FOUND
HTTP 302 Found.
Definition: az_http.h:59
az_result_failed
AZ_NODISCARD AZ_INLINE bool az_result_failed(az_result result)
Checks whether the result provided indicates a failure.
Definition: az_result.h:149
AZ_HTTP_STATUS_CODE_CONFLICT
@ AZ_HTTP_STATUS_CODE_CONFLICT
HTTP 409 Conflict.
Definition: az_http.h:77
AZ_HTTP_STATUS_CODE_TOO_EARLY
@ AZ_HTTP_STATUS_CODE_TOO_EARLY
HTTP 425 Too Early.
Definition: az_http.h:90
AZ_HTTP_STATUS_CODE_NETWORK_AUTHENTICATION_REQUIRED
@ AZ_HTTP_STATUS_CODE_NETWORK_AUTHENTICATION_REQUIRED
HTTP 511 Network Authentication Required.
Definition: az_http.h:110
AZ_HTTP_STATUS_CODE_CONTINUE
@ AZ_HTTP_STATUS_CODE_CONTINUE
HTTP 100 Continue.
Definition: az_http.h:38
AZ_HTTP_STATUS_CODE_NOT_MODIFIED
@ AZ_HTTP_STATUS_CODE_NOT_MODIFIED
HTTP 304 Not Modified.
Definition: az_http.h:61
az_context.h
Context for canceling long running operations.
AZ_HTTP_STATUS_CODE_LOOP_DETECTED
@ AZ_HTTP_STATUS_CODE_LOOP_DETECTED
HTTP 508 Loop Detected.
Definition: az_http.h:108
AZ_HTTP_STATUS_CODE_NOT_FOUND
@ AZ_HTTP_STATUS_CODE_NOT_FOUND
HTTP 404 Not Found.
Definition: az_http.h:71
AZ_HTTP_STATUS_CODE_OK
@ AZ_HTTP_STATUS_CODE_OK
HTTP 200 OK.
Definition: az_http.h:44
az_http_policy_retry_options
Allows you to customize the retry policy used by SDK clients whenever they perform an I/O operation.
Definition: az_http.h:123
AZ_HTTP_STATUS_CODE_SERVICE_UNAVAILABLE
@ AZ_HTTP_STATUS_CODE_SERVICE_UNAVAILABLE
HTTP 503 Unavailable.
Definition: az_http.h:103
AZ_HTTP_STATUS_CODE_PRECONDITION_FAILED
@ AZ_HTTP_STATUS_CODE_PRECONDITION_FAILED
HTTP 412 Precondition Failed.
Definition: az_http.h:80
AZ_HTTP_STATUS_CODE_BAD_REQUEST
@ AZ_HTTP_STATUS_CODE_BAD_REQUEST
HTTP 400 Bad Request.
Definition: az_http.h:67
AZ_HTTP_STATUS_CODE_ACCEPTED
@ AZ_HTTP_STATUS_CODE_ACCEPTED
HTTP 202 Accepted.
Definition: az_http.h:46
AZ_HTTP_STATUS_CODE_USE_PROXY
@ AZ_HTTP_STATUS_CODE_USE_PROXY
HTTP 305 Use Proxy.
Definition: az_http.h:62
AZ_HTTP_STATUS_CODE_NON_AUTHORITATIVE_INFORMATION
@ AZ_HTTP_STATUS_CODE_NON_AUTHORITATIVE_INFORMATION
HTTP 203 Non-Authoritative Information.
Definition: az_http.h:47
az_span.h
An az_span represents a contiguous byte buffer and is used for string manipulations,...
AZ_HTTP_STATUS_CODE_PROCESSING
@ AZ_HTTP_STATUS_CODE_PROCESSING
HTTP 102 Processing.
Definition: az_http.h:40
AZ_HTTP_STATUS_CODE_GONE
@ AZ_HTTP_STATUS_CODE_GONE
HTTP 410 Gone.
Definition: az_http.h:78
AZ_HTTP_STATUS_CODE_LENGTH_REQUIRED
@ AZ_HTTP_STATUS_CODE_LENGTH_REQUIRED
HTTP 411 Length Required.
Definition: az_http.h:79
AZ_HTTP_STATUS_CODE_RESET_CONTENT
@ AZ_HTTP_STATUS_CODE_RESET_CONTENT
HTTP 205 Rest Content.
Definition: az_http.h:50
AZ_HTTP_STATUS_CODE_MULTIPLE_CHOICES
@ AZ_HTTP_STATUS_CODE_MULTIPLE_CHOICES
HTTP 300 Multiple Choices.
Definition: az_http.h:57
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.
az_http_response_status_line::major_version
uint8_t major_version
HTTP Major Version.
Definition: az_http.h:205
AZ_HTTP_STATUS_CODE_PROXY_AUTHENTICATION_REQUIRED
@ AZ_HTTP_STATUS_CODE_PROXY_AUTHENTICATION_REQUIRED
HTTP 407 Proxy Authentication Required.
Definition: az_http.h:74
AZ_HTTP_STATUS_CODE_METHOD_NOT_ALLOWED
@ AZ_HTTP_STATUS_CODE_METHOD_NOT_ALLOWED
HTTP 405 Method Not Allowed.
Definition: az_http.h:72
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.
AZ_HTTP_STATUS_CODE_SWITCHING_PROTOCOLS
@ AZ_HTTP_STATUS_CODE_SWITCHING_PROTOCOLS
HTTP 101 Switching Protocols.
Definition: az_http.h:39
AZ_HTTP_STATUS_CODE_TEMPORARY_REDIRECT
@ AZ_HTTP_STATUS_CODE_TEMPORARY_REDIRECT
HTTP 307 Temporary Redirect.
Definition: az_http.h:63
AZ_HTTP_STATUS_CODE_EXPECTATION_FAILED
@ AZ_HTTP_STATUS_CODE_EXPECTATION_FAILED
HTTP 417 Expectation Failed.
Definition: az_http.h:85
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...
Definition: az_http.h:178
AZ_HTTP_STATUS_CODE_UNAUTHORIZED
@ AZ_HTTP_STATUS_CODE_UNAUTHORIZED
HTTP 401 Unauthorized.
Definition: az_http.h:68
az_http_response_status_line::status_code
az_http_status_code status_code
Status Code.
Definition: az_http.h:204
AZ_OK
@ AZ_OK
Success.
Definition: az_result.h:67
AZ_HTTP_STATUS_CODE_NONE
@ AZ_HTTP_STATUS_CODE_NONE
No HTTP status code.
Definition: az_http.h:35
AZ_HTTP_STATUS_CODE_RANGE_NOT_SATISFIABLE
@ AZ_HTTP_STATUS_CODE_RANGE_NOT_SATISFIABLE
HTTP 416 Range Not Satisfiable.
Definition: az_http.h:84
AZ_HTTP_STATUS_CODE_SEE_OTHER
@ AZ_HTTP_STATUS_CODE_SEE_OTHER
HTTP 303 See Other.
Definition: az_http.h:60
AZ_HTTP_STATUS_CODE_BAD_GATEWAY
@ AZ_HTTP_STATUS_CODE_BAD_GATEWAY
HTTP 502 Bad Gateway.
Definition: az_http.h:102
AZ_HTTP_STATUS_CODE_LOCKED
@ AZ_HTTP_STATUS_CODE_LOCKED
HTTP 423 Locked.
Definition: az_http.h:88
AZ_HTTP_STATUS_CODE_INTERNAL_SERVER_ERROR
@ AZ_HTTP_STATUS_CODE_INTERNAL_SERVER_ERROR
HTTP 500 Internal Server Error.
Definition: az_http.h:100
az_http_response_status_line
Represents the result of making an HTTP request. An application obtains this initialized structure by...
Definition: az_http.h:202
AZ_HTTP_STATUS_CODE_NOT_EXTENDED
@ AZ_HTTP_STATUS_CODE_NOT_EXTENDED
HTTP 510 Not Extended.
Definition: az_http.h:109
AZ_HTTP_STATUS_CODE_REQUEST_TIMEOUT
@ AZ_HTTP_STATUS_CODE_REQUEST_TIMEOUT
HTTP 408 Request Timeout.
Definition: az_http.h:76
AZ_HTTP_STATUS_CODE_TOO_MANY_REQUESTS
@ AZ_HTTP_STATUS_CODE_TOO_MANY_REQUESTS
HTTP 429 Too Many Requests.
Definition: az_http.h:93
AZ_HTTP_STATUS_CODE_NOT_IMPLEMENTED
@ AZ_HTTP_STATUS_CODE_NOT_IMPLEMENTED
HTTP 501 Not Implemented.
Definition: az_http.h:101
az_http_response_status_line::reason_phrase
az_span reason_phrase
Reason Phrase.
Definition: az_http.h:203
az_http_response_status_line::minor_version
uint8_t minor_version
HTTP Minor Version.
Definition: az_http.h:206
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.
Definition: az_http.h:238
AZ_HTTP_STATUS_CODE_EARLY_HINTS
@ AZ_HTTP_STATUS_CODE_EARLY_HINTS
HTTP 103 Early Hints.
Definition: az_http.h:41
az_config.h
Configurable constants used by the Azure SDK.
AZ_HTTP_STATUS_CODE_UNAVAILABLE_FOR_LEGAL_REASONS
@ AZ_HTTP_STATUS_CODE_UNAVAILABLE_FOR_LEGAL_REASONS
HTTP 451 Unavailable For Legal Reasons.
Definition: az_http.h:96
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.
AZ_HTTP_STATUS_CODE_PERMANENT_REDIRECT
@ AZ_HTTP_STATUS_CODE_PERMANENT_REDIRECT
HTTP 308 Permanent Redirect.
Definition: az_http.h:64
az_http_response
Allows you to parse an HTTP response's status line, headers, and body.
Definition: az_http.h:151
az_span
Represents a "view" over a byte buffer that represents a contiguous region of memory....
Definition: az_span.h:33
az_http_policy_retry_options::max_retries
int32_t max_retries
Maximum number of retries.
Definition: az_http.h:131
AZ_HTTP_STATUS_CODE_INSUFFICIENT_STORAGE
@ AZ_HTTP_STATUS_CODE_INSUFFICIENT_STORAGE
HTTP 507 Insufficient Storage.
Definition: az_http.h:107
AZ_HTTP_STATUS_CODE_CREATED
@ AZ_HTTP_STATUS_CODE_CREATED
HTTP 201 Created.
Definition: az_http.h:45