Expand description
Rust wrapper for the aws-c-http library. For testing purposes only.
For interacting with AWS services, use the aws-sdk-rust crate instead.
Structs
struct aws_atomic_var represents an atomic variable - a value which can hold an integer or pointer
that can be manipulated atomically. struct aws_atomic_vars should normally only be manipulated
with atomics methods defined in this header.
Represents a length-delimited binary string or buffer. If byte buffer points
to constant memory or memory that should otherwise not be freed by this
struct, set allocator to NULL and free function will be a no-op.
Represents a movable pointer within a larger binary string or buffer.
Pattern-struct that functions as a base “class” for all statistics structures. To conform
to the pattern, a statistics structure must have its first member be the category. In that
case it becomes “safe” to cast from aws_crt_statistics_base to the specific statistics structure
based on the category value.
Base structure for all statistics handler implementations.
Vtable for functions that all statistics handlers must implement
A statistics struct for http handlers. Tracks the actual amount of time that incoming and outgoing requests are
waiting for their IO to complete.
The start and end time, in milliseconds-since-epoch, that a set of statistics was gathered over.
Optional
If set, requests that a specific event loop be used to seat the connection, rather than the next one
in the event loop group. Useful for serializing all io and external events related to a client onto
a single thread.
Optional.
Pointer to the hash map containing the ALPN string to protocol to use.
Hash from
struct aws_string * to enum aws_http_version.
If not set, only the predefined string h2 and http/1.1 will be recognized. Other negotiated ALPN string will
result in a HTTP1/1 connection
Note: Connection will keep a deep copy of the table and the strings.HTTP/1.1 chunk extension for chunked encoding.
Note that the underlying strings are not owned by the byte cursors.
Encoding options for an HTTP/1.1 chunked transfer encoding chunk.
Options specific to HTTP/1.x connections.
Options specific to HTTP/2 connections.
HTTP/2 stream manager configuration struct.
Encoding options for manual H2 data frame writes
Options for creating an HTTP client connection.
Initialize with AWS_HTTP_CLIENT_CONNECTION_OPTIONS_INIT to set default values.
An HTTP connection.
This type is used by both server-side and client-side connections.
This type is also used by all supported versions of HTTP.
Configuration options for connection monitoring
A lightweight HTTP header struct.
Note that the underlying strings are not owned by the byte cursors.
A transformable block of HTTP headers.
Provides a nice API for getting/setting header names and values.
Options for creating a stream which sends a request from the client and receives a response from the server.
Metrics for logging and debugging purpose.
The definition for an outgoing HTTP request or response.
The message may be transformed (ex: signing the request) before its data is eventually sent.
Vtable for forwarding-based proxy negotiators
Vtable for tunneling-based proxy negotiators
Options for http proxy server usage
A listening socket which accepts incoming HTTP connections,
creating a server-side aws_http_connection to handle each one.
Options for configuring a server-side aws_http_connection.
Initialized with AWS_HTTP_SERVER_CONNECTION_OPTIONS_INIT to set default values.
Options for creating an HTTP server.
Initialize with AWS_HTTP_SERVER_OPTIONS_INIT to set default values.
A stream exists for the duration of a request/response exchange.
A client creates a stream to send a request and receive a response.
A server creates a stream to receive a request and send a response.
In http/2, a push-promise stream can be sent by a server and received by a client.
Options for aws_logger_init_standard().
Set
filename to open a file for logging and close it when the logger cleans up.
Set file to use a file that is already open, such as stderr or stdout.We separate the log level function from the log call itself so that we can do the filter check in the macros (see
below)
Required.
Server makes copy.
A websocket connection.
Options for creating a websocket client connection.
Data about an incoming frame.
See RFC-6455 Section 5.2.
Options for sending a websocket frame.
This structure is copied immediately by aws_websocket_send().
For descriptions of opcode, fin, rsv, and payload_length see in RFC-6455 Section 5.2.
Constants
Encode header strings literally.
If an intermediary re-broadcasts the headers, it is permitted to use cache.
Best for unique headers that are unlikely to repeat.
Encode header strings literally and forbid all intermediaries from using
cache when re-broadcasting.
Best for header fields that are highly valuable or sensitive to recovery.
Compress header by encoding the cached index of its strings,
or by updating the cache to contain these strings for future reference.
Best for headers that are sent repeatedly.
This is the default setting.
Use the proxy to forward http requests. Attempting to use both this mode and TLS on the tunnel destination
is a configuration error.
Deprecated, but 0-valued for backwards compatibility
Use the proxy to establish a connection to a remote endpoint via a CONNECT request through the proxy.
Works for both plaintext and tls connections.
Default.
Disable reading from environment variable for proxy.
Enable get proxy URL from environment variable, when the manual proxy options of connection manager is not set.
env HTTPS_PROXY/https_proxy will be checked when the main connection use tls.
env HTTP_PROXY/http_proxy will be checked when the main connection NOT use tls.
The lower case version has precedence.
Specifies acquire-release order; if this operation acts as a load, it acts as an
acquire operation; if it acts as a store, it acts as a release operation; if it’s
a load-store, it does both.
Specifies acquire ordering. No reads or writes on the current thread can be
reordered to happen before this operation. This is typically paired with a release
ordering; any writes that happened on the releasing operation will be visible
after the paired acquire operation.
No particular ordering constraints are guaranteed relative to other
operations at all; we merely ensure that the operation itself is atomic.
Specifies release order. No reads or writes can be reordered to come after this
operation. Typically paired with an acquire operation.
Specifies acquire-release order; if this operation acts as a load, it acts as an
acquire operation; if it acts as a store, it acts as a release operation; if it’s
a load-store, it does both.
Statics
Shortcuts for common HTTP request methods
Functions
Adds [num] arguments (expected to be of size_t), and returns the result in *r.
If the result overflows, returns AWS_OP_ERR; otherwise returns AWS_OP_SUCCESS.
Inexpensive (constant time) check of data-structure invariants.
Compare two arrays.
Return whether their contents are equivalent.
NULL may be passed as the array pointer if its length is declared to be 0.
Compare an array and a null-terminated string.
Returns true if their contents are equivalent.
The array should NOT contain a null-terminator, or the comparison will always return false.
NULL may be passed as the array pointer if its length is declared to be 0.
Perform a case-insensitive string comparison of an array and a null-terminated string.
Return whether their contents are equivalent.
The array should NOT contain a null-terminator, or the comparison will always return false.
NULL may be passed as the array pointer if its length is declared to be 0.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
Perform a case-insensitive string comparison of two arrays.
Return whether their contents are equivalent.
NULL may be passed as the array pointer if its length is declared to be 0.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
Copies the elements from from to to. If to is in static mode, it must at least be the same length as from. Any data
in to will be overwritten in this copy.
Ensures that the array list has enough capacity to store a value at the specified index. If there is not already
enough capacity, and the list is in dynamic mode, this function will attempt to allocate more memory, expanding the
list. In static mode, if ‘index’ is beyond the maximum index, AWS_ERROR_INVALID_INDEX will be raised.
If in dynamic mode, shrinks the allocated array size to the minimum amount necessary to store its elements.
Swap elements at the specified indices, which must be within the bounds of the array.
Appends a sub-buffer to the specified buffer.
Copies from to to. If to is too small, AWS_ERROR_DEST_COPY_TOO_SMALL will be
returned. dest->len will contain the amount of data actually copied to dest.
Copy contents of cursor to buffer, then update cursor to reference the memory stored in the buffer.
If buffer is too small, AWS_ERROR_DEST_COPY_TOO_SMALL will be returned.
Copies a single byte into
to. If to is too small, the buffer will be grown appropriately and
the old contents copied over, before the byte is appended.Copies a single byte into
to. If to is too small, the buffer will be grown appropriately and
the old contents copied over, before the byte is appended.Copies from to to. If to is too small, the buffer will be grown appropriately and
the old contents copied to, before the new contents are appended.
Copies
from to to. If to is too small, the buffer will be grown appropriately and
the old contents copied over, before the new contents are appended.Appends ‘\0’ at the end of the buffer.
Copies from to to while converting bytes via the passed in lookup table.
If to is too small, AWS_ERROR_DEST_COPY_TOO_SMALL will be
returned. to->len will contain its original size plus the amount of data actually copied to to.
Concatenates a variable number of struct aws_byte_buf * into destination.
Number of args must be greater than 1. If dest is too small,
AWS_ERROR_DEST_COPY_TOO_SMALL will be returned. dest->len will contain the
amount of data actually copied to dest.
Equivalent to calling aws_byte_buf_secure_zero and then aws_byte_buf_clean_up
on the buffer.
Compare two aws_byte_buf structures.
Return whether their contents are equivalent.
Compare an aws_byte_buf and a null-terminated string.
Returns true if their contents are equivalent.
The buffer should NOT contain a null-terminator, or the comparison will always return false.
Perform a case-insensitive string comparison of an aws_byte_buf and a null-terminated string.
Return whether their contents are equivalent.
The buffer should NOT contain a null-terminator, or the comparison will always return false.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
Perform a case-insensitive string comparison of two aws_byte_buf structures.
Return whether their contents are equivalent.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
For creating a byte buffer from a null-terminated string literal.
Init buffer with contents of multiple cursors, and update cursors to reference the memory stored in the buffer.
Each cursor arg must be an
struct aws_byte_cursor *. NULL must be passed as the final arg.
NOTE: Do not append/grow/resize buffers initialized this way, or the cursors will end up referencing invalid memory.
Returns AWS_OP_SUCCESS in case of success.
AWS_OP_ERR is returned if memory can’t be allocated or the total cursor length exceeds SIZE_MAX.Initializes an aws_byte_buf structure base on another valid one.
Requires: *src and *allocator are valid objects.
Ensures: *dest is a valid aws_byte_buf with a new backing array dest->buffer
which is a copy of the elements from src->buffer.
Copies src buffer into dest and sets the correct len and capacity.
A new memory zone is allocated for dest->buffer. When dest is no longer needed it will have to be cleaned-up using
aws_byte_buf_clean_up(dest).
Dest capacity and len will be equal to the src len. Allocator of the dest will be identical with parameter allocator.
If src buffer is null the dest will have a null buffer with a len and a capacity of 0
Returns AWS_OP_SUCCESS in case of success or AWS_OP_ERR when memory can’t be allocated.
Reads ‘filename’ into ‘out_buf’. If successful, ‘out_buf’ is allocated and filled with the data;
It is your responsibility to call ‘aws_byte_buf_clean_up()’ on it. Otherwise, ‘out_buf’ remains
unused. In the very unfortunate case where some API needs to treat out_buf as a c_string, a null terminator
is appended, but is not included as part of the length field.
Evaluates the set of properties that define the shape of all valid aws_byte_buf structures.
It is also a cheap check, in the sense it run in constant time (i.e., no loops or recursion).
Attempts to increase the capacity of a buffer to the requested capacity
Convenience function that attempts to increase the capacity of a buffer relative to the current
length.
Resets the len of the buffer to 0, but does not free the memory. The buffer can then be reused.
Optionally zeroes the contents, if the “zero_contents” flag is true.
Sets all bytes of buffer to zero and resets len to zero.
Write specified number of bytes from array to byte buffer.
Writes a 16-bit integer in network byte order (big endian) to buffer.
Writes low 24-bits (3 bytes) of an unsigned integer in network byte order (big endian) to buffer.
Ex: If x is 0x00AABBCC then {0xAA, 0xBB, 0xCC} is written to buffer.
Writes a 32-bit integer in network byte order (big endian) to buffer.
Writes a 64-bit integer in network byte order (big endian) to buffer.
Writes a 32-bit float in network byte order (big endian) to buffer.
Writes a 64-bit float in network byte order (big endian) to buffer.
Copies all bytes from buffer to buffer.
Copies all bytes from buffer to buffer.
Without increasing buf’s capacity, write as much as possible from advancing_cursor into buf.
Copies one byte to buffer.
Writes one byte repeatedly to buffer (like memset)
Tests if the given aws_byte_cursor has at least len bytes remaining. If so,
*buf is advanced by len bytes (incrementing ->ptr and decrementing ->len),
and an aws_byte_cursor referring to the first len bytes of the original *buf
is returned. Otherwise, an aws_byte_cursor with ->ptr = NULL, ->len = 0 is
returned.
Behaves identically to aws_byte_cursor_advance, but avoids speculative
execution potentially reading out-of-bounds pointers (by returning an
empty ptr in such speculated paths).
Lexical (byte value) comparison of two byte cursors
Lexical (byte value) comparison of two byte cursors where the raw values are sent through a lookup table first
Compare two aws_byte_cursor structures.
Return whether their contents are equivalent.
Compare an aws_byte_cursor and an aws_byte_buf.
Return whether their contents are equivalent.
Perform a case-insensitive string comparison of an aws_byte_cursor and an aws_byte_buf.
Return whether their contents are equivalent.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
Compare an aws_byte_cursor and a null-terminated string.
Returns true if their contents are equivalent.
The cursor should NOT contain a null-terminator, or the comparison will always return false.
Perform a case-insensitive string comparison of an aws_byte_cursor and a null-terminated string.
Return whether their contents are equivalent.
The cursor should NOT contain a null-terminator, or the comparison will always return false.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
Perform a case-insensitive string comparison of two aws_byte_cursor structures.
Return whether their contents are equivalent.
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
Search for an exact byte match inside a cursor. The first match will be returned. Returns AWS_OP_SUCCESS
on successful match and first_find will be set to the offset in input_str, and length will be the remaining length
from input_str past the returned offset. If the match was not found, AWS_OP_ERR will be returned and
AWS_ERROR_STRING_MATCH_NOT_FOUND will be raised.
Evaluates the set of properties that define the shape of all valid aws_byte_cursor structures.
It is also a cheap check, in the sense it runs in constant time (i.e., no loops or recursion).
Shrinks a byte cursor from the left for as long as the supplied predicate is true
No copies, no buffer allocations. Iterates over input_str, and returns the
next substring between split_on instances relative to previous substr.
Behaves similar to strtok with substr being used as state for next split.
Reads specified length of data from byte cursor and copies it to the
destination array.
Reads as many bytes from cursor as size of buffer, and copies them to buffer.
Reads a 16-bit value in network byte order from cur, and places it in host
byte order into var.
Reads an unsigned 24-bit value (3 bytes) in network byte order from cur,
and places it in host byte order into 32-bit var.
Ex: if cur’s next 3 bytes are {0xAA, 0xBB, 0xCC}, then var becomes 0x00AABBCC.
Reads a 32-bit value in network byte order from cur, and places it in host
byte order into var.
Reads a 64-bit value in network byte order from cur, and places it in host
byte order into var.
Reads a 32-bit value in network byte order from cur, and places it in host
byte order into var.
Reads a 64-bit value in network byte order from cur, and places it in host
byte order into var.
Reads 2 hex characters from ASCII/UTF-8 text to produce an 8-bit number.
Accepts both lowercase ‘a’-‘f’ and uppercase ‘A’-‘F’.
For example: “0F” produces 15.
Reads a single byte from cursor, placing it in *var.
Shrinks a byte cursor from the right for as long as the supplied predicate is true
Returns true if the byte cursor’s range of bytes all satisfy the predicate
No copies, no buffer allocations. Fills in output with a list of
aws_byte_cursor instances where buffer is an offset into the input_str and
len is the length of that string in the original buffer.
No copies, no buffer allocations. Fills in output with a list of aws_byte_cursor instances where buffer is
an offset into the input_str and len is the length of that string in the original buffer. N is the max number of
splits, if this value is zero, it will add all splits to the output.
Return true if the input starts with the prefix (exact byte comparison).
Return true if the input starts with the prefix (case-insensitive).
The “C” locale is used for comparing upper and lowercase letters.
Data is assumed to be ASCII text, UTF-8 will work fine too.
Shrinks a byte cursor from both sides for as long as the supplied predicate is true
Read entire cursor as ASCII/UTF-8 unsigned base-10 number.
Stricter than strtoull(), which allows whitespace and inputs that start with “0x”
Read entire cursor as ASCII/UTF-8 unsigned base-16 number with NO “0x” prefix.
Shuts down the internal datastructures used by aws-c-common.
Initializes internal datastructures used by aws-c-common.
Must be called before using any functionality in aws-c-common.
completely destroys a statistics handler. The handler’s cleanup function must clean up the impl portion completely
(including its allocation, if done separately).
Queries the frequency (via an interval in milliseconds) which a statistics handler would like to be informed
of statistics.
Submits a list of statistics objects to a statistics handler for processing
Cleans up a http channel handler statistics struct
Initializes a http channel handler statistics struct
Resets a http channel handler statistics struct’s statistics
Initializes a HTTP/2 channel handler statistics struct
Resets a HTTP/2 channel handler statistics struct’s statistics
Returns an instance of system default thread options.
Case-insensitive hash function for array containing ASCII or UTF-8 text.
Case-insensitive hash function for aws_byte_cursors stored in an aws_hash_table.
For case-sensitive hashing, use aws_hash_byte_cursor_ptr().
Add a list of headers to be added as trailing headers sent after the last chunk is sent.
a “Trailer” header field which indicates the fields present in the trailer.
Submit a chunk of data to be sent on an HTTP/1.1 stream.
The stream must have specified “chunked” in a “transfer-encoding” header.
For client streams, activate() must be called before any chunks are submitted.
For server streams, the response must be submitted before any chunks.
A final chunk with size 0 must be submitted to successfully complete the HTTP-stream.
Send a SETTINGS frame (HTTP/2 only).
SETTINGS will be applied locally when SETTINGS ACK is received from peer.
Get the local settings we are using to affect the decoding.
Get data about the latest GOAWAY frame received from peer (HTTP/2 only).
If no GOAWAY has been received, or the GOAWAY payload is still in transmitting,
AWS_ERROR_HTTP_DATA_NOT_AVAILABLE will be raised.
Get the settings received from remote peer, which we are using to restricts the message to send.
Get data about the latest GOAWAY frame sent to peer (HTTP/2 only).
If no GOAWAY has been sent, AWS_ERROR_HTTP_DATA_NOT_AVAILABLE will be raised.
Note that GOAWAY frames are typically sent automatically by the connection
during shutdown.
Send a PING frame (HTTP/2 only).
Round-trip-time is calculated when PING ACK is received from peer.
Send a custom GOAWAY frame (HTTP/2 only).
Increment the connection’s flow-control window to keep data flowing (HTTP/2 only).
Get the
:method value (HTTP/2 headers only).Get
:status (response pseudo headers only).
If no status is set, AWS_ERROR_HTTP_DATA_NOT_AVAILABLE is raised.Set
:authority (request pseudo headers only).
The pseudo headers makes its own copy of the underlying string.Set
:method (HTTP/2 headers only).
The headers makes its own copy of the underlying string.Set
:path (request pseudo headers only).
The pseudo headers makes its own copy of the underlying string.Set
:scheme (request pseudo headers only).
The pseudo headers makes its own copy of the underlying string.Set
:status (response pseudo headers only).Create an HTTP/2 message from HTTP/1.1 message.
pseudo headers will be created from the context and added to the headers of new message.
Normal headers will be copied to the headers of new message.
Note: if
host exist, it will stay and :authority will be added using the information.
:scheme is default to be “https”. If a different scheme wants to be used, create the HTTP/2 message directlyCreate a new HTTP/2 request message.
pseudo headers need to be set from aws_http2_headers_set_request_* to the headers of the aws_http_message.
Will be errored out if used in HTTP/1.1 connection.
Create a new HTTP/2 response message.
pseudo headers need to be set from aws_http2_headers_set_response_status to the headers of the aws_http_message.
Will be errored out if used in HTTP/1.1 connection.
Get the error code received in rst_stream.
Only valid if the stream has completed, and an RST_STREAM frame has received.
Get the HTTP/2 error code sent in the RST_STREAM frame (HTTP/2 only).
Only valid if the stream has completed, and has sent an RST_STREAM frame.
Acquire a refcount from the stream manager, stream manager will start to destroy after the refcount drops to zero.
NULL is acceptable. Initial refcount after new is 1.
Acquire a stream from stream manager asynchronously.
Fetch the current metrics from stream manager.
Release a refcount from the stream manager, stream manager will start to destroy after the refcount drops to zero.
NULL is acceptable. Initial refcount after new is 1.
Reset the HTTP/2 stream (HTTP/2 only).
Note that if the stream closes before this async call is fully processed, the RST_STREAM frame will not be sent.
The stream must have specified
http2_use_manual_data_writes during request creation.
For client streams, activate() must be called before any frames are submitted.
For server streams, the response headers must be submitted before any frames.
A write with options that has end_stream set to be true will end the stream and prevent any further write.Initialize an empty hash-table that maps
struct aws_string * to enum aws_http_version.
This map can used in aws_http_client_connections_options.alpn_string_map.Initialize an map copied from the *src map, which maps
struct aws_string * to enum aws_http_version.Asynchronously establish a client connection.
The on_setup callback is invoked when the operation has created a connection or failed.
Begin shutdown sequence of the connection if it hasn’t already started. This will schedule shutdown tasks on the
EventLoop that may send HTTP/TLS/TCP shutdown messages to peers if necessary, and will eventually cause internal
connection memory to stop being accessed and on_shutdown() callback to be called.
Configure a server connection.
This must be called from the server’s on_incoming_connection callback.
Returns the channel hosting the HTTP connection.
Do not expose this function to language bindings.
Returns true if this is a client connection.
Returns true unless the connection is closed or closing.
Returns true if this is a server connection.
Create a stream, with a client connection sending a request.
The request does not start sending automatically once the stream is created. You must call
aws_http_stream_activate to begin execution of the request.
Fetch the current manager metrics from connection manager.
Return whether the connection can make a new requests.
If false, then a new connection must be established to make further requests.
Users must release the connection when they are done with it.
The connection’s memory cannot be reclaimed until this is done.
If the connection was not already shutting down, it will be shut down.
Stop accepting new requests for the connection. It will NOT start the shutdown process for the connection. The
requests that are already open can still wait to be completed, but new requests will fail to be created,
Return whether both names are equivalent.
This is a case-insensitive string comparison.
Acquire a hold on the object, preventing it from being deleted until
aws_http_headers_release() is called by all those with a hold on it.
Add a header.
The underlying strings are copied.
Add an array of headers.
The underlying strings are copied.
Add a header.
The underlying strings are copied.
Clear all headers.
Get the total number of headers.
Remove all headers with this name.
AWS_ERROR_HTTP_HEADER_NOT_FOUND is raised if no headers with this name are found.
Remove the header at the specified index.
Remove the first header found with this name and value.
AWS_ERROR_HTTP_HEADER_NOT_FOUND is raised if no such header is found.
Get the first value for this name, ignoring any additional values.
AWS_ERROR_HTTP_HEADER_NOT_FOUND is raised if the name is not found.
Get the header at the specified index.
The index of a given header may change any time headers are modified.
When iterating headers, the following ordering rules apply:
Test if header name exists or not in headers
Create a new headers object.
The caller has a hold on the object and must call aws_http_headers_release() when they are done with it.
Release a hold on the object.
The object is deleted when all holds on it are released.
Set a header value.
The header is added if necessary and any existing values for this name are removed.
The underlying strings are copied.
Clean up internal datastructures used by aws-c-http.
Must not be called until application is done using functionality in aws-c-http.
Initializes internal datastructures used by aws-c-http.
Must be called before using any functionality in aws-c-http.
Acquire a hold on the object, preventing it from being deleted until
aws_http_message_release() is called by all those with a hold on it.
Add a header to the end of the array.
The message makes its own copy of the underlying strings.
Add an array of headers to the end of the header array.
The message makes its own copy of the underlying strings.
Deprecated. This is equivalent to aws_http_message_release().
Remove the header at the specified index.
Headers after this index are all shifted back one position.
Get the body stream.
Returns NULL if no body stream is set.
Get the message’s const aws_http_headers.
Get the header at the specified index.
This function cannot fail if a valid index is provided.
Otherwise, AWS_ERROR_INVALID_INDEX will be raised.
Get the number of headers.
This datastructure has more functions for inspecting and modifying headers than
are available on the aws_http_message datastructure.
Get the protocol version of the http message.
Get the method (request messages only).
Get the status code (response messages only).
If no status is set, AWS_ERROR_HTTP_DATA_NOT_AVAILABLE is raised.
Create a new HTTP/1.1 request message.
The message is blank, all properties (method, path, etc) must be set individually.
If HTTP/1.1 message used in HTTP/2 connection, the transformation will be automatically applied.
A HTTP/2 message will created and sent based on the HTTP/1.1 message.
Like aws_http_message_new_request(), but uses existing aws_http_headers instead of creating a new one.
Acquires a hold on the headers, and releases it when the request is destroyed.
Create a new HTTP/1.1 response message.
The message is blank, all properties (status, headers, etc) must be set individually.
Create request with all required fields for a websocket upgrade request.
The method and path are set, and the the following headers are added:
Release a hold on the object.
The object is deleted when all holds on it are released.
Set the body stream.
NULL is an acceptable value for messages with no body.
Note: The message does NOT take ownership of the body stream.
The stream must not be destroyed until the message is complete.
Set the method (request messages only).
The request makes its own copy of the underlying string.
Set the path-and-query value (request messages only).
The request makes its own copy of the underlying string.
Set the status code (response messages only).
Checks http proxy options for correctness
Destroys an http proxy configuration
@param config http proxy configuration to destroy
Clones an existing proxy configuration. A refactor could remove this (do a “move” between the old and new user
data in the one spot it’s used) but that should wait until we have better test cases for the logic where this
gets invoked (ntlm/kerberos chains).
Create a persistent proxy configuration from http connection options
@param allocator memory allocator to use
@param options http connection options to source proxy configuration from
@return
Create a persistent proxy configuration from http connection manager options
@param allocator memory allocator to use
@param options http connection manager options to source proxy configuration from
@return
Create a persistent proxy configuration from non-persistent proxy options.
Legacy connection type of proxy options will be rejected.
Create a persistent proxy configuration from non-persistent proxy options. The resulting
proxy configuration assumes a tunneling connection type.
Take a reference to an http proxy negotiator
@param proxy_negotiator negotiator to take a reference to
@return the strategy
Release a reference to an http proxy negotiator
@param proxy_negotiator negotiator to release a reference to
Establish an arbitrary protocol connection through an http proxy via tunneling CONNECT. Alpn is
not required for this connection process to succeed, but we encourage its use if available.
Initializes non-persistent http proxy options from a persistent http proxy configuration
@param options http proxy options to initialize
@param config the http proxy config to use as an initialization source
Take a reference to an http proxy strategy
@param proxy_strategy strategy to take a reference to
@return the strategy
Creates a new proxy negotiator from a proxy strategy
@param allocator memory allocator to use
@param strategy strategy to creation a new negotiator for
@return a new proxy negotiator if successful, otherwise NULL
A constructor for a proxy strategy that performs basic authentication by adding the appropriate
header and header value to requests or CONNECT requests.
Constructor for an adaptive tunneling proxy strategy. This strategy attempts a vanilla CONNECT and if that
fails it may make followup CONNECT attempts using kerberos or ntlm tokens, based on configuration and proxy
response properties.
Release a reference to an http proxy strategy
@param proxy_strategy strategy to release a reference to
Create server, a listening socket that accepts incoming connections.
Release the server. It will close the listening socket and all the connections existing in the server.
The on_destroy_complete will be invoked when the destroy operation completes
Returns the description of common status codes.
Ex: 404 -> “Not Found”
An empty string is returned if the status code is not recognized.
Only used for client initiated streams (immediately following a call to aws_http_connection_make_request).
Gets the HTTP/2 id associated with a stream. Even h1 streams have an id (using the same allocation procedure
as http/2) for easier tracking purposes. For client streams, this will only be non-zero after a successful call
to aws_http_stream_activate()
Create a stream, with a server connection receiving and responding to a request.
This function can only be called from the
aws_http_on_incoming_request_fn callback.
aws_http_stream_send_response() should be used to send a response.Users must release the stream when they are done with it, or its memory will never be cleaned up.
This will not cancel the stream, its callbacks will still fire if the stream is still in progress.
Send response (only callable from “request handler” streams)
The response object must stay alive at least until the stream’s on_complete is called.
Increment the stream’s flow-control window to keep data flowing.
Shuts down the internal datastructures used by aws-c-io.
Initializes internal datastructures used by aws-c-io.
Must be called before using any functionality in aws-c-io.
Like isalnum(), but ignores C locale.
Returns true if ch has the value of ASCII/UTF-8: ‘a’-‘z’, ‘A’-‘Z’, or ‘0’-‘9’.
Like isalpha(), but ignores C locale.
Returns true if ch has the value of ASCII/UTF-8: ‘a’-‘z’ or ‘A’-‘Z’.
Like isdigit().
Returns true if ch has the value of ASCII/UTF-8: ‘0’-‘9’.
Like isspace(), but ignores C locale.
Return true if ch has the value of ASCII/UTF-8: space (0x20), form feed (0x0C),
line feed (0x0A), carriage return (0x0D), horizontal tab (0x09), or vertical tab (0x0B).
Like isxdigit().
Returns true if ch has the value of ASCII/UTF-8: ‘0’-‘9’, ‘a’-‘f’, or ‘A’-‘F’.
Converts a log level to a c-string constant. Intended primarily to support building log lines that
include the level in them, i.e.
Get subject name from log subject.
Cleans up all resources used by the logger; simply invokes the clean_up v-function
Gets the aws logger used globally across the process.
Gets the aws logger used globally across the process if the logging level is at least the inputted level.
Sets the aws logger used globally across the process. Not thread-safe. Must only be called once.
Sets the current logging level for the logger. Loggers are not require to support this.
@param logger logger to set the log level for
@param level new log level for the logger
@return AWS_OP_SUCCESS if the level was successfully set, AWS_OP_ERR otherwise
Returns lookup table to go from ASCII/UTF-8 hex character to a number (0-15).
Non-hex characters map to 255.
Valid examples:
‘0’ -> 0
‘F’ -> 15
‘f’ -> 15
Invalid examples:
’ ’ -> 255
‘Z’ -> 255
‘\0’ -> 255
Returns a lookup table for bytes that is the identity transformation with the exception
of uppercase ascii characters getting replaced with lowercase characters. Used in
caseless comparisons.
Returns at least
size of memory ready for usage. In versions v0.6.8 and prior, this function was allowed to return
NULL. In later versions, if allocator->mem_acquire() returns NULL, this function will assert and exit. To handle
conditions where OOM is not a fatal error, allocator->mem_acquire() is responsible for finding/reclaiming/running a
GC etc…before returning.Allocates many chunks of bytes into a single block. Expects to be called with alternating void ** (dest), size_t
(size). The first void ** will be set to the root of the allocation. Alignment is assumed to be sizeof(intmax_t).
Allocates a block of memory for an array of num elements, each of them size bytes long, and initializes all its bits
to zero. In versions v0.6.8 and prior, this function was allowed to return NULL.
In later versions, if allocator->mem_calloc() returns NULL, this function will assert and exit. To handle
conditions where OOM is not a fatal error, allocator->mem_calloc() is responsible for finding/reclaiming/running a
GC etc…before returning.
Attempts to adjust the size of the pointed-to memory buffer from oldsize to
newsize. The pointer (*ptr) may be changed if the memory needs to be
reallocated.
Releases ptr back to whatever allocated it.
Nothing happens if ptr is NULL.
Increments a ref-counter’s ref count
Initializes a ref-counter structure. After initialization, the ref count will be 1.
Decrements a ref-counter’s ref count. Invokes the on_zero callback if the ref count drops to zero
@param ref_count ref-counter to decrement the count for
@return the value of the decremented ref count
TODO: this needs to be a private function (wait till we have the cmake story
better before moving it though). It should be external for the purpose of
other libs we own, but customers should not be able to hit it without going
out of their way to do so.
Connects log subject strings with log subject integer values
Securely zeroes a memory buffer. This function will attempt to ensure that
the compiler will not optimize away this zeroing operation.
Converts a c-string constant to a log level value. Uses case-insensitive comparison
and simply iterates all possibilities until a match or nothing remains. If no match
is found, AWS_OP_ERR is returned.
Cleans up the thread handle. Don’t call this on a managed thread. If you wish to join the thread, you must join
before calling this function.
Adds a callback to the chain to be called when the current thread joins.
Callbacks are called from the current thread, in the reverse order they
were added, after the thread function returns.
If not called from within an aws_thread, has no effect.
Sleeps the current thread by nanos.
Returns the thread id of the calling thread.
Decrements the count of unjoined threads in the managed thread system. Used by managed threads and
event loop threads. Additional usage requires the user to join corresponding threads themselves and
correctly increment/decrement even in the face of launch/join errors.
Gets the detach state of the thread. For example, is it safe to call join on
this thread? Has it been detached()?
Gets the id of thread
Converts an aws_thread_id_t to a c-string. For portability, aws_thread_id_t
must not be printed directly. Intended primarily to support building log
lines that include the thread id in them. The parameter
buffer must
point-to a char buffer of length bufsz == AWS_THREAD_ID_T_REPR_BUFSZ. The
thread id representation is returned in buffer.Increments the count of unjoined threads in the managed thread system. Used by managed threads and
event loop threads. Additional usage requires the user to join corresponding threads themselves and
correctly increment/decrement even in the face of launch/join errors.
Initializes a new platform specific thread object struct (not the os-level
thread itself).
Joins the calling thread to a thread instance. Returns when thread is
finished. Calling this from the associated OS thread will cause a deadlock.
Blocking call that waits for all managed threads to complete their join call. This can only be called
from the main thread or a non-managed thread.
Creates an OS level thread and associates it with func. context will be passed to func when it is executed.
options will be applied to the thread if they are applicable for the platform.
Overrides how long, in nanoseconds, that aws_thread_join_all_managed will wait for threads to complete.
A value of zero will result in an unbounded wait.
Compare thread ids.
Convert a c library io error into an aws error.
Disconnects log subject strings with log subject integer values
Asynchronously establish a client websocket connection.
The on_connection_setup callback is invoked when the operation has finished creating a connection, or failed.
Close the websocket connection.
It is safe to call this, even if the connection is already closed or closing.
The websocket will attempt to send a CLOSE frame during normal shutdown.
If
free_scarce_resources_immediately is true, the connection will be torn down as quickly as possible.
This function may be called from any thread.Convert the websocket into a mid-channel handler.
The websocket will stop being usable via its public API and become just another handler in the channel.
The caller will likely install a channel handler to the right.
This must not be called in the middle of an incoming frame (between “frame begin” and “frame complete” callbacks).
This MUST be called from the websocket’s thread.
Returns the websocket’s underlying I/O channel.
Manually increment the read window.
The read window shrinks as payload data is received, and reading stops when its size reaches 0.
Note that the read window can also be controlled from the aws_websocket_on_incoming_frame_payload_fn(),
callback, by manipulating the
out_increment_window argument.
This function may be called from any thread.Return true if opcode is for a data frame, false if opcode if for a control frame.
Generate value for a Sec-WebSocket-Key header and write it into
dst buffer.
The buffer should have at least AWS_WEBSOCKET_MAX_HANDSHAKE_KEY_LENGTH space available.Users must release the websocket when they are done with it.
The websocket’s memory cannot be reclaimed until this is done.
If the websocket connection was not already shutting down, it will be shut down.
Callbacks may continue firing after this is called, with “shutdown” being the final callback.
This function may be called from any thread.
Send a websocket frame.
The
options struct is copied.
A callback will be invoked when the operation completes.
This function may be called from any thread.Type Definitions
Prototype for a comparator function for sorting elements.
Signature for function argument to trim APIs
The common-specific range of the aws_crt_statistics_category cross-library enum.
Invoked when the data of an outgoing HTTP/1.1 chunk is no longer in use.
This is always invoked on the HTTP connection’s event-loop thread.
Invoked when the HTTP/2 settings change is complete.
If connection setup successfully this will always be invoked whether settings change successfully or unsuccessfully.
If error_code is AWS_ERROR_SUCCESS (0), then the peer has acknowledged the settings and the change has been applied.
If error_code is non-zero, then a connection error occurred before the settings could be fully acknowledged and
applied. This is always invoked on the connection’s event-loop thread.
Invoked when an HTTP/2 GOAWAY frame is received from peer.
Implies that the peer has initiated shutdown, or encountered a serious error.
Once a GOAWAY is received, no further streams may be created on this connection.
Invoked when the HTTP/2 PING completes, whether peer has acknowledged it or not.
If error_code is AWS_ERROR_SUCCESS (0), then the peer has acknowledged the PING and round_trip_time_ns will be the
round trip time in nano seconds for the connection.
If error_code is non-zero, then a connection error occurred before the PING get acknowledgment and round_trip_time_ns
will be useless in this case.
Invoked when new HTTP/2 settings from peer have been applied.
Settings_array is the array of aws_http2_settings that contains all the settings we just changed in the order we
applied (the order settings arrived). Num_settings is the number of elements in that array.
Always invoked asynchronously when the stream was created, successfully or not.
When stream is NULL, error code will be set to indicate what happened.
If there is a stream returned, you own the stream completely.
Invoked on the same thread as other callback of the stream, which will be the thread of the connection, ideally.
If there is no connection made, the callback will be invoked from a sperate thread.
Invoked asynchronously when the stream manager has been shutdown completely.
Never invoked when
aws_http2_stream_manager_new failed.Invoked when the data of an outgoing HTTP2 data frame is no longer in use.
This is always invoked on the HTTP connection’s event-loop thread.
Header block type.
INFORMATIONAL: Header block for 1xx informational (interim) responses.
MAIN: Main header block sent with request or response.
TRAILING: Headers sent after the body of a request or response.
Controls whether a header’s strings may be compressed by encoding the index of
strings in a cache, rather than encoding the literal string.
Function to invoke when a message transformation completes.
This function MUST be invoked or the application will soft-lock.
message and complete_ctx must be the same pointers provided to the aws_http_message_transform_fn.
error_code should should be AWS_ERROR_SUCCESS if transformation was successful,
otherwise pass a different AWS_ERROR_X value.A function that may modify a request or response before it is sent.
The transformation may be asynchronous or immediate.
The user MUST invoke the
complete_fn when transformation is complete or the application will soft-lock.
When invoking the complete_fn, pass along the message and complete_ctx provided here and an error code.
The error code should be AWS_ERROR_SUCCESS if transformation was successful,
otherwise pass a different AWS_ERROR_X value.Invoked when connect completes.
Invoked when the connection has finished shutting down.
Never invoked if on_setup failed.
This is always invoked on connection’s event-loop thread.
Note that the connection is not completely done until on_shutdown has been invoked
AND aws_http_connection_release() has been called.
Called repeatedly as body data is received.
The data must be copied immediately if you wish to preserve it.
This is always invoked on the HTTP connection’s event-loop thread.
Invoked when the incoming header block of this type(informational/main/trailing) has been completely read.
This is always invoked on the HTTP connection’s event-loop thread.
Invoked repeatedly times as headers are received.
At this point, aws_http_stream_get_incoming_response_status() can be called for the client.
And aws_http_stream_get_incoming_request_method() and aws_http_stream_get_incoming_request_uri() can be called for
the server.
This is always invoked on the HTTP connection’s event-loop thread.
Invoked when request has been completely read.
This is always invoked on the HTTP connection’s event-loop thread.
Invoked at the start of an incoming request.
To process the request, the user must create a request handler stream and return it to the connection.
If NULL is returned, the request will not be processed and the last error will be reported as the reason for failure.
Invoked when request/response stream is completely destroyed.
This may be invoked synchronously when aws_http_stream_release() is called.
This is invoked even if the stream is never activated.
Invoked when request/response stream destroy completely.
This can be invoked within the same thead who release the refcount on http stream.
@Deprecated - Supported proxy authentication modes. Superceded by proxy strategy.
Supported proxy connection types
Tunneling proxy connections only. A callback that lets the negotiator examine the headers in the
response to the most recent CONNECT request as they arrive.
Synchronous (for now) callback function to fetch a token used in modifying CONNECT request. Includes a (byte string)
context intended to be used as part of a challenge-response flow.
Synchronous (for now) callback function to fetch a token used in modifying CONNECT requests
Proxy negotiation logic must call this function to forward the potentially-mutated request back to the proxy
connection logic.
User-supplied transform callback which implements the proxy request flow and ultimately, across all execution
pathways, invokes either the terminate function or the forward function appropriately.
Proxy negotiation logic must call this function to indicate an unsuccessful outcome
Tunneling proxy connections only. A callback that lets the negotiator examine the body of the response
to the most recent CONNECT request.
Tunneling proxy connections only. A callback that lets the negotiator examine the status code of the
response to the most recent CONNECT request.
Callback invoked on each statistics sample.
Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
SPDX-License-Identifier: Apache-2.0.
Invoked when the data stream of an outgoing HTTP write operation is no longer in use.
This is always invoked on the HTTP connection’s event-loop thread.
Controls what log calls pass through the logger and what log calls get filtered out.
If a log level has a value of X, then all log calls using a level <= X will appear, while
those using a value > X will not occur.
Log subject is a way of designating the topic of logging.
@deprecated Use int64_t instead for offsets in public APIs.
Specifies the join strategy used on an aws_thread, which in turn controls whether or not a thread participates
in the managed thread system. The managed thread system provides logic to guarantee a join on all participating
threads at the cost of laziness (the user cannot control when joins happen).
Called when websocket setup is complete.
An error_code of zero indicates that setup was completely successful.
Called exactly once on the websocket’s event-loop thread.
Called when the websocket has finished shutting down.
Called once on the websocket’s event-loop thread if setup succeeded.
If setup failed, this is never called.
Called when a new frame arrives.
Invoked once per frame on the websocket’s event-loop thread.
Each incoming-frame-begin call will eventually be followed by an incoming-frame-complete call,
before the next frame begins and before the websocket shuts down.
Called when done processing an incoming frame.
If error_code is non-zero, an error occurred and the payload may not have been completely received.
Invoked once per frame on the websocket’s event-loop thread.
Called repeatedly as payload data arrives.
Invoked 0 or more times on the websocket’s event-loop thread.
Payload data will not be valid after this call, so copy if necessary.
The payload data is always unmasked at this point.
Opcode describing the type of a websocket frame.
RFC-6455 Section 5.2
Called when a aws_websocket_send_frame() operation completes.
error_code will be zero if the operation was successful.
“Success” does not guarantee that the peer actually received or processed the frame.
Invoked exactly once per sent frame on the websocket’s event-loop thread.
Called repeatedly as the websocket’s payload is streamed out.
The user should write payload data to out_buf, up to available capacity.
The websocket will mask this data for you, if necessary.
Invoked repeatedly on the websocket’s event-loop thread.