LibAWSCRT

Documentation for LibAWSCRT.

LibAWSCRT.aws_array_list_comparator_fn — Type

Prototype for a comparator function for sorting elements.

a and b should be cast to pointers to the element type held in the list before being dereferenced. The function should compare the elements and return a positive number if a > b, zero if a = b, and a negative number if a < b.

source
LibAWSCRT.aws_atomic_var — Type
aws_atomic_var

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.

source
LibAWSCRT.aws_byte_buf — Type
aws_byte_buf

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.

This structure used to define the output for all functions that write to a buffer.

Note that this structure allocates memory at the buffer pointer only. The struct itself does not get dynamically allocated and must be either maintained or copied to avoid losing access to the memory.

source
LibAWSCRT.aws_byte_cursor — Type
aws_byte_cursor

Represents a movable pointer within a larger binary string or buffer.

This structure is used to define buffers for reading.

source
LibAWSCRT.aws_channel_options — Type
aws_channel_options

Args for creating a new channel. event_loop to use for IO and tasks. on_setup_completed will be invoked when the setup process is finished It will be executed in the event loop's thread. on_shutdown_completed will be executed upon channel shutdown.

enable_read_back_pressure toggles whether or not back pressure will be applied in the channel. Leave this option off unless you're using something like reactive-streams, since it is a slight throughput penalty.

Unless otherwise specified all functions for channels and channel slots must be executed within that channel's event-loop's thread.

source
LibAWSCRT.aws_cli_subcommand_dispatch — Type
aws_cli_subcommand_dispatch

Dispatch table to dispatch cli commands from. command_name should be the exact string for the command you want to handle from the command line.

source
LibAWSCRT.aws_client_bootstrap_on_channel_event_fn — Type

Generic event function for channel lifecycle events.

Callbacks are provided for: (1) Channel creation (2) Channel setup - If TLS is being used, this function is called once the socket has connected, the channel has been initialized, and TLS has been successfully negotiated. A TLS handler has already been added to the channel. If TLS negotiation fails, this function will be called with the corresponding error code. If TLS is not being used, this function is called once the socket has connected and the channel has been initialized. (3) Channel shutdown

These callbacks are always invoked within the thread of the event-loop that the channel is assigned to.

This function does NOT always imply "success" – if error_code is AWS_OP_SUCCESS then everything was successful, otherwise an error condition occurred.

source
LibAWSCRT.aws_credentials_provider — Type
aws_credentials_provider

A baseclass for credentials providers. A credentials provider is an object that has an asynchronous query function for retrieving AWS credentials.

Ref-counted. Thread-safe.

source
LibAWSCRT.aws_credentials_provider_cached_options — Type
aws_credentials_provider_cached_options

Configuration options for a provider that functions as a caching decorator. Credentials sourced through this provider will be cached within it until their expiration time. When the cached credentials expire, new credentials will be fetched when next queried.

source
LibAWSCRT.aws_credentials_provider_chain_options — Type
aws_credentials_provider_chain_options

Configuration options for a provider that queries, in order, a list of providers. This provider uses the first set of credentials successfully queried. Providers are queried one at a time; a provider is not queried until the preceding provider has failed to source credentials.

source
LibAWSCRT.aws_credentials_provider_process_options — Type
aws_credentials_provider_process_options

Configuration options for the process credentials provider

The process credentials provider sources credentials from running a command or process. The command to run is sourced from a profile in the AWS config file, using the standard profile selection rules. The profile key the command is read from is "credential_process." E.g.: [default] credential_process=/opt/amazon/bin/my-credential-fetcher –argsA=abc On successfully running the command, the output should be a json data with the following format: { "Version": 1, "AccessKeyId": "accesskey", "SecretAccessKey": "secretAccessKey" "SessionToken": "....", "Expiration": "2019-05-29T00:21:43Z" } Version here identifies the command output format version.

source
LibAWSCRT.aws_credentials_provider_sts_web_identity_options — Type
aws_credentials_provider_sts_web_identity_options

Configuration options for the STS web identity provider

Sts with web identity credentials provider sources a set of temporary security credentials for users who have been authenticated in a mobile or web application with a web identity provider. Example providers include Amazon Cognito, Login with Amazon, Facebook, Google, or any OpenID Connect-compatible identity provider like Elastic Kubernetes Service https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html The required parameters used in the request (region, roleArn, sessionName, tokenFilePath) are automatically resolved by SDK from envrionment variables or config file. ––––––––––––––––––––––––––––––––––––––––- | Parameter | Environment Variable Name | Config File Property Name | ––––––––––––––––––––––––––––––––––––––––– | region | AWS_DEFAULT_REGION | region | | role_arn | AWS_ROLE_ARN | role_arn | | role_session_name | AWS_ROLE_SESSION_NAME | role_session_name | | token_file_path | AWS_WEB_IDENTITY_TOKEN_FILE | web_identity_token_file | |––––––––––––––––––––––––––––––––––––––––|

source
LibAWSCRT.aws_credentials_provider_x509_options — Type
aws_credentials_provider_x509_options

Configuration options for the X509 credentials provider

The x509 credentials provider sources temporary credentials from AWS IoT Core using TLS mutual authentication. See details: https://docs.aws.amazon.com/iot/latest/developerguide/authorizing-direct-aws.html An end to end demo with detailed steps can be found here: https://aws.amazon.com/blogs/security/how-to-eliminate-the-need-for-hardcoded-aws-credentials-in-devices-by-using-the-aws-iot-credentials-provider/

source
LibAWSCRT.aws_crt_common_statistics_category — Type
aws_crt_common_statistics_category

The common-specific range of the aws_crt_statistics_category cross-library enum.

This enum functions as an RTTI value that lets statistics handler's interpret (via cast) a specific statistics structure if the RTTI value is understood.

Common doesn't have any statistics structures presently, so its range is essentially empty.

source
LibAWSCRT.aws_crt_statistics_base — Type
aws_crt_statistics_base

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.

source
LibAWSCRT.aws_crt_statistics_handler — Type
aws_crt_statistics_handler

Base structure for all statistics handler implementations.

A statistics handler is an object that listens to a stream of polymorphic (via the category RTTI enum) statistics structures emitted from some arbitrary source. In the initial implementation, statistics handlers are primarily attached to channels, where they monitor IO throughput and state data (from channel handlers) to determine a connection's health.

Statistics handlers are a generalization of the timeout and bandwidth filters that are often associated with SDK network connections. Configurable, default implementations are defined at the protocol level (http, etc...) where they can be attached at connection (channel) creation time.

source
LibAWSCRT.aws_custom_key_op_handler — Type
aws_custom_key_op_handler

The custom key operation that is used when performing a mutual TLS handshake. This can be extended to provide custom private key operations, like PKCS11 or similar.

source
LibAWSCRT.aws_event_stream_prelude_received_fn — Type

Called by aws_aws_event_stream_streaming_decoder when a new message has arrived. The prelude will contain metadata about the message. At this point no headers or payload have been received. prelude is copyable.

source
LibAWSCRT.aws_event_stream_process_on_payload_segment_fn — Type

Called by aws_aws_event_stream_streaming_decoder when payload data has been received. 'data' doesn't belong to you, so copy the data if it is needed beyond the scope of your callback. final_segment == 1 indicates the current data is the last payload buffer for that message.

source
LibAWSCRT.aws_event_stream_rpc_client_on_connection_setup_fn — Type

Invoked when a connection attempt completes.

If the attempt was unsuccessful, the error_code will be non-zero and the connection pointer will be NULL, and aws_event_stream_rpc_client_on_connection_shutdown_fn will not be invoked.

If the attempt was successful, error_code will be 0 and the connection pointer will be valid. You must call aws_event_stream_rpc_client_connection_acquire() to prevent the pointer's memory from being destroyed before you are ready. When you are completely done with the connection pointer you must call aws_event_stream_rpc_client_connection_release() or its memory will leak. aws_event_stream_rpc_client_on_connection_shutdown_fn will be invoked when the network connection has closed. If you are done with the connection, but it is still open, you must call aws_aws_event_stream_rpc_client_close() or network connection will remain open, even if you call release().

source
LibAWSCRT.aws_event_stream_rpc_server_on_incoming_stream_fn — Type

Invoked when a new stream has been received on the connection. If you return AWS_OP_SUCCESS (0), You must fill in the fields for continuation options or the program will assert and exit.

A failure path MUST leave the ref count of the continuation alone.

A success path should probably take a ref which will leave the continuation (assuming no other interference) at two AFTER creation is complete: 1 for the connection's continuation table, and one for the callback recipient which is presumably tracking it as well.

source
LibAWSCRT.aws_event_stream_rpc_server_on_new_connection_fn — Type

Invoked when a new connection is received on a server listener. If you return AWS_OP_SUCCESS, You must fill in the fields for connection_options or the program will assert and exit.

If error_code is non-zero, an error occurred upon setting up the channel and connection will be NULL. Otherwise, connection is non-null. If you intend to seat a pointer to connection, you MUST call aws_event_stream_rpc_server_connection_acquire() and when you're finished with the connection you MUST call aws_event_stream_server_connection_release().

source
LibAWSCRT.aws_hash_callback_destroy_fn — Type

Prototype for a hash table key or value destructor function pointer.

This function is used to destroy elements in the hash table when the table is cleared or cleaned up.

Note that functions which remove individual elements from the hash table provide options of whether or not to invoke the destructors on the key and value of a removed element.

source
LibAWSCRT.aws_hash_callback_eq_fn — Type

Prototype for a hash table equality check function pointer.

This type is usually used for a function that compares two hash table keys, but note that the same type is used for a function that compares two hash table values in aws_hash_table_eq.

Equality functions used in a hash table must be reflexive (i.e., a == b if and only if b == a), and must be consistent with the hash function in use.

source
LibAWSCRT.aws_hash_element — Type
aws_hash_element

Represents an element in the hash table. Various operations on the hash table may provide pointers to elements stored within the hash table; generally, calling code may alter value, but must not alter key (or any information used to compute key's hash code).

Pointers to elements within the hash are invalidated whenever an operation which may change the number of elements in the hash is invoked (i.e. put, delete, clear, and clean_up), regardless of whether the number of elements actually changes.

source
LibAWSCRT.aws_http1_stream_write_chunk_complete_fn — Type

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.

Parameters

  • stream: HTTP-stream this chunk was submitted to.
  • error_code: If error_code is AWS_ERROR_SUCCESS (0), the data was successfully sent. Any other error_code indicates that the HTTP-stream is in the process of terminating. If the error_code is AWS_ERROR_HTTP_STREAM_HAS_COMPLETED, the stream's termination has nothing to do with this chunk. Any other non-zero error code indicates a problem with this particular chunk's data.
  • user_data: User data for this chunk.
source
LibAWSCRT.aws_http2_on_change_settings_complete_fn — Type

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.

source
LibAWSCRT.aws_http2_on_goaway_received_fn — Type

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.

Parameters

  • http2_connection: This HTTP/2 connection.
  • last_stream_id: ID of the last locally-initiated stream that peer will process. Any locally-initiated streams with a higher ID are ignored by peer, and are safe to retry on another connection.
  • http2_error_code: The HTTP/2 error code (RFC-7540 section 7) sent by peer. enum [awshttp2error_code](@ref) lists official codes.
  • debug_data: The debug data sent by peer. It can be empty. (NOTE: this data is only valid for the lifetime of the callback. Make a deep copy if you wish to keep it longer.)
  • user_data: User-data passed to the callback.
source
LibAWSCRT.aws_http2_on_ping_complete_fn — Type

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.

source
LibAWSCRT.aws_http2_on_remote_settings_change_fn — Type

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.

source
LibAWSCRT.aws_http2_stream_manager_on_stream_acquired_fn — Type

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.

source
LibAWSCRT.aws_http2_stream_manager_options — Type
aws_http2_stream_manager_options

HTTP/2 stream manager configuration struct.

Contains all of the configuration needed to create an http2 connection as well as connection manager under the hood.

source
LibAWSCRT.aws_http2_stream_write_data_complete_fn — Type

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.

Parameters

  • stream: HTTP2-stream this write was submitted to.
  • error_code: If error_code is AWS_ERROR_SUCCESS (0), the data was successfully sent. Any other error_code indicates that the HTTP-stream is in the process of terminating. If the error_code is AWS_ERROR_HTTP_STREAM_HAS_COMPLETED, the stream's termination has nothing to do with this write. Any other non-zero error code indicates a problem with this particular write's data.
  • user_data: User data for this write.
source
LibAWSCRT.aws_http_header — Type
aws_http_header

A lightweight HTTP header struct. Note that the underlying strings are not owned by the byte cursors.

source
LibAWSCRT.aws_http_header_block — Type
aws_http_header_block

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.

source
LibAWSCRT.aws_http_header_compression — Type
aws_http_header_compression

Controls whether a header's strings may be compressed by encoding the index of strings in a cache, rather than encoding the literal string.

This setting has no effect on HTTP/1.x connections. On HTTP/2 connections this controls HPACK behavior. See RFC-7541 Section 7.1 for security considerations.

source
LibAWSCRT.aws_http_message_transform_fn — Type

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.

source
LibAWSCRT.aws_http_on_client_connection_setup_fn — Type

Invoked when connect completes.

If unsuccessful, error_code will be set, connection will be NULL, and the on_shutdown callback will never be invoked.

If successful, error_code will be 0 and connection will be valid. The user is now responsible for the connection and must call aws_http_connection_release() when they are done with it.

The connection uses one event-loop thread to do all its work. The thread invoking this callback will be the same thread that invokes all future callbacks for this connection and its streams.

source
LibAWSCRT.aws_http_on_incoming_body_fn — Type

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.

Note that, if the connection is using manual_window_management then the window size has shrunk by the amount of body data received. If the window size reaches 0 no further data will be received. Increment the window size with aws_http_stream_update_window().

Return AWS_OP_SUCCESS to continue processing the stream. Return AWS_OP_ERR to indicate failure and cancel the stream.

source
LibAWSCRT.aws_http_on_incoming_headers_fn — Type

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.

Return AWS_OP_SUCCESS to continue processing the stream. Return AWS_OP_ERR to indicate failure and cancel the stream.

source
LibAWSCRT.aws_http_on_incoming_request_fn — Type

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.

source
LibAWSCRT.aws_http_proxy_negotiation_http_request_transform_async_fn — Type

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.

For tunneling proxy connections, this request flow transform only applies to the CONNECT stage of proxy connection establishment.

For forwarding proxy connections, this request flow transform applies to every single http request that goes out on the connection.

Forwarding proxy connections cannot yet support a truly async request transform without major surgery on http stream creation, so for now, we split into an async version (for tunneling proxies) and a separate synchronous version for forwarding proxies. Also forwarding proxies are a kind of legacy dead-end in some sense.

source
LibAWSCRT.aws_http_stream_write_complete_fn — Type

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.

Parameters

  • stream: HTTP-stream this write operation was submitted to.
  • error_code: If error_code is AWS_ERROR_SUCCESS (0), the data was successfully sent. Any other error_code indicates that the HTTP-stream is in the process of terminating. If the error_code is AWS_ERROR_HTTP_STREAM_HAS_COMPLETED, the stream's termination has nothing to do with this write operation. Any other non-zero error code indicates a problem with this particular write operation's data.
  • user_data: User data for this write operation.
source
LibAWSCRT.aws_imds_instance_info — Type
aws_imds_instance_info

Block of per-instance EC2-specific data

https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html

source
LibAWSCRT.aws_input_stream — Type
aws_input_stream

Base class for input streams. Note: when you implement one input stream, the ref_count needs to be initialized to clean up the resource when reaches to zero.

source
LibAWSCRT.aws_iotdevice_defender_get_ip_list_fn — Type

User callback type invoked to retrieve an ip list custom metric

List provided will already be initialized and caller must push items into the list of type (struct aws_string *). String allocated that are placed into the list are destroyed by the defender task after it is done with the list.

returns: AWS_OP_SUCCESS if the custom metric was successfully added to the task config

source
LibAWSCRT.aws_iotdevice_defender_get_string_list_fn — Type

User callback type invoked to retrieve a string list custom metric

List provided will already be initialized and caller must push items into the list of type (struct aws_string *). String allocated that are placed into the list are destroyed by the defender task after it is done with the list.

returns: AWS_OP_SUCCESS if the custom metric was successfully added to the task config

source
LibAWSCRT.aws_iotdevice_defender_publish_fn — Type

Callback to invoke when the defender task needs to "publish" a report. Useful to override default MQTT publish behavior, for testing report outputs

Notes: * This function should not perform blocking IO. * This function should copy the report if it needs to hold on to the memory for an IO operation

returns: AWS_OP_SUCCESS if the user callback wants to consider the publish failed.

source
LibAWSCRT.aws_iotdevice_defender_report_rejected_fn — Type

User callback type invoked when a report fails to submit.

There are two possibilities for failed submission: 1. The MQTT client fails to publish the message and returns an error code. In this scenario, the client_error_code will be a value other than AWS_ERROR_SUCCESS. The rejected_message_payload parameter will be NULL. 2. After a successful publish, a reply is received on the respective MQTT rejected topic with a message. In this scenario, the client_error_code will be AWS_ERROR_SUCCESS, and rejected_message_payload will contain the payload of the rejected message received.

Parameters

  • rejected_message_payload:[in] response payload recieved from rejection topic
  • userdata:[in] callback userdata
source
LibAWSCRT.aws_iotdevice_defender_task_canceled_fn — Type

User callback type invoked when DeviceDefender task has completed cancellation. After a request to stop the task, this signals the completion of the cancellation and no further user callbacks will be invoked.

Parameters

  • userdata:[in] callback userdata
source
LibAWSCRT.aws_iotdevice_defender_task_failure_fn — Type

General callback handler for the task to report that an error occurred while running the DeviceDefender task. Error codes can only go so far in describing where/when and how the failure occur so the errors here may best communicate where/when and the how of the underlying call should be found in log output

Parameters

  • is_task_stopped:[in] flag indicating whether or not the task is unable to continue running
  • error_code:[in] error code describing the nature of the failure
source
LibAWSCRT.aws_linked_hash_table — Type
aws_linked_hash_table

Simple linked hash table. Preserves insertion order, and can be iterated in insertion order.

You can also change the order safely without altering the shape of the underlying hash table.

source
LibAWSCRT.aws_log_level — Type
aws_log_level

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.

You can filter both dynamically (by setting the log level on the logger object) or statically (by defining AWS_STATIC_LOG_LEVEL to be an appropriate integer module-wide). Statically filtered log calls will be completely compiled out but require a rebuild if you want to get more detail about what's happening.

source
LibAWSCRT.aws_log_subject_t — Type

Log subject is a way of designating the topic of logging.

The general idea is to support a finer-grained approach to log level control. The primary use case is for situations that require more detailed logging within a specific domain, where enabling that detail globally leads to an untenable flood of information.

For example, enable TRACE logging for tls-related log statements (handshake binary payloads), but only WARN logging everywhere else (because http payloads would blow up the log files).

Log subject is an enum similar to aws error: each library has its own value-space and someone is responsible for registering the value <-> string connections.

source
LibAWSCRT.aws_logger_vtable — Type
aws_logger_vtable

We separate the log level function from the log call itself so that we can do the filter check in the macros (see below)

By doing so, we make it so that the variadic format arguments are not even evaluated if the filter check does not succeed.

source
LibAWSCRT.aws_mqtt_client_on_connection_complete_fn — Type

Called when a connection attempt is completed, either in success or error.

If error code is AWS_ERROR_SUCCESS, then a CONNACK has been received from the server and return_code and session_present contain the values received. If error_code is not AWS_ERROR_SUCCESS, it refers to the internal error that occurred during connection, and return_code and session_present are invalid.

source
LibAWSCRT.aws_mqtt_client_publish_received_fn — Type

Called when a publish message is received.

Parameters

  • connection:[in] The connection object
  • topic:[in] The information channel to which the payload data was published.
  • payload:[in] The payload data.
  • dup:[in] DUP flag. If true, this might be re-delivery of an earlier attempt to send the message.
  • qos:[in] Quality of Service used to deliver the message.
  • retain:[in] Retain flag. If true, the message was sent as a result of a new subscription being made by the client.
source
LibAWSCRT.aws_mqtt_connection_options — Type
aws_mqtt_connection_options

host_name The server name to connect to. This resource may be freed immediately on return. port The port on the server to connect to client_id The clientid to place in the CONNECT packet. socket_options The socket options to pass to the aws_client_bootstrap functions. This is copied into the connection tls_options TLS settings to use when opening a connection. This is copied into the connection Pass NULL to connect without TLS (NOT RECOMMENDED) clean_session True to discard all server session data and start fresh keep_alive_time_secs The keep alive value to place in the CONNECT PACKET, a PING will automatically be sent at this interval as well. If you specify 0, defaults will be used and a ping will be sent once per 20 minutes. This duration must be longer than ping_timeout_ms. ping_timeout_ms Network connection is re-established if a ping response is not received within this amount of time (milliseconds). If you specify 0, a default value of 3 seconds is used. Alternatively, tcp keep-alive may be away to accomplish this in a more efficient (low-power) scenario, but keep-alive options may not work the same way on every platform and OS version. This duration must be shorter than keep_alive_time_secs. protocol_operation_timeout_ms Timeout when waiting for the response to some operation requires response by protocol. Set to zero to disable timeout. Otherwise, the operation will fail with error AWS_ERROR_MQTT_TIMEOUT if no response is received within this amount of time after the packet is written to the socket. The timer is reset if the connection is interrupted. It applied to PUBLISH (QoS>0) and UNSUBSCRIBE now. Note: While the MQTT 3 specification states that a broker MUST respond, some brokers are known to ignore publish packets in exceptional circumstances (e.g. AWS IoT Core will not respond if the publish quota is exceeded). on_connection_complete The callback to fire when the connection attempt completes user_data Passed to the userdata param of on_connection_complete

source
LibAWSCRT.aws_mqtt_suback_fn — Type

Called when a single-topic subscription request is complete. Note: If the qos value is AWS_MQTT_QOS_FAILURE, then the subscription was rejected by the broker.

source
LibAWSCRT.aws_mqtt_suback_multi_fn — Type

Called when a multi-topic subscription request is complete. Note: If any topic_suback's qos value is AWS_MQTT_QOS_FAILURE, then that topic subscription was rejected by the broker.

source
LibAWSCRT.aws_mqtt_transform_websocket_handshake_fn — Type

Function that may transform the websocket handshake request. Called each time a websocket connection is attempted.

The default request uses path "/mqtt". All required headers are present, plus the optional header "Sec-WebSocket-Protocol: mqtt".

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 request 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.

source
LibAWSCRT.aws_pipe_on_readable_fn — Type

Callback for when the pipe is readable (edge-triggered), or an error has occurred. Afer subscribing, the callback is invoked when the pipe has data to read, or the pipe has an error. The readable callback is invoked again any time the user reads all data, and then more data arrives. Note that it will not be invoked again if the pipe still has unread data when more data arrives. error_code of AWS_ERROR_SUCCESS indicates a readable event, and otherwise contains the value of the error. user_data corresponds to the user_data passed into aws_pipe_subscribe_to_read_events(). This callback is always invoked on the read-end's event-loop thread.

source
LibAWSCRT.aws_pipe_on_write_completed_fn — Type

Callback for when the asynchronous aws_pipe_write() operation has either completed or failed. write_end will be NULL if this callback is invoked after the the write-end has been cleaned up, this does not necessarily mean that the write operation failed. error_code will be AWS_ERROR_SUCCESS if all data was written, or a code corresponding to the error. src_buffer corresponds to the buffer passed into aws_pipe_write() user_data corresponds to the user_data passed into aws_pipe_write(). This callback is always invoked on the write-end's event-loop thread.

source
LibAWSCRT.aws_retry_strategy_on_retry_ready_fn — Type

Invoked after a successful call to aws_retry_strategy_schedule_retry(). This function will always be invoked if and only if aws_retry_strategy_schedule_retry() returns AWS_OP_SUCCESS. It will never be invoked synchronously from aws_retry_strategy_schedule_retry(). After attempting the operation, either call aws_retry_strategy_schedule_retry() with an aws_retry_error_type or call aws_retry_token_record_success() and then release the token via. aws_retry_token_release().

source
LibAWSCRT.aws_retry_strategy_on_retry_token_acquired_fn — Type

Invoked upon the acquisition, or failure to acquire a retry token. This function will always be invoked if and only if aws_retry_strategy_acquire_retry_token() returns AWS_OP_SUCCESS. It will never be invoked synchronously from aws_retry_strategy_acquire_retry_token(). Token will always be NULL if error_code is non-zero, and vice-versa. If token is non-null, it will have a reference count of 1, and you must call aws_retry_token_release() on it later. See the comments for aws_retry_strategy_on_retry_ready_fn for more info.

source
LibAWSCRT.aws_ring_buffer — Type
aws_ring_buffer

Lockless ring buffer implementation that is thread safe assuming a single thread acquires and a single thread releases. For any other use case (other than the single-threaded use-case), you must manage thread-safety manually.

Also, a very important note: release must happen in the same order as acquire. If you do not your application, and possibly computers within a thousand mile radius, may die terrible deaths, and the local drinking water will be poisoned for generations with fragments of what is left of your radioactive corrupted memory.

source
LibAWSCRT.aws_s3_meta_request_headers_callback_fn — Type

Invoked to provide response headers received during execution of the meta request, both for success and error HTTP status codes.

Return AWS_OP_SUCCESS to continue processing the request.

Return aws_raise_error(E) to cancel the request. The error you raise will be reflected in [awss3metarequestresult](@ref).error\_code. If you're not sure which error to raise, use AWS_ERROR_S3_CANCELED.

source
LibAWSCRT.aws_s3_meta_request_options — Type
aws_s3_meta_request_options

Options for a new meta request, ie, file transfer that will be handled by the high performance client.

There are several ways to pass the request's body data: 1) If the data is already in memory, set the body-stream on message. 2) If the data is on disk, set send_filepath for best performance. 3) If the data will be be produced in asynchronous chunks, set send_async_stream.

source
LibAWSCRT.aws_s3_meta_request_progress_fn — Type

Invoked to report progress of a meta-request. For PutObject, progress refers to bytes uploaded. For CopyObject, progress refers to bytes copied. For GetObject, progress refers to bytes downloaded. For anything else, progress refers to response body bytes received.

source
LibAWSCRT.aws_s3_meta_request_receive_body_callback_fn — Type

Invoked to provide the response body as it is received.

Note: If you set enable_read_backpressure true on the S3 client, you must maintain the flow-control window. The flow-control window shrinks as you receive body data via this callback. Whenever the flow-control window reaches 0 you will stop downloading data. Use aws_s3_meta_request_increment_read_window() to increment the window and keep data flowing. Maintain a larger window to keep up a high download throughput, parts cannot download in parallel unless the window is large enough to hold multiple parts. Maintain a smaller window to limit the amount of data buffered in memory.

If manual_window_management is false, you do not need to maintain the flow-control window. No back-pressure is applied and data arrives as fast as possible.

Return AWS_OP_SUCCESS to continue processing the request.

Return aws_raise_error(E) to cancel the request. The error you raise will be reflected in [awss3metarequestresult](@ref).error\_code. If you're not sure which error to raise, use AWS_ERROR_S3_CANCELED.

source
LibAWSCRT.aws_s3_meta_request_type — Type
aws_s3_meta_request_type

A Meta Request represents a group of generated requests that are being done on behalf of the original request. For example, one large GetObject request can be transformed into a series of ranged GetObject requests that are executed in parallel to improve throughput.

The aws_s3_meta_request_type is a hint of transformation to be applied.

source
LibAWSCRT.aws_s3_meta_request_upload_review_fn — Type

Optional callback, for you to review an upload before it completes. For example, you can review each part's checksum and fail the upload if you do not agree with them.

Return AWS_OP_SUCCESS to continue processing the request.

Return aws_raise_error(E) to cancel the request. The error you raise will be reflected in [awss3metarequestresult](@ref).error\_code. If you're not sure which error to raise, use AWS_ERROR_S3_CANCELED.

WARNING: This feature is experimental/unstable. At this time, the callback is only invoked for multipart upload (when Content-Length is above the multipart_upload_threshold, or Content-Length not specified).

Parameters

  • meta_request: pointer to the aws_s3_meta_request of the upload.
  • info: Detailed info about the upload.
source
LibAWSCRT.aws_s3_upload_review — Type
aws_s3_upload_review

Info for you to review before an upload completes.

WARNING: This feature is experimental/unstable. At this time, review is only available for multipart upload (when Content-Length is above the multipart_upload_threshold, or Content-Length not specified).

source
LibAWSCRT.aws_secure_tunnel_message_type — Type
aws_secure_tunnel_message_type

Type of IoT Secure Tunnel message. Enum values match IoT Secure Tunneling Local Proxy V3 Websocket Protocol Guide values.

https://github.com/aws-samples/aws-iot-securetunneling-localproxy/blob/main/V3WebSocketProtocolGuide.md

source
LibAWSCRT.aws_server_bootstrap_on_accept_channel_setup_fn — Type

If TLS is being used, this function is called once the socket has received an incoming connection, the channel has been initialized, and TLS has been successfully negotiated. A TLS handler has already been added to the channel. If TLS negotiation fails, this function will be called with the corresponding error code.

If TLS is not being used, this function is called once the socket has received an incoming connection and the channel has been initialized.

This function is always called within the thread of the event-loop that the new channel is assigned to upon success.

On failure, the channel might not be assigned to an event loop yet, and will thus be invoked on the listener's event-loop thread.

This function does NOT mean "success", if error_code is AWS_OP_SUCCESS then everything was successful, otherwise an error condition occurred.

If an error occurred, you do not need to shutdown the channel. The aws_channel_client_shutdown_callback will be invoked once the channel has finished shutting down.

source
LibAWSCRT.aws_server_socket_channel_bootstrap_options — Type
aws_server_socket_channel_bootstrap_options

Arguments to setup a server socket listener which will also negotiate and configure TLS. This creates a socket listener bound to host and 'port' using socket options options, and TLS options tls_options. incoming_callback will be invoked once an incoming channel is ready for use and TLS is finished negotiating, or if an error is encountered. shutdown_callback will be invoked once the channel has shutdown. destroy_callback will be invoked after the server socket listener is destroyed, and all associated connections and channels have finished shutting down. Immediately after the shutdown_callback returns, the channel is cleaned up automatically. All callbacks are invoked in the thread of the event-loop that listener is assigned to.

Upon shutdown of your application, you'll want to call aws_server_bootstrap_destroy_socket_listener with the return value from this function.

The socket type in options must be AWS_SOCKET_STREAM if tls_options is set. DTLS is not currently supported for tls.

source
LibAWSCRT.aws_signable — Type
aws_signable

Signable is a generic interface for any kind of object that can be cryptographically signed.

Like signing_result, the signable interface presents

(1) Properties - A set of key-value pairs (2) Property Lists - A set of named key-value pair lists

as well as

(3) A message payload modeled as a stream

When creating a signable "subclass" the query interface should map to retrieving the properties of the underlying object needed by signing algorithms that can operate on it.

As an example, if a signable implementation wrapped an http request, you would query request elements like method and uri from the property interface, headers would be queried via the property list interface, and the request body would map to the payload stream.

String constants that map to agreed on keys for particular signable types ("METHOD", "URI", "HEADERS", etc...) are exposed in appropriate header files.

source
LibAWSCRT.aws_signing_complete_fn — Type

Gets called by the signing function when the signing is complete.

Note that result will be destroyed after this function returns, so either copy it, or do all necessary adjustments inside the callback.

When performing event or chunk signing, you will need to copy out the signature value in order to correctly configure the signable that wraps the event or chunk you want signed next. The signature is found in the "signature" property on the signing result. This value must be added as the "previous-signature" property on the next signable.

source
LibAWSCRT.aws_signing_config_type — Type
aws_signing_config_type

A primitive RTTI indicator for signing configuration structs

There must be one entry per config structure type and it's a fatal error to put the wrong value in the "config_type" member of your config structure.

source
LibAWSCRT.aws_signing_result — Type
aws_signing_result

A structure for tracking all the signer-requested changes to a signable. Interpreting these changes is signing-algorithm specific.

A signing result consists of

(1) Properties - A set of key-value pairs (2) Property Lists - A set of named key-value pair lists

The hope is that these two generic structures are enough to model the changes required by any generic message-signing algorithm.

Note that the key-value pairs of a signing_result are different types (but same intent) as the key-value pairs in the signable interface. This is because the signing result stands alone and owns its own copies of all values, whereas a signable can wrap an existing object and thus use non-owning references (like byte cursors) if appropriate to its implementation.

source
LibAWSCRT.aws_socket_channel_bootstrap_options — Type
aws_socket_channel_bootstrap_options

Socket-based channel creation options.

bootstrap - configs name resolution and which event loop group the connection will be seated into host_name - host to connect to; if a dns address, will be resolved prior to connecting port - port to connect to socket_options - socket properties, including type (tcp vs. udp vs. unix domain) and connect timeout. TLS connections are currently restricted to tcp (AWS_SOCKET_STREAM) only. tls_options - (optional) tls context to apply after connection establishment. If NULL, the connection will not be protected by TLS. creation_callback - (optional) callback invoked when the channel is first created. This is always right after the connection was successfully established. Does NOT get called if the initial connect failed. setup_callback - callback invoked once the channel is ready for use and TLS has been negotiated or if an error is encountered shutdown_callback - callback invoked once the channel has shutdown. enable_read_back_pressure - controls whether or not back pressure will be applied in the channel user_data - arbitrary data to pass back to the various callbacks requested_event_loop - if set, the connection will be placed on the requested event loop rather than one chosen internally from the bootstrap's associated event loop group. It is an error to pass in an event loop that is not associated with the bootstrap's event loop group.

Immediately after the shutdown_callback returns, the channel is cleaned up automatically. All callbacks are invoked in the thread of the event-loop that the new channel is assigned to.

source
LibAWSCRT.aws_socket_on_accept_result_fn — Type

Called by a listening socket when either an incoming connection has been received or an error occurred.

In the normal use-case, this function will be called multiple times over the lifetime of a single listening socket. new_socket is already connected and initialized, and is using the same options and allocator as the listening socket. A user may want to call aws_socket_set_options() on the new socket if different options are desired.

new_socket is not yet assigned to an event-loop. The user should call aws_socket_assign_to_event_loop() before performing IO operations.

When error_code is AWS_ERROR_SUCCESS, new_socket is the recently accepted connection. If error_code is non-zero, an error occurred and you should aws_socket_close() the socket.

Do not call aws_socket_clean_up() from this callback.

source
LibAWSCRT.aws_socket_on_connection_result_fn — Type

Called in client mode when an outgoing connection has succeeded or an error has occurred. If the connection was successful error_code will be AWS_ERROR_SUCCESS and the socket has already been assigned to the event loop specified in aws_socket_connect().

If an error occurred error_code will be non-zero.

source
LibAWSCRT.aws_socket_on_readable_fn — Type

Callback for when socket is either readable (edge-triggered) or when an error has occurred. If the socket is readable, error_code will be AWS_ERROR_SUCCESS.

source
LibAWSCRT.aws_thread_join_strategy — Type
aws_thread_join_strategy

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).

Manual - thread does not participate in the managed thread system; any joins must be done by the user. This is the default. The user must call aws_thread_clean_up(), but only after any desired join operation has completed. Not doing so will cause the windows handle to leak.

Managed - the managed thread system will automatically perform a join some time after the thread's run function has completed. It is an error to call aws_thread_join on a thread configured with the managed join strategy. The managed thread system will call aws_thread_clean_up() on the thread after the background join has completed.

Additionally, an API exists, aws_thread_join_all_managed(), which blocks and returns when all outstanding threads with the managed strategy have fully joined. This API is useful for tests (rather than waiting for many individual signals) and program shutdown or DLL unload. This API is automatically invoked by the common library clean up function. If the common library clean up is called from a managed thread, this will cause deadlock.

Lazy thread joining is done only when threads finish their run function or when the user calls aws_thread_join_all_managed(). This means it may be a long time between thread function completion and the join being applied, but the queue of unjoined threads is always one or fewer so there is no critical resource backlog.

Currently, only event loop group async cleanup and host resolver threads participate in the managed thread system. Additionally, event loop threads will increment and decrement the pending join count (they are manually joined internally) in order to have an accurate view of internal thread usage and also to prevent failure to release an event loop group fully from allowing aws_thread_join_all_managed() from running to completion when its intent is such that it should block instead.

source
LibAWSCRT.aws_tls_ctx_pkcs11_options — Type
aws_tls_ctx_pkcs11_options

This struct exists as a graceful way to pass many arguments when calling init-with-pkcs11 functions on aws_tls_ctx_options (this also makes it easy to introduce optional arguments in the future). Instances of this struct should only exist briefly on the stack.

Instructions for binding this to high-level languages: - Python: The members of this struct should be the keyword args to the init-with-pkcs11 functions. - JavaScript: This should be an options map passed to init-with-pkcs11 functions. - Java: This should be an options class passed to init-with-pkcs11 functions. - C++: Same as Java

Notes on integer types: PKCS#11 uses unsigned long for IDs, handles, etc but we expose them as uint64_t in public APIs. We do this because sizeof(long) is inconsistent across platform/arch/language (ex: always 64bit in Java, always 32bit in C on Windows, matches CPU in C on Linux and Apple). By using uint64_t in our public API, we can keep the careful bounds-checking all in one place, instead of expecting each high-level language binding to get it just right.

source
LibAWSCRT.aws_tls_hash_algorithm — Type
aws_tls_hash_algorithm

The hash algorithm of a TLS private key operation. Any custom private key operation handlers are expected to perform operations on the input TLS data using the correct hash algorithm or fail the operation.

source
LibAWSCRT.aws_tls_key_operation — Type

A struct containing all of the data needed for a private key operation when making a mutual TLS connection. This struct contains the data that needs to be operated on, like performing a sign operation or a decrypt operation.

source
LibAWSCRT.aws_tls_key_operation_type — Type
aws_tls_key_operation_type

The TLS private key operation that needs to be performed by a custom private key operation handler when making a connection using mutual TLS.

source
LibAWSCRT.aws_tls_on_data_read_fn — Type

Only used if the TLS handler is the last handler in the channel. This allows you to read any data that was read and decrypted by the handler. If you have application protocol channel handlers, this function is not necessary and certainly not recommended.

source
LibAWSCRT.aws_tls_signature_algorithm — Type
aws_tls_signature_algorithm

The signature of a TLS private key operation. Any custom private key operation handlers are expected to perform operations on the input TLS data using the correct signature algorithm or fail the operation.

source
LibAWSCRT.aws_uri — Type
aws_uri

Data representing a URI. uri_str is always allocated and filled in. The other portions are merely storing offsets into uri_str.

source
LibAWSCRT.aws_uri_builder_options — Type
aws_uri_builder_options

Arguments for building a URI instance. All members must be initialized before passing them to aws_uri_init().

query_string and query_params are exclusive to each other. If you set query_string, do not prepend it with '?'

source
LibAWSCRT.aws_uri_param — Type
aws_uri_param

key/value pairs for a query string. If the query fragment was not in format key=value, the fragment value will be stored in key

source
LibAWSCRT.aws_websocket_on_connection_setup_data — Type
aws_websocket_on_connection_setup_data

Data passed to the websocket on_connection_setup callback.

An error_code of zero indicates that setup was completely successful. You own the websocket pointer now and must call aws_websocket_release() when you are done with it. You can inspect the response headers, if you're interested.

A non-zero error_code indicates that setup failed. The websocket pointer will be NULL. If the server sent a response, you can inspect its status-code, headers, and body, but this data will NULL if setup failed before a full response could be received. If you wish to persist data from the response make a deep copy. The response data becomes invalid once the callback completes.

source
LibAWSCRT.aws_websocket_on_incoming_frame_begin_fn — Type

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.

Return true to proceed normally. If false is returned, the websocket will read no further data, the frame will complete with an error-code, and the connection will close.

source
LibAWSCRT.aws_websocket_on_incoming_frame_complete_fn — Type

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.

Return true to proceed normally. If false is returned, the websocket will read no further data and the connection will close.

source
LibAWSCRT.aws_websocket_on_incoming_frame_payload_fn — Type

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.

NOTE: If you created the websocket with manual_window_management set true, you must maintain the read window. Whenever the read window reaches 0, you will stop receiving anything. The websocket's initial_window_size determines the starting size of the read window. The read window shrinks as you receive the payload from "data" frames (TEXT, BINARY, and CONTINUATION). Use aws_websocket_increment_read_window() to increment the window again and keep frames flowing. Maintain a larger window to keep up high throughput. You only need to worry about the payload from "data" frames. The websocket automatically increments the window to account for any other incoming bytes, including other parts of a frame (opcode, payload-length, etc) and the payload of other frame types (PING, PONG, CLOSE).

Return true to proceed normally. If false is returned, the websocket will read no further data, the frame will complete with an error-code, and the connection will close.

source
LibAWSCRT.aws_websocket_send_frame_options — Type
aws_websocket_send_frame_options

Options for sending a websocket frame. This structure is copied immediately by aws_websocket_send(). For descriptions of opcode, fin, and payload_length see in RFC-6455 Section 5.2.

source
LibAWSCRT.aws_websocket_stream_outgoing_payload_fn — Type

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.

Return true to proceed normally. If false is returned, the websocket will send no further data, the frame will complete with an error-code, and the connection will close.

source
LibAWSCRT.aws_xml_parser_on_node_encountered_fn — Type

Callback for when an xml node is encountered in the document. As a user you have a few options:

  1. fail the parse by returning AWS_OP_ERR (after an error has been raised). This will stop any further parsing. 2. call aws_xml_node_traverse() on the node to descend into the node with a new callback and user_data. 3. call aws_xml_node_as_body() to retrieve the contents of the node as text.

You MUST NOT call both aws_xml_node_traverse() and aws_xml_node_as_body() on the same node.

return true to continue the parsing operation.

source
LibAWSCRT.defender_custom_metric_type — Type
defender_custom_metric_type

Change name if this needs external exposure. Needed to keep track of how to interpret instantiated metrics, and cast the supplier_fn correctly.

source
LibAWSCRT.hash_table_state — Type

Hash table data structure. This module provides an automatically resizing hash table implementation for general purpose use. The hash table stores a mapping between void * keys and values; it is expected that in most cases, these will point to a structure elsewhere in the heap, instead of inlining a key or value into the hash table element itself.

Currently, this hash table implements a variant of robin hood hashing, but we do not guarantee that this won't change in the future.

Associated with each hash function are four callbacks:

hash_fn - A hash function from the keys to a uint64_t. It is critical that the hash function for a key does not change while the key is in the hash table; violating this results in undefined behavior. Collisions are tolerated, though naturally with reduced performance.

equals_fn - An equality comparison function. This function must be reflexive and consistent with hash_fn.

destroy_key_fn, destroy_value_fn - Optional callbacks invoked when the table is cleared or cleaned up and at the caller's option when an element is removed from the table. Either or both may be set to NULL, which has the same effect as a no-op destroy function.

This datastructure can be safely moved between threads, subject to the requirements of the underlying allocator. It is also safe to invoke non-mutating operations on the hash table from multiple threads. A suitable memory barrier must be used when transitioning from single-threaded mutating usage to multithreaded usage.

source
LibAWSCRT.aws_add_size_saturating — Method
aws_add_size_saturating(a, b)

Adds a + b. If the result overflows returns SIZE_MAX.

Prototype

AWS_STATIC_IMPL size_t aws_add_size_saturating(size_t a, size_t b);
source
LibAWSCRT.aws_add_u32_saturating — Method
aws_add_u32_saturating(a, b)

Adds a + b. If the result overflows, returns 2^32 - 1.

Prototype

AWS_STATIC_IMPL uint32_t aws_add_u32_saturating(uint32_t a, uint32_t b);
source
LibAWSCRT.aws_add_u64_saturating — Method
aws_add_u64_saturating(a, b)

Adds a + b. If the result overflows, returns 2^64 - 1.

Prototype

AWS_STATIC_IMPL uint64_t aws_add_u64_saturating(uint64_t a, uint64_t b);
source
LibAWSCRT.aws_aes_cbc_256_new — Method
aws_aes_cbc_256_new(allocator, key, iv)

Creates an instance of AES CBC with 256-bit key. If key and iv are NULL, they will be generated internally. You can get the generated key and iv back by calling:

aws_symmetric_cipher_get_key() and aws_symmetric_cipher_get_initialization_vector()

respectively.

If they are set, that key and iv will be copied internally and used by the cipher.

Returns NULL on failure. You can check aws_last_error() to get the error code indicating the failure cause.

Prototype

struct aws_symmetric_cipher *aws_aes_cbc_256_new( struct aws_allocator *allocator, const struct aws_byte_cursor *key, const struct aws_byte_cursor *iv);
source
LibAWSCRT.aws_aes_ctr_256_new — Method
aws_aes_ctr_256_new(allocator, key, iv)

Creates an instance of AES CTR with 256-bit key. If key and iv are NULL, they will be generated internally. You can get the generated key and iv back by calling:

aws_symmetric_cipher_get_key() and aws_symmetric_cipher_get_initialization_vector()

respectively.

If they are set, that key and iv will be copied internally and used by the cipher.

Returns NULL on failure. You can check aws_last_error() to get the error code indicating the failure cause.

Prototype

struct aws_symmetric_cipher *aws_aes_ctr_256_new( struct aws_allocator *allocator, const struct aws_byte_cursor *key, const struct aws_byte_cursor *iv);
source
LibAWSCRT.aws_aes_gcm_256_new — Method
aws_aes_gcm_256_new(allocator, key, iv, aad, decryption_tag)

Creates an instance of AES GCM with 256-bit key. If key, iv are NULL, they will be generated internally. You can get the generated key and iv back by calling:

aws_symmetric_cipher_get_key() and aws_symmetric_cipher_get_initialization_vector()

respectively.

If they are set, that key and iv will be copied internally and used by the cipher.

If tag and aad are set they will be copied internally and used by the cipher. decryption_tag would most likely be used for a decrypt operation to detect tampering or corruption. The Tag for the most recent encrypt operation will be available in:

aws_symmetric_cipher_get_tag()

If aad is set it will be copied and applied to the cipher.

Returns NULL on failure. You can check aws_last_error() to get the error code indicating the failure cause.

Prototype

struct aws_symmetric_cipher *aws_aes_gcm_256_new( struct aws_allocator *allocator, const struct aws_byte_cursor *key, const struct aws_byte_cursor *iv, const struct aws_byte_cursor *aad, const struct aws_byte_cursor *decryption_tag);
source
LibAWSCRT.aws_aes_keywrap_256_new — Method
aws_aes_keywrap_256_new(allocator, key)

Creates an instance of AES Keywrap with 256-bit key. If key is NULL, it will be generated internally. You can get the generated key back by calling:

aws_symmetric_cipher_get_key()

If key is set, that key will be copied internally and used by the cipher.

Returns NULL on failure. You can check aws_last_error() to get the error code indicating the failure cause.

Prototype

struct aws_symmetric_cipher *aws_aes_keywrap_256_new( struct aws_allocator *allocator, const struct aws_byte_cursor *key);
source
LibAWSCRT.aws_allocator_is_valid — Method
aws_allocator_is_valid(alloc)

Inexpensive (constant time) check of data-structure invariants.

Prototype

bool aws_allocator_is_valid(const struct aws_allocator *alloc);
source
LibAWSCRT.aws_apply_signing_result_to_http_request — Method
aws_apply_signing_result_to_http_request(request, allocator, result)

Prototype

int aws_apply_signing_result_to_http_request( struct aws_http_message *request, struct aws_allocator *allocator, const struct aws_signing_result *result);
source
LibAWSCRT.aws_array_eq — Method
aws_array_eq(array_a, len_a, array_b, len_b)

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.

Prototype

bool aws_array_eq(const void *const array_a, const size_t len_a, const void *array_b, const size_t len_b);
source
LibAWSCRT.aws_array_eq_c_str — Method
aws_array_eq_c_str(array, array_len, c_str)

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.

Prototype

bool aws_array_eq_c_str(const void *const array, const size_t array_len, const char *const c_str);
source
LibAWSCRT.aws_array_eq_c_str_ignore_case — Method
aws_array_eq_c_str_ignore_case(array, array_len, c_str)

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.

Prototype

bool aws_array_eq_c_str_ignore_case(const void *const array, const size_t array_len, const char *const c_str);
source
LibAWSCRT.aws_array_eq_ignore_case — Method
aws_array_eq_ignore_case(array_a, len_a, array_b, len_b)

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.

Prototype

bool aws_array_eq_ignore_case( const void *const array_a, const size_t len_a, const void *const array_b, const size_t len_b);
source
LibAWSCRT.aws_array_list_back — Method
aws_array_list_back(list, val)

Copies the element at the end of the list if it exists. If list is empty, AWS_ERROR_LIST_EMPTY will be raised.

Prototype

AWS_STATIC_IMPL int aws_array_list_back(const struct aws_array_list *AWS_RESTRICT list, void *val);
source
LibAWSCRT.aws_array_list_capacity — Method
aws_array_list_capacity(list)

Returns the number of elements that can fit in the internal array. If list is initialized in dynamic mode, the capacity changes over time.

Prototype

AWS_STATIC_IMPL size_t aws_array_list_capacity(const struct aws_array_list *AWS_RESTRICT list);
source
LibAWSCRT.aws_array_list_clean_up — Method
aws_array_list_clean_up(list)

Deallocates any memory that was allocated for this list, and resets list for reuse or deletion.

Prototype

AWS_STATIC_IMPL void aws_array_list_clean_up(struct aws_array_list *AWS_RESTRICT list);
source
LibAWSCRT.aws_array_list_clean_up_secure — Method
aws_array_list_clean_up_secure(list)

Erases and then deallocates any memory that was allocated for this list, and resets list for reuse or deletion.

Prototype

AWS_STATIC_IMPL void aws_array_list_clean_up_secure(struct aws_array_list *AWS_RESTRICT list);
source
LibAWSCRT.aws_array_list_clear — Method
aws_array_list_clear(list)

Clears all elements in the array and resets length to zero. Size does not change in this operation.

Prototype

AWS_STATIC_IMPL void aws_array_list_clear(struct aws_array_list *AWS_RESTRICT list);
source
LibAWSCRT.aws_array_list_copy — Method
aws_array_list_copy(from, to)

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.

Prototype

int aws_array_list_copy(const struct aws_array_list *AWS_RESTRICT from, struct aws_array_list *AWS_RESTRICT to);
source
LibAWSCRT.aws_array_list_ensure_capacity — Method
aws_array_list_ensure_capacity(list, index)

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.

Prototype

int aws_array_list_ensure_capacity(struct aws_array_list *AWS_RESTRICT list, size_t index);
source
LibAWSCRT.aws_array_list_erase — Method
aws_array_list_erase(list, index)

Deletes the element this index in the list if it exists. If element does not exist, AWS_ERROR_INVALID_INDEX will be raised. This call results in shifting all remaining elements towards the front. Avoid this call unless that is intended behavior.

Prototype

int aws_array_list_erase(struct aws_array_list *AWS_RESTRICT list, size_t index);
source
LibAWSCRT.aws_array_list_front — Method
aws_array_list_front(list, val)

Copies the element at the front of the list if it exists. If list is empty, AWS_ERROR_LIST_EMPTY will be raised

Prototype

AWS_STATIC_IMPL int aws_array_list_front(const struct aws_array_list *AWS_RESTRICT list, void *val);
source
LibAWSCRT.aws_array_list_get_at — Method
aws_array_list_get_at(list, val, index)

Copies the memory at index to val. If element does not exist, AWS_ERROR_INVALID_INDEX will be raised.

Prototype

AWS_STATIC_IMPL int aws_array_list_get_at(const struct aws_array_list *AWS_RESTRICT list, void *val, size_t index);
source
LibAWSCRT.aws_array_list_get_at_ptr — Method
aws_array_list_get_at_ptr(list, val, index)

Copies the memory address of the element at index to *val. If element does not exist, AWS_ERROR_INVALID_INDEX will be raised.

Prototype

AWS_STATIC_IMPL int aws_array_list_get_at_ptr(const struct aws_array_list *AWS_RESTRICT list, void **val, size_t index);
source
LibAWSCRT.aws_array_list_init_dynamic — Method
aws_array_list_init_dynamic(list, alloc, initial_item_allocation, item_size)

Initializes an array list with an array of size initial_item_allocation * item_size. In this mode, the array size will grow by a factor of 2 upon insertion if space is not available. initial_item_allocation is the number of elements you want space allocated for. item_size is the size of each element in bytes. Mixing items types is not supported by this API.

Prototype

AWS_STATIC_IMPL int aws_array_list_init_dynamic( struct aws_array_list *AWS_RESTRICT list, struct aws_allocator *alloc, size_t initial_item_allocation, size_t item_size);
source
LibAWSCRT.aws_array_list_init_static — Method
aws_array_list_init_static(list, raw_array, item_count, item_size)

Initializes an array list with a preallocated array of void *. item_count is the number of elements in the array, and item_size is the size in bytes of each element. Mixing items types is not supported by this API. Once this list is full, new items will be rejected.

Prototype

AWS_STATIC_IMPL void aws_array_list_init_static( struct aws_array_list *AWS_RESTRICT list, void *raw_array, size_t item_count, size_t item_size);
source
LibAWSCRT.aws_array_list_init_static_from_initialized — Method
aws_array_list_init_static_from_initialized(list, raw_array, item_count, item_size)

Initializes an array list with a preallocated array of already-initialized elements. item_count is the number of elements in the array, and item_size is the size in bytes of each element.

Once initialized, nothing further can be added to the list, since it will be full and cannot resize.

Primary use case is to treat an already-initialized C array as an array list.

Prototype

AWS_STATIC_IMPL void aws_array_list_init_static_from_initialized( struct aws_array_list *AWS_RESTRICT list, void *raw_array, size_t item_count, size_t item_size);
source
LibAWSCRT.aws_array_list_length — Method
aws_array_list_length(list)

Returns the number of elements in the internal array.

Prototype

AWS_STATIC_IMPL size_t aws_array_list_length(const struct aws_array_list *AWS_RESTRICT list);
source
LibAWSCRT.aws_array_list_pop_back — Method
aws_array_list_pop_back(list)

Deletes the element at the end of the list if it exists. If list is empty, AWS_ERROR_LIST_EMPTY will be raised.

Prototype

AWS_STATIC_IMPL int aws_array_list_pop_back(struct aws_array_list *AWS_RESTRICT list);
source
LibAWSCRT.aws_array_list_pop_front — Method
aws_array_list_pop_front(list)

Deletes the element at the front of the list if it exists. If list is empty, AWS_ERROR_LIST_EMPTY will be raised. This call results in shifting all of the elements at the end of the array to the front. Avoid this call unless that is intended behavior.

Prototype

AWS_STATIC_IMPL int aws_array_list_pop_front(struct aws_array_list *AWS_RESTRICT list);
source
LibAWSCRT.aws_array_list_pop_front_n — Method
aws_array_list_pop_front_n(list, n)

Delete N elements from the front of the list. Remaining elements are shifted to the front of the list. If the list has less than N elements, the list is cleared. This call is more efficient than calling aws_array_list_pop_front() N times.

Prototype

AWS_STATIC_IMPL void aws_array_list_pop_front_n(struct aws_array_list *AWS_RESTRICT list, size_t n);
source
LibAWSCRT.aws_array_list_push_back — Method
aws_array_list_push_back(list, val)

Pushes the memory pointed to by val onto the end of internal list

Prototype

AWS_STATIC_IMPL int aws_array_list_push_back(struct aws_array_list *AWS_RESTRICT list, const void *val);
source
LibAWSCRT.aws_array_list_push_front — Method
aws_array_list_push_front(list, val)

Pushes the memory pointed to by val onto the front of internal list. This call results in shifting all of the elements in the list. Avoid this call unless that is intended behavior.

Prototype

AWS_STATIC_IMPL int aws_array_list_push_front(struct aws_array_list *AWS_RESTRICT list, const void *val);
source
LibAWSCRT.aws_array_list_set_at — Method
aws_array_list_set_at(list, val, index)

Copies the the memory pointed to by val into the array at index. If in dynamic mode, the size will grow by a factor of two when the array is full. In static mode, AWS_ERROR_INVALID_INDEX will be raised if the index is past the bounds of the array.

Prototype

AWS_STATIC_IMPL int aws_array_list_set_at(struct aws_array_list *AWS_RESTRICT list, const void *val, size_t index);
source
LibAWSCRT.aws_array_list_shrink_to_fit — Method
aws_array_list_shrink_to_fit(list)

If in dynamic mode, shrinks the allocated array size to the minimum amount necessary to store its elements.

Prototype

int aws_array_list_shrink_to_fit(struct aws_array_list *AWS_RESTRICT list);
source
LibAWSCRT.aws_array_list_sort — Method
aws_array_list_sort(list, compare_fn)

Sort elements in the list in-place according to the comparator function.

Prototype

void aws_array_list_sort(struct aws_array_list *AWS_RESTRICT list, aws_array_list_comparator_fn *compare_fn);
source
LibAWSCRT.aws_array_list_swap — Method
aws_array_list_swap(list, a, b)

Swap elements at the specified indices, which must be within the bounds of the array.

Prototype

void aws_array_list_swap(struct aws_array_list *AWS_RESTRICT list, size_t a, size_t b);
source
LibAWSCRT.aws_array_list_swap_contents — Method
aws_array_list_swap_contents(list_a, list_b)

Swap contents between two dynamic lists. Both lists must use the same allocator.

Prototype

AWS_STATIC_IMPL void aws_array_list_swap_contents( struct aws_array_list *AWS_RESTRICT list_a, struct aws_array_list *AWS_RESTRICT list_b);
source
LibAWSCRT.aws_async_input_stream_acquire — Method
aws_async_input_stream_acquire(stream)

Increment reference count. You may pass in NULL (has no effect). Returns whatever pointer was passed in.

Prototype

struct aws_async_input_stream *aws_async_input_stream_acquire(struct aws_async_input_stream *stream);
source
LibAWSCRT.aws_async_input_stream_read — Method
aws_async_input_stream_read(stream, dest)

Read once from the async stream into the buffer. The read completes when at least 1 byte is read, the buffer is full, or EOF is reached. Depending on implementation, the read could complete at any time. It may complete synchronously. It may complete on another thread. Returns a future, which will contain an error code if something went wrong, or a result bool indicating whether EOF has been reached.

WARNING: The buffer must have space available. WARNING: Do not read again until the previous read is complete.

Prototype

struct aws_future_bool *aws_async_input_stream_read(struct aws_async_input_stream *stream, struct aws_byte_buf *dest);
source
LibAWSCRT.aws_async_input_stream_read_to_fill — Method
aws_async_input_stream_read_to_fill(stream, dest)

Read repeatedly from the async stream until the buffer is full, or EOF is reached. Depending on implementation, this could complete at any time. It may complete synchronously. It may complete on another thread. Returns a future, which will contain an error code if something went wrong, or a result bool indicating whether EOF has been reached.

WARNING: The buffer must have space available. WARNING: Do not read again until the previous read is complete.

Prototype

struct aws_future_bool *aws_async_input_stream_read_to_fill( struct aws_async_input_stream *stream, struct aws_byte_buf *dest);
source
LibAWSCRT.aws_async_input_stream_release — Method
aws_async_input_stream_release(stream)

Decrement reference count. You may pass in NULL (has no effect). Always returns NULL.

Prototype

struct aws_async_input_stream *aws_async_input_stream_release(struct aws_async_input_stream *stream);
source
LibAWSCRT.aws_atomic_compare_exchange_int — Method
aws_atomic_compare_exchange_int(var, expected, desired)

Atomically compares *var to *expected; if they are equal, atomically sets *var = desired. Otherwise, *expected is set to the value in *var. Uses sequentially consistent memory ordering, regardless of success or failure. Returns true if the compare was successful and the variable updated to desired.

Prototype

AWS_STATIC_IMPL bool aws_atomic_compare_exchange_int(volatile struct aws_atomic_var *var, size_t *expected, size_t desired);
source
LibAWSCRT.aws_atomic_compare_exchange_int_explicit — Method
aws_atomic_compare_exchange_int_explicit(var, expected, desired, order_success, order_failure)

Atomically compares *var to *expected; if they are equal, atomically sets *var = desired. Otherwise, *expected is set to the value in *var. On success, the memory ordering used was order_success; otherwise, it was order_failure. order_failure must be no stronger than order_success, and must not be release or acq_rel.

Prototype

AWS_STATIC_IMPL bool aws_atomic_compare_exchange_int_explicit( volatile struct aws_atomic_var *var, size_t *expected, size_t desired, enum aws_memory_order order_success, enum aws_memory_order order_failure);
source
LibAWSCRT.aws_atomic_compare_exchange_ptr — Method
aws_atomic_compare_exchange_ptr(var, expected, desired)

Atomically compares *var to *expected; if they are equal, atomically sets *var = desired. Otherwise, *expected is set to the value in *var. Uses sequentially consistent memory ordering, regardless of success or failure. Returns true if the compare was successful and the variable updated to desired.

Prototype

AWS_STATIC_IMPL bool aws_atomic_compare_exchange_ptr(volatile struct aws_atomic_var *var, void **expected, void *desired);
source
LibAWSCRT.aws_atomic_compare_exchange_ptr_explicit — Method
aws_atomic_compare_exchange_ptr_explicit(var, expected, desired, order_success, order_failure)

Atomically compares *var to *expected; if they are equal, atomically sets *var = desired. Otherwise, *expected is set to the value in *var. On success, the memory ordering used was order_success; otherwise, it was order_failure. order_failure must be no stronger than order_success, and must not be release or acq_rel.

Prototype

AWS_STATIC_IMPL bool aws_atomic_compare_exchange_ptr_explicit( volatile struct aws_atomic_var *var, void **expected, void *desired, enum aws_memory_order order_success, enum aws_memory_order order_failure);
source
LibAWSCRT.aws_atomic_exchange_int — Method
aws_atomic_exchange_int(var, n)

Exchanges an integer with the value in an atomic_var, using sequentially consistent ordering. Returns the value that was previously in the atomic_var.

Prototype

AWS_STATIC_IMPL size_t aws_atomic_exchange_int(volatile struct aws_atomic_var *var, size_t n);
source
LibAWSCRT.aws_atomic_exchange_int_explicit — Method
aws_atomic_exchange_int_explicit(var, n, memory_order)

Exchanges an integer with the value in an atomic_var, using the specified ordering. Returns the value that was previously in the atomic_var.

Prototype

AWS_STATIC_IMPL size_t aws_atomic_exchange_int_explicit( volatile struct aws_atomic_var *var, size_t n, enum aws_memory_order memory_order);
source
LibAWSCRT.aws_atomic_exchange_ptr — Method
aws_atomic_exchange_ptr(var, p)

Exchanges an integer with the value in an atomic_var, using sequentially consistent ordering. Returns the value that was previously in the atomic_var.

Prototype

AWS_STATIC_IMPL void *aws_atomic_exchange_ptr(volatile struct aws_atomic_var *var, void *p);
source
LibAWSCRT.aws_atomic_exchange_ptr_explicit — Method
aws_atomic_exchange_ptr_explicit(var, p, memory_order)

Exchanges a pointer with the value in an atomic_var, using the specified ordering. Returns the value that was previously in the atomic_var.

Prototype

AWS_STATIC_IMPL void *aws_atomic_exchange_ptr_explicit( volatile struct aws_atomic_var *var, void *p, enum aws_memory_order memory_order);
source
LibAWSCRT.aws_atomic_fetch_add — Method
aws_atomic_fetch_add(var, n)

Atomically adds n to *var, and returns the previous value of *var. Uses sequentially consistent ordering.

Prototype

AWS_STATIC_IMPL size_t aws_atomic_fetch_add(volatile struct aws_atomic_var *var, size_t n);
source
LibAWSCRT.aws_atomic_fetch_add_explicit — Method
aws_atomic_fetch_add_explicit(var, n, order)

Atomically adds n to *var, and returns the previous value of *var.

Prototype

AWS_STATIC_IMPL size_t aws_atomic_fetch_add_explicit(volatile struct aws_atomic_var *var, size_t n, enum aws_memory_order order);
source
LibAWSCRT.aws_atomic_fetch_and — Method
aws_atomic_fetch_and(var, n)

Atomically ands n into *var, and returns the previous value of *var. Uses sequentially consistent ordering.

Prototype

AWS_STATIC_IMPL size_t aws_atomic_fetch_and(volatile struct aws_atomic_var *var, size_t n);
source
LibAWSCRT.aws_atomic_fetch_and_explicit — Method
aws_atomic_fetch_and_explicit(var, n, order)

Atomically ANDs n with *var, and returns the previous value of *var.

Prototype

AWS_STATIC_IMPL size_t aws_atomic_fetch_and_explicit(volatile struct aws_atomic_var *var, size_t n, enum aws_memory_order order);
source
LibAWSCRT.aws_atomic_fetch_or — Method
aws_atomic_fetch_or(var, n)

Atomically ors n into *var, and returns the previous value of *var. Uses sequentially consistent ordering.

Prototype

AWS_STATIC_IMPL size_t aws_atomic_fetch_or(volatile struct aws_atomic_var *var, size_t n);
source
LibAWSCRT.aws_atomic_fetch_or_explicit — Method
aws_atomic_fetch_or_explicit(var, n, order)

Atomically ORs n with *var, and returns the previous value of *var.

Prototype

AWS_STATIC_IMPL size_t aws_atomic_fetch_or_explicit(volatile struct aws_atomic_var *var, size_t n, enum aws_memory_order order);
source
LibAWSCRT.aws_atomic_fetch_sub — Method
aws_atomic_fetch_sub(var, n)

Atomically subtracts n from *var, and returns the previous value of *var. Uses sequentially consistent ordering.

Prototype

AWS_STATIC_IMPL size_t aws_atomic_fetch_sub(volatile struct aws_atomic_var *var, size_t n);
source
LibAWSCRT.aws_atomic_fetch_sub_explicit — Method
aws_atomic_fetch_sub_explicit(var, n, order)

Atomically subtracts n from *var, and returns the previous value of *var.

Prototype

AWS_STATIC_IMPL size_t aws_atomic_fetch_sub_explicit(volatile struct aws_atomic_var *var, size_t n, enum aws_memory_order order);
source
LibAWSCRT.aws_atomic_fetch_xor — Method
aws_atomic_fetch_xor(var, n)

Atomically xors n into *var, and returns the previous value of *var. Uses sequentially consistent ordering.

Prototype

AWS_STATIC_IMPL size_t aws_atomic_fetch_xor(volatile struct aws_atomic_var *var, size_t n);
source
LibAWSCRT.aws_atomic_fetch_xor_explicit — Method
aws_atomic_fetch_xor_explicit(var, n, order)

Atomically XORs n with *var, and returns the previous value of *var.

Prototype

AWS_STATIC_IMPL size_t aws_atomic_fetch_xor_explicit(volatile struct aws_atomic_var *var, size_t n, enum aws_memory_order order);
source
LibAWSCRT.aws_atomic_init_int — Method
aws_atomic_init_int(var, n)

Initializes an atomic variable with an integer value. This operation should be done before any other operations on this atomic variable, and must be done before attempting any parallel operations.

Prototype

AWS_STATIC_IMPL void aws_atomic_init_int(volatile struct aws_atomic_var *var, size_t n);
source
LibAWSCRT.aws_atomic_init_ptr — Method
aws_atomic_init_ptr(var, p)

Initializes an atomic variable with a pointer value. This operation should be done before any other operations on this atomic variable, and must be done before attempting any parallel operations.

Prototype

AWS_STATIC_IMPL void aws_atomic_init_ptr(volatile struct aws_atomic_var *var, void *p);
source
LibAWSCRT.aws_atomic_load_int — Method
aws_atomic_load_int(var)

Reads an atomic var as an integer, using sequentially consistent ordering, and returns the result.

Prototype

AWS_STATIC_IMPL size_t aws_atomic_load_int(volatile const struct aws_atomic_var *var);
source
LibAWSCRT.aws_atomic_load_int_explicit — Method
aws_atomic_load_int_explicit(var, memory_order)

Reads an atomic var as an integer, using the specified ordering, and returns the result.

Prototype

AWS_STATIC_IMPL size_t aws_atomic_load_int_explicit(volatile const struct aws_atomic_var *var, enum aws_memory_order memory_order);
source
LibAWSCRT.aws_atomic_load_ptr — Method
aws_atomic_load_ptr(var)

Reads an atomic var as a pointer, using sequentially consistent ordering, and returns the result.

Prototype

AWS_STATIC_IMPL void *aws_atomic_load_ptr(volatile const struct aws_atomic_var *var);
source
LibAWSCRT.aws_atomic_load_ptr_explicit — Method
aws_atomic_load_ptr_explicit(var, memory_order)

Reads an atomic var as a pointer, using the specified ordering, and returns the result.

Prototype

AWS_STATIC_IMPL void *aws_atomic_load_ptr_explicit(volatile const struct aws_atomic_var *var, enum aws_memory_order memory_order);
source
LibAWSCRT.aws_atomic_store_int — Method
aws_atomic_store_int(var, n)

Stores an integer into an atomic var, using sequentially consistent ordering.

Prototype

AWS_STATIC_IMPL void aws_atomic_store_int(volatile struct aws_atomic_var *var, size_t n);
source
LibAWSCRT.aws_atomic_store_int_explicit — Method
aws_atomic_store_int_explicit(var, n, memory_order)

Stores an integer into an atomic var, using the specified ordering.

Prototype

AWS_STATIC_IMPL void aws_atomic_store_int_explicit(volatile struct aws_atomic_var *var, size_t n, enum aws_memory_order memory_order);
source
LibAWSCRT.aws_atomic_store_ptr — Method
aws_atomic_store_ptr(var, p)

Stores a pointer into an atomic var, using sequentially consistent ordering.

Prototype

AWS_STATIC_IMPL void aws_atomic_store_ptr(volatile struct aws_atomic_var *var, void *p);
source
LibAWSCRT.aws_atomic_store_ptr_explicit — Method
aws_atomic_store_ptr_explicit(var, p, memory_order)

Stores an pointer into an atomic var, using the specified ordering.

Prototype

AWS_STATIC_IMPL void aws_atomic_store_ptr_explicit(volatile struct aws_atomic_var *var, void *p, enum aws_memory_order memory_order);
source
LibAWSCRT.aws_atomic_thread_fence — Method
aws_atomic_thread_fence(order)

Provides the same reordering guarantees as an atomic operation with the specified memory order, without needing to actually perform an atomic operation.

Prototype

AWS_STATIC_IMPL void aws_atomic_thread_fence(enum aws_memory_order order);
source
LibAWSCRT.aws_auth_library_clean_up — Method
aws_auth_library_clean_up()

Clean up internal datastructures used by aws-c-auth. Must not be called until application is done using functionality in aws-c-auth.

Prototype

void aws_auth_library_clean_up(void);
source
LibAWSCRT.aws_auth_library_init — Method
aws_auth_library_init(allocator)

Initializes internal datastructures used by aws-c-auth. Must be called before using any functionality in aws-c-auth.

Parameters

  • allocator: memory allocator to use for any module-level memory allocation

Prototype

void aws_auth_library_init(struct aws_allocator *allocator);
source
LibAWSCRT.aws_backtrace — Method
aws_backtrace(stack_frames, num_frames)

Prototype

size_t aws_backtrace(void **stack_frames, size_t num_frames);
source
LibAWSCRT.aws_backtrace_print — Method
aws_backtrace_print(fp, call_site_data)

Print a backtrace from either the current stack, or (if provided) the current exception/signal call_site_data is siginfo_t* on POSIX, and LPEXCEPTION_POINTERS on Windows, and can be null

Prototype

void aws_backtrace_print(FILE *fp, void *call_site_data);
source
LibAWSCRT.aws_base64_compute_decoded_len — Method
aws_base64_compute_decoded_len(to_decode, decoded_len)

Prototype

int aws_base64_compute_decoded_len(const struct aws_byte_cursor *AWS_RESTRICT to_decode, size_t *decoded_len);
source
LibAWSCRT.aws_base64_decode — Method
aws_base64_decode(to_decode, output)

Prototype

int aws_base64_decode(const struct aws_byte_cursor *AWS_RESTRICT to_decode, struct aws_byte_buf *AWS_RESTRICT output);
source
LibAWSCRT.aws_base64_encode — Method
aws_base64_encode(to_encode, output)

Prototype

int aws_base64_encode(const struct aws_byte_cursor *AWS_RESTRICT to_encode, struct aws_byte_buf *AWS_RESTRICT output);
source
LibAWSCRT.aws_byte_buf_advance — Method
aws_byte_buf_advance(buffer, output, len)

Appends a sub-buffer to the specified buffer.

If the buffer has at least len' bytes remaining (buffer->capacity - buffer->len >= len), then buffer->len is incremented by len, and an [awsbytebuf](@ref) is assigned to *output corresponding to the last len bytes of the input buffer. The [awsbytebuf`](@ref) at *output will have a null allocator, a zero initial length, and a capacity of 'len'. The function then returns true.

If there is insufficient space, then this function nulls all fields in *output and returns false.

Prototype

bool aws_byte_buf_advance( struct aws_byte_buf *const AWS_RESTRICT buffer, struct aws_byte_buf *const AWS_RESTRICT output, const size_t len);
source
LibAWSCRT.aws_byte_buf_append — Method
aws_byte_buf_append(to, from)

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.

from and to may be the same buffer, permitting copying a buffer into itself.

Prototype

int aws_byte_buf_append(struct aws_byte_buf *to, const struct aws_byte_cursor *from);
source
LibAWSCRT.aws_byte_buf_append_and_update — Method
aws_byte_buf_append_and_update(to, from_and_update)

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.

The cursor is permitted to reference memory from earlier in the buffer.

Prototype

int aws_byte_buf_append_and_update(struct aws_byte_buf *to, struct aws_byte_cursor *from_and_update);
source
LibAWSCRT.aws_byte_buf_append_byte_dynamic — Method
aws_byte_buf_append_byte_dynamic(buffer, value)

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.

If the grow fails (overflow or OOM), then an error will be returned.

Prototype

int aws_byte_buf_append_byte_dynamic(struct aws_byte_buf *buffer, uint8_t value);
source
LibAWSCRT.aws_byte_buf_append_byte_dynamic_secure — Method
aws_byte_buf_append_byte_dynamic_secure(buffer, value)

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.

If the grow fails (overflow or OOM), then an error will be returned.

If the buffer is grown, the old buffer will be securely cleared before getting freed.

Prototype

int aws_byte_buf_append_byte_dynamic_secure(struct aws_byte_buf *buffer, uint8_t value);
source
LibAWSCRT.aws_byte_buf_append_decoding_uri — Method
aws_byte_buf_append_decoding_uri(buffer, cursor)

Writes the uri decoding of a UTF-8 cursor to a buffer, replacing xx escapes by their single byte equivalent. For example, reading "a20b_c" would write "a b_c".

Prototype

int aws_byte_buf_append_decoding_uri(struct aws_byte_buf *buffer, const struct aws_byte_cursor *cursor);
source
LibAWSCRT.aws_byte_buf_append_dynamic — Method
aws_byte_buf_append_dynamic(to, from)

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.

If the grow fails (overflow or OOM), then an error will be returned.

from and to may be the same buffer, permitting copying a buffer into itself.

Prototype

int aws_byte_buf_append_dynamic(struct aws_byte_buf *to, const struct aws_byte_cursor *from);
source
LibAWSCRT.aws_byte_buf_append_dynamic_secure — Method
aws_byte_buf_append_dynamic_secure(to, from)

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.

If the grow fails (overflow or OOM), then an error will be returned.

If the buffer is grown, the old buffer will be securely cleared before getting freed.

from and to may be the same buffer, permitting copying a buffer into itself.

Prototype

int aws_byte_buf_append_dynamic_secure(struct aws_byte_buf *to, const struct aws_byte_cursor *from);
source
LibAWSCRT.aws_byte_buf_append_encoding_uri_param — Method
aws_byte_buf_append_encoding_uri_param(buffer, cursor)

Writes the uri query param encoding (passthrough alnum + '-' '_' '~' '.') of a UTF-8 cursor to a buffer For example, reading "a b_c" would write "a20b_c".

Prototype

int aws_byte_buf_append_encoding_uri_param( struct aws_byte_buf *buffer, const struct aws_byte_cursor *cursor);
source
LibAWSCRT.aws_byte_buf_append_encoding_uri_path — Method
aws_byte_buf_append_encoding_uri_path(buffer, cursor)

Writes the uri path encoding of a cursor to a buffer. This is the modified version of rfc3986 used by sigv4 signing.

Prototype

int aws_byte_buf_append_encoding_uri_path( struct aws_byte_buf *buffer, const struct aws_byte_cursor *cursor);
source
LibAWSCRT.aws_byte_buf_append_json_string — Method
aws_byte_buf_append_json_string(value, output)

Appends a unformatted JSON string representation of the aws_json_value into the passed byte buffer. The byte buffer is expected to be already initialized so the function can append the JSON into it.

Note: The byte buffer will automatically have its size extended if the JSON string is over the byte buffer capacity AND the byte buffer has an allocator associated with it. If the byte buffer does not have an allocator associated and the JSON string is over capacity, AWS_OP_ERR will be returned.

Note: When you are finished with the aws_byte_buf, you must call "aws_byte_buf_clean_up_secure" to free the memory used, as it will NOT be called automatically.

Parameters

  • value: The aws_json_value to format.
  • output: The destination for the JSON string

Returns

AWS_OP_SUCCESS if the JSON string was allocated to output without any errors Will return AWS_OP_ERR if the value passed is not an aws_json_value or if there was an error appending the JSON into the byte buffer.

Prototype

int aws_byte_buf_append_json_string(const struct aws_json_value *value, struct aws_byte_buf *output);
source
LibAWSCRT.aws_byte_buf_append_json_string_formatted — Method
aws_byte_buf_append_json_string_formatted(value, output)

Appends a formatted JSON string representation of the aws_json_value into the passed byte buffer. The byte buffer is expected to already be initialized so the function can append the JSON into it.

Note: The byte buffer will automatically have its size extended if the JSON string is over the byte buffer capacity AND the byte buffer has an allocator associated with it. If the byte buffer does not have an allocator associated and the JSON string is over capacity, AWS_OP_ERR will be returned.

Note: When you are finished with the aws_byte_buf, you must call "aws_byte_buf_clean_up_secure" to free the memory used, as it will NOT be called automatically.

Parameters

  • value: The aws_json_value to format.
  • output: The destination for the JSON string

Returns

AWS_OP_SUCCESS if the JSON string was allocated to output without any errors Will return AWS_ERROR_INVALID_ARGUMENT if the value passed is not an aws_json_value or if there aws an error appending the JSON into the byte buffer.

Prototype

int aws_byte_buf_append_json_string_formatted(const struct aws_json_value *value, struct aws_byte_buf *output);
source
LibAWSCRT.aws_byte_buf_append_resource_name — Method
aws_byte_buf_append_resource_name(buf, arn)

Serializes an ARN structure into the lexical string format

Prototype

int aws_byte_buf_append_resource_name(struct aws_byte_buf *buf, const struct aws_resource_name *arn);
source
LibAWSCRT.aws_byte_buf_append_with_lookup — Method
aws_byte_buf_append_with_lookup(to, from, lookup_table)

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.

from and to should not be the same buffer (overlap is not handled) lookup_table must be at least 256 bytes

Prototype

int aws_byte_buf_append_with_lookup( struct aws_byte_buf *AWS_RESTRICT to, const struct aws_byte_cursor *AWS_RESTRICT from, const uint8_t *lookup_table);
source
LibAWSCRT.aws_byte_buf_eq — Method
aws_byte_buf_eq(a, b)

Compare two aws_byte_buf structures. Return whether their contents are equivalent.

Prototype

bool aws_byte_buf_eq(const struct aws_byte_buf *const a, const struct aws_byte_buf *const b);
source
LibAWSCRT.aws_byte_buf_eq_c_str — Method
aws_byte_buf_eq_c_str(buf, c_str)

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.

Prototype

bool aws_byte_buf_eq_c_str(const struct aws_byte_buf *const buf, const char *const c_str);
source
LibAWSCRT.aws_byte_buf_eq_c_str_ignore_case — Method
aws_byte_buf_eq_c_str_ignore_case(buf, c_str)

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.

Prototype

bool aws_byte_buf_eq_c_str_ignore_case(const struct aws_byte_buf *const buf, const char *const c_str);
source
LibAWSCRT.aws_byte_buf_eq_ignore_case — Method
aws_byte_buf_eq_ignore_case(a, b)

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.

Prototype

bool aws_byte_buf_eq_ignore_case(const struct aws_byte_buf *const a, const struct aws_byte_buf *const b);
source
LibAWSCRT.aws_byte_buf_from_c_str — Method
aws_byte_buf_from_c_str(c_str)

For creating a byte buffer from a null-terminated string literal.

Prototype

struct aws_byte_buf aws_byte_buf_from_c_str(const char *c_str);
source
LibAWSCRT.aws_byte_buf_init — Method
aws_byte_buf_init(buf, allocator, capacity)

Prototype

int aws_byte_buf_init(struct aws_byte_buf *buf, struct aws_allocator *allocator, size_t capacity);
source
LibAWSCRT.aws_byte_buf_init_copy — Method
aws_byte_buf_init_copy(dest, allocator, src)

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.

Prototype

int aws_byte_buf_init_copy( struct aws_byte_buf *dest, struct aws_allocator *allocator, const struct aws_byte_buf *src);
source
LibAWSCRT.aws_byte_buf_init_copy_from_cursor — Method
aws_byte_buf_init_copy_from_cursor(dest, allocator, src)

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.

Prototype

int aws_byte_buf_init_copy_from_cursor( struct aws_byte_buf *dest, struct aws_allocator *allocator, struct aws_byte_cursor src);
source
LibAWSCRT.aws_byte_buf_init_from_file — Method
aws_byte_buf_init_from_file(out_buf, alloc, filename)

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.

Prototype

int aws_byte_buf_init_from_file(struct aws_byte_buf *out_buf, struct aws_allocator *alloc, const char *filename);
source
LibAWSCRT.aws_byte_buf_is_valid — Method
aws_byte_buf_is_valid(buf)

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).

Prototype

bool aws_byte_buf_is_valid(const struct aws_byte_buf *const buf);
source
LibAWSCRT.aws_byte_buf_reserve — Method
aws_byte_buf_reserve(buffer, requested_capacity)

Attempts to increase the capacity of a buffer to the requested capacity

If the the buffer's capacity is currently larger than the request capacity, the function does nothing (no shrink is performed).

Prototype

int aws_byte_buf_reserve(struct aws_byte_buf *buffer, size_t requested_capacity);
source
LibAWSCRT.aws_byte_buf_reset — Method
aws_byte_buf_reset(buf, zero_contents)

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.

Prototype

void aws_byte_buf_reset(struct aws_byte_buf *buf, bool zero_contents);
source
LibAWSCRT.aws_byte_buf_secure_zero — Method
aws_byte_buf_secure_zero(buf)

Sets all bytes of buffer to zero and resets len to zero.

Prototype

void aws_byte_buf_secure_zero(struct aws_byte_buf *buf);
source
LibAWSCRT.aws_byte_buf_write — Method
aws_byte_buf_write(buf, src, len)

Write specified number of bytes from array to byte buffer.

On success, returns true and updates the buffer length accordingly. If there is insufficient space in the buffer, returns false, leaving the buffer unchanged.

Prototype

bool aws_byte_buf_write( struct aws_byte_buf *AWS_RESTRICT buf, const uint8_t *AWS_RESTRICT src, size_t len);
source
LibAWSCRT.aws_byte_buf_write_be16 — Method
aws_byte_buf_write_be16(buf, x)

Writes a 16-bit integer in network byte order (big endian) to buffer.

On success, returns true and updates the buffer /length accordingly. If there is insufficient space in the buffer, returns false, leaving the buffer unchanged.

Prototype

bool aws_byte_buf_write_be16(struct aws_byte_buf *buf, uint16_t x);
source
LibAWSCRT.aws_byte_buf_write_be24 — Method
aws_byte_buf_write_be24(buf, x)

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.

On success, returns true and updates the buffer /length accordingly. If there is insufficient space in the buffer, or x's value cannot fit in 3 bytes, returns false, leaving the buffer unchanged.

Prototype

bool aws_byte_buf_write_be24(struct aws_byte_buf *buf, uint32_t x);
source
LibAWSCRT.aws_byte_buf_write_be32 — Method
aws_byte_buf_write_be32(buf, x)

Writes a 32-bit integer in network byte order (big endian) to buffer.

On success, returns true and updates the buffer /length accordingly. If there is insufficient space in the buffer, returns false, leaving the buffer unchanged.

Prototype

bool aws_byte_buf_write_be32(struct aws_byte_buf *buf, uint32_t x);
source
LibAWSCRT.aws_byte_buf_write_be64 — Method
aws_byte_buf_write_be64(buf, x)

Writes a 64-bit integer in network byte order (big endian) to buffer.

On success, returns true and updates the buffer /length accordingly. If there is insufficient space in the buffer, returns false, leaving the buffer unchanged.

Prototype

bool aws_byte_buf_write_be64(struct aws_byte_buf *buf, uint64_t x);
source
LibAWSCRT.aws_byte_buf_write_float_be32 — Method
aws_byte_buf_write_float_be32(buf, x)

Writes a 32-bit float in network byte order (big endian) to buffer.

On success, returns true and updates the buffer /length accordingly. If there is insufficient space in the buffer, returns false, leaving the buffer unchanged.

Prototype

bool aws_byte_buf_write_float_be32(struct aws_byte_buf *buf, float x);
source
LibAWSCRT.aws_byte_buf_write_float_be64 — Method
aws_byte_buf_write_float_be64(buf, x)

Writes a 64-bit float in network byte order (big endian) to buffer.

On success, returns true and updates the buffer /length accordingly. If there is insufficient space in the buffer, returns false, leaving the buffer unchanged.

Prototype

bool aws_byte_buf_write_float_be64(struct aws_byte_buf *buf, double x);
source
LibAWSCRT.aws_byte_buf_write_from_whole_buffer — Method
aws_byte_buf_write_from_whole_buffer(buf, src)

Copies all bytes from buffer to buffer.

On success, returns true and updates the buffer /length accordingly. If there is insufficient space in the buffer, returns false, leaving the buffer unchanged.

Prototype

bool aws_byte_buf_write_from_whole_buffer( struct aws_byte_buf *AWS_RESTRICT buf, struct aws_byte_buf src);
source
LibAWSCRT.aws_byte_buf_write_from_whole_cursor — Method
aws_byte_buf_write_from_whole_cursor(buf, src)

Copies all bytes from buffer to buffer.

On success, returns true and updates the buffer /length accordingly. If there is insufficient space in the buffer, returns false, leaving the buffer unchanged.

Prototype

bool aws_byte_buf_write_from_whole_cursor( struct aws_byte_buf *AWS_RESTRICT buf, struct aws_byte_cursor src);
source
LibAWSCRT.aws_byte_buf_write_from_whole_string — Method
aws_byte_buf_write_from_whole_string(buf, src)

Copies all bytes from string to buf.

On success, returns true and updates the buf pointer/length accordingly. If there is insufficient space in the buf, returns false, leaving the buf unchanged.

Prototype

bool aws_byte_buf_write_from_whole_string( struct aws_byte_buf *AWS_RESTRICT buf, const struct aws_string *AWS_RESTRICT src);
source
LibAWSCRT.aws_byte_buf_write_to_capacity — Method
aws_byte_buf_write_to_capacity(buf, advancing_cursor)

Without increasing buf's capacity, write as much as possible from advancing_cursor into buf.

buf's len is updated accordingly. advancing_cursor is advanced so it contains the remaining unwritten parts. Returns the section of advancing_cursor which was written.

This function cannot fail. If buf is full (len == capacity) or advancing_len has 0 length, then buf and advancing_cursor are not altered and a cursor with 0 length is returned.

Example: Given a buf with 2 bytes of space available and advancing_cursor with contents "abc". "ab" will be written to buf and buf->len will increase 2 and become equal to buf->capacity. advancing_cursor will advance so its contents become the unwritten "c". The returned cursor's contents will be the "ab" from the original advancing_cursor.

Prototype

struct aws_byte_cursor aws_byte_buf_write_to_capacity( struct aws_byte_buf *buf, struct aws_byte_cursor *advancing_cursor);
source
LibAWSCRT.aws_byte_buf_write_u8 — Method
aws_byte_buf_write_u8(buf, c)

Copies one byte to buffer.

On success, returns true and updates the cursor /length accordingly.

If there is insufficient space in the buffer, returns false, leaving the buffer unchanged.

Prototype

bool aws_byte_buf_write_u8(struct aws_byte_buf *AWS_RESTRICT buf, uint8_t c);
source
LibAWSCRT.aws_byte_buf_write_u8_n — Method
aws_byte_buf_write_u8_n(buf, c, count)

Writes one byte repeatedly to buffer (like memset)

If there is insufficient space in the buffer, returns false, leaving the buffer unchanged.

Prototype

bool aws_byte_buf_write_u8_n(struct aws_byte_buf *buf, uint8_t c, size_t count);
source
LibAWSCRT.aws_byte_cursor_advance — Method
aws_byte_cursor_advance(cursor, len)

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.

Note that if len is above (SIZE_MAX / 2), this function will also treat it as a buffer overflow, and return NULL without changing *buf.

Prototype

struct aws_byte_cursor aws_byte_cursor_advance(struct aws_byte_cursor *const cursor, const size_t len);
source
LibAWSCRT.aws_byte_cursor_advance_nospec — Method
aws_byte_cursor_advance_nospec(cursor, len)

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).

This should generally be done when using an untrusted or data-dependent value for 'len', to avoid speculating into a path where cursor->ptr points outside the true ptr length.

Prototype

struct aws_byte_cursor aws_byte_cursor_advance_nospec(struct aws_byte_cursor *const cursor, size_t len);
source
LibAWSCRT.aws_byte_cursor_compare_lexical — Method
aws_byte_cursor_compare_lexical(lhs, rhs)

Lexical (byte value) comparison of two byte cursors

Prototype

int aws_byte_cursor_compare_lexical(const struct aws_byte_cursor *lhs, const struct aws_byte_cursor *rhs);
source
LibAWSCRT.aws_byte_cursor_compare_lookup — Method
aws_byte_cursor_compare_lookup(lhs, rhs, lookup_table)

Lexical (byte value) comparison of two byte cursors where the raw values are sent through a lookup table first

Prototype

int aws_byte_cursor_compare_lookup( const struct aws_byte_cursor *lhs, const struct aws_byte_cursor *rhs, const uint8_t *lookup_table);
source
LibAWSCRT.aws_byte_cursor_eq — Method
aws_byte_cursor_eq(a, b)

Compare two aws_byte_cursor structures. Return whether their contents are equivalent.

Prototype

bool aws_byte_cursor_eq(const struct aws_byte_cursor *a, const struct aws_byte_cursor *b);
source
LibAWSCRT.aws_byte_cursor_eq_byte_buf_ignore_case — Method
aws_byte_cursor_eq_byte_buf_ignore_case(a, b)

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.

Prototype

bool aws_byte_cursor_eq_byte_buf_ignore_case(const struct aws_byte_cursor *const a, const struct aws_byte_buf *const b);
source
LibAWSCRT.aws_byte_cursor_eq_c_str — Method
aws_byte_cursor_eq_c_str(cursor, c_str)

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.

Prototype

bool aws_byte_cursor_eq_c_str(const struct aws_byte_cursor *const cursor, const char *const c_str);
source
LibAWSCRT.aws_byte_cursor_eq_c_str_ignore_case — Method
aws_byte_cursor_eq_c_str_ignore_case(cursor, c_str)

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.

Prototype

bool aws_byte_cursor_eq_c_str_ignore_case(const struct aws_byte_cursor *const cursor, const char *const c_str);
source
LibAWSCRT.aws_byte_cursor_eq_ignore_case — Method
aws_byte_cursor_eq_ignore_case(a, b)

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.

Prototype

bool aws_byte_cursor_eq_ignore_case(const struct aws_byte_cursor *a, const struct aws_byte_cursor *b);
source
LibAWSCRT.aws_byte_cursor_find_exact — Method
aws_byte_cursor_find_exact(input_str, to_find, first_find)

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.

Prototype

int aws_byte_cursor_find_exact( const struct aws_byte_cursor *AWS_RESTRICT input_str, const struct aws_byte_cursor *AWS_RESTRICT to_find, struct aws_byte_cursor *first_find);
source
LibAWSCRT.aws_byte_cursor_is_valid — Method
aws_byte_cursor_is_valid(cursor)

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).

Prototype

bool aws_byte_cursor_is_valid(const struct aws_byte_cursor *cursor);
source
LibAWSCRT.aws_byte_cursor_left_trim_pred — Method
aws_byte_cursor_left_trim_pred(source, predicate)

Shrinks a byte cursor from the left for as long as the supplied predicate is true

Prototype

struct aws_byte_cursor aws_byte_cursor_left_trim_pred( const struct aws_byte_cursor *source, aws_byte_predicate_fn *predicate);
source
LibAWSCRT.aws_byte_cursor_next_split — Method
aws_byte_cursor_next_split(input_str, split_on, substr)

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.

Returns true each time substr is set and false when there is no more splits (substr is set to empty in that case).

Example usage. struct aws_byte_cursor substr = {0}; while (aws_byte_cursor_next_split(&input_str, ';', &substr)) { // ...use substr... }

Note: It is the user's responsibility zero-initialize substr before the first call.

Edge case rules are as follows: empty input will have single empty split. ex. "" splits into "" if input starts with split_on then first split is empty. ex ";A" splits into "", "A" adjacent split tokens result in empty split. ex "A;;B" splits into "A", "", "B" If the input ends with split_on, last split is empty. ex. "A;" splits into "A", ""

It is the user's responsibility to make sure the input buffer stays in memory long enough to use the results.

Prototype

bool aws_byte_cursor_next_split( const struct aws_byte_cursor *AWS_RESTRICT input_str, char split_on, struct aws_byte_cursor *AWS_RESTRICT substr);
source
LibAWSCRT.aws_byte_cursor_read — Method
aws_byte_cursor_read(cur, dest, len)

Reads specified length of data from byte cursor and copies it to the destination array.

On success, returns true and updates the cursor pointer/length accordingly. If there is insufficient space in the cursor, returns false, leaving the cursor unchanged.

Prototype

bool aws_byte_cursor_read( struct aws_byte_cursor *AWS_RESTRICT cur, void *AWS_RESTRICT dest, const size_t len);
source
LibAWSCRT.aws_byte_cursor_read_and_fill_buffer — Method
aws_byte_cursor_read_and_fill_buffer(cur, dest)

Reads as many bytes from cursor as size of buffer, and copies them to buffer.

On success, returns true and updates the cursor pointer/length accordingly. If there is insufficient space in the cursor, returns false, leaving the cursor unchanged.

Prototype

bool aws_byte_cursor_read_and_fill_buffer( struct aws_byte_cursor *AWS_RESTRICT cur, struct aws_byte_buf *AWS_RESTRICT dest);
source
LibAWSCRT.aws_byte_cursor_read_be16 — Method
aws_byte_cursor_read_be16(cur, var)

Reads a 16-bit value in network byte order from cur, and places it in host byte order into var.

On success, returns true and updates the cursor pointer/length accordingly. If there is insufficient space in the cursor, returns false, leaving the cursor unchanged.

Prototype

bool aws_byte_cursor_read_be16(struct aws_byte_cursor *cur, uint16_t *var);
source
LibAWSCRT.aws_byte_cursor_read_be24 — Method
aws_byte_cursor_read_be24(cur, 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.

On success, returns true and updates the cursor pointer/length accordingly. If there is insufficient space in the cursor, returns false, leaving the cursor unchanged.

Prototype

bool aws_byte_cursor_read_be24(struct aws_byte_cursor *cur, uint32_t *var);
source
LibAWSCRT.aws_byte_cursor_read_be32 — Method
aws_byte_cursor_read_be32(cur, var)

Reads a 32-bit value in network byte order from cur, and places it in host byte order into var.

On success, returns true and updates the cursor pointer/length accordingly. If there is insufficient space in the cursor, returns false, leaving the cursor unchanged.

Prototype

bool aws_byte_cursor_read_be32(struct aws_byte_cursor *cur, uint32_t *var);
source
LibAWSCRT.aws_byte_cursor_read_be64 — Method
aws_byte_cursor_read_be64(cur, var)

Reads a 64-bit value in network byte order from cur, and places it in host byte order into var.

On success, returns true and updates the cursor pointer/length accordingly. If there is insufficient space in the cursor, returns false, leaving the cursor unchanged.

Prototype

bool aws_byte_cursor_read_be64(struct aws_byte_cursor *cur, uint64_t *var);
source
LibAWSCRT.aws_byte_cursor_read_float_be32 — Method
aws_byte_cursor_read_float_be32(cur, var)

Reads a 32-bit value in network byte order from cur, and places it in host byte order into var.

On success, returns true and updates the cursor pointer/length accordingly. If there is insufficient space in the cursor, returns false, leaving the cursor unchanged.

Prototype

bool aws_byte_cursor_read_float_be32(struct aws_byte_cursor *cur, float *var);
source
LibAWSCRT.aws_byte_cursor_read_float_be64 — Method
aws_byte_cursor_read_float_be64(cur, var)

Reads a 64-bit value in network byte order from cur, and places it in host byte order into var.

On success, returns true and updates the cursor pointer/length accordingly. If there is insufficient space in the cursor, returns false, leaving the cursor unchanged.

Prototype

bool aws_byte_cursor_read_float_be64(struct aws_byte_cursor *cur, double *var);
source
LibAWSCRT.aws_byte_cursor_read_hex_u8 — Method
aws_byte_cursor_read_hex_u8(cur, 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.

On success, returns true and advances the cursor by 2. If there is insufficient space in the cursor or an invalid character is encountered, returns false, leaving the cursor unchanged.

Prototype

bool aws_byte_cursor_read_hex_u8(struct aws_byte_cursor *cur, uint8_t *var);
source
LibAWSCRT.aws_byte_cursor_read_u8 — Method
aws_byte_cursor_read_u8(cur, var)

Reads a single byte from cursor, placing it in *var.

On success, returns true and updates the cursor pointer/length accordingly. If there is insufficient space in the cursor, returns false, leaving the cursor unchanged.

Prototype

bool aws_byte_cursor_read_u8(struct aws_byte_cursor *AWS_RESTRICT cur, uint8_t *AWS_RESTRICT var);
source
LibAWSCRT.aws_byte_cursor_right_trim_pred — Method
aws_byte_cursor_right_trim_pred(source, predicate)

Shrinks a byte cursor from the right for as long as the supplied predicate is true

Prototype

struct aws_byte_cursor aws_byte_cursor_right_trim_pred( const struct aws_byte_cursor *source, aws_byte_predicate_fn *predicate);
source
LibAWSCRT.aws_byte_cursor_satisfies_pred — Method
aws_byte_cursor_satisfies_pred(source, predicate)

Returns true if the byte cursor's range of bytes all satisfy the predicate

Prototype

bool aws_byte_cursor_satisfies_pred(const struct aws_byte_cursor *source, aws_byte_predicate_fn *predicate);
source
LibAWSCRT.aws_byte_cursor_split_on_char — Method
aws_byte_cursor_split_on_char(input_str, split_on, output)

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.

Edge case rules are as follows: if the input begins with split_on, an empty cursor will be the first entry in output. if the input has two adjacent split_on tokens, an empty cursor will be inserted into the output. if the input ends with split_on, an empty cursor will be appended to the output.

It is the user's responsibility to properly initialize output. Recommended number of preallocated elements from output is your most likely guess for the upper bound of the number of elements resulting from the split.

The type that will be stored in output is struct aws_byte_cursor (you'll need this for the item size param).

It is the user's responsibility to make sure the input buffer stays in memory long enough to use the results.

Prototype

int aws_byte_cursor_split_on_char( const struct aws_byte_cursor *AWS_RESTRICT input_str, char split_on, struct aws_array_list *AWS_RESTRICT output);
source
LibAWSCRT.aws_byte_cursor_split_on_char_n — Method
aws_byte_cursor_split_on_char_n(input_str, split_on, n, output)

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.

Edge case rules are as follows: if the input begins with split_on, an empty cursor will be the first entry in output if the input has two adjacent split_on tokens, an empty cursor will be inserted into the output. if the input ends with split_on, an empty cursor will be appended to the output.

It is the user's responsibility to properly initialize output. Recommended number of preallocated elements from output is your most likely guess for the upper bound of the number of elements resulting from the split.

If the output array is not large enough, input_str will be updated to point to the first character after the last processed split_on instance.

The type that will be stored in output is struct aws_byte_cursor (you'll need this for the item size param).

It is the user's responsibility to make sure the input buffer stays in memory long enough to use the results.

Prototype

int aws_byte_cursor_split_on_char_n( const struct aws_byte_cursor *AWS_RESTRICT input_str, char split_on, size_t n, struct aws_array_list *AWS_RESTRICT output);
source
LibAWSCRT.aws_byte_cursor_starts_with — Method
aws_byte_cursor_starts_with(input, prefix)

Return true if the input starts with the prefix (exact byte comparison).

Prototype

bool aws_byte_cursor_starts_with(const struct aws_byte_cursor *input, const struct aws_byte_cursor *prefix);
source
LibAWSCRT.aws_byte_cursor_starts_with_ignore_case — Method
aws_byte_cursor_starts_with_ignore_case(input, prefix)

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.

Prototype

bool aws_byte_cursor_starts_with_ignore_case(const struct aws_byte_cursor *input, const struct aws_byte_cursor *prefix);
source
LibAWSCRT.aws_byte_cursor_trim_pred — Method
aws_byte_cursor_trim_pred(source, predicate)

Shrinks a byte cursor from both sides for as long as the supplied predicate is true

Prototype

struct aws_byte_cursor aws_byte_cursor_trim_pred( const struct aws_byte_cursor *source, aws_byte_predicate_fn *predicate);
source
LibAWSCRT.aws_byte_cursor_utf8_parse_u64 — Method
aws_byte_cursor_utf8_parse_u64(cursor, dst)

Read entire cursor as ASCII/UTF-8 unsigned base-10 number. Stricter than strtoull(), which allows whitespace and inputs that start with "0x"

Examples: "0" -> 0 "123" -> 123 "00004" -> 4 // leading zeros ok

Rejects things like: "-1" // negative numbers not allowed "1,000" // only characters 0-9 allowed "" // blank string not allowed " 0 " // whitespace not allowed "0x0" // hex not allowed "FF" // hex not allowed "999999999999999999999999999999999999999999" // larger than max u64

Prototype

int aws_byte_cursor_utf8_parse_u64(struct aws_byte_cursor cursor, uint64_t *dst);
source
LibAWSCRT.aws_byte_cursor_utf8_parse_u64_hex — Method
aws_byte_cursor_utf8_parse_u64_hex(cursor, dst)

Read entire cursor as ASCII/UTF-8 unsigned base-16 number with NO "0x" prefix.

Examples: "F" -> 15 "000000ff" -> 255 // leading zeros ok "Ff" -> 255 // mixed case ok "123" -> 291 "FFFFFFFFFFFFFFFF" -> 18446744073709551616 // max u64

Rejects things like: "0x0" // 0x prefix not allowed "" // blank string not allowed " F " // whitespace not allowed "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF" // larger than max u64

Prototype

int aws_byte_cursor_utf8_parse_u64_hex(struct aws_byte_cursor cursor, uint64_t *dst);
source
LibAWSCRT.aws_cache_destroy — Method
aws_cache_destroy(cache)

Cleans up the cache. Elements in the cache will be evicted and cleanup callbacks will be invoked.

Prototype

void aws_cache_destroy(struct aws_cache *cache);
source
LibAWSCRT.aws_cache_find — Method
aws_cache_find(cache, key, p_value)

Finds element in the cache by key. If found, *p_value will hold the stored value, and AWS_OP_SUCCESS will be returned. If not found, AWS_OP_SUCCESS will be returned and *p_value will be NULL.

If any errors occur AWS_OP_ERR will be returned.

Prototype

int aws_cache_find(struct aws_cache *cache, const void *key, void **p_value);
source
LibAWSCRT.aws_cache_new_fifo — Method
aws_cache_new_fifo(allocator, hash_fn, equals_fn, destroy_key_fn, destroy_value_fn, max_items)

Initializes the first-in-first-out cache. Sets up the underlying linked hash table. Once max_items elements have been added, the oldest(first-in) item will be removed. For the other parameters, see aws/common/hash_table.h. Hash table semantics of these arguments are preserved.

Prototype

struct aws_cache *aws_cache_new_fifo( struct aws_allocator *allocator, aws_hash_fn *hash_fn, aws_hash_callback_eq_fn *equals_fn, aws_hash_callback_destroy_fn *destroy_key_fn, aws_hash_callback_destroy_fn *destroy_value_fn, size_t max_items);
source
LibAWSCRT.aws_cache_new_lifo — Method
aws_cache_new_lifo(allocator, hash_fn, equals_fn, destroy_key_fn, destroy_value_fn, max_items)

Initializes the last-in-first-out cache. Sets up the underlying linked hash table. Once max_items elements have been added, the latest(last-in) item will be removed. For the other parameters, see aws/common/hash_table.h. Hash table semantics of these arguments are preserved.

Prototype

struct aws_cache *aws_cache_new_lifo( struct aws_allocator *allocator, aws_hash_fn *hash_fn, aws_hash_callback_eq_fn *equals_fn, aws_hash_callback_destroy_fn *destroy_key_fn, aws_hash_callback_destroy_fn *destroy_value_fn, size_t max_items);
source
LibAWSCRT.aws_cache_new_lru — Method
aws_cache_new_lru(allocator, hash_fn, equals_fn, destroy_key_fn, destroy_value_fn, max_items)

Initializes the Least-recently-used cache. Sets up the underlying linked hash table. Once max_items elements have been added, the least recently used item will be removed. For the other parameters, see aws/common/hash_table.h. Hash table semantics of these arguments are preserved.(Yes the one that was the answer to that interview question that one time).

Prototype

struct aws_cache *aws_cache_new_lru( struct aws_allocator *allocator, aws_hash_fn *hash_fn, aws_hash_callback_eq_fn *equals_fn, aws_hash_callback_destroy_fn *destroy_key_fn, aws_hash_callback_destroy_fn *destroy_value_fn, size_t max_items);
source
LibAWSCRT.aws_cache_put — Method
aws_cache_put(cache, key, p_value)

Puts p_value at key. If an element is already stored at key it will be replaced. If the cache is already full, an item will be removed based on the cache policy.

Prototype

int aws_cache_put(struct aws_cache *cache, const void *key, void *p_value);
source
LibAWSCRT.aws_cache_remove — Method
aws_cache_remove(cache, key)

Removes item at key from the cache.

Prototype

int aws_cache_remove(struct aws_cache *cache, const void *key);
source
LibAWSCRT.aws_channel_acquire_hold — Method
aws_channel_acquire_hold(channel)

Prevent a channel's memory from being freed. Any number of users may acquire a hold to prevent a channel and its handlers from being unexpectedly freed. Any user which acquires a hold must release it via aws_channel_release_hold(). Memory will be freed once all holds are released and aws_channel_destroy() has been called.

Prototype

void aws_channel_acquire_hold(struct aws_channel *channel);
source
LibAWSCRT.aws_channel_acquire_message_from_pool — Method
aws_channel_acquire_message_from_pool(channel, message_type, size_hint)

Acquires a message from the event loop's message pool. size_hint is merely a hint, it may be smaller than you requested and you are responsible for checking the bounds of it. If the returned message is not large enough, you must send multiple messages.

Prototype

struct aws_io_message *aws_channel_acquire_message_from_pool( struct aws_channel *channel, enum aws_io_message_type message_type, size_t size_hint);
source
LibAWSCRT.aws_channel_current_clock_time — Method
aws_channel_current_clock_time(channel, time_nanos)

Fetches the current timestamp from the event-loop's clock, in nanoseconds.

Prototype

int aws_channel_current_clock_time(struct aws_channel *channel, uint64_t *time_nanos);
source
LibAWSCRT.aws_channel_fetch_local_object — Method
aws_channel_fetch_local_object(channel, key, obj)

Retrieves an object by key from the event loop's local storage.

Prototype

int aws_channel_fetch_local_object( struct aws_channel *channel, const void *key, struct aws_event_loop_local_object *obj);
source
LibAWSCRT.aws_channel_get_event_loop — Method
aws_channel_get_event_loop(channel)

Fetches the event loop the channel is a part of.

Prototype

struct aws_event_loop *aws_channel_get_event_loop(struct aws_channel *channel);
source
LibAWSCRT.aws_channel_handler_increment_read_window — Method
aws_channel_handler_increment_read_window(handler, slot, size)

Calls on_window_update on handler's vtable.

Prototype

int aws_channel_handler_increment_read_window( struct aws_channel_handler *handler, struct aws_channel_slot *slot, size_t size);
source
LibAWSCRT.aws_channel_handler_process_read_message — Method
aws_channel_handler_process_read_message(handler, slot, message)

Calls process_read_message on handler's vtable

Prototype

int aws_channel_handler_process_read_message( struct aws_channel_handler *handler, struct aws_channel_slot *slot, struct aws_io_message *message);
source
LibAWSCRT.aws_channel_handler_process_write_message — Method
aws_channel_handler_process_write_message(handler, slot, message)

Calls process_write_message on handler's vtable.

Prototype

int aws_channel_handler_process_write_message( struct aws_channel_handler *handler, struct aws_channel_slot *slot, struct aws_io_message *message);
source
LibAWSCRT.aws_channel_handler_shutdown — Method
aws_channel_handler_shutdown(handler, slot, dir, error_code, free_scarce_resources_immediately)

calls shutdown_direction on handler's vtable.

Prototype

int aws_channel_handler_shutdown( struct aws_channel_handler *handler, struct aws_channel_slot *slot, enum aws_channel_direction dir, int error_code, bool free_scarce_resources_immediately);
source
LibAWSCRT.aws_channel_new — Method
aws_channel_new(allocator, creation_args)

Allocates new channel, Unless otherwise specified all functions for channels and channel slots must be executed within that channel's event-loop's thread. channel_options are copied.

Prototype

struct aws_channel *aws_channel_new(struct aws_allocator *allocator, const struct aws_channel_options *creation_args);
source
LibAWSCRT.aws_channel_put_local_object — Method
aws_channel_put_local_object(channel, key, obj)

Stores an object by key in the event loop's local storage.

Prototype

int aws_channel_put_local_object( struct aws_channel *channel, const void *key, const struct aws_event_loop_local_object *obj);
source
LibAWSCRT.aws_channel_remove_local_object — Method
aws_channel_remove_local_object(channel, key, removed_obj)

Removes an object by key from the event loop's local storage.

Prototype

int aws_channel_remove_local_object( struct aws_channel *channel, const void *key, struct aws_event_loop_local_object *removed_obj);
source
LibAWSCRT.aws_channel_schedule_task_future — Method
aws_channel_schedule_task_future(channel, task, run_at_nanos)

Schedules a task to run on the event loop at the specified time. This is the ideal way to move a task into the correct thread. It's also handy for context switches. Use aws_channel_current_clock_time() to get the current time in nanoseconds. This function is safe to call from any thread.

The task should not be cleaned up or modified until its function is executed.

Prototype

void aws_channel_schedule_task_future( struct aws_channel *channel, struct aws_channel_task *task, uint64_t run_at_nanos);
source
LibAWSCRT.aws_channel_schedule_task_now — Method
aws_channel_schedule_task_now(channel, task)

Schedules a task to run on the event loop as soon as possible. This is the ideal way to move a task into the correct thread. It's also handy for context switches. This function is safe to call from any thread.

If called from the channel's event loop, the task will get directly added to the run-now list. If called from outside the channel's event loop, the task will go into a cross-thread task queue.

If tasks must be serialized relative to some source synchronization, you may not want to use this API because tasks submitted from the event loop thread can "jump ahead" of tasks submitted from external threads due to this optimization. If this is a problem, you can either refactor your submission logic or use the aws_channel_schedule_task_now_serialized variant which does not perform this optimization.

The task should not be cleaned up or modified until its function is executed.

Prototype

void aws_channel_schedule_task_now(struct aws_channel *channel, struct aws_channel_task *task);
source
LibAWSCRT.aws_channel_schedule_task_now_serialized — Method
aws_channel_schedule_task_now_serialized(channel, task)

Schedules a task to run on the event loop as soon as possible.

This variant always uses the cross thread queue rather than conditionally skipping it when already in the destination event loop. While not "optimal", this allows us to serialize task execution no matter where the task was submitted from: if you are submitting tasks from a critical section, the serialized order that you submit is guaranteed to be the order that they execute on the event loop.

The task should not be cleaned up or modified until its function is executed.

Prototype

void aws_channel_schedule_task_now_serialized(struct aws_channel *channel, struct aws_channel_task *task);
source
LibAWSCRT.aws_channel_set_statistics_handler — Method
aws_channel_set_statistics_handler(channel, handler)

Instrument a channel with a statistics handler. While instrumented with a statistics handler, the channel will periodically report per-channel-handler-specific statistics about handler performance and state.

Assigning a statistics handler to a channel is a transfer of ownership – the channel will clean up the handler appropriately. Statistics handlers may be changed dynamically (for example, the upgrade from a vanilla http channel to a websocket channel), but this function may only be called from the event loop thread that the channel is a part of.

The first possible hook to set a statistics handler is the channel's creation callback.

Prototype

int aws_channel_set_statistics_handler(struct aws_channel *channel, struct aws_crt_statistics_handler *handler);
source
LibAWSCRT.aws_channel_setup_client_tls — Method
aws_channel_setup_client_tls(right_of_slot, tls_options)

******************************* Misc TLS related ********************************

Prototype

int aws_channel_setup_client_tls( struct aws_channel_slot *right_of_slot, struct aws_tls_connection_options *tls_options);
source
LibAWSCRT.aws_channel_shutdown — Method
aws_channel_shutdown(channel, error_code)

Initiates shutdown of the channel. Shutdown will begin with the left-most slot. Each handler will invoke 'aws_channel_slot_on_handler_shutdown_complete' once they've finished their shutdown process for the read direction. Once the right-most slot has shutdown in the read direction, the process will start shutting down starting on the right-most slot. Once the left-most slot has shutdown in the write direction, 'callbacks->shutdown_completed' will be invoked in the event loop's thread.

This function can be called from any thread.

Prototype

int aws_channel_shutdown(struct aws_channel *channel, int error_code);
source
LibAWSCRT.aws_channel_slot_downstream_read_window — Method
aws_channel_slot_downstream_read_window(slot)

Fetches the downstream read window. This gives you the information necessary to honor the read window. If you call send_message() and it exceeds this window, the message will be rejected.

Prototype

size_t aws_channel_slot_downstream_read_window(struct aws_channel_slot *slot);
source
LibAWSCRT.aws_channel_slot_increment_read_window — Method
aws_channel_slot_increment_read_window(slot, window)

Issues a window update notification upstream (to the left.)

Prototype

int aws_channel_slot_increment_read_window(struct aws_channel_slot *slot, size_t window);
source
LibAWSCRT.aws_channel_slot_insert_end — Method
aws_channel_slot_insert_end(channel, to_add)

Inserts to 'to_add' the end of the channel. Note that the first call to aws_channel_slot_new() adds it to the channel implicitly.

Prototype

int aws_channel_slot_insert_end(struct aws_channel *channel, struct aws_channel_slot *to_add);
source
LibAWSCRT.aws_channel_slot_insert_left — Method
aws_channel_slot_insert_left(slot, to_add)

inserts 'to_add' to the position immediately to the left of slot. Note that the first call to aws_channel_slot_new() adds it to the channel implicitly.

Prototype

int aws_channel_slot_insert_left(struct aws_channel_slot *slot, struct aws_channel_slot *to_add);
source
LibAWSCRT.aws_channel_slot_insert_right — Method
aws_channel_slot_insert_right(slot, to_add)

inserts 'to_add' to the position immediately to the right of slot. Note that the first call to aws_channel_slot_new() adds it to the channel implicitly.

Prototype

int aws_channel_slot_insert_right(struct aws_channel_slot *slot, struct aws_channel_slot *to_add);
source
LibAWSCRT.aws_channel_slot_new — Method
aws_channel_slot_new(channel)

Allocates and initializes a new slot for use with the channel. If this is the first slot in the channel, it will automatically be added to the channel as the first slot. For all subsequent calls on a given channel, the slot will need to be added to the channel via. the aws_channel_slot_insert_right(), aws_channel_slot_insert_end(), and aws_channel_slot_insert_left() APIs.

Prototype

struct aws_channel_slot *aws_channel_slot_new(struct aws_channel *channel);
source
LibAWSCRT.aws_channel_slot_on_handler_shutdown_complete — Method
aws_channel_slot_on_handler_shutdown_complete(slot, dir, err_code, free_scarce_resources_immediately)

Called by handlers once they have finished their shutdown in the 'dir' direction. Propagates the shutdown process to the next handler in the channel.

Prototype

int aws_channel_slot_on_handler_shutdown_complete( struct aws_channel_slot *slot, enum aws_channel_direction dir, int err_code, bool free_scarce_resources_immediately);
source
LibAWSCRT.aws_channel_slot_remove — Method
aws_channel_slot_remove(slot)

Removes slot from the channel and deallocates the slot and its handler.

Prototype

int aws_channel_slot_remove(struct aws_channel_slot *slot);
source
LibAWSCRT.aws_channel_slot_replace — Method
aws_channel_slot_replace(remove, new_slot)

Replaces remove with new_slot. Deallocates remove and its handler.

Prototype

int aws_channel_slot_replace(struct aws_channel_slot *remove, struct aws_channel_slot *new_slot);
source
LibAWSCRT.aws_channel_slot_send_message — Method
aws_channel_slot_send_message(slot, message, dir)

Sends a message to the adjacent slot in the channel based on dir. Also does window size checking.

NOTE: if this function returns an error code, it is the caller's responsibility to release message back to the pool. If this function returns AWS_OP_SUCCESS, the recipient of the message has taken ownership of the message. So, for example, don't release a message to the pool and then return an error. If you encounter an error condition in this case, shutdown the channel with the appropriate error code.

Prototype

int aws_channel_slot_send_message( struct aws_channel_slot *slot, struct aws_io_message *message, enum aws_channel_direction dir);
source
LibAWSCRT.aws_channel_slot_set_handler — Method
aws_channel_slot_set_handler(slot, handler)

Sets the handler for a slot, the slot will also call get_current_window_size() and propagate a window update upstream.

Prototype

int aws_channel_slot_set_handler(struct aws_channel_slot *slot, struct aws_channel_handler *handler);
source
LibAWSCRT.aws_channel_slot_shutdown — Method
aws_channel_slot_shutdown(slot, dir, err_code, free_scarce_resources_immediately)

Initiates shutdown on slot. callbacks->on_shutdown_completed will be called once the shutdown process is completed.

Prototype

int aws_channel_slot_shutdown( struct aws_channel_slot *slot, enum aws_channel_direction dir, int err_code, bool free_scarce_resources_immediately);
source
LibAWSCRT.aws_channel_slot_upstream_message_overhead — Method
aws_channel_slot_upstream_message_overhead(slot)

Fetches the current overhead of upstream handlers. This provides a hint to avoid fragmentation if you care.

Prototype

size_t aws_channel_slot_upstream_message_overhead(struct aws_channel_slot *slot);
source
LibAWSCRT.aws_channel_task_init — Method
aws_channel_task_init(channel_task, task_fn, arg, type_tag)

Initializes channel_task for use.

Prototype

void aws_channel_task_init( struct aws_channel_task *channel_task, aws_channel_task_fn *task_fn, void *arg, const char *type_tag);
source
LibAWSCRT.aws_channel_thread_is_callers_thread — Method
aws_channel_thread_is_callers_thread(channel)

Returns true if the caller is on the event loop's thread. If false, you likely need to use aws_channel_schedule_task(). This function is safe to call from any thread.

Prototype

bool aws_channel_thread_is_callers_thread(struct aws_channel *channel);
source
LibAWSCRT.aws_channel_trigger_read — Method
aws_channel_trigger_read(channel)

A way for external processes to force a read by the data-source channel handler. Necessary in certain cases, like when a server channel finishes setting up its initial handlers, a read may have already been triggered on the socket (the client's CLIENT_HELLO tls payload, for example) and absent further data/notifications, this data would never get processed.

Prototype

int aws_channel_trigger_read(struct aws_channel *channel);
source
LibAWSCRT.aws_checksums_crc32 — Method
aws_checksums_crc32(input, length, previousCrc32)

The entry point function to perform a CRC32 (Ethernet, gzip) computation. Selects a suitable implementation based on hardware capabilities. Pass 0 in the previousCrc32 parameter as an initial value unless continuing to update a running crc in a subsequent call.

Prototype

uint32_t aws_checksums_crc32(const uint8_t *input, int length, uint32_t previousCrc32);
source
LibAWSCRT.aws_checksums_crc32c — Method
aws_checksums_crc32c(input, length, previousCrc32)

The entry point function to perform a Castagnoli CRC32c (iSCSI) computation. Selects a suitable implementation based on hardware capabilities. Pass 0 in the previousCrc32 parameter as an initial value unless continuing to update a running crc in a subsequent call.

Prototype

uint32_t aws_checksums_crc32c(const uint8_t *input, int length, uint32_t previousCrc32);
source
LibAWSCRT.aws_cli_dispatch_on_subcommand — Method
aws_cli_dispatch_on_subcommand(argc, argv, dispatch_table, table_length, user_data)

Dispatches the current command line arguments with a subcommand from the second input argument in argv[], if dispatch table contains a command that matches the argument. When the command is dispatched, argc and argv will be updated to reflect the new argument count. The cli options are required to come after the subcommand. If either, no dispatch was found or there was no argument passed to the program, this function will return AWS_OP_ERR. Check aws_last_error() for details on the error.

Parameters

  • argc: number of arguments passed to int main()
  • argv: the arguments passed to int main()
  • parse_cb,: optional, specify NULL if you don't want to handle this. This argument is for parsing "meta" commands from the command line options prior to dispatch occurring.
  • dispatch_table: table containing functions and command name to dispatch on.
  • table_length: number of entries in dispatch_table.

Returns

AWS_OP_SUCCESS(0) on success, AWS_OP_ERR(-1) on failure

Prototype

int aws_cli_dispatch_on_subcommand( int argc, char *const argv[], struct aws_cli_subcommand_dispatch *dispatch_table, int table_length, void *user_data);
source
LibAWSCRT.aws_cli_getopt_long — Method
aws_cli_getopt_long(argc, argv, optstring, longopts, longindex)

A mostly compliant implementation of posix getopt_long(). Parses command-line arguments. argc is the number of command line arguments passed in argv. optstring contains the legitimate option characters. The option characters correspond to aws_cli_option::val. If the character is followed by a :, the option requires an argument. If it is followed by '::', the argument is optional (not implemented yet).

longopts, is an array of struct aws_cli_option. These are the allowed options for the program. The last member of the array must be zero initialized.

If longindex is non-null, it will be set to the index in longopts, for the found option.

Returns option val if it was found, '?' if an option was encountered that was not specified in the option string, 0x02 (START_OF_TEXT) will be returned if a positional argument was encountered. returns -1 when all arguments that can be parsed have been parsed.

Prototype

int aws_cli_getopt_long( int argc, char *const argv[], const char *optstring, const struct aws_cli_option *longopts, int *longindex);
source
LibAWSCRT.aws_cli_reset_state — Method
aws_cli_reset_state()

Resets global parser state for use in another parser run for the application.

Prototype

void aws_cli_reset_state(void);
source
LibAWSCRT.aws_client_bootstrap_acquire — Method
aws_client_bootstrap_acquire(bootstrap)

Increments a client bootstrap's ref count, allowing the caller to take a reference to it.

Returns the same client bootstrap passed in.

Prototype

struct aws_client_bootstrap *aws_client_bootstrap_acquire(struct aws_client_bootstrap *bootstrap);
source
LibAWSCRT.aws_client_bootstrap_new — Method
aws_client_bootstrap_new(allocator, options)

Create the client bootstrap.

Prototype

struct aws_client_bootstrap *aws_client_bootstrap_new( struct aws_allocator *allocator, const struct aws_client_bootstrap_options *options);
source
LibAWSCRT.aws_client_bootstrap_release — Method
aws_client_bootstrap_release(bootstrap)

Decrements a client bootstrap's ref count. When the ref count drops to zero, the bootstrap will be destroyed.

Prototype

void aws_client_bootstrap_release(struct aws_client_bootstrap *bootstrap);
source
LibAWSCRT.aws_client_bootstrap_set_alpn_callback — Method
aws_client_bootstrap_set_alpn_callback(bootstrap, on_protocol_negotiated)

When using TLS, if ALPN is used, this callback will be invoked from the channel. The returned handler will be added to the channel.

Prototype

int aws_client_bootstrap_set_alpn_callback( struct aws_client_bootstrap *bootstrap, aws_channel_on_protocol_negotiated_fn *on_protocol_negotiated);
source
LibAWSCRT.aws_clz_u32 — Method
aws_clz_u32(n)

Search from the MSB to LSB, looking for a 1

Prototype

AWS_STATIC_IMPL size_t aws_clz_u32(uint32_t n);
source
LibAWSCRT.aws_common_library_init — Method
aws_common_library_init(allocator)

Initializes internal data structures used by aws-c-common. Must be called before using any functionality in aws-c-common.

Prototype

void aws_common_library_init(struct aws_allocator *allocator);
source
LibAWSCRT.aws_compression_library_clean_up — Method
aws_compression_library_clean_up()

Clean up internal datastructures used by aws-c-compression. Must not be called until application is done using functionality in aws-c-compression.

Prototype

void aws_compression_library_clean_up(void);
source
LibAWSCRT.aws_compression_library_init — Method
aws_compression_library_init(alloc)

Initializes internal datastructures used by aws-c-compression. Must be called before using any functionality in aws-c-compression.

Prototype

void aws_compression_library_init(struct aws_allocator *alloc);
source
LibAWSCRT.aws_condition_variable_clean_up — Method
aws_condition_variable_clean_up(condition_variable)

Cleans up a condition variable.

Prototype

void aws_condition_variable_clean_up(struct aws_condition_variable *condition_variable);
source
LibAWSCRT.aws_condition_variable_init — Method
aws_condition_variable_init(condition_variable)

Initializes a condition variable.

Prototype

int aws_condition_variable_init(struct aws_condition_variable *condition_variable);
source
LibAWSCRT.aws_condition_variable_notify_all — Method
aws_condition_variable_notify_all(condition_variable)

Notifies/Wakes all waiting threads.

Prototype

int aws_condition_variable_notify_all(struct aws_condition_variable *condition_variable);
source
LibAWSCRT.aws_condition_variable_wait — Method
aws_condition_variable_wait(condition_variable, mutex)

Waits the calling thread on a notification from another thread.

Prototype

int aws_condition_variable_wait(struct aws_condition_variable *condition_variable, struct aws_mutex *mutex);
source
LibAWSCRT.aws_condition_variable_wait_for — Method
aws_condition_variable_wait_for(condition_variable, mutex, time_to_wait)

Waits the calling thread on a notification from another thread. Times out after time_to_wait. time_to_wait is in nanoseconds.

Prototype

int aws_condition_variable_wait_for( struct aws_condition_variable *condition_variable, struct aws_mutex *mutex, int64_t time_to_wait);
source
LibAWSCRT.aws_condition_variable_wait_for_pred — Method
aws_condition_variable_wait_for_pred(condition_variable, mutex, time_to_wait, pred, pred_ctx)

Waits the calling thread on a notification from another thread. Times out after time_to_wait. time_to_wait is in nanoseconds. If predicate returns false, the wait is reentered, otherwise control returns to the caller.

Prototype

int aws_condition_variable_wait_for_pred( struct aws_condition_variable *condition_variable, struct aws_mutex *mutex, int64_t time_to_wait, aws_condition_predicate_fn *pred, void *pred_ctx);
source
LibAWSCRT.aws_condition_variable_wait_pred — Method
aws_condition_variable_wait_pred(condition_variable, mutex, pred, pred_ctx)

Waits the calling thread on a notification from another thread. If predicate returns false, the wait is reentered, otherwise control returns to the caller.

Prototype

int aws_condition_variable_wait_pred( struct aws_condition_variable *condition_variable, struct aws_mutex *mutex, aws_condition_predicate_fn *pred, void *pred_ctx);
source
LibAWSCRT.aws_cpu_has_feature — Method
aws_cpu_has_feature(feature_name)

Returns true if a cpu feature is supported, false otherwise.

Prototype

bool aws_cpu_has_feature(enum aws_cpu_feature_name feature_name);
source
LibAWSCRT.aws_credentials_acquire — Method
aws_credentials_acquire(credentials)

Add a reference to some credentials

Parameters

  • credentials: credentials to increment the ref count on

Prototype

void aws_credentials_acquire(const struct aws_credentials *credentials);
source
LibAWSCRT.aws_credentials_get_access_key_id — Method
aws_credentials_get_access_key_id(credentials)

Get the AWS access key id from a set of credentials

Parameters

  • credentials: credentials to get the access key id from

Returns

a byte cursor to the access key id

Prototype

struct aws_byte_cursor aws_credentials_get_access_key_id(const struct aws_credentials *credentials);
source
LibAWSCRT.aws_credentials_get_ecc_key_pair — Method
aws_credentials_get_ecc_key_pair(credentials)

Get the elliptic curve key associated with this set of credentials

Parameters

  • credentials: credentials to get the the elliptic curve key for

Returns

the elliptic curve key associated with the credentials, or NULL if no key is associated with these credentials

Prototype

struct aws_ecc_key_pair *aws_credentials_get_ecc_key_pair(const struct aws_credentials *credentials);
source
LibAWSCRT.aws_credentials_get_expiration_timepoint_seconds — Method
aws_credentials_get_expiration_timepoint_seconds(credentials)

Get the expiration timepoint (in seconds since epoch) associated with a set of credentials

Parameters

  • credentials: credentials to get the expiration timepoint for

Returns

the time, in seconds since epoch, the credentials will expire; UINT64_MAX for credentials without a specific expiration time

Prototype

uint64_t aws_credentials_get_expiration_timepoint_seconds(const struct aws_credentials *credentials);
source
LibAWSCRT.aws_credentials_get_secret_access_key — Method
aws_credentials_get_secret_access_key(credentials)

Get the AWS secret access key from a set of credentials

Parameters

  • credentials: credentials to get the secret access key from

Returns

a byte cursor to the secret access key

Prototype

struct aws_byte_cursor aws_credentials_get_secret_access_key(const struct aws_credentials *credentials);
source
LibAWSCRT.aws_credentials_get_session_token — Method
aws_credentials_get_session_token(credentials)

Get the AWS session token from a set of credentials

Parameters

  • credentials: credentials to get the session token from

Returns

a byte cursor to the session token or an empty byte cursor if there is no session token

Prototype

struct aws_byte_cursor aws_credentials_get_session_token(const struct aws_credentials *credentials);
source
LibAWSCRT.aws_credentials_is_anonymous — Method
aws_credentials_is_anonymous(credentials)

If credentials are anonymous, then the signing process is skipped.

Parameters

  • credentials: credentials to check

Returns

true if the credentials are anonymous; false otherwise.

Prototype

bool aws_credentials_is_anonymous(const struct aws_credentials *credentials);
source
LibAWSCRT.aws_credentials_new — Method
aws_credentials_new(allocator, access_key_id_cursor, secret_access_key_cursor, session_token_cursor, expiration_timepoint_seconds)

Creates a new set of aws credentials

Parameters

  • allocator: memory allocator to use
  • access_key_id_cursor: value for the aws access key id field
  • secret_access_key_cursor: value for the secret access key field
  • session_token_cursor: (optional) security token associated with the credentials
  • expiration_timepoint_seconds: timepoint, in seconds since epoch, that the credentials will no longer be valid past. For credentials that do not expire, use UINT64_MAX

Returns

a valid credentials object, or NULL

Prototype

struct aws_credentials *aws_credentials_new( struct aws_allocator *allocator, struct aws_byte_cursor access_key_id_cursor, struct aws_byte_cursor secret_access_key_cursor, struct aws_byte_cursor session_token_cursor, uint64_t expiration_timepoint_seconds);
source
LibAWSCRT.aws_credentials_new_anonymous — Method
aws_credentials_new_anonymous(allocator)

Creates a new set of aws anonymous credentials. Use Anonymous credentials, when you want to skip the signing process.

Parameters

  • allocator: memory allocator to use

Returns

a valid credentials object, or NULL

Prototype

struct aws_credentials *aws_credentials_new_anonymous(struct aws_allocator *allocator);
source
LibAWSCRT.aws_credentials_new_ecc — Method
aws_credentials_new_ecc(allocator, access_key_id, ecc_key, session_token, expiration_timepoint_in_seconds)

Creates a set of AWS credentials that includes an ECC key pair. These credentials do not have a value for the secret access key; the ecc key takes over that field's role in sigv4a signing.

Parameters

  • allocator: memory allocator to use for all memory allocation
  • access_key_id: access key id for the credential set
  • ecc_key: ecc key to use during signing when using these credentials
  • session_token: (optional) session token associated with the credentials
  • expiration_timepoint_in_seconds: (optional) if session-based, time at which these credentials expire

Returns

a new pair of AWS credentials, or NULL

Prototype

struct aws_credentials *aws_credentials_new_ecc( struct aws_allocator *allocator, struct aws_byte_cursor access_key_id, struct aws_ecc_key_pair *ecc_key, struct aws_byte_cursor session_token, uint64_t expiration_timepoint_in_seconds);
source
LibAWSCRT.aws_credentials_new_from_string — Method
aws_credentials_new_from_string(allocator, access_key_id, secret_access_key, session_token, expiration_timepoint_seconds)

Creates a new set of AWS credentials

Parameters

  • allocator: memory allocator to use
  • access_key_id: value for the aws access key id field
  • secret_access_key: value for the secret access key field
  • session_token: (optional) security token associated with the credentials
  • expiration_timepoint_seconds: timepoint, in seconds since epoch, that the credentials will no longer be valid past. For credentials that do not expire, use UINT64_MAX

Returns

a valid credentials object, or NULL

Prototype

struct aws_credentials *aws_credentials_new_from_string( struct aws_allocator *allocator, const struct aws_string *access_key_id, const struct aws_string *secret_access_key, const struct aws_string *session_token, uint64_t expiration_timepoint_seconds);
source
LibAWSCRT.aws_credentials_provider_get_credentials — Method
aws_credentials_provider_get_credentials(provider, callback, user_data)

Prototype

int aws_credentials_provider_get_credentials( struct aws_credentials_provider *provider, aws_on_get_credentials_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_credentials_provider_new_anonymous — Method
aws_credentials_provider_new_anonymous(allocator, shutdown_options)

Creates a simple anonymous credentials provider

Parameters

  • allocator: memory allocator to use for all memory allocation
  • shutdown_options: an optional shutdown callback that gets invoked when the resources used by the provider are no longer in use.

Returns

the newly-constructed credentials provider, or NULL if an error occurred.

Prototype

struct aws_credentials_provider *aws_credentials_provider_new_anonymous( struct aws_allocator *allocator, const struct aws_credentials_provider_shutdown_options *shutdown_options);
source
LibAWSCRT.aws_credentials_provider_new_cached — Method
aws_credentials_provider_new_cached(allocator, options)

Creates a provider that functions as a caching decorating of another provider.

For example, the default chain is implemented as:

CachedProvider -> ProviderChain(EnvironmentProvider -> ProfileProvider -> ECS/EC2IMD etc...)

A reference is taken on the target provider

Parameters

  • allocator: memory allocator to use for all memory allocation
  • options: provider-specific configuration options

Returns

the newly-constructed credentials provider, or NULL if an error occurred.

Prototype

struct aws_credentials_provider *aws_credentials_provider_new_cached( struct aws_allocator *allocator, const struct aws_credentials_provider_cached_options *options);
source
LibAWSCRT.aws_credentials_provider_new_chain — Method
aws_credentials_provider_new_chain(allocator, options)

Creates a provider that sources credentials from an ordered sequence of providers, with the overall result being from the first provider to return a valid set of credentials

References are taken on all supplied providers

Parameters

  • allocator: memory allocator to use for all memory allocation
  • options: provider-specific configuration options

Returns

the newly-constructed credentials provider, or NULL if an error occurred.

Prototype

struct aws_credentials_provider *aws_credentials_provider_new_chain( struct aws_allocator *allocator, const struct aws_credentials_provider_chain_options *options);
source
LibAWSCRT.aws_credentials_provider_new_chain_default — Method
aws_credentials_provider_new_chain_default(allocator, options)

Creates the default provider chain used by most AWS SDKs.

Generally:

(1) Environment (2) Profile (3) STS web identity (4) (conditional, off by default) ECS (5) (conditional, on by default) EC2 Instance Metadata

Support for environmental control of the default provider chain is not yet implemented.

Parameters

  • allocator: memory allocator to use for all memory allocation
  • options: provider-specific configuration options

Returns

the newly-constructed credentials provider, or NULL if an error occurred.

Prototype

struct aws_credentials_provider *aws_credentials_provider_new_chain_default( struct aws_allocator *allocator, const struct aws_credentials_provider_chain_default_options *options);
source
LibAWSCRT.aws_credentials_provider_new_cognito — Method
aws_credentials_provider_new_cognito(allocator, options)

Creates a provider that sources credentials from the Cognito-Identity service via an invocation of the GetCredentialsForIdentity API call.

Parameters

  • allocator: memory allocator to use for all memory allocation
  • options: provider-specific configuration options

Returns

the newly-constructed credentials provider, or NULL if an error occurred.

Prototype

struct aws_credentials_provider *aws_credentials_provider_new_cognito( struct aws_allocator *allocator, const struct aws_credentials_provider_cognito_options *options);
source
LibAWSCRT.aws_credentials_provider_new_cognito_caching — Method
aws_credentials_provider_new_cognito_caching(allocator, options)

Creates a cognito-based provider that has a caching layer wrapped around it

Parameters

  • allocator: memory allocator to use for all memory allocation
  • options: cognito-specific configuration options

Returns

the newly-constructed credentials provider, or NULL if an error occurred.

Prototype

struct aws_credentials_provider *aws_credentials_provider_new_cognito_caching( struct aws_allocator *allocator, const struct aws_credentials_provider_cognito_options *options);
source
LibAWSCRT.aws_credentials_provider_new_delegate — Method
aws_credentials_provider_new_delegate(allocator, options)

Create a credentials provider depends on provided vtable to fetch the credentials.

Parameters

  • allocator: memory allocator to use for all memory allocation
  • options: provider-specific configuration options

Returns

the newly-constructed credentials provider, or NULL if an error occurred.

Prototype

struct aws_credentials_provider *aws_credentials_provider_new_delegate( struct aws_allocator *allocator, const struct aws_credentials_provider_delegate_options *options);
source
LibAWSCRT.aws_credentials_provider_new_ecs — Method
aws_credentials_provider_new_ecs(allocator, options)

Creates a provider that sources credentials from the ecs role credentials service

Parameters

  • allocator: memory allocator to use for all memory allocation
  • options: provider-specific configuration options

Returns

the newly-constructed credentials provider, or NULL if an error occurred.

Prototype

struct aws_credentials_provider *aws_credentials_provider_new_ecs( struct aws_allocator *allocator, const struct aws_credentials_provider_ecs_options *options);
source
LibAWSCRT.aws_credentials_provider_new_environment — Method
aws_credentials_provider_new_environment(allocator, options)

Creates a provider that returns credentials sourced from the environment variables:

AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN

Parameters

  • allocator: memory allocator to use for all memory allocation
  • options: provider-specific configuration options

Returns

the newly-constructed credentials provider, or NULL if an error occurred.

Prototype

struct aws_credentials_provider *aws_credentials_provider_new_environment( struct aws_allocator *allocator, const struct aws_credentials_provider_environment_options *options);
source
LibAWSCRT.aws_credentials_provider_new_imds — Method
aws_credentials_provider_new_imds(allocator, options)

Creates a provider that sources credentials from the ec2 instance metadata service

Parameters

  • allocator: memory allocator to use for all memory allocation
  • options: provider-specific configuration options

Returns

the newly-constructed credentials provider, or NULL if an error occurred.

Prototype

struct aws_credentials_provider *aws_credentials_provider_new_imds( struct aws_allocator *allocator, const struct aws_credentials_provider_imds_options *options);
source
LibAWSCRT.aws_credentials_provider_new_process — Method
aws_credentials_provider_new_process(allocator, options)

Prototype

struct aws_credentials_provider *aws_credentials_provider_new_process( struct aws_allocator *allocator, const struct aws_credentials_provider_process_options *options);
source
LibAWSCRT.aws_credentials_provider_new_profile — Method
aws_credentials_provider_new_profile(allocator, options)

Creates a provider that sources credentials from key-value profiles loaded from the aws credentials file ("~/.aws/credentials" by default) and the aws config file ("~/.aws/config" by default)

Parameters

  • allocator: memory allocator to use for all memory allocation
  • options: provider-specific configuration options

Returns

the newly-constructed credentials provider, or NULL if an error occurred.

Prototype

struct aws_credentials_provider *aws_credentials_provider_new_profile( struct aws_allocator *allocator, const struct aws_credentials_provider_profile_options *options);
source
LibAWSCRT.aws_credentials_provider_new_sso — Method
aws_credentials_provider_new_sso(allocator, options)

Creates a provider that sources credentials from SSO using a SSOToken.

Parameters

  • allocator: memory allocator to use for all memory allocation
  • options: provider-specific configuration options

Returns

the newly-constructed credentials provider, or NULL if an error occurred.

Prototype

struct aws_credentials_provider *aws_credentials_provider_new_sso( struct aws_allocator *allocator, const struct aws_credentials_provider_sso_options *options);
source
LibAWSCRT.aws_credentials_provider_new_static — Method
aws_credentials_provider_new_static(allocator, options)

Creates a simple provider that just returns a fixed set of credentials

Parameters

  • allocator: memory allocator to use for all memory allocation
  • options: provider-specific configuration options

Returns

the newly-constructed credentials provider, or NULL if an error occurred.

Prototype

struct aws_credentials_provider *aws_credentials_provider_new_static( struct aws_allocator *allocator, const struct aws_credentials_provider_static_options *options);
source
LibAWSCRT.aws_credentials_provider_new_sts — Method
aws_credentials_provider_new_sts(allocator, options)

Creates a provider that assumes an IAM role via. STS AssumeRole() API. This provider will fetch new credentials upon each call to aws_credentials_provider_get_credentials().

Parameters

  • allocator: memory allocator to use for all memory allocation
  • options: provider-specific configuration options

Returns

the newly-constructed credentials provider, or NULL if an error occurred.

Prototype

struct aws_credentials_provider *aws_credentials_provider_new_sts( struct aws_allocator *allocator, const struct aws_credentials_provider_sts_options *options);
source
LibAWSCRT.aws_credentials_provider_new_sts_web_identity — Method
aws_credentials_provider_new_sts_web_identity(allocator, options)

Creates a provider that sources credentials from STS using AssumeRoleWithWebIdentity

Parameters

  • allocator: memory allocator to use for all memory allocation
  • options: provider-specific configuration options

Returns

the newly-constructed credentials provider, or NULL if an error occurred.

Prototype

struct aws_credentials_provider *aws_credentials_provider_new_sts_web_identity( struct aws_allocator *allocator, const struct aws_credentials_provider_sts_web_identity_options *options);
source
LibAWSCRT.aws_credentials_provider_new_x509 — Method
aws_credentials_provider_new_x509(allocator, options)

Creates a provider that sources credentials from IoT Core

Parameters

  • allocator: memory allocator to use for all memory allocation
  • options: provider-specific configuration options

Returns

the newly-constructed credentials provider, or NULL if an error occurred.

Prototype

struct aws_credentials_provider *aws_credentials_provider_new_x509( struct aws_allocator *allocator, const struct aws_credentials_provider_x509_options *options);
source
LibAWSCRT.aws_credentials_provider_release — Method
aws_credentials_provider_release(provider)

Release a reference to a credentials provider

Parameters

  • provider: provider to decrement the ref count on

Prototype

struct aws_credentials_provider *aws_credentials_provider_release(struct aws_credentials_provider *provider);
source
LibAWSCRT.aws_credentials_release — Method
aws_credentials_release(credentials)

Remove a reference to some credentials

Parameters

  • credentials: credentials to decrement the ref count on

Prototype

void aws_credentials_release(const struct aws_credentials *credentials);
source
LibAWSCRT.aws_crt_statistics_handler_destroy — Method
aws_crt_statistics_handler_destroy(handler)

completely destroys a statistics handler. The handler's cleanup function must clean up the impl portion completely (including its allocation, if done separately).

Prototype

void aws_crt_statistics_handler_destroy(struct aws_crt_statistics_handler *handler);
source
LibAWSCRT.aws_crt_statistics_handler_get_report_interval_ms — Method
aws_crt_statistics_handler_get_report_interval_ms(handler)

Queries the frequency (via an interval in milliseconds) which a statistics handler would like to be informed of statistics.

Prototype

uint64_t aws_crt_statistics_handler_get_report_interval_ms(struct aws_crt_statistics_handler *handler);
source
LibAWSCRT.aws_crt_statistics_handler_process_statistics — Method
aws_crt_statistics_handler_process_statistics(handler, interval, stats, context)

Submits a list of statistics objects to a statistics handler for processing

handler - the statistics handler that will process the statistics objects interval - time period over which the statistics were gathered stats - list of pointers to structures that can be case to aws_crt_statistics_base (i.e. have category as a first member) context - (optional) additional context specific to where the statistics handler has been attached

Prototype

void aws_crt_statistics_handler_process_statistics( struct aws_crt_statistics_handler *handler, struct aws_crt_statistics_sample_interval *interval, struct aws_array_list *stats, void *context);
source
LibAWSCRT.aws_crt_statistics_http1_channel_reset — Method
aws_crt_statistics_http1_channel_reset(stats)

Resets a http channel handler statistics struct's statistics

Prototype

void aws_crt_statistics_http1_channel_reset(struct aws_crt_statistics_http1_channel *stats);
source
LibAWSCRT.aws_crt_statistics_http2_channel_reset — Method
aws_crt_statistics_http2_channel_reset(stats)

Resets a HTTP/2 channel handler statistics struct's statistics

Prototype

void aws_crt_statistics_http2_channel_reset(struct aws_crt_statistics_http2_channel *stats);
source
LibAWSCRT.aws_crt_statistics_socket_reset — Method
aws_crt_statistics_socket_reset(stats)

Resets socket channel handler statistics for the next gather interval. Calculate-once results are left alone.

Prototype

void aws_crt_statistics_socket_reset(struct aws_crt_statistics_socket *stats);
source
LibAWSCRT.aws_crt_statistics_tls_reset — Method
aws_crt_statistics_tls_reset(stats)

Resets tls channel handler statistics for the next gather interval. Calculate-once results are left alone.

Prototype

void aws_crt_statistics_tls_reset(struct aws_crt_statistics_tls *stats);
source
LibAWSCRT.aws_ctz_u32 — Method
aws_ctz_u32(n)

Search from the LSB to MSB, looking for a 1

Prototype

AWS_STATIC_IMPL size_t aws_ctz_u32(uint32_t n);
source
LibAWSCRT.aws_date_time_diff — Method
aws_date_time_diff(a, b)

returns the difference of a and b (a - b) in seconds.

Prototype

time_t aws_date_time_diff(const struct aws_date_time *a, const struct aws_date_time *b);
source
LibAWSCRT.aws_date_time_init_epoch_millis — Method
aws_date_time_init_epoch_millis(dt, ms_since_epoch)

Initializes dt to be the time represented in milliseconds since unix epoch.

Prototype

void aws_date_time_init_epoch_millis(struct aws_date_time *dt, uint64_t ms_since_epoch);
source
LibAWSCRT.aws_date_time_init_epoch_secs — Method
aws_date_time_init_epoch_secs(dt, sec_ms)

Initializes dt to be the time represented in seconds.millis since unix epoch.

Prototype

void aws_date_time_init_epoch_secs(struct aws_date_time *dt, double sec_ms);
source
LibAWSCRT.aws_date_time_init_from_str — Method
aws_date_time_init_from_str(dt, date_str, fmt)

Initializes dt to be the time represented by date_str in format 'fmt'. Returns AWS_OP_SUCCESS if the string was successfully parsed, returns AWS_OP_ERR if parsing failed.

Notes for AWS_DATE_FORMAT_RFC822: If no time zone information is provided, it is assumed to be local time (please don't do this).

If the time zone is something other than something indicating Universal Time (e.g. Z, UT, UTC, or GMT) or an offset from UTC (e.g. +0100, -0700), parsing will fail.

Really, it's just better if you always use Universal Time.

Prototype

int aws_date_time_init_from_str( struct aws_date_time *dt, const struct aws_byte_buf *date_str, enum aws_date_format fmt);
source
LibAWSCRT.aws_date_time_init_from_str_cursor — Method
aws_date_time_init_from_str_cursor(dt, date_str_cursor, fmt)

aws_date_time_init variant that takes a byte_cursor rather than a byte_buf

Prototype

int aws_date_time_init_from_str_cursor( struct aws_date_time *dt, const struct aws_byte_cursor *date_str_cursor, enum aws_date_format fmt);
source
LibAWSCRT.aws_date_time_month — Method
aws_date_time_month(dt, local_time)

Prototype

enum aws_date_month aws_date_time_month(const struct aws_date_time *dt, bool local_time);
source
LibAWSCRT.aws_date_time_to_local_time_short_str — Method
aws_date_time_to_local_time_short_str(dt, fmt, output_buf)

Copies the current time as a formatted short date string in local time into output_buf. If buffer is too small, it will return AWS_OP_ERR. A good size suggestion is AWS_DATE_TIME_STR_MAX_LEN bytes. AWS_DATE_FORMAT_AUTO_DETECT is not allowed.

Prototype

int aws_date_time_to_local_time_short_str( const struct aws_date_time *dt, enum aws_date_format fmt, struct aws_byte_buf *output_buf);
source
LibAWSCRT.aws_date_time_to_local_time_str — Method
aws_date_time_to_local_time_str(dt, fmt, output_buf)

Copies the current time as a formatted date string in local time into output_buf. If buffer is too small, it will return AWS_OP_ERR. A good size suggestion is AWS_DATE_TIME_STR_MAX_LEN bytes. AWS_DATE_FORMAT_AUTO_DETECT is not allowed.

Prototype

int aws_date_time_to_local_time_str( const struct aws_date_time *dt, enum aws_date_format fmt, struct aws_byte_buf *output_buf);
source
LibAWSCRT.aws_date_time_to_utc_time_short_str — Method
aws_date_time_to_utc_time_short_str(dt, fmt, output_buf)

Copies the current time as a formatted short date string in utc time into output_buf. If buffer is too small, it will return AWS_OP_ERR. A good size suggestion is AWS_DATE_TIME_STR_MAX_LEN bytes. AWS_DATE_FORMAT_AUTO_DETECT is not allowed.

Prototype

int aws_date_time_to_utc_time_short_str( const struct aws_date_time *dt, enum aws_date_format fmt, struct aws_byte_buf *output_buf);
source
LibAWSCRT.aws_date_time_to_utc_time_str — Method
aws_date_time_to_utc_time_str(dt, fmt, output_buf)

Copies the current time as a formatted date string in utc time into output_buf. If buffer is too small, it will return AWS_OP_ERR. A good size suggestion is AWS_DATE_TIME_STR_MAX_LEN bytes. AWS_DATE_FORMAT_AUTO_DETECT is not allowed.

Prototype

int aws_date_time_to_utc_time_str( const struct aws_date_time *dt, enum aws_date_format fmt, struct aws_byte_buf *output_buf);
source
LibAWSCRT.aws_decode_utf8 — Method
aws_decode_utf8(bytes, options)

Decode a complete string of UTF8/ASCII text. Text is always validated according to RFC-3629 (you may perform additional validation in the on_codepoint callback). The text does not need to begin with a UTF8 BOM. If you need to decode text incrementally as you receive it, use aws_utf8_decoder_new() instead.

Parameters

  • bytes: Text to decode.
  • options: Options for decoding. If NULL is passed, the text is simply validated.

Returns

AWS_OP_SUCCESS if successful. An error is raised if the text is not valid, or the on_codepoint callback raises an error.

Prototype

int aws_decode_utf8(struct aws_byte_cursor bytes, const struct aws_utf8_decoder_options *options);
source
LibAWSCRT.aws_default_dns_resolve — Method
aws_default_dns_resolve(allocator, host_name, output_addresses, user_data)

WARNING! do not call this function directly (getaddrinfo()): it blocks. Provide a pointer to this function for other resolution functions.

Prototype

int aws_default_dns_resolve( struct aws_allocator *allocator, const struct aws_string *host_name, struct aws_array_list *output_addresses, void *user_data);
source
LibAWSCRT.aws_device_random_buffer — Method
aws_device_random_buffer(output)

Fill the rest of a buffer with unpredictably random bytes, suitable for cryptographic use.

Prototype

int aws_device_random_buffer(struct aws_byte_buf *output);
source
LibAWSCRT.aws_device_random_buffer_append — Method
aws_device_random_buffer_append(output, n)

Write N unpredictably random bytes to a buffer, suitable for cryptographic use. If there is insufficient space in the buffer, AWS_ERROR_SHORT_BUFFER is raised and the buffer will be unchanged.

Prototype

int aws_device_random_buffer_append(struct aws_byte_buf *output, size_t n);
source
LibAWSCRT.aws_device_random_u16 — Method
aws_device_random_u16(output)

Get an unpredictably random 16bit number, suitable for cryptographic use.

Prototype

int aws_device_random_u16(uint16_t *output);
source
LibAWSCRT.aws_device_random_u32 — Method
aws_device_random_u32(output)

Get an unpredictably random 32bit number, suitable for cryptographic use.

Prototype

int aws_device_random_u32(uint32_t *output);
source
LibAWSCRT.aws_device_random_u64 — Method
aws_device_random_u64(output)

Get an unpredictably random 64bit number, suitable for cryptographic use.

Prototype

int aws_device_random_u64(uint64_t *output);
source
LibAWSCRT.aws_device_random_u8 — Method
aws_device_random_u8(output)

Get an unpredictably random 8bit number, suitable for cryptographic use.

Prototype

int aws_device_random_u8(uint8_t *output);
source
LibAWSCRT.aws_directory_create — Method
aws_directory_create(dir_path)

Creates a directory if it doesn't currently exist. If the directory already exists, it's ignored and assumed successful.

Returns AWS_OP_SUCCESS on success. Otherwise, check aws_last_error().

Prototype

int aws_directory_create(const struct aws_string *dir_path);
source
LibAWSCRT.aws_directory_delete — Method
aws_directory_delete(dir_path, recursive)

Deletes a directory. If the directory is not empty, this will fail unless the recursive parameter is set to true. If recursive is true then the entire directory and all of its contents will be deleted. If it is set to false, the directory will be deleted only if it is empty. Returns AWS_OP_SUCCESS if the operation was successful. Otherwise, aws_last_error() will contain the error that occurred. If the directory doesn't exist, AWS_OP_SUCCESS is still returned.

Prototype

int aws_directory_delete(const struct aws_string *dir_path, bool recursive);
source
LibAWSCRT.aws_directory_entry_iterator_get_value — Method
aws_directory_entry_iterator_get_value(iterator)

Gets the aws_directory_entry value for iterator at the current position. Returns NULL if the iterator contains no entries.

Prototype

const struct aws_directory_entry *aws_directory_entry_iterator_get_value( const struct aws_directory_iterator *iterator);
source
LibAWSCRT.aws_directory_entry_iterator_new — Method
aws_directory_entry_iterator_new(allocator, path)

Creates a read-only iterator of a directory starting at path. If path is invalid or there's any other error condition, NULL will be returned. Call aws_last_error() for the exact error in that case.

Prototype

struct aws_directory_iterator *aws_directory_entry_iterator_new( struct aws_allocator *allocator, const struct aws_string *path);
source
LibAWSCRT.aws_directory_exists — Method
aws_directory_exists(dir_path)

Returns true if the directory currently exists. Otherwise, it returns false.

Prototype

bool aws_directory_exists(const struct aws_string *dir_path);
source
LibAWSCRT.aws_directory_traverse — Method
aws_directory_traverse(allocator, path, recursive, on_entry, user_data)

Traverse a directory starting at path.

If you want the traversal to recurse the entire directory, pass recursive as true. Passing false for this parameter will only iterate the contents of the directory, but will not descend into any directories it encounters.

If recursive is set to true, the traversal is performed post-order, depth-first (for practical reasons such as deleting a directory that contains subdirectories or files).

returns AWS_OP_SUCCESS(0) on success.

Prototype

int aws_directory_traverse( struct aws_allocator *allocator, const struct aws_string *path, bool recursive, aws_on_directory_entry *on_entry, void *user_data);
source
LibAWSCRT.aws_ecc_curve_name_from_oid — Method
aws_ecc_curve_name_from_oid(oid, curve_name)

Get the curve name from the oid. OID here is the payload of the DER encoded ASN.1 part (doesn't include type specifier or length. On success, the value of curve_name will be set.

Prototype

int aws_ecc_curve_name_from_oid(struct aws_byte_cursor *oid, enum aws_ecc_curve_name *curve_name);
source
LibAWSCRT.aws_ecc_key_new_from_hex_coordinates — Method
aws_ecc_key_new_from_hex_coordinates(allocator, curve_name, pub_x_hex_cursor, pub_y_hex_cursor)

Creates an Elliptic curve public key from x and y coordinates encoded as hex strings Returns a new instance of aws_ecc_key_pair if the key was successfully built. Otherwise returns NULL.

Prototype

struct aws_ecc_key_pair *aws_ecc_key_new_from_hex_coordinates( struct aws_allocator *allocator, enum aws_ecc_curve_name curve_name, struct aws_byte_cursor pub_x_hex_cursor, struct aws_byte_cursor pub_y_hex_cursor);
source
LibAWSCRT.aws_ecc_key_pair_derive_public_key — Method
aws_ecc_key_pair_derive_public_key(key_pair)

Derives a public key from the private key if supported by this operating system (not supported on OSX). key_pair::pub_x and key_pair::pub_y will be set with the raw key buffers.

Prototype

int aws_ecc_key_pair_derive_public_key(struct aws_ecc_key_pair *key_pair);
source
LibAWSCRT.aws_ecc_key_pair_get_public_key — Method
aws_ecc_key_pair_get_public_key(key_pair, pub_x, pub_y)

Prototype

void aws_ecc_key_pair_get_public_key( const struct aws_ecc_key_pair *key_pair, struct aws_byte_cursor *pub_x, struct aws_byte_cursor *pub_y);
source
LibAWSCRT.aws_ecc_key_pair_new_ecdsa_p256_key_from_aws_credentials — Method
aws_ecc_key_pair_new_ecdsa_p256_key_from_aws_credentials(allocator, credentials)

Derives an ecc key pair (based on the nist P256 curve) from the access key id and secret access key components of a set of AWS credentials using an internal key derivation specification. Used to perform sigv4a signing in the hybrid mode based on AWS credentials.

Parameters

  • allocator: memory allocator to use for all memory allocation
  • credentials: AWS credentials to derive the ECC key from using the AWS sigv4a key deriviation specification

Returns

a new ecc key pair or NULL on failure

Prototype

struct aws_ecc_key_pair *aws_ecc_key_pair_new_ecdsa_p256_key_from_aws_credentials( struct aws_allocator *allocator, const struct aws_credentials *credentials);
source
LibAWSCRT.aws_ecc_key_pair_new_from_asn1 — Method
aws_ecc_key_pair_new_from_asn1(allocator, encoded_keys)

Creates an Elliptic Curve public/private key pair from a DER encoded key pair. Returns a new instance of aws_ecc_key_pair if the key was successfully built. Otherwise returns NULL. Whether or not signing or verification can be perform depends on if encoded_keys is a public/private pair or a public key.

Prototype

struct aws_ecc_key_pair *aws_ecc_key_pair_new_from_asn1( struct aws_allocator *allocator, const struct aws_byte_cursor *encoded_keys);
source
LibAWSCRT.aws_ecc_key_pair_new_from_private_key — Method
aws_ecc_key_pair_new_from_private_key(allocator, curve_name, priv_key)

Creates an Elliptic Curve private key that can be used for signing. Returns a new instance of aws_ecc_key_pair if the key was successfully built. Otherwise returns NULL. Note: priv_key::len must match the appropriate length for the selected curve_name.

Prototype

struct aws_ecc_key_pair *aws_ecc_key_pair_new_from_private_key( struct aws_allocator *allocator, enum aws_ecc_curve_name curve_name, const struct aws_byte_cursor *priv_key);
source
LibAWSCRT.aws_ecc_key_pair_new_from_public_key — Method
aws_ecc_key_pair_new_from_public_key(allocator, curve_name, public_key_x, public_key_y)

Creates an Elliptic Curve public key that can be used for verifying. Returns a new instance of aws_ecc_key_pair if the key was successfully built. Otherwise returns NULL. Note: public_key_x::len and public_key_y::len must match the appropriate length for the selected curve_name.

Prototype

struct aws_ecc_key_pair *aws_ecc_key_pair_new_from_public_key( struct aws_allocator *allocator, enum aws_ecc_curve_name curve_name, const struct aws_byte_cursor *public_key_x, const struct aws_byte_cursor *public_key_y);
source
LibAWSCRT.aws_ecc_key_pair_new_generate_random — Method
aws_ecc_key_pair_new_generate_random(allocator, curve_name)

Creates an Elliptic Curve public/private key pair that can be used for signing and verifying. Returns a new instance of aws_ecc_key_pair if the key was successfully built. Otherwise returns NULL.

Prototype

struct aws_ecc_key_pair *aws_ecc_key_pair_new_generate_random( struct aws_allocator *allocator, enum aws_ecc_curve_name curve_name);
source
LibAWSCRT.aws_ecc_key_pair_release — Method
aws_ecc_key_pair_release(key_pair)

Subtracts one from an ecc key pair's ref count. If ref count reaches zero, the key pair is destroyed.

Prototype

void aws_ecc_key_pair_release(struct aws_ecc_key_pair *key_pair);
source
LibAWSCRT.aws_ecc_key_pair_sign_message — Method
aws_ecc_key_pair_sign_message(key_pair, message, signature)

Uses the key_pair's private key to sign message. The output will be in signature. Signature must be large enough to hold the signature. Check aws_ecc_key_pair_signature_length() for the appropriate size. Signature will be DER encoded.

It is the callers job to make sure message is the appropriate cryptographic digest for this operation. It's usually something like a SHA256.

Prototype

int aws_ecc_key_pair_sign_message( const struct aws_ecc_key_pair *key_pair, const struct aws_byte_cursor *message, struct aws_byte_buf *signature);
source
LibAWSCRT.aws_ecc_key_pair_verify_signature — Method
aws_ecc_key_pair_verify_signature(key_pair, message, signature)

Uses the key_pair's public key to verify signature of message. Signature should be DER encoded.

It is the callers job to make sure message is the appropriate cryptographic digest for this operation. It's usually something like a SHA256.

returns AWS_OP_SUCCESS if the signature is valid.

Prototype

int aws_ecc_key_pair_verify_signature( const struct aws_ecc_key_pair *key_pair, const struct aws_byte_cursor *message, const struct aws_byte_cursor *signature);
source
LibAWSCRT.aws_ecc_oid_from_curve_name — Method
aws_ecc_oid_from_curve_name(curve_name, oid)

Get the DER encoded OID from the curve_name. The OID in this case will not contain the type or the length specifier.

Prototype

int aws_ecc_oid_from_curve_name(enum aws_ecc_curve_name curve_name, struct aws_byte_cursor *oid);
source
LibAWSCRT.aws_endpoints_request_context_add_boolean — Method
aws_endpoints_request_context_add_boolean(allocator, context, name, value)

Prototype

int aws_endpoints_request_context_add_boolean( struct aws_allocator *allocator, struct aws_endpoints_request_context *context, struct aws_byte_cursor name, bool value);
source
LibAWSCRT.aws_endpoints_request_context_add_string — Method
aws_endpoints_request_context_add_string(allocator, context, name, value)

Prototype

int aws_endpoints_request_context_add_string( struct aws_allocator *allocator, struct aws_endpoints_request_context *context, struct aws_byte_cursor name, struct aws_byte_cursor value);
source
LibAWSCRT.aws_endpoints_resolved_endpoint_get_error — Method
aws_endpoints_resolved_endpoint_get_error(resolved_endpoint, out_error)

Prototype

int aws_endpoints_resolved_endpoint_get_error( const struct aws_endpoints_resolved_endpoint *resolved_endpoint, struct aws_byte_cursor *out_error);
source
LibAWSCRT.aws_endpoints_resolved_endpoint_get_headers — Method
aws_endpoints_resolved_endpoint_get_headers(resolved_endpoint, out_headers)

Prototype

int aws_endpoints_resolved_endpoint_get_headers( const struct aws_endpoints_resolved_endpoint *resolved_endpoint, const struct aws_hash_table **out_headers);
source
LibAWSCRT.aws_endpoints_resolved_endpoint_get_properties — Method
aws_endpoints_resolved_endpoint_get_properties(resolved_endpoint, out_properties)

Prototype

int aws_endpoints_resolved_endpoint_get_properties( const struct aws_endpoints_resolved_endpoint *resolved_endpoint, struct aws_byte_cursor *out_properties);
source
LibAWSCRT.aws_endpoints_resolved_endpoint_get_type — Method
aws_endpoints_resolved_endpoint_get_type(resolved_endpoint)

Prototype

enum aws_endpoints_resolved_endpoint_type aws_endpoints_resolved_endpoint_get_type( const struct aws_endpoints_resolved_endpoint *resolved_endpoint);
source
LibAWSCRT.aws_endpoints_resolved_endpoint_get_url — Method
aws_endpoints_resolved_endpoint_get_url(resolved_endpoint, out_url)

Prototype

int aws_endpoints_resolved_endpoint_get_url( const struct aws_endpoints_resolved_endpoint *resolved_endpoint, struct aws_byte_cursor *out_url);
source
LibAWSCRT.aws_endpoints_rule_engine_new — Method
aws_endpoints_rule_engine_new(allocator, ruleset, partitions_config)

Create new rule engine for a given ruleset. In cases of failure NULL is returned and last error is set.

Prototype

struct aws_endpoints_rule_engine *aws_endpoints_rule_engine_new( struct aws_allocator *allocator, struct aws_endpoints_ruleset *ruleset, struct aws_partitions_config *partitions_config);
source
LibAWSCRT.aws_endpoints_rule_engine_resolve — Method
aws_endpoints_rule_engine_resolve(engine, context, out_resolved_endpoint)

Prototype

int aws_endpoints_rule_engine_resolve( struct aws_endpoints_rule_engine *engine, const struct aws_endpoints_request_context *context, struct aws_endpoints_resolved_endpoint **out_resolved_endpoint);
source
LibAWSCRT.aws_endpoints_ruleset_new_from_string — Method
aws_endpoints_ruleset_new_from_string(allocator, ruleset_json)

Prototype

struct aws_endpoints_ruleset *aws_endpoints_ruleset_new_from_string( struct aws_allocator *allocator, struct aws_byte_cursor ruleset_json);
source
LibAWSCRT.aws_event_loop_cancel_task — Method
aws_event_loop_cancel_task(event_loop, task)

Cancels task. This function must be called from the event loop's thread, and is only guaranteed to work properly on tasks scheduled from within the event loop's thread. The task will be executed with the AWS_TASK_STATUS_CANCELED status inside this call.

Prototype

void aws_event_loop_cancel_task(struct aws_event_loop *event_loop, struct aws_task *task);
source
LibAWSCRT.aws_event_loop_clean_up_base — Method
aws_event_loop_clean_up_base(event_loop)

Common cleanup code for all implementations. This is only called from the *destroy() function of event loop implementations.

Prototype

void aws_event_loop_clean_up_base(struct aws_event_loop *event_loop);
source
LibAWSCRT.aws_event_loop_current_clock_time — Method
aws_event_loop_current_clock_time(event_loop, time_nanos)

Gets the current timestamp for the event loop's clock, in nanoseconds. This function is thread-safe.

Prototype

int aws_event_loop_current_clock_time(struct aws_event_loop *event_loop, uint64_t *time_nanos);
source
LibAWSCRT.aws_event_loop_destroy — Method
aws_event_loop_destroy(event_loop)

Invokes the destroy() fn for the event loop implementation. If the event loop is still in a running state, this function will block waiting on the event loop to shutdown. If you do not want this function to block, call aws_event_loop_stop() manually first. If the event loop is shared by multiple threads then destroy must be called by exactly one thread. All other threads must ensure their API calls to the event loop happen-before the call to destroy.

Prototype

void aws_event_loop_destroy(struct aws_event_loop *event_loop);
source
LibAWSCRT.aws_event_loop_fetch_local_object — Method
aws_event_loop_fetch_local_object(event_loop, key, obj)

Fetches an object from the event-loop's data store. Key will be taken as the memory address of the memory pointed to by key. This function is not thread safe and should be called inside the event-loop's thread.

Prototype

int aws_event_loop_fetch_local_object( struct aws_event_loop *event_loop, void *key, struct aws_event_loop_local_object *obj);
source
LibAWSCRT.aws_event_loop_free_io_event_resources — Method
aws_event_loop_free_io_event_resources(event_loop, handle)

Cleans up resources (user_data) associated with the I/O eventing subsystem for a given handle. This should only ever be necessary in the case where you are cleaning up an event loop during shutdown and its thread has already been joined.

Prototype

void aws_event_loop_free_io_event_resources(struct aws_event_loop *event_loop, struct aws_io_handle *handle);
source
LibAWSCRT.aws_event_loop_group_acquire — Method
aws_event_loop_group_acquire(el_group)

Increments the reference count on the event loop group, allowing the caller to take a reference to it.

Returns the same event loop group passed in.

Prototype

struct aws_event_loop_group *aws_event_loop_group_acquire(struct aws_event_loop_group *el_group);
source
LibAWSCRT.aws_event_loop_group_get_next_loop — Method
aws_event_loop_group_get_next_loop(el_group)

Fetches the next loop for use. The purpose is to enable load balancing across loops. You should not depend on how this load balancing is done as it is subject to change in the future. Currently it uses the "best-of-two" algorithm based on the load factor of each loop.

Prototype

struct aws_event_loop *aws_event_loop_group_get_next_loop(struct aws_event_loop_group *el_group);
source
LibAWSCRT.aws_event_loop_group_new — Method
aws_event_loop_group_new(alloc, clock, el_count, new_loop_fn, new_loop_user_data, shutdown_options)

Creates an event loop group, with clock, number of loops to manage, and the function to call for creating a new event loop.

Prototype

struct aws_event_loop_group *aws_event_loop_group_new( struct aws_allocator *alloc, aws_io_clock_fn *clock, uint16_t el_count, aws_new_event_loop_fn *new_loop_fn, void *new_loop_user_data, const struct aws_shutdown_callback_options *shutdown_options);
source
LibAWSCRT.aws_event_loop_group_new_default — Method
aws_event_loop_group_new_default(alloc, max_threads, shutdown_options)

Initializes an event loop group with platform defaults. If max_threads == 0, then the loop count will be the number of available processors on the machine / 2 (to exclude hyper-threads). Otherwise, max_threads will be the number of event loops in the group.

Prototype

struct aws_event_loop_group *aws_event_loop_group_new_default( struct aws_allocator *alloc, uint16_t max_threads, const struct aws_shutdown_callback_options *shutdown_options);
source
LibAWSCRT.aws_event_loop_group_new_default_pinned_to_cpu_group — Method
aws_event_loop_group_new_default_pinned_to_cpu_group(alloc, max_threads, cpu_group, shutdown_options)

Creates an event loop group, with clock, number of loops to manage, the function to call for creating a new event loop, and also pins all loops to hw threads on the same cpu_group (e.g. NUMA nodes). Note: If el_count exceeds the number of hw threads in the cpu_group it will be clamped to the number of hw threads on the assumption that if you care about NUMA, you don't want hyper-threads doing your IO and you especially don't want IO on a different node.

If max_threads == 0, then the loop count will be the number of available processors in the cpu_group / 2 (to exclude hyper-threads)

Prototype

struct aws_event_loop_group *aws_event_loop_group_new_default_pinned_to_cpu_group( struct aws_allocator *alloc, uint16_t max_threads, uint16_t cpu_group, const struct aws_shutdown_callback_options *shutdown_options);
source
LibAWSCRT.aws_event_loop_group_new_pinned_to_cpu_group — Method
aws_event_loop_group_new_pinned_to_cpu_group(alloc, clock, el_count, cpu_group, new_loop_fn, new_loop_user_data, shutdown_options)

Creates an event loop group, with clock, number of loops to manage, the function to call for creating a new event loop, and also pins all loops to hw threads on the same cpu_group (e.g. NUMA nodes). Note: If el_count exceeds the number of hw threads in the cpu_group it will be ignored on the assumption that if you care about NUMA, you don't want hyper-threads doing your IO and you especially don't want IO on a different node.

Prototype

struct aws_event_loop_group *aws_event_loop_group_new_pinned_to_cpu_group( struct aws_allocator *alloc, aws_io_clock_fn *clock, uint16_t el_count, uint16_t cpu_group, aws_new_event_loop_fn *new_loop_fn, void *new_loop_user_data, const struct aws_shutdown_callback_options *shutdown_options);
source
LibAWSCRT.aws_event_loop_group_release — Method
aws_event_loop_group_release(el_group)

Decrements an event loop group's ref count. When the ref count drops to zero, the event loop group will be destroyed.

Prototype

void aws_event_loop_group_release(struct aws_event_loop_group *el_group);
source
LibAWSCRT.aws_event_loop_init_base — Method
aws_event_loop_init_base(event_loop, alloc, clock)

Initializes common event-loop data structures. This is only called from the *new() function of event loop implementations.

Prototype

int aws_event_loop_init_base(struct aws_event_loop *event_loop, struct aws_allocator *alloc, aws_io_clock_fn *clock);
source
LibAWSCRT.aws_event_loop_new_default — Method
aws_event_loop_new_default(alloc, clock)

Creates an instance of the default event loop implementation for the current architecture and operating system.

Prototype

struct aws_event_loop *aws_event_loop_new_default(struct aws_allocator *alloc, aws_io_clock_fn *clock);
source
LibAWSCRT.aws_event_loop_new_default_with_options — Method
aws_event_loop_new_default_with_options(alloc, options)

Creates an instance of the default event loop implementation for the current architecture and operating system using extendable options.

Prototype

struct aws_event_loop *aws_event_loop_new_default_with_options( struct aws_allocator *alloc, const struct aws_event_loop_options *options);
source
LibAWSCRT.aws_event_loop_put_local_object — Method
aws_event_loop_put_local_object(event_loop, obj)

Puts an item object the event-loop's data store. Key will be taken as the memory address of the memory pointed to by key. The lifetime of item must live until remove or a put item overrides it. This function is not thread safe and should be called inside the event-loop's thread.

Prototype

int aws_event_loop_put_local_object(struct aws_event_loop *event_loop, struct aws_event_loop_local_object *obj);
source
LibAWSCRT.aws_event_loop_register_tick_end — Method
aws_event_loop_register_tick_end(event_loop)

For event-loop implementations to use for providing metrics info to the base event-loop. This enables the event-loop load balancer to take into account load when vending another event-loop to a caller.

Call this function at the end of your event-loop tick: after processing IO and tasks.

Prototype

void aws_event_loop_register_tick_end(struct aws_event_loop *event_loop);
source
LibAWSCRT.aws_event_loop_register_tick_start — Method
aws_event_loop_register_tick_start(event_loop)

For event-loop implementations to use for providing metrics info to the base event-loop. This enables the event-loop load balancer to take into account load when vending another event-loop to a caller.

Call this function at the beginning of your event-loop tick: after wake-up, but before processing any IO or tasks.

Prototype

void aws_event_loop_register_tick_start(struct aws_event_loop *event_loop);
source
LibAWSCRT.aws_event_loop_remove_local_object — Method
aws_event_loop_remove_local_object(event_loop, key, removed_obj)

Removes an object from the event-loop's data store. Key will be taken as the memory address of the memory pointed to by key. If removed_item is not null, the removed item will be moved to it if it exists. Otherwise, the default deallocation strategy will be used. This function is not thread safe and should be called inside the event-loop's thread.

Prototype

int aws_event_loop_remove_local_object( struct aws_event_loop *event_loop, void *key, struct aws_event_loop_local_object *removed_obj);
source
LibAWSCRT.aws_event_loop_schedule_task_future — Method
aws_event_loop_schedule_task_future(event_loop, task, run_at_nanos)

The event loop will schedule the task and run it at the specified time. Use aws_event_loop_current_clock_time() to query the current time in nanoseconds. Note that cancelled tasks may execute outside the event loop thread. This function may be called from outside or inside the event loop thread.

The task should not be cleaned up or modified until its function is executed.

Prototype

void aws_event_loop_schedule_task_future( struct aws_event_loop *event_loop, struct aws_task *task, uint64_t run_at_nanos);
source
LibAWSCRT.aws_event_loop_schedule_task_now — Method
aws_event_loop_schedule_task_now(event_loop, task)

The event loop will schedule the task and run it on the event loop thread as soon as possible. Note that cancelled tasks may execute outside the event loop thread. This function may be called from outside or inside the event loop thread.

The task should not be cleaned up or modified until its function is executed.

Prototype

void aws_event_loop_schedule_task_now(struct aws_event_loop *event_loop, struct aws_task *task);
source
LibAWSCRT.aws_event_loop_stop — Method
aws_event_loop_stop(event_loop)

Triggers the event loop to stop, but does not wait for the loop to stop completely. This function may be called from outside or inside the event loop thread. It is safe to call multiple times. This function is called from destroy().

If you do not call destroy(), an event loop can be run again by calling stop(), wait_for_stop_completion(), run().

Prototype

int aws_event_loop_stop(struct aws_event_loop *event_loop);
source
LibAWSCRT.aws_event_loop_subscribe_to_io_events — Method
aws_event_loop_subscribe_to_io_events(event_loop, handle, events, on_event, user_data)

Subscribes on_event to events on the event-loop for handle. events is a bitwise concatenation of the events that were received. The definition for these values can be found in aws_io_event_type. Currently, only AWS_IO_EVENT_TYPE_READABLE and AWS_IO_EVENT_TYPE_WRITABLE are honored. You always are registered for error conditions and closure. This function may be called from outside or inside the event loop thread. However, the unsubscribe function must be called inside the event-loop's thread.

Prototype

int aws_event_loop_subscribe_to_io_events( struct aws_event_loop *event_loop, struct aws_io_handle *handle, int events, aws_event_loop_on_event_fn *on_event, void *user_data);
source
LibAWSCRT.aws_event_loop_thread_is_callers_thread — Method
aws_event_loop_thread_is_callers_thread(event_loop)

Returns true if the event loop's thread is the same thread that called this function, otherwise false.

Prototype

bool aws_event_loop_thread_is_callers_thread(struct aws_event_loop *event_loop);
source
LibAWSCRT.aws_event_loop_unsubscribe_from_io_events — Method
aws_event_loop_unsubscribe_from_io_events(event_loop, handle)

Unsubscribes handle from event-loop notifications. This function is not thread safe and should be called inside the event-loop's thread.

NOTE: if you are using io completion ports, this is a risky call. We use it in places, but only when we're certain there's no pending events. If you want to use it, it's your job to make sure you don't have pending events before calling it.

Prototype

int aws_event_loop_unsubscribe_from_io_events(struct aws_event_loop *event_loop, struct aws_io_handle *handle);
source
LibAWSCRT.aws_event_stream_add_bool_header — Method
aws_event_stream_add_bool_header(headers, name, name_len, value)

Adds a bool header to the list of headers.

Prototype

int aws_event_stream_add_bool_header( struct aws_array_list *headers, const char *name, uint8_t name_len, int8_t value);
source
LibAWSCRT.aws_event_stream_add_bool_header_by_cursor — Method
aws_event_stream_add_bool_header_by_cursor(headers, name, value)

Adds a boolean-valued header to a header list

Parameters

  • headers: header list to add to
  • name: name of the header to add
  • value: value of the header to add

Returns

AWS_OP_SUCCESS on success, AWS_OP_ERR on failure

Prototype

int aws_event_stream_add_bool_header_by_cursor( struct aws_array_list *headers, struct aws_byte_cursor name, bool value);
source
LibAWSCRT.aws_event_stream_add_byte_buf_header_by_cursor — Method
aws_event_stream_add_byte_buf_header_by_cursor(headers, name, value)

Adds a byte_buf-valued header to a header list

Parameters

  • headers: header list to add to
  • name: name of the header to add
  • value: value of the header to add

Returns

AWS_OP_SUCCESS on success, AWS_OP_ERR on failure

Prototype

int aws_event_stream_add_byte_buf_header_by_cursor( struct aws_array_list *headers, struct aws_byte_cursor name, struct aws_byte_cursor value);
source
LibAWSCRT.aws_event_stream_add_byte_header — Method
aws_event_stream_add_byte_header(headers, name, name_len, value)

Adds a byte header to the list of headers.

Prototype

int aws_event_stream_add_byte_header( struct aws_array_list *headers, const char *name, uint8_t name_len, int8_t value);
source
LibAWSCRT.aws_event_stream_add_byte_header_by_cursor — Method
aws_event_stream_add_byte_header_by_cursor(headers, name, value)

Adds a byte-valued header to a header list

Parameters

  • headers: header list to add to
  • name: name of the header to add
  • value: value of the header to add

Returns

AWS_OP_SUCCESS on success, AWS_OP_ERR on failure

Prototype

int aws_event_stream_add_byte_header_by_cursor( struct aws_array_list *headers, struct aws_byte_cursor name, int8_t value);
source
LibAWSCRT.aws_event_stream_add_bytebuf_header — Method
aws_event_stream_add_bytebuf_header(headers, name, name_len, value, value_len, copy)

Adds a byte-buffer header to the list of headers. If copy is set to true, this will result in an allocation for the header value. Otherwise, the value will be set to the memory address of 'value'.

Prototype

int aws_event_stream_add_bytebuf_header( struct aws_array_list *headers, const char *name, uint8_t name_len, uint8_t *value, uint16_t value_len, int8_t copy);
source
LibAWSCRT.aws_event_stream_add_header — Method
aws_event_stream_add_header(headers, header)

Adds a generic header to the list of headers. Makes a copy of the underlaying data.

Prototype

int aws_event_stream_add_header( struct aws_array_list *headers, const struct aws_event_stream_header_value_pair *header);
source
LibAWSCRT.aws_event_stream_add_int16_header — Method
aws_event_stream_add_int16_header(headers, name, name_len, value)

adds a 16 bit integer to the list of headers.

Prototype

int aws_event_stream_add_int16_header( struct aws_array_list *headers, const char *name, uint8_t name_len, int16_t value);
source
LibAWSCRT.aws_event_stream_add_int16_header_by_cursor — Method
aws_event_stream_add_int16_header_by_cursor(headers, name, value)

Adds a int16-valued header to a header list

Parameters

  • headers: header list to add to
  • name: name of the header to add
  • value: value of the header to add

Returns

AWS_OP_SUCCESS on success, AWS_OP_ERR on failure

Prototype

int aws_event_stream_add_int16_header_by_cursor( struct aws_array_list *headers, struct aws_byte_cursor name, int16_t value);
source
LibAWSCRT.aws_event_stream_add_int32_header — Method
aws_event_stream_add_int32_header(headers, name, name_len, value)

adds a 32 bit integer to the list of headers.

Prototype

int aws_event_stream_add_int32_header( struct aws_array_list *headers, const char *name, uint8_t name_len, int32_t value);
source
LibAWSCRT.aws_event_stream_add_int32_header_by_cursor — Method
aws_event_stream_add_int32_header_by_cursor(headers, name, value)

Adds a int32-valued header to a header list

Parameters

  • headers: header list to add to
  • name: name of the header to add
  • value: value of the header to add

Returns

AWS_OP_SUCCESS on success, AWS_OP_ERR on failure

Prototype

int aws_event_stream_add_int32_header_by_cursor( struct aws_array_list *headers, struct aws_byte_cursor name, int32_t value);
source
LibAWSCRT.aws_event_stream_add_int64_header — Method
aws_event_stream_add_int64_header(headers, name, name_len, value)

adds a 64 bit integer to the list of headers.

Prototype

int aws_event_stream_add_int64_header( struct aws_array_list *headers, const char *name, uint8_t name_len, int64_t value);
source
LibAWSCRT.aws_event_stream_add_int64_header_by_cursor — Method
aws_event_stream_add_int64_header_by_cursor(headers, name, value)

Adds a int64-valued header to a header list

Parameters

  • headers: header list to add to
  • name: name of the header to add
  • value: value of the header to add

Returns

AWS_OP_SUCCESS on success, AWS_OP_ERR on failure

Prototype

int aws_event_stream_add_int64_header_by_cursor( struct aws_array_list *headers, struct aws_byte_cursor name, int64_t value);
source
LibAWSCRT.aws_event_stream_add_string_header — Method
aws_event_stream_add_string_header(headers, name, name_len, value, value_len, copy)

Adds a string header to the list of headers. If copy is set to true, this will result in an allocation for the header value. Otherwise, the value will be set to the memory address of 'value'.

Prototype

int aws_event_stream_add_string_header( struct aws_array_list *headers, const char *name, uint8_t name_len, const char *value, uint16_t value_len, int8_t copy);
source
LibAWSCRT.aws_event_stream_add_string_header_by_cursor — Method
aws_event_stream_add_string_header_by_cursor(headers, name, value)

Adds a string-valued header to a header list

Parameters

  • headers: header list to add to
  • name: name of the header to add
  • value: value of the header to add

Returns

AWS_OP_SUCCESS on success, AWS_OP_ERR on failure

Prototype

int aws_event_stream_add_string_header_by_cursor( struct aws_array_list *headers, struct aws_byte_cursor name, struct aws_byte_cursor value);
source
LibAWSCRT.aws_event_stream_add_timestamp_header — Method
aws_event_stream_add_timestamp_header(headers, name, name_len, value)

adds a 64 bit integer representing milliseconds since unix epoch to the list of headers.

Prototype

int aws_event_stream_add_timestamp_header( struct aws_array_list *headers, const char *name, uint8_t name_len, int64_t value);
source
LibAWSCRT.aws_event_stream_add_timestamp_header_by_cursor — Method
aws_event_stream_add_timestamp_header_by_cursor(headers, name, value)

Adds a timestamp-valued header to a header list

Parameters

  • headers: header list to add to
  • name: name of the header to add
  • value: value of the header to add

Returns

AWS_OP_SUCCESS on success, AWS_OP_ERR on failure

Prototype

int aws_event_stream_add_timestamp_header_by_cursor( struct aws_array_list *headers, struct aws_byte_cursor name, int64_t value);
source
LibAWSCRT.aws_event_stream_add_uuid_header — Method
aws_event_stream_add_uuid_header(headers, name, name_len, value)

adds a uuid buffer to the list of headers. Value must always be 16 bytes long.

Prototype

int aws_event_stream_add_uuid_header( struct aws_array_list *headers, const char *name, uint8_t name_len, const uint8_t *value);
source
LibAWSCRT.aws_event_stream_add_uuid_header_by_cursor — Method
aws_event_stream_add_uuid_header_by_cursor(headers, name, value)

Adds a uuid-valued header to a header list

Parameters

  • headers: header list to add to
  • name: name of the header to add
  • value: value of the header to add

Returns

AWS_OP_SUCCESS on success, AWS_OP_ERR on failure

Prototype

int aws_event_stream_add_uuid_header_by_cursor( struct aws_array_list *headers, struct aws_byte_cursor name, struct aws_byte_cursor value);
source
LibAWSCRT.aws_event_stream_channel_handler_increment_read_window — Method
aws_event_stream_channel_handler_increment_read_window(handler, window_update_size)

Updates the read window for the channel if automatic_window_managemanet was set to false.

Prototype

void aws_event_stream_channel_handler_increment_read_window( struct aws_channel_handler *handler, size_t window_update_size);
source
LibAWSCRT.aws_event_stream_channel_handler_new — Method
aws_event_stream_channel_handler_new(allocator, handler_options)

Allocates and initializes a new channel handler for processing aws_event_stream_message() events. Handler options must not be null.

Prototype

struct aws_channel_handler *aws_event_stream_channel_handler_new( struct aws_allocator *allocator, const struct aws_event_stream_channel_handler_options *handler_options);
source
LibAWSCRT.aws_event_stream_channel_handler_write_message — Method
aws_event_stream_channel_handler_write_message(handler, message, on_message_written, user_data)

Writes an aws_event_stream_message() to the channel. Once the channel flushes or an error occurs, on_message_written will be invoked. message should stay valid until the callback is invoked. If an error an occurs, the channel will automatically be shutdown.

Prototype

int aws_event_stream_channel_handler_write_message( struct aws_channel_handler *handler, struct aws_event_stream_message *message, aws_event_stream_channel_handler_on_message_written_fn *on_message_written, void *user_data);
source
LibAWSCRT.aws_event_stream_header_name — Method
aws_event_stream_header_name(header)

Returns the header name. Note: this value is not null terminated

Prototype

struct aws_byte_buf aws_event_stream_header_name( struct aws_event_stream_header_value_pair *header);
source
LibAWSCRT.aws_event_stream_header_value_as_string — Method
aws_event_stream_header_value_as_string(header)

Returns the header value as a string. Note: this value is not null terminated.

Prototype

struct aws_byte_buf aws_event_stream_header_value_as_string( struct aws_event_stream_header_value_pair *header);
source
LibAWSCRT.aws_event_stream_header_value_as_timestamp — Method
aws_event_stream_header_value_as_timestamp(header)

Returns the header value as a 64 bit integer representing milliseconds since unix epoch.

Prototype

int64_t aws_event_stream_header_value_as_timestamp(struct aws_event_stream_header_value_pair *header);
source
LibAWSCRT.aws_event_stream_header_value_as_uuid — Method
aws_event_stream_header_value_as_uuid(header)

Returns the header value a byte buffer which is 16 bytes long. Represents a UUID.

Prototype

struct aws_byte_buf aws_event_stream_header_value_as_uuid( struct aws_event_stream_header_value_pair *header);
source
LibAWSCRT.aws_event_stream_header_value_length — Method
aws_event_stream_header_value_length(header)

Returns the length of the header value buffer. This is mostly intended for string and byte buffer types.

Prototype

uint16_t aws_event_stream_header_value_length(struct aws_event_stream_header_value_pair *header);
source
LibAWSCRT.aws_event_stream_headers_list_cleanup — Method
aws_event_stream_headers_list_cleanup(headers)

Cleans up the headers list. Also deallocates any headers that were the result of a copy flag for strings or buffer.

Prototype

void aws_event_stream_headers_list_cleanup(struct aws_array_list *headers);
source
LibAWSCRT.aws_event_stream_headers_list_init — Method
aws_event_stream_headers_list_init(headers, allocator)

initializes a headers list for you. It will default to a capacity of 4 in dynamic mode.

Prototype

int aws_event_stream_headers_list_init( struct aws_array_list *headers, struct aws_allocator *allocator);
source
LibAWSCRT.aws_event_stream_library_clean_up — Method
aws_event_stream_library_clean_up()

Clean up internal datastructures used by aws-c-event-stream. Must not be called until application is done using functionality in aws-c-event-stream.

Prototype

void aws_event_stream_library_clean_up(void);
source
LibAWSCRT.aws_event_stream_library_init — Method
aws_event_stream_library_init(allocator)

Initializes internal datastructures used by aws-c-event-stream. Must be called before using any functionality in aws-c-event-stream.

Prototype

void aws_event_stream_library_init(struct aws_allocator *allocator);
source
LibAWSCRT.aws_event_stream_message_buffer — Method
aws_event_stream_message_buffer(message)

Returns the message as a buffer ready for transport.

Prototype

const uint8_t *aws_event_stream_message_buffer(const struct aws_event_stream_message *message);
source
LibAWSCRT.aws_event_stream_message_clean_up — Method
aws_event_stream_message_clean_up(message)

Cleans up any internally allocated memory. Always call this for API compatibility reasons, even if you only used the aws_aws_event_stream_message_from_buffer function.

Prototype

void aws_event_stream_message_clean_up(struct aws_event_stream_message *message);
source
LibAWSCRT.aws_event_stream_message_from_buffer — Method
aws_event_stream_message_from_buffer(message, alloc, buffer)

Zero allocation, Zero copy. The message will simply wrap the buffer. The message functions are only useful as long as buffer is referencable memory.

Prototype

int aws_event_stream_message_from_buffer( struct aws_event_stream_message *message, struct aws_allocator *alloc, struct aws_byte_buf *buffer);
source
LibAWSCRT.aws_event_stream_message_from_buffer_copy — Method
aws_event_stream_message_from_buffer_copy(message, alloc, buffer)

Allocates memory and copies buffer. Otherwise the same as aws_aws_event_stream_message_from_buffer. This is slower, but possibly safer.

Prototype

int aws_event_stream_message_from_buffer_copy( struct aws_event_stream_message *message, struct aws_allocator *alloc, const struct aws_byte_buf *buffer);
source
LibAWSCRT.aws_event_stream_message_headers — Method
aws_event_stream_message_headers(message, headers)

Adds the headers for the message to list. The memory in each header is owned as part of the message, do not free it or pass its address around.

Prototype

int aws_event_stream_message_headers( const struct aws_event_stream_message *message, struct aws_array_list *headers);
source
LibAWSCRT.aws_event_stream_message_headers_len — Method
aws_event_stream_message_headers_len(message)

Returns the length of the headers portion of the message.

Prototype

uint32_t aws_event_stream_message_headers_len(const struct aws_event_stream_message *message);
source
LibAWSCRT.aws_event_stream_message_init — Method
aws_event_stream_message_init(message, alloc, headers, payload)

Initializes with a list of headers, the payload, and a payload length. CRCs will be computed for you. If headers or payload is NULL, then the fields will be appropriately set to indicate no headers and/or no payload. Both payload and headers will result in an allocation.

Prototype

int aws_event_stream_message_init( struct aws_event_stream_message *message, struct aws_allocator *alloc, const struct aws_array_list *headers, const struct aws_byte_buf *payload);
source
LibAWSCRT.aws_event_stream_message_message_crc — Method
aws_event_stream_message_message_crc(message)

Returns the checksum of the entire message (crc32)

Prototype

uint32_t aws_event_stream_message_message_crc(const struct aws_event_stream_message *message);
source
LibAWSCRT.aws_event_stream_message_payload — Method
aws_event_stream_message_payload(message)

Returns a pointer to the beginning of the message payload.

Prototype

const uint8_t *aws_event_stream_message_payload(const struct aws_event_stream_message *message);
source
LibAWSCRT.aws_event_stream_message_to_debug_str — Method
aws_event_stream_message_to_debug_str(fd, message)

Writes the message to fd in json format. All strings and binary fields are base64 encoded.

Prototype

int aws_event_stream_message_to_debug_str( FILE *fd, const struct aws_event_stream_message *message);
source
LibAWSCRT.aws_event_stream_message_total_length — Method
aws_event_stream_message_total_length(message)

Returns the total length of the message (including the length field).

Prototype

uint32_t aws_event_stream_message_total_length(const struct aws_event_stream_message *message);
source
LibAWSCRT.aws_event_stream_read_headers_from_buffer — Method
aws_event_stream_read_headers_from_buffer(headers, buffer, headers_len)

Get the headers from the buffer, store them in the headers list. the user's responsibility to cleanup the list when they are finished with it. no buffer copies happen here, the lifetime of the buffer, must outlive the usage of the headers. returns error codes defined in the public interface.

Prototype

int aws_event_stream_read_headers_from_buffer( struct aws_array_list *headers, const uint8_t *buffer, size_t headers_len);
source
LibAWSCRT.aws_event_stream_rpc_client_connection_close — Method
aws_event_stream_rpc_client_connection_close(connection, shutdown_error_code)

Closes the connection if it is open and aws_event_stream_rpc_client_connection_options::on_connection_shutdown will be invoked upon shutdown. shutdown_error_code will indicate the reason for shutdown. For a graceful shutdown pass 0 or AWS_ERROR_SUCCESS.

Prototype

void aws_event_stream_rpc_client_connection_close( struct aws_event_stream_rpc_client_connection *connection, int shutdown_error_code);
source
LibAWSCRT.aws_event_stream_rpc_client_connection_connect — Method
aws_event_stream_rpc_client_connection_connect(allocator, conn_options)

Initiate a new connection. If this function returns AWS_OP_SUCESSS, the aws_event_stream_rpc_client_connection_options::on_connection_setup is guaranteed to be called exactly once. If that callback successfully creates a connection, aws_event_stream_rpc_client_connection_options::on_connection_shutdown will be invoked upon connection closure. However if the connection was never successfully setup, aws_event_stream_rpc_client_connection_options::on_connection_shutdown will not be invoked later.

Prototype

int aws_event_stream_rpc_client_connection_connect( struct aws_allocator *allocator, const struct aws_event_stream_rpc_client_connection_options *conn_options);
source
LibAWSCRT.aws_event_stream_rpc_client_connection_is_open — Method
aws_event_stream_rpc_client_connection_is_open(connection)

Returns true if the connection is open, false otherwise.

Prototype

bool aws_event_stream_rpc_client_connection_is_open( const struct aws_event_stream_rpc_client_connection *connection);
source
LibAWSCRT.aws_event_stream_rpc_client_connection_new_stream — Method
aws_event_stream_rpc_client_connection_new_stream(connection, continuation_options)

Create a new stream. continuation_option's callbacks will not be invoked, and nothing will be sent across the wire until aws_event_stream_rpc_client_continuation_activate() is invoked.

returns an instance of a aws_event_stream_rpc_client_continuation_token on success with a reference count of 1. You must call aws_event_stream_rpc_client_continuation_release() when you're finished with it. Returns NULL on failure.

Prototype

struct aws_event_stream_rpc_client_continuation_token * aws_event_stream_rpc_client_connection_new_stream( struct aws_event_stream_rpc_client_connection *connection, const struct aws_event_stream_rpc_client_stream_continuation_options *continuation_options);
source
LibAWSCRT.aws_event_stream_rpc_client_connection_send_protocol_message — Method
aws_event_stream_rpc_client_connection_send_protocol_message(connection, message_args, flush_fn, user_data)

Sends a message on the connection. These must be connection level messages (not application messages).

flush_fn will be invoked when the message has been successfully writen to the wire or when it fails.

returns AWS_OP_SUCCESS if the message was successfully created and queued, and in that case flush_fn will always be invoked. Otherwise, flush_fn will not be invoked.

Prototype

int aws_event_stream_rpc_client_connection_send_protocol_message( struct aws_event_stream_rpc_client_connection *connection, const struct aws_event_stream_rpc_message_args *message_args, aws_event_stream_rpc_client_message_flush_fn *flush_fn, void *user_data);
source
LibAWSCRT.aws_event_stream_rpc_client_continuation_activate — Method
aws_event_stream_rpc_client_continuation_activate(continuation, operation_name, message_args, flush_fn, user_data)

Actually sends the initial stream to the peer. Callbacks from aws_event_stream_rpc_client_connection_new_stream() will actually be invoked if this function returns AWS_OP_SUCCESS, otherwise, the stream has not been queued and no callbacks will be invoked.

operation_name is the name to identify which logical rpc call you want to kick off with the peer. It must be non-empty. flush_fn will be invoked once the message has either been written to the wire or it fails.

Prototype

int aws_event_stream_rpc_client_continuation_activate( struct aws_event_stream_rpc_client_continuation_token *continuation, struct aws_byte_cursor operation_name, const struct aws_event_stream_rpc_message_args *message_args, aws_event_stream_rpc_client_message_flush_fn *flush_fn, void *user_data);
source
LibAWSCRT.aws_event_stream_rpc_client_continuation_is_closed — Method
aws_event_stream_rpc_client_continuation_is_closed(continuation)

returns true if the continuation has been closed.

Prototype

bool aws_event_stream_rpc_client_continuation_is_closed( const struct aws_event_stream_rpc_client_continuation_token *continuation);
source
LibAWSCRT.aws_event_stream_rpc_client_continuation_send_message — Method
aws_event_stream_rpc_client_continuation_send_message(continuation, message_args, flush_fn, user_data)

Sends a message on the continuation. aws_event_stream_rpc_client_continuation_activate() must be successfully invoked prior to calling this function.

If this function returns AWS_OP_SUCCESS, flush_fn will be invoked once the message has either been written to the wire or it fails.

Prototype

int aws_event_stream_rpc_client_continuation_send_message( struct aws_event_stream_rpc_client_continuation_token *continuation, const struct aws_event_stream_rpc_message_args *message_args, aws_event_stream_rpc_client_message_flush_fn *flush_fn, void *user_data);
source
LibAWSCRT.aws_event_stream_rpc_server_connection_close — Method
aws_event_stream_rpc_server_connection_close(connection, shutdown_error_code)

Closes the connection (including all continuations on the connection), and releases the connection ref count. shutdown_error_code is the error code to use when shutting down the channel. Use AWS_ERROR_SUCCESS for non-error cases.

Prototype

void aws_event_stream_rpc_server_connection_close( struct aws_event_stream_rpc_server_connection *connection, int shutdown_error_code);
source
LibAWSCRT.aws_event_stream_rpc_server_connection_from_existing_channel — Method
aws_event_stream_rpc_server_connection_from_existing_channel(server, channel, connection_options)

Bypasses server, and creates a connection on an already existing channel. No connection lifetime callbacks will be invoked on the returned connection. Returns NULL if an error occurs. If and only if, you use this API, the returned connection is already ref counted and you must call aws_event_stream_rpc_server_connection_release() even if you did not explictly call aws_event_stream_rpc_server_connection_acquire()

Prototype

struct aws_event_stream_rpc_server_connection * aws_event_stream_rpc_server_connection_from_existing_channel( struct aws_event_stream_rpc_server_listener *server, struct aws_channel *channel, const struct aws_event_stream_rpc_connection_options *connection_options);
source
LibAWSCRT.aws_event_stream_rpc_server_connection_send_protocol_message — Method
aws_event_stream_rpc_server_connection_send_protocol_message(connection, message_args, flush_fn, user_data)

Sends a protocol message on the connection (not application data). If the message is valid and successfully written to the channel, flush_fn will be invoked.

Prototype

int aws_event_stream_rpc_server_connection_send_protocol_message( struct aws_event_stream_rpc_server_connection *connection, const struct aws_event_stream_rpc_message_args *message_args, aws_event_stream_rpc_server_message_flush_fn *flush_fn, void *user_data);
source
LibAWSCRT.aws_event_stream_rpc_server_continuation_is_closed — Method
aws_event_stream_rpc_server_continuation_is_closed(continuation)

returns true if the continuation is still in an open state.

Prototype

bool aws_event_stream_rpc_server_continuation_is_closed( struct aws_event_stream_rpc_server_continuation_token *continuation);
source
LibAWSCRT.aws_event_stream_rpc_server_continuation_send_message — Method
aws_event_stream_rpc_server_continuation_send_message(continuation, message_args, flush_fn, user_data)

Sends an application message on the continuation. If the message is valid and successfully written to the channel, flush_fn will be invoked.

Prototype

int aws_event_stream_rpc_server_continuation_send_message( struct aws_event_stream_rpc_server_continuation_token *continuation, const struct aws_event_stream_rpc_message_args *message_args, aws_event_stream_rpc_server_message_flush_fn *flush_fn, void *user_data);
source
LibAWSCRT.aws_event_stream_rpc_server_new_listener — Method
aws_event_stream_rpc_server_new_listener(allocator, options)

Creates a listener with a ref count of 1. You are responsible for calling aws_event_stream_rpc_server_listener_release() when you're finished with the listener. Returns NULL if an error occurs.

Prototype

struct aws_event_stream_rpc_server_listener *aws_event_stream_rpc_server_new_listener( struct aws_allocator *allocator, struct aws_event_stream_rpc_server_listener_options *options);
source
LibAWSCRT.aws_event_stream_streaming_decoder_clean_up — Method
aws_event_stream_streaming_decoder_clean_up(decoder)

Currently, no memory is allocated inside aws_aws_event_stream_streaming_decoder, but for future API compatibility, you should call this when finished with it.

Prototype

void aws_event_stream_streaming_decoder_clean_up( struct aws_event_stream_streaming_decoder *decoder);
source
LibAWSCRT.aws_event_stream_streaming_decoder_init — Method
aws_event_stream_streaming_decoder_init(decoder, alloc, on_payload_segment, on_prelude, on_header, on_error, user_data)

Deprecated. Use aws_event_stream_streaming_decoder_init_from_options instead. Initialize a streaming decoder for messages with callbacks for usage and an optional user context pointer.

Prototype

void aws_event_stream_streaming_decoder_init( struct aws_event_stream_streaming_decoder *decoder, struct aws_allocator *alloc, aws_event_stream_process_on_payload_segment_fn *on_payload_segment, aws_event_stream_prelude_received_fn *on_prelude, aws_event_stream_header_received_fn *on_header, aws_event_stream_on_error_fn *on_error, void *user_data);
source
LibAWSCRT.aws_event_stream_streaming_decoder_init_from_options — Method
aws_event_stream_streaming_decoder_init_from_options(decoder, allocator, options)

Initialize a streaming decoder for messages with callbacks for usage and an optional user context pointer.

Prototype

void aws_event_stream_streaming_decoder_init_from_options( struct aws_event_stream_streaming_decoder *decoder, struct aws_allocator *allocator, const struct aws_event_stream_streaming_decoder_options *options);
source
LibAWSCRT.aws_event_stream_streaming_decoder_pump — Method
aws_event_stream_streaming_decoder_pump(decoder, data)

The main driver of the decoder. Pass data that should be decoded with its length. A likely use-case here is in response to a read event from an io-device

Prototype

int aws_event_stream_streaming_decoder_pump( struct aws_event_stream_streaming_decoder *decoder, const struct aws_byte_buf *data);
source
LibAWSCRT.aws_event_stream_write_headers_to_buffer_safe — Method
aws_event_stream_write_headers_to_buffer_safe(headers, buf)

Writes headers to buf assuming buf is large enough to hold the data. Prefer this function over the unsafe variant 'aws_event_stream_write_headers_to_buffer'.

Returns AWS_OP_SUCCESS if the headers were successfully and completely written and AWS_OP_ERR otherwise.

Prototype

int aws_event_stream_write_headers_to_buffer_safe( const struct aws_array_list *headers, struct aws_byte_buf *buf);
source
LibAWSCRT.aws_fatal_assert — Method
aws_fatal_assert(cond_str, file, line)

Prototype

void aws_fatal_assert(const char *cond_str, const char *file, int line) AWS_ATTRIBUTE_NORETURN;
source
LibAWSCRT.aws_fopen — Method
aws_fopen(file_path, mode)

Deprecated - Use aws_fopen_safe() instead, avoid const char * in public APIs. Opens file at file_path using mode. Returns the FILE pointer if successful. Otherwise, aws_last_error() will contain the error that occurred

Prototype

FILE *aws_fopen(const char *file_path, const char *mode);
source
LibAWSCRT.aws_fopen_safe — Method
aws_fopen_safe(file_path, mode)

Opens file at file_path using mode. Returns the FILE pointer if successful. Otherwise, aws_last_error() will contain the error that occurred

Prototype

FILE *aws_fopen_safe(const struct aws_string *file_path, const struct aws_string *mode);
source
LibAWSCRT.aws_fseek — Method
aws_fseek(file, offset, whence)

Prototype

int aws_fseek(FILE *file, int64_t offset, int whence);
source
LibAWSCRT.aws_future_http_message_wait — Method
aws_future_http_message_wait(future, timeout_ns)

Prototype

AWS_FUTURE_T_POINTER_WITH_RELEASE_DECLARATION(aws_future_http_message, struct aws_http_message, AWS_HTTP_API);
source
LibAWSCRT.aws_future_impl_new_by_value_with_clean_up — Method
aws_future_impl_new_by_value_with_clean_up(alloc, sizeof_result, result_clean_up)

Prototype

struct aws_future_impl *aws_future_impl_new_by_value_with_clean_up( struct aws_allocator *alloc, size_t sizeof_result, aws_future_impl_result_clean_up_fn *result_clean_up);
source
LibAWSCRT.aws_future_impl_new_pointer_with_destroy — Method
aws_future_impl_new_pointer_with_destroy(alloc, result_destroy)

Prototype

struct aws_future_impl *aws_future_impl_new_pointer_with_destroy( struct aws_allocator *alloc, aws_future_impl_result_destroy_fn *result_destroy);
source
LibAWSCRT.aws_future_impl_new_pointer_with_release — Method
aws_future_impl_new_pointer_with_release(alloc, result_release)

Prototype

struct aws_future_impl *aws_future_impl_new_pointer_with_release( struct aws_allocator *alloc, aws_future_impl_result_release_fn *result_release);
source
LibAWSCRT.aws_future_impl_register_callback — Method
aws_future_impl_register_callback(future, on_done, user_data)

Prototype

void aws_future_impl_register_callback( struct aws_future_impl *future, aws_future_callback_fn *on_done, void *user_data);
source
LibAWSCRT.aws_future_impl_register_channel_callback — Method
aws_future_impl_register_channel_callback(future, channel, on_done, user_data)

Prototype

void aws_future_impl_register_channel_callback( struct aws_future_impl *future, struct aws_channel *channel, aws_future_callback_fn *on_done, void *user_data);
source
LibAWSCRT.aws_future_impl_register_event_loop_callback — Method
aws_future_impl_register_event_loop_callback(future, event_loop, on_done, user_data)

Prototype

void aws_future_impl_register_event_loop_callback( struct aws_future_impl *future, struct aws_event_loop *event_loop, aws_future_callback_fn *on_done, void *user_data);
source
LibAWSCRT.aws_future_impl_wait — Method
aws_future_impl_wait(future, timeout_ns)

Prototype

bool aws_future_impl_wait(const struct aws_future_impl *future, uint64_t timeout_ns);
source
LibAWSCRT.aws_get_config_file_path — Method
aws_get_config_file_path(allocator, override_path)

Computes the final platform-specific path for the profile config file. Does limited home directory expansion/resolution.

override_path, if not null, will be searched first instead of using the standard home directory config path

Prototype

struct aws_string *aws_get_config_file_path( struct aws_allocator *allocator, const struct aws_byte_cursor *override_path);
source
LibAWSCRT.aws_get_cpu_group_count — Method
aws_get_cpu_group_count()

Returns the logical processor groupings on the system (such as multiple numa nodes).

Prototype

uint16_t aws_get_cpu_group_count(void);
source
LibAWSCRT.aws_get_cpu_ids_for_group — Method
aws_get_cpu_ids_for_group(group_idx, cpu_ids_array, cpu_ids_array_length)

Fills in cpu_ids_array with the cpu_id's for the group. To obtain the size to allocate for cpu_ids_array and the value for argument for cpu_ids_array_length, call aws_get_cpu_count_for_group().

Prototype

void aws_get_cpu_ids_for_group(uint16_t group_idx, struct aws_cpu_info *cpu_ids_array, size_t cpu_ids_array_length);
source
LibAWSCRT.aws_get_credentials_file_path — Method
aws_get_credentials_file_path(allocator, override_path)

Computes the final platform-specific path for the profile credentials file. Does limited home directory expansion/resolution.

override_path, if not null, will be searched first instead of using the standard home directory config path

Prototype

struct aws_string *aws_get_credentials_file_path( struct aws_allocator *allocator, const struct aws_byte_cursor *override_path);
source
LibAWSCRT.aws_get_environment_value — Method
aws_get_environment_value(allocator, variable_name, value_out)

Prototype

int aws_get_environment_value( struct aws_allocator *allocator, const struct aws_string *variable_name, struct aws_string **value_out);
source
LibAWSCRT.aws_get_hard_limit_io_handles — Method
aws_get_hard_limit_io_handles()

Returns the hard limit for max io handles (max fds in unix terminology). This limit is one more than the actual limit. This limit cannot be increased without sudo permissions.

Prototype

size_t aws_get_hard_limit_io_handles(void);
source
LibAWSCRT.aws_get_home_directory — Method
aws_get_home_directory(allocator)

Returns the current user's home directory.

Prototype

struct aws_string *aws_get_home_directory(struct aws_allocator *allocator);
source
LibAWSCRT.aws_get_pid — Method
aws_get_pid()

Returns the current process's PID (process id).

Returns

PID as int

Prototype

int aws_get_pid(void);
source
LibAWSCRT.aws_get_profile_name — Method
aws_get_profile_name(allocator, override_name)

Computes the profile to use for credentials lookups based on profile resolution rules

Prototype

struct aws_string *aws_get_profile_name(struct aws_allocator *allocator, const struct aws_byte_cursor *override_name);
source
LibAWSCRT.aws_get_soft_limit_io_handles — Method
aws_get_soft_limit_io_handles()

Returns the soft limit for max io handles (max fds in unix terminology). This limit is one more than the actual limit. The soft limit can be changed up to the hard limit by any process regardless of permissions.

Prototype

size_t aws_get_soft_limit_io_handles(void);
source
LibAWSCRT.aws_gmtime — Method
aws_gmtime(time, t)

Cross platform friendly version of gmtime_r

Prototype

void aws_gmtime(time_t time, struct tm *t);
source
LibAWSCRT.aws_hash_array_ignore_case — Method
aws_hash_array_ignore_case(array, len)

Case-insensitive hash function for array containing ASCII or UTF-8 text.

Prototype

uint64_t aws_hash_array_ignore_case(const void *array, const size_t len);
source
LibAWSCRT.aws_hash_c_string — Method
aws_hash_c_string(item)

Convenience hash function for NULL-terminated C-strings

Prototype

uint64_t aws_hash_c_string(const void *item);
source
LibAWSCRT.aws_hash_finalize — Method
aws_hash_finalize(hash, output, truncate_to)

Completes the hash computation and writes the final digest to output. Allocation of output is the caller's responsibility. If you specify truncate_to to something other than 0, the output will be truncated to that number of bytes. For example, if you want a SHA256 digest as the first 16 bytes, set truncate_to to 16. If you want the full digest size, just set this to 0.

Prototype

int aws_hash_finalize(struct aws_hash *hash, struct aws_byte_buf *output, size_t truncate_to);
source
LibAWSCRT.aws_hash_iter_begin — Method
aws_hash_iter_begin(map)

Returns an iterator to be used for iterating through a hash table. Iterator will already point to the first element of the table it finds, which can be accessed as iter.element.

This function cannot fail, but if there are no elements in the table, the returned iterator will return true for aws_hash_iter_done(&iter).

Prototype

struct aws_hash_iter aws_hash_iter_begin(const struct aws_hash_table *map);
source
LibAWSCRT.aws_hash_iter_delete — Method
aws_hash_iter_delete(iter, destroy_contents)

Deletes the element currently pointed-to by the hash iterator. After calling this method, the element member of the iterator should not be accessed until the next call to aws_hash_iter_next.

Parameters

  • destroy_contents: If true, the destructors for the key and value will be called.

Prototype

void aws_hash_iter_delete(struct aws_hash_iter *iter, bool destroy_contents);
source
LibAWSCRT.aws_hash_iter_done — Method
aws_hash_iter_done(iter)

Returns true if iterator is done iterating through table, false otherwise. If this is true, the iterator will not include an element of the table.

Prototype

bool aws_hash_iter_done(const struct aws_hash_iter *iter);
source
LibAWSCRT.aws_hash_iter_is_valid — Method
aws_hash_iter_is_valid(iter)

Given a pointer to a hash_iter, checks that it is well-formed, with all data-structure invariants.

Prototype

bool aws_hash_iter_is_valid(const struct aws_hash_iter *iter);
source
LibAWSCRT.aws_hash_iter_next — Method
aws_hash_iter_next(iter)

Updates iterator so that it points to next element of hash table.

This and the two previous functions are designed to be used together with the following idiom:

for (struct aws_hash_iter iter = aws_hash_iter_begin(&map); `aws_hash_iter_done`(&iter); aws_hash_iter_next(&iter)) { const key_type key = *(const key_type *)iter.element.key; value_type value = *(value_type *)iter.element.value; // etc. }

Note that calling this on an iter which is "done" is idempotent: i.e. it will return another iter which is "done".

Prototype

void aws_hash_iter_next(struct aws_hash_iter *iter);
source
LibAWSCRT.aws_hash_ptr — Method
aws_hash_ptr(item)

Convenience hash function which hashes the pointer value directly, without dereferencing. This can be used in cases where pointer identity is desired, or where a uintptr_t is encoded into a const void *.

Prototype

uint64_t aws_hash_ptr(const void *item);
source
LibAWSCRT.aws_hash_table_clean_up — Method
aws_hash_table_clean_up(map)

Deletes every element from map and frees all associated memory. destroy_fn will be called for each element. aws_hash_table_init must be called before reusing the hash table.

This method is idempotent.

Prototype

void aws_hash_table_clean_up(struct aws_hash_table *map);
source
LibAWSCRT.aws_hash_table_clear — Method
aws_hash_table_clear(map)

Removes every element from the hash map. destroy_fn will be called for each element.

Prototype

void aws_hash_table_clear(struct aws_hash_table *map);
source
LibAWSCRT.aws_hash_table_create — Method
aws_hash_table_create(map, key, p_elem, was_created)

Attempts to locate an element at key. If no such element was found, creates a new element, with value initialized to NULL. In either case, a pointer to the element is placed in *p_elem.

If was_created is non-NULL, *was_created is set to 0 if an existing element was found, or 1 is a new element was created.

Returns AWS_OP_SUCCESS if an item was found or created. Raises AWS_ERROR_OOM if hash table expansion was required and memory allocation failed.

Prototype

int aws_hash_table_create( struct aws_hash_table *map, const void *key, struct aws_hash_element **p_elem, int *was_created);
source
LibAWSCRT.aws_hash_table_eq — Method
aws_hash_table_eq(a, b, value_eq)

Compares two hash tables for equality. Both hash tables must have equivalent key comparators; values will be compared using the comparator passed into this function. The key hash function does not need to be equivalent between the two hash tables.

Prototype

bool aws_hash_table_eq( const struct aws_hash_table *a, const struct aws_hash_table *b, aws_hash_callback_eq_fn *value_eq);
source
LibAWSCRT.aws_hash_table_find — Method
aws_hash_table_find(map, key, p_elem)

Attempts to locate an element at key. If the element is found, a pointer to the value is placed in *p_elem; if it is not found, *pElem is set to NULL. Either way, AWS_OP_SUCCESS is returned.

This method does not change the state of the hash table. Therefore, it is safe to call _find from multiple threads on the same hash table, provided no mutating operations happen in parallel.

Calling code may update the value in the hash table by modifying **pElem after a successful find. However, this pointer is not guaranteed to remain usable after a subsequent call to _put, _delete, _clear, or _clean_up.

Prototype

int aws_hash_table_find(const struct aws_hash_table *map, const void *key, struct aws_hash_element **p_elem);
source
LibAWSCRT.aws_hash_table_foreach — Method
aws_hash_table_foreach(map, callback, context)

Iterates through every element in the map and invokes the callback on that item. Iteration is performed in an arbitrary, implementation-defined order, and is not guaranteed to be consistent across invocations.

The callback may change the value associated with the key by overwriting the value pointed-to by value. In this case, the on_element_removed callback will not be invoked, unless the callback invokes AWS_COMMON_HASH_TABLE_ITER_DELETE (in which case the on_element_removed is given the updated value).

The callback must return a bitmask of zero or more of the following values ORed together:

AWS_COMMON_HASH_TABLE_ITER_CONTINUE - Continues iteration to the next element (if not set, iteration stops) # AWS_COMMON_HASH_TABLE_ITER_DELETE - Deletes the current value and continues iteration. destroy_fn will NOT be invoked. # AWS_COMMON_HASH_TABLE_ITER_ERROR - Stop iteration with error. No action will be taken for the current value and the value before this. No rolling back. The deleted value before will NOT be back. aws_hash_table_foreach returns AWS_OP_ERR after stropping the iteration.

Invoking any method which may change the contents of the hashtable during iteration results in undefined behavior. However, you may safely invoke non-mutating operations during an iteration.

This operation is mutating only if AWS_COMMON_HASH_TABLE_ITER_DELETE is returned at some point during iteration. Otherwise, it is non-mutating and is safe to invoke in parallel with other non-mutating operations.

Prototype

int aws_hash_table_foreach( struct aws_hash_table *map, int (*callback)(void *context, struct aws_hash_element *p_element), void *context);
source
LibAWSCRT.aws_hash_table_init — Method
aws_hash_table_init(map, alloc, size, hash_fn, equals_fn, destroy_key_fn, destroy_value_fn)

Initializes a hash map with initial capacity for 'size' elements without resizing. Uses hash_fn to compute the hash of each element. equals_fn to compute equality of two keys. Whenever an element is removed without being returned, destroy_key_fn is run on the pointer to the key and destroy_value_fn is run on the pointer to the value. Either or both may be NULL if a callback is not desired in this case.

Prototype

int aws_hash_table_init( struct aws_hash_table *map, struct aws_allocator *alloc, size_t size, aws_hash_fn *hash_fn, aws_hash_callback_eq_fn *equals_fn, aws_hash_callback_destroy_fn *destroy_key_fn, aws_hash_callback_destroy_fn *destroy_value_fn);
source
LibAWSCRT.aws_hash_table_move — Method
aws_hash_table_move(to, from)

Moves the hash table in 'from' to 'to'. After this move, 'from' will be identical to the state of the original 'to' hash table, and 'to' will be in the same state as if it had been passed to aws_hash_table_clean_up (that is, it will have no memory allocated, and it will be safe to either discard it or call aws_hash_table_clean_up again).

Note that 'to' will not be cleaned up. You should make sure that 'to' is either uninitialized or cleaned up before moving a hashtable into it.

Prototype

void aws_hash_table_move(struct aws_hash_table *AWS_RESTRICT to, struct aws_hash_table *AWS_RESTRICT from);
source
LibAWSCRT.aws_hash_table_put — Method
aws_hash_table_put(map, key, value, was_created)

Inserts a new element at key, with the given value. If another element exists at that key, the old element will be overwritten; both old key and value objects will be destroyed.

If was_created is non-NULL, *was_created is set to 0 if an existing element was found, or 1 is a new element was created.

Returns AWS_OP_SUCCESS if an item was found or created. Raises AWS_ERROR_OOM if hash table expansion was required and memory

Prototype

int aws_hash_table_put(struct aws_hash_table *map, const void *key, void *value, int *was_created);
source
LibAWSCRT.aws_hash_table_remove — Method
aws_hash_table_remove(map, key, p_value, was_present)

Removes element at key. Always returns AWS_OP_SUCCESS.

If pValue is non-NULL, the existing value (if any) is moved into (*value) before removing from the table, and destroy_fn is _not_ invoked. If pValue is NULL, then (if the element existed) destroy_fn will be invoked on the element being removed.

If was_present is non-NULL, it is set to 0 if the element was not present, or 1 if it was present (and is now removed).

Prototype

int aws_hash_table_remove( struct aws_hash_table *map, const void *key, struct aws_hash_element *p_value, int *was_present);
source
LibAWSCRT.aws_hash_table_remove_element — Method
aws_hash_table_remove_element(map, p_value)

Removes element already known (typically by find()).

p_value should point to a valid element returned by create() or find().

NOTE: DO NOT call this method from inside of a aws_hash_table_foreach callback, return AWS_COMMON_HASH_TABLE_ITER_DELETE instead.

Prototype

int aws_hash_table_remove_element(struct aws_hash_table *map, struct aws_hash_element *p_value);
source
LibAWSCRT.aws_hash_table_swap — Method
aws_hash_table_swap(a, b)

Safely swaps two hash tables. Note that we swap the entirety of the hash table, including which allocator is associated.

Neither hash table is required to be initialized; if one or both is uninitialized, then the uninitialized state is also swapped.

Prototype

void aws_hash_table_swap(struct aws_hash_table *AWS_RESTRICT a, struct aws_hash_table *AWS_RESTRICT b);
source
LibAWSCRT.aws_hash_update — Method
aws_hash_update(hash, to_hash)

Updates the running hash with to_hash. this can be called multiple times.

Prototype

int aws_hash_update(struct aws_hash *hash, const struct aws_byte_cursor *to_hash);
source
LibAWSCRT.aws_hex_decode — Method
aws_hex_decode(to_decode, output)

Prototype

int aws_hex_decode(const struct aws_byte_cursor *AWS_RESTRICT to_decode, struct aws_byte_buf *AWS_RESTRICT output);
source
LibAWSCRT.aws_hex_encode — Method
aws_hex_encode(to_encode, output)

Prototype

int aws_hex_encode(const struct aws_byte_cursor *AWS_RESTRICT to_encode, struct aws_byte_buf *AWS_RESTRICT output);
source
LibAWSCRT.aws_hex_encode_append_dynamic — Method
aws_hex_encode_append_dynamic(to_encode, output)

Prototype

int aws_hex_encode_append_dynamic( const struct aws_byte_cursor *AWS_RESTRICT to_encode, struct aws_byte_buf *AWS_RESTRICT output);
source
LibAWSCRT.aws_high_res_clock_get_ticks — Method
aws_high_res_clock_get_ticks(timestamp)

Get ticks in nanoseconds (usually 100 nanosecond precision) on the high resolution clock (most-likely TSC). This clock has no bearing on the actual system time. On success, timestamp will be set.

Prototype

int aws_high_res_clock_get_ticks(uint64_t *timestamp);
source
LibAWSCRT.aws_hmac_finalize — Method
aws_hmac_finalize(hmac, output, truncate_to)

Completes the hmac computation and writes the final digest to output. Allocation of output is the caller's responsibility. If you specify truncate_to to something other than 0, the output will be truncated to that number of bytes. For example if you want a SHA256 digest as the first 16 bytes, set truncate_to to 16. If you want the full digest size, just set this to 0.

Prototype

int aws_hmac_finalize(struct aws_hmac *hmac, struct aws_byte_buf *output, size_t truncate_to);
source
LibAWSCRT.aws_hmac_update — Method
aws_hmac_update(hmac, to_hmac)

Updates the running hmac with to_hash. this can be called multiple times.

Prototype

int aws_hmac_update(struct aws_hmac *hmac, const struct aws_byte_cursor *to_hmac);
source
LibAWSCRT.aws_host_address_copy — Method
aws_host_address_copy(from, to)

Copies from to to.

Prototype

int aws_host_address_copy(const struct aws_host_address *from, struct aws_host_address *to);
source
LibAWSCRT.aws_host_address_move — Method
aws_host_address_move(from, to)

Moves from to to. After this call, from is no longer usable. Though, it could be resused for another move or copy operation.

Prototype

void aws_host_address_move(struct aws_host_address *from, struct aws_host_address *to);
source
LibAWSCRT.aws_host_resolver_acquire — Method
aws_host_resolver_acquire(resolver)

Increments the reference count on the host resolver, allowing the caller to take a reference to it.

Returns the same host resolver passed in.

Prototype

struct aws_host_resolver *aws_host_resolver_acquire(struct aws_host_resolver *resolver);
source
LibAWSCRT.aws_host_resolver_get_host_address_count — Method
aws_host_resolver_get_host_address_count(resolver, host_name, flags)

get number of addresses for a given host.

Prototype

size_t aws_host_resolver_get_host_address_count( struct aws_host_resolver *resolver, const struct aws_string *host_name, uint32_t flags);
source
LibAWSCRT.aws_host_resolver_init_default_resolution_config — Method
aws_host_resolver_init_default_resolution_config()

Returns the default host resolution config used internally if none specified.

Returns

default host resolution config

Prototype

struct aws_host_resolution_config aws_host_resolver_init_default_resolution_config(void);
source
LibAWSCRT.aws_host_resolver_new_default — Method
aws_host_resolver_new_default(allocator, options)

Creates a host resolver with the default behavior. Here's the behavior:

Since there's not a reliable way to do non-blocking DNS without a ton of risky work that would need years of testing on every Unix system in existence, we work around it by doing a threaded implementation.

When you request an address, it checks the cache. If the entry isn't in the cache it creates a new one. Each entry has a potentially short lived back-ground thread based on ttl for the records. Once we've populated the cache and you keep the resolver active, the resolution callback will be invoked immediately. When it's idle, it will take a little while in the background thread to fetch more, evaluate TTLs etc... In that case your callback will be invoked from the background thread.

A few things to note about TTLs and connection failures.

We attempt to honor your max ttl but will not honor it if dns queries are failing or all of your connections are marked as failed. Once we are able to query dns again, we will re-evaluate the TTLs.

Upon notification connection failures, we move them to a separate list. Eventually we retry them when it's likely that the endpoint is healthy again or we don't really have another choice, but we try to keep them out of your hot path.

Finally, this entire design attempts to prevent problems where developers have to choose between large TTLs and thus sticky hosts or short TTLs and good fleet utilization but now higher latencies. In this design, we resolve every second in the background (only while you're actually using the record), but we do not expire the earlier resolved addresses until max ttl has passed.

This for example, should enable you to hit thousands of hosts in the Amazon S3 fleet instead of just one or two.

Prototype

struct aws_host_resolver *aws_host_resolver_new_default( struct aws_allocator *allocator, const struct aws_host_resolver_default_options *options);
source
LibAWSCRT.aws_host_resolver_purge_cache — Method
aws_host_resolver_purge_cache(resolver)

\deprecated Use purge_cache_with_callback instead calls purge_cache on the vtable.

Prototype

int aws_host_resolver_purge_cache(struct aws_host_resolver *resolver);
source
LibAWSCRT.aws_host_resolver_purge_host_cache — Method
aws_host_resolver_purge_host_cache(resolver, options)

Removes the cache for a host asynchronously.

Prototype

int aws_host_resolver_purge_host_cache( struct aws_host_resolver *resolver, const struct aws_host_resolver_purge_host_options *options);
source
LibAWSCRT.aws_host_resolver_record_connection_failure — Method
aws_host_resolver_record_connection_failure(resolver, address)

calls record_connection_failure on the vtable.

Prototype

int aws_host_resolver_record_connection_failure( struct aws_host_resolver *resolver, const struct aws_host_address *address);
source
LibAWSCRT.aws_host_resolver_release — Method
aws_host_resolver_release(resolver)

Decrements a host resolver's ref count. When the ref count drops to zero, the resolver will be destroyed.

Prototype

void aws_host_resolver_release(struct aws_host_resolver *resolver);
source
LibAWSCRT.aws_host_resolver_resolve_host — Method
aws_host_resolver_resolve_host(resolver, host_name, res, config, user_data)

calls resolve_host on the vtable. config will be copied.

Prototype

int aws_host_resolver_resolve_host( struct aws_host_resolver *resolver, const struct aws_string *host_name, aws_on_host_resolved_result_fn *res, const struct aws_host_resolution_config *config, void *user_data);
source
LibAWSCRT.aws_hton16 — Method
aws_hton16(x)

Convert 16 bit integer from host to network byte order.

Prototype

AWS_STATIC_IMPL uint16_t aws_hton16(uint16_t x);
source
LibAWSCRT.aws_hton32 — Method
aws_hton32(x)

Convert 32 bit integer from host to network byte order.

Prototype

AWS_STATIC_IMPL uint32_t aws_hton32(uint32_t x);
source
LibAWSCRT.aws_hton64 — Method
aws_hton64(x)

Convert 64 bit integer from host to network byte order.

Prototype

AWS_STATIC_IMPL uint64_t aws_hton64(uint64_t x);
source
LibAWSCRT.aws_htonf32 — Method
aws_htonf32(x)

Convert 32 bit float from host to network byte order.

Prototype

AWS_STATIC_IMPL float aws_htonf32(float x);
source
LibAWSCRT.aws_htonf64 — Method
aws_htonf64(x)

Convert 64 bit double from host to network byte order.

Prototype

AWS_STATIC_IMPL double aws_htonf64(double x);
source
LibAWSCRT.aws_http1_stream_add_chunked_trailer — Method
aws_http1_stream_add_chunked_trailer(http1_stream, trailing_headers)

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.

Certain headers are forbidden in the trailer (e.g., Transfer-Encoding, Content-Length, Host). See RFC-7541 Section 4.1.2 for more details.

For client streams, activate() must be called before any chunks are submitted.

For server streams, the response must be submitted before the trailer can be added

aws_http1_stream_add_chunked_trailer must be called before the final size 0 chunk, and at the moment can only be called once, though this could change if need be.

Returns AWS_OP_SUCCESS if the chunk has been submitted.

Prototype

int aws_http1_stream_add_chunked_trailer( struct aws_http_stream *http1_stream, const struct aws_http_headers *trailing_headers);
source
LibAWSCRT.aws_http1_stream_write_chunk — Method
aws_http1_stream_write_chunk(http1_stream, options)

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.

Returns AWS_OP_SUCCESS if the chunk has been submitted. The chunk's completion callback will be invoked when the HTTP-stream is done with the chunk data, whether or not it was successfully sent (see aws_http1_stream_write_chunk_complete_fn). The chunk data must remain valid until the completion callback is invoked.

Returns AWS_OP_ERR and raises an error if the chunk could not be submitted. In this case, the chunk's completion callback will never be invoked. Note that it is always possible for the HTTP-stream to terminate unexpectedly prior to this call being made, in which case the error raised is AWS_ERROR_HTTP_STREAM_HAS_COMPLETED.

Prototype

int aws_http1_stream_write_chunk( struct aws_http_stream *http1_stream, const struct aws_http1_chunk_options *options);
source
LibAWSCRT.aws_http2_connection_change_settings — Method
aws_http2_connection_change_settings(http2_connection, settings_array, num_settings, on_completed, user_data)

Send a SETTINGS frame (HTTP/2 only). SETTINGS will be applied locally when SETTINGS ACK is received from peer.

Parameters

  • http2_connection: HTTP/2 connection.
  • settings_array: The array of settings to change. Note: each setting has its boundary.
  • num_settings: The num of settings to change in settings_array.
  • on_completed: Optional callback, see aws_http2_on_change_settings_complete_fn.
  • user_data: User-data pass to on_completed callback.

Prototype

int aws_http2_connection_change_settings( struct aws_http_connection *http2_connection, const struct aws_http2_setting *settings_array, size_t num_settings, aws_http2_on_change_settings_complete_fn *on_completed, void *user_data);
source
LibAWSCRT.aws_http2_connection_get_local_settings — Method
aws_http2_connection_get_local_settings(http2_connection, out_settings)

Get the local settings we are using to affect the decoding.

Parameters

  • http2_connection: HTTP/2 connection.
  • out_settings: fixed size array of aws_http2_setting gets set to the local settings

Prototype

void aws_http2_connection_get_local_settings( const struct aws_http_connection *http2_connection, struct aws_http2_setting out_settings[AWS_HTTP2_SETTINGS_COUNT]);
source
LibAWSCRT.aws_http2_connection_get_received_goaway — Method
aws_http2_connection_get_received_goaway(http2_connection, out_http2_error, out_last_stream_id)

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.

Parameters

  • http2_connection: HTTP/2 connection.
  • out_http2_error: Gets set to HTTP/2 error code received in most recent GOAWAY.
  • out_last_stream_id: Gets set to Last-Stream-ID received in most recent GOAWAY.

Prototype

int aws_http2_connection_get_received_goaway( struct aws_http_connection *http2_connection, uint32_t *out_http2_error, uint32_t *out_last_stream_id);
source
LibAWSCRT.aws_http2_connection_get_remote_settings — Method
aws_http2_connection_get_remote_settings(http2_connection, out_settings)

Get the settings received from remote peer, which we are using to restricts the message to send.

Parameters

  • http2_connection: HTTP/2 connection.
  • out_settings: fixed size array of aws_http2_setting gets set to the remote settings

Prototype

void aws_http2_connection_get_remote_settings( const struct aws_http_connection *http2_connection, struct aws_http2_setting out_settings[AWS_HTTP2_SETTINGS_COUNT]);
source
LibAWSCRT.aws_http2_connection_get_sent_goaway — Method
aws_http2_connection_get_sent_goaway(http2_connection, out_http2_error, out_last_stream_id)

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.

Parameters

  • http2_connection: HTTP/2 connection.
  • out_http2_error: Gets set to HTTP/2 error code sent in most recent GOAWAY.
  • out_last_stream_id: Gets set to Last-Stream-ID sent in most recent GOAWAY.

Prototype

int aws_http2_connection_get_sent_goaway( struct aws_http_connection *http2_connection, uint32_t *out_http2_error, uint32_t *out_last_stream_id);
source
LibAWSCRT.aws_http2_connection_ping — Method
aws_http2_connection_ping(http2_connection, optional_opaque_data, on_completed, user_data)

Send a PING frame (HTTP/2 only). Round-trip-time is calculated when PING ACK is received from peer.

Parameters

  • http2_connection: HTTP/2 connection.
  • optional_opaque_data: Optional payload for PING frame. Must be NULL, or exactly 8 bytes (AWS_HTTP2_PING_DATA_SIZE). If NULL, the 8 byte payload will be all zeroes.
  • on_completed: Optional callback, invoked when PING ACK is received from peer, or when a connection error prevents the PING ACK from being received. Callback always fires on the connection's event-loop thread.
  • user_data: User-data pass to on_completed callback.

Prototype

int aws_http2_connection_ping( struct aws_http_connection *http2_connection, const struct aws_byte_cursor *optional_opaque_data, aws_http2_on_ping_complete_fn *on_completed, void *user_data);
source
LibAWSCRT.aws_http2_connection_send_goaway — Method
aws_http2_connection_send_goaway(http2_connection, http2_error, allow_more_streams, optional_debug_data)

Send a custom GOAWAY frame (HTTP/2 only).

Note that the connection automatically attempts to send a GOAWAY during shutdown (unless a GOAWAY with a valid Last-Stream-ID has already been sent).

This call can be used to gracefully warn the peer of an impending shutdown (http2_error=0, allow_more_streams=true), or to customize the final GOAWAY frame that is sent by this connection.

The other end may not receive the goaway, if the connection already closed.

Parameters

  • http2_connection: HTTP/2 connection.
  • http2_error: The HTTP/2 error code (RFC-7540 section 7) to send. enum [awshttp2error_code](@ref) lists official codes.
  • allow_more_streams: If true, new peer-initiated streams will continue to be acknowledged and the GOAWAY's Last-Stream-ID will be set to a max value. If false, new peer-initiated streams will be ignored and the GOAWAY's Last-Stream-ID will be set to the latest acknowledged stream.
  • optional_debug_data: Optional debug data to send. Size must not exceed 16KB.

Prototype

void aws_http2_connection_send_goaway( struct aws_http_connection *http2_connection, uint32_t http2_error, bool allow_more_streams, const struct aws_byte_cursor *optional_debug_data);
source
LibAWSCRT.aws_http2_connection_update_window — Method
aws_http2_connection_update_window(http2_connection, increment_size)

Increment the connection's flow-control window to keep data flowing (HTTP/2 only).

If the connection was created with conn_manual_window_management set true, the flow-control window of the connection will shrink as body data is received for all the streams created on it. (headers, padding, and other metadata do not affect the window). The initial connection flow-control window is 65,535. Once the connection's flow-control window reaches to 0, all the streams on the connection stop receiving any further data.

If conn_manual_window_management is false, this call will have no effect. The connection maintains its flow-control windows such that no back-pressure is applied and data arrives as fast as possible.

If you are not connected, this call will have no effect.

Crashes when the connection is not http2 connection. The limit of the Maximum Size is 2**31 - 1. If the increment size cause the connection flow window exceeds the Maximum size, this call will result in the connection lost.

Parameters

  • http2_connection: HTTP/2 connection.
  • increment_size: The size to increment for the connection's flow control window

Prototype

void aws_http2_connection_update_window(struct aws_http_connection *http2_connection, uint32_t increment_size);
source
LibAWSCRT.aws_http2_headers_get_request_method — Method
aws_http2_headers_get_request_method(h2_headers, out_method)

Get the :method value (HTTP/2 headers only).

Prototype

int aws_http2_headers_get_request_method(const struct aws_http_headers *h2_headers, struct aws_byte_cursor *out_method);
source
LibAWSCRT.aws_http2_headers_get_response_status — Method
aws_http2_headers_get_response_status(h2_headers, out_status_code)

Get :status (response pseudo headers only). If no status is set, AWS_ERROR_HTTP_DATA_NOT_AVAILABLE is raised.

Prototype

int aws_http2_headers_get_response_status(const struct aws_http_headers *h2_headers, int *out_status_code);
source
LibAWSCRT.aws_http2_headers_set_request_authority — Method
aws_http2_headers_set_request_authority(h2_headers, authority)

Set :authority (request pseudo headers only). The pseudo headers makes its own copy of the underlying string.

Prototype

int aws_http2_headers_set_request_authority(struct aws_http_headers *h2_headers, struct aws_byte_cursor authority);
source
LibAWSCRT.aws_http2_headers_set_request_method — Method
aws_http2_headers_set_request_method(h2_headers, method)

Set :method (HTTP/2 headers only). The headers makes its own copy of the underlying string.

Prototype

int aws_http2_headers_set_request_method(struct aws_http_headers *h2_headers, struct aws_byte_cursor method);
source
LibAWSCRT.aws_http2_headers_set_request_path — Method
aws_http2_headers_set_request_path(h2_headers, path)

Set :path (request pseudo headers only). The pseudo headers makes its own copy of the underlying string.

Prototype

int aws_http2_headers_set_request_path(struct aws_http_headers *h2_headers, struct aws_byte_cursor path);
source
LibAWSCRT.aws_http2_headers_set_request_scheme — Method
aws_http2_headers_set_request_scheme(h2_headers, scheme)

Set :scheme (request pseudo headers only). The pseudo headers makes its own copy of the underlying string.

Prototype

int aws_http2_headers_set_request_scheme(struct aws_http_headers *h2_headers, struct aws_byte_cursor scheme);
source
LibAWSCRT.aws_http2_headers_set_response_status — Method
aws_http2_headers_set_response_status(h2_headers, status_code)

Set :status (response pseudo headers only).

Prototype

int aws_http2_headers_set_response_status(struct aws_http_headers *h2_headers, int status_code);
source
LibAWSCRT.aws_http2_message_new_from_http1 — Method
aws_http2_message_new_from_http1(alloc, http1_msg)

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 be removed and :authority will be added using the information. - :scheme always defaults to "https". To use a different scheme create the HTTP/2 message directly

Prototype

struct aws_http_message *aws_http2_message_new_from_http1( struct aws_allocator *alloc, const struct aws_http_message *http1_msg);
source
LibAWSCRT.aws_http2_message_new_request — Method
aws_http2_message_new_request(allocator)

Create 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.

The caller has a hold on the object and must call aws_http_message_release() when they are done with it.

Prototype

struct aws_http_message *aws_http2_message_new_request(struct aws_allocator *allocator);
source
LibAWSCRT.aws_http2_message_new_response — Method
aws_http2_message_new_response(allocator)

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.

The caller has a hold on the object and must call aws_http_message_release() when they are done with it.

Prototype

struct aws_http_message *aws_http2_message_new_response(struct aws_allocator *allocator);
source
LibAWSCRT.aws_http2_stream_get_received_reset_error_code — Method
aws_http2_stream_get_received_reset_error_code(http2_stream, out_http2_error)

Get the error code received in rst_stream. Only valid if the stream has completed, and an RST_STREAM frame has received.

Parameters

  • http2_stream: HTTP/2 stream.
  • out_http2_error: Gets to set to HTTP/2 error code received in rst_stream.

Prototype

int aws_http2_stream_get_received_reset_error_code(struct aws_http_stream *http2_stream, uint32_t *out_http2_error);
source
LibAWSCRT.aws_http2_stream_get_sent_reset_error_code — Method
aws_http2_stream_get_sent_reset_error_code(http2_stream, out_http2_error)

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.

Parameters

  • http2_stream: HTTP/2 stream.
  • out_http2_error: Gets to set to HTTP/2 error code sent in rst_stream.

Prototype

int aws_http2_stream_get_sent_reset_error_code(struct aws_http_stream *http2_stream, uint32_t *out_http2_error);
source
LibAWSCRT.aws_http2_stream_manager_acquire — Method
aws_http2_stream_manager_acquire(manager)

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.

Parameters

  • manager:

Returns

The same pointer acquiring.

Prototype

struct aws_http2_stream_manager *aws_http2_stream_manager_acquire(struct aws_http2_stream_manager *manager);
source
LibAWSCRT.aws_http2_stream_manager_acquire_stream — Method
aws_http2_stream_manager_acquire_stream(http2_stream_manager, acquire_stream_option)

Acquire a stream from stream manager asynchronously.

Parameters

Prototype

void aws_http2_stream_manager_acquire_stream( struct aws_http2_stream_manager *http2_stream_manager, const struct aws_http2_stream_manager_acquire_stream_options *acquire_stream_option);
source
LibAWSCRT.aws_http2_stream_manager_fetch_metrics — Method
aws_http2_stream_manager_fetch_metrics(http2_stream_manager, out_metrics)

Fetch the current metrics from stream manager.

Parameters

  • http2_stream_manager:
  • out_metrics: The metrics to be fetched

Prototype

void aws_http2_stream_manager_fetch_metrics( const struct aws_http2_stream_manager *http2_stream_manager, struct aws_http_manager_metrics *out_metrics);
source
LibAWSCRT.aws_http2_stream_manager_new — Method
aws_http2_stream_manager_new(allocator, options)

Prototype

struct aws_http2_stream_manager *aws_http2_stream_manager_new( struct aws_allocator *allocator, const struct aws_http2_stream_manager_options *options);
source
LibAWSCRT.aws_http2_stream_manager_release — Method
aws_http2_stream_manager_release(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.

Parameters

  • manager:

Returns

NULL

Prototype

struct aws_http2_stream_manager *aws_http2_stream_manager_release(struct aws_http2_stream_manager *manager);
source
LibAWSCRT.aws_http2_stream_reset — Method
aws_http2_stream_reset(http2_stream, http2_error)

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.

Parameters

Prototype

int aws_http2_stream_reset(struct aws_http_stream *http2_stream, uint32_t http2_error);
source
LibAWSCRT.aws_http2_stream_write_data — Method
aws_http2_stream_write_data(http2_stream, options)

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.

Typical usage will be something like: options.http2_use_manual_data_writes = true; stream = aws_http_connection_make_request(connection, &options); aws_http_stream_activate(stream); ... struct aws_http2_stream_write_data_options write; aws_http2_stream_write_data(stream, &write); ... struct aws_http2_stream_write_data_options last_write; last_write.end_stream = true; aws_http2_stream_write_data(stream, &write); ... aws_http_stream_release(stream);

Returns

AWS_OP_SUCCESS if the write was queued AWS_OP_ERROR indicating the attempt raised an error code. AWS_ERROR_INVALID_STATE will be raised for invalid usage. AWS_ERROR_HTTP_STREAM_HAS_COMPLETED will be raised if the stream ended for reasons behind the scenes.

Prototype

int aws_http2_stream_write_data( struct aws_http_stream *http2_stream, const struct aws_http2_stream_write_data_options *options);
source
LibAWSCRT.aws_http_alpn_map_init — Method
aws_http_alpn_map_init(allocator, map)

Initialize an empty hash-table that maps struct [awsstring](@ref) * to enum [awshttpversion](@ref). This map can used in aws\http_client_connections_options.alpn_string_map.

Prototype

int aws_http_alpn_map_init(struct aws_allocator *allocator, struct aws_hash_table *map);
source
LibAWSCRT.aws_http_alpn_map_init_copy — Method
aws_http_alpn_map_init_copy(allocator, dest, src)

Initialize an map copied from the *src map, which maps struct [awsstring](@ref) * to enum [awshttp_version](@ref).

Prototype

int aws_http_alpn_map_init_copy( struct aws_allocator *allocator, struct aws_hash_table *dest, struct aws_hash_table *src);
source
LibAWSCRT.aws_http_client_connect — Method
aws_http_client_connect(options)

Asynchronously establish a client connection. The on_setup callback is invoked when the operation has created a connection or failed.

Prototype

int aws_http_client_connect(const struct aws_http_client_connection_options *options);
source
LibAWSCRT.aws_http_connection_close — Method
aws_http_connection_close(connection)

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.

It's safe to call this function regardless of the connection state as long as you hold a reference to the connection.

Prototype

void aws_http_connection_close(struct aws_http_connection *connection);
source
LibAWSCRT.aws_http_connection_configure_server — Method
aws_http_connection_configure_server(connection, options)

Configure a server connection. This must be called from the server's on_incoming_connection callback.

Prototype

int aws_http_connection_configure_server( struct aws_http_connection *connection, const struct aws_http_server_connection_options *options);
source
LibAWSCRT.aws_http_connection_get_channel — Method
aws_http_connection_get_channel(connection)

Returns the channel hosting the HTTP connection. Do not expose this function to language bindings.

Prototype

struct aws_channel *aws_http_connection_get_channel(struct aws_http_connection *connection);
source
LibAWSCRT.aws_http_connection_get_remote_endpoint — Method
aws_http_connection_get_remote_endpoint(connection)

Returns the remote endpoint of the HTTP connection.

Prototype

const struct aws_socket_endpoint *aws_http_connection_get_remote_endpoint(const struct aws_http_connection *connection);
source
LibAWSCRT.aws_http_connection_is_client — Method
aws_http_connection_is_client(connection)

Returns true if this is a client connection.

Prototype

bool aws_http_connection_is_client(const struct aws_http_connection *connection);
source
LibAWSCRT.aws_http_connection_is_open — Method
aws_http_connection_is_open(connection)

Returns true unless the connection is closed or closing.

Prototype

bool aws_http_connection_is_open(const struct aws_http_connection *connection);
source
LibAWSCRT.aws_http_connection_is_server — Method
aws_http_connection_is_server(connection)

Returns true if this is a server connection.

Prototype

bool aws_http_connection_is_server(const struct aws_http_connection *connection);
source
LibAWSCRT.aws_http_connection_make_request — Method
aws_http_connection_make_request(client_connection, options)

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.

The options are copied during this call.

Tip for language bindings: Do not bind the options struct. Use something more natural for your language, such as Builder Pattern in Java, or Python's ability to take many optional arguments by name.

Note: The header of the request will be sent as it is when the message to send protocol matches the protocol of the connection. - No user-agent will be added. - No security check will be enforced. eg: referer header privacy should be enforced by the user-agent who adds the header - When HTTP/1 message sent on HTTP/2 connection, aws_http2_message_new_from_http1 will be applied under the hood. - When HTTP/2 message sent on HTTP/1 connection, no change will be made.

Prototype

struct aws_http_stream *aws_http_connection_make_request( struct aws_http_connection *client_connection, const struct aws_http_make_request_options *options);
source
LibAWSCRT.aws_http_connection_manager_acquire_connection — Method
aws_http_connection_manager_acquire_connection(manager, callback, user_data)

Prototype

void aws_http_connection_manager_acquire_connection( struct aws_http_connection_manager *manager, aws_http_connection_manager_on_connection_setup_fn *callback, void *user_data);
source
LibAWSCRT.aws_http_connection_manager_fetch_metrics — Method
aws_http_connection_manager_fetch_metrics(manager, out_metrics)

Fetch the current manager metrics from connection manager.

Prototype

void aws_http_connection_manager_fetch_metrics( const struct aws_http_connection_manager *manager, struct aws_http_manager_metrics *out_metrics);
source
LibAWSCRT.aws_http_connection_manager_new — Method
aws_http_connection_manager_new(allocator, options)

Prototype

struct aws_http_connection_manager *aws_http_connection_manager_new( struct aws_allocator *allocator, const struct aws_http_connection_manager_options *options);
source
LibAWSCRT.aws_http_connection_new_requests_allowed — Method
aws_http_connection_new_requests_allowed(connection)

Return whether the connection can make a new requests. If false, then a new connection must be established to make further requests.

Prototype

bool aws_http_connection_new_requests_allowed(const struct aws_http_connection *connection);
source
LibAWSCRT.aws_http_connection_release — Method
aws_http_connection_release(connection)

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.

Users should always wait for the on_shutdown() callback to be called before releasing any data passed to the http_connection (Eg aws_tls_connection_options, aws_socket_options) otherwise there will be race conditions between http_connection shutdown tasks and memory release tasks, causing Segfaults.

Prototype

void aws_http_connection_release(struct aws_http_connection *connection);
source
LibAWSCRT.aws_http_connection_stop_new_requests — Method
aws_http_connection_stop_new_requests(connection)

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,

Prototype

void aws_http_connection_stop_new_requests(struct aws_http_connection *connection);
source
LibAWSCRT.aws_http_header_name_eq — Method
aws_http_header_name_eq(name_a, name_b)

Return whether both names are equivalent. This is a case-insensitive string comparison.

Example Matches: "Content-Length" == "content-length" // upper or lower case ok

Example Mismatches: "Content-Length" != " Content-Length" // leading whitespace bad

Prototype

bool aws_http_header_name_eq(struct aws_byte_cursor name_a, struct aws_byte_cursor name_b);
source
LibAWSCRT.aws_http_headers_add — Method
aws_http_headers_add(headers, name, value)

Add a header. The underlying strings are copied.

Prototype

int aws_http_headers_add(struct aws_http_headers *headers, struct aws_byte_cursor name, struct aws_byte_cursor value);
source
LibAWSCRT.aws_http_headers_add_array — Method
aws_http_headers_add_array(headers, array, count)

Add an array of headers. The underlying strings are copied.

Prototype

int aws_http_headers_add_array(struct aws_http_headers *headers, const struct aws_http_header *array, size_t count);
source
LibAWSCRT.aws_http_headers_add_header — Method
aws_http_headers_add_header(headers, header)

Add a header. The underlying strings are copied.

Prototype

int aws_http_headers_add_header(struct aws_http_headers *headers, const struct aws_http_header *header);
source
LibAWSCRT.aws_http_headers_count — Method
aws_http_headers_count(headers)

Get the total number of headers.

Prototype

size_t aws_http_headers_count(const struct aws_http_headers *headers);
source
LibAWSCRT.aws_http_headers_erase — Method
aws_http_headers_erase(headers, name)

Remove all headers with this name. AWS_ERROR_HTTP_HEADER_NOT_FOUND is raised if no headers with this name are found.

Prototype

int aws_http_headers_erase(struct aws_http_headers *headers, struct aws_byte_cursor name);
source
LibAWSCRT.aws_http_headers_erase_index — Method
aws_http_headers_erase_index(headers, index)

Remove the header at the specified index.

AWS_ERROR_INVALID_INDEX is raised if the index is invalid.

Prototype

int aws_http_headers_erase_index(struct aws_http_headers *headers, size_t index);
source
LibAWSCRT.aws_http_headers_erase_value — Method
aws_http_headers_erase_value(headers, name, value)

Remove the first header found with this name and value. AWS_ERROR_HTTP_HEADER_NOT_FOUND is raised if no such header is found.

Prototype

int aws_http_headers_erase_value( struct aws_http_headers *headers, struct aws_byte_cursor name, struct aws_byte_cursor value);
source
LibAWSCRT.aws_http_headers_get — Method
aws_http_headers_get(headers, name, out_value)

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.

Prototype

int aws_http_headers_get( const struct aws_http_headers *headers, struct aws_byte_cursor name, struct aws_byte_cursor *out_value);
source
LibAWSCRT.aws_http_headers_get_all — Method
aws_http_headers_get_all(headers, name)

Get all values with this name, combined into one new aws_string that you are responsible for destroying. If there are multiple headers with this name, their values are appended with comma-separators. If there are no headers with this name, NULL is returned and AWS_ERROR_HTTP_HEADER_NOT_FOUND is raised.

Prototype

struct aws_string *aws_http_headers_get_all(const struct aws_http_headers *headers, struct aws_byte_cursor name);
source
LibAWSCRT.aws_http_headers_get_index — Method
aws_http_headers_get_index(headers, index, out_header)

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:

  • Headers with the same name will always be in the same order, relative to one another. If "A: one" is added before "A: two", then "A: one" will always precede "A: two".

  • Headers with different names could be in any order, relative to one another. If "A: one" is seen before "B: bee" in one iteration, you might see "B: bee" before "A: one" on the next.

AWS_ERROR_INVALID_INDEX is raised if the index is invalid.

Prototype

int aws_http_headers_get_index( const struct aws_http_headers *headers, size_t index, struct aws_http_header *out_header);
source
LibAWSCRT.aws_http_headers_has — Method
aws_http_headers_has(headers, name)

Test if header name exists or not in headers

Prototype

bool aws_http_headers_has(const struct aws_http_headers *headers, struct aws_byte_cursor name);
source
LibAWSCRT.aws_http_headers_release — Method
aws_http_headers_release(headers)

Release a hold on the object. The object is deleted when all holds on it are released.

Prototype

void aws_http_headers_release(struct aws_http_headers *headers);
source
LibAWSCRT.aws_http_headers_set — Method
aws_http_headers_set(headers, name, value)

Set a header value. The header is added if necessary and any existing values for this name are removed. The underlying strings are copied.

Prototype

int aws_http_headers_set(struct aws_http_headers *headers, struct aws_byte_cursor name, struct aws_byte_cursor value);
source
LibAWSCRT.aws_http_library_clean_up — Method
aws_http_library_clean_up()

Clean up internal datastructures used by aws-c-http. Must not be called until application is done using functionality in aws-c-http.

Prototype

void aws_http_library_clean_up(void);
source
LibAWSCRT.aws_http_library_init — Method
aws_http_library_init(alloc)

Initializes internal datastructures used by aws-c-http. Must be called before using any functionality in aws-c-http.

Prototype

void aws_http_library_init(struct aws_allocator *alloc);
source
LibAWSCRT.aws_http_message_acquire — Method
aws_http_message_acquire(message)

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.

This function returns the passed in message (possibly NULL) so that acquire-and-assign can be done with a single statement.

Prototype

struct aws_http_message *aws_http_message_acquire(struct aws_http_message *message);
source
LibAWSCRT.aws_http_message_add_header — Method
aws_http_message_add_header(message, header)

Add a header to the end of the array. The message makes its own copy of the underlying strings.

Prototype

int aws_http_message_add_header(struct aws_http_message *message, struct aws_http_header header);
source
LibAWSCRT.aws_http_message_add_header_array — Method
aws_http_message_add_header_array(message, headers, num_headers)

Add an array of headers to the end of the header array. The message makes its own copy of the underlying strings.

This is a helper function useful when it's easier to define headers as a stack array, rather than calling add_header repeatedly.

Prototype

int aws_http_message_add_header_array( struct aws_http_message *message, const struct aws_http_header *headers, size_t num_headers);
source
LibAWSCRT.aws_http_message_erase_header — Method
aws_http_message_erase_header(message, index)

Remove the header at the specified index. Headers after this index are all shifted back one position.

This function cannot fail if a valid index is provided. Otherwise, AWS_ERROR_INVALID_INDEX will be raised.

Prototype

int aws_http_message_erase_header(struct aws_http_message *message, size_t index);
source
LibAWSCRT.aws_http_message_get_body_stream — Method
aws_http_message_get_body_stream(message)

Get the body stream. Returns NULL if no body stream is set.

Prototype

struct aws_input_stream *aws_http_message_get_body_stream(const struct aws_http_message *message);
source
LibAWSCRT.aws_http_message_get_header — Method
aws_http_message_get_header(message, out_header, index)

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.

The underlying strings are stored within the message.

Prototype

int aws_http_message_get_header( const struct aws_http_message *message, struct aws_http_header *out_header, size_t index);
source
LibAWSCRT.aws_http_message_get_headers — Method
aws_http_message_get_headers(message)

This datastructure has more functions for inspecting and modifying headers than are available on the aws_http_message datastructure.

Prototype

struct aws_http_headers *aws_http_message_get_headers(const struct aws_http_message *message);
source
LibAWSCRT.aws_http_message_get_request_method — Method
aws_http_message_get_request_method(request_message, out_method)

Get the method (request messages only).

Prototype

int aws_http_message_get_request_method( const struct aws_http_message *request_message, struct aws_byte_cursor *out_method);
source
LibAWSCRT.aws_http_message_get_request_path — Method
aws_http_message_get_request_path(request_message, out_path)

Prototype

int aws_http_message_get_request_path(const struct aws_http_message *request_message, struct aws_byte_cursor *out_path);
source
LibAWSCRT.aws_http_message_get_response_status — Method
aws_http_message_get_response_status(response_message, out_status_code)

Get the status code (response messages only). If no status is set, AWS_ERROR_HTTP_DATA_NOT_AVAILABLE is raised.

Prototype

int aws_http_message_get_response_status(const struct aws_http_message *response_message, int *out_status_code);
source
LibAWSCRT.aws_http_message_new_request — Method
aws_http_message_new_request(allocator)

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.

The caller has a hold on the object and must call aws_http_message_release() when they are done with it.

Prototype

struct aws_http_message *aws_http_message_new_request(struct aws_allocator *allocator);
source
LibAWSCRT.aws_http_message_new_response — Method
aws_http_message_new_response(allocator)

Create a new HTTP/1.1 response message. The message is blank, all properties (status, headers, etc) must be set individually.

The caller has a hold on the object and must call aws_http_message_release() when they are done with it.

Prototype

struct aws_http_message *aws_http_message_new_response(struct aws_allocator *allocator);
source
LibAWSCRT.aws_http_message_new_websocket_handshake_request — Method
aws_http_message_new_websocket_handshake_request(allocator, path, host)

Create request with all required fields for a websocket upgrade request. The method and path are set, and the the following headers are added:

Host: <host> Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: <base64 encoding of 16 random bytes> Sec-WebSocket-Version: 13

Prototype

struct aws_http_message *aws_http_message_new_websocket_handshake_request( struct aws_allocator *allocator, struct aws_byte_cursor path, struct aws_byte_cursor host);
source
LibAWSCRT.aws_http_message_release — Method
aws_http_message_release(message)

Release a hold on the object. The object is deleted when all holds on it are released.

This function always returns NULL so that release-and-assign-NULL can be done with a single statement.

Prototype

struct aws_http_message *aws_http_message_release(struct aws_http_message *message);
source
LibAWSCRT.aws_http_message_set_body_stream — Method
aws_http_message_set_body_stream(message, body_stream)

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.

Prototype

void aws_http_message_set_body_stream(struct aws_http_message *message, struct aws_input_stream *body_stream);
source
LibAWSCRT.aws_http_message_set_request_method — Method
aws_http_message_set_request_method(request_message, method)

Set the method (request messages only). The request makes its own copy of the underlying string.

Prototype

int aws_http_message_set_request_method(struct aws_http_message *request_message, struct aws_byte_cursor method);
source
LibAWSCRT.aws_http_message_set_request_path — Method
aws_http_message_set_request_path(request_message, path)

Set the path-and-query value (request messages only). The request makes its own copy of the underlying string.

Prototype

int aws_http_message_set_request_path(struct aws_http_message *request_message, struct aws_byte_cursor path);
source
LibAWSCRT.aws_http_message_set_response_status — Method
aws_http_message_set_response_status(response_message, status_code)

Set the status code (response messages only).

Prototype

int aws_http_message_set_response_status(struct aws_http_message *response_message, int status_code);
source
LibAWSCRT.aws_http_proxy_config_destroy — Method
aws_http_proxy_config_destroy(config)

Destroys an http proxy configuration

Parameters

  • config: http proxy configuration to destroy

Prototype

void aws_http_proxy_config_destroy(struct aws_http_proxy_config *config);
source
LibAWSCRT.aws_http_proxy_config_new_clone — Method
aws_http_proxy_config_new_clone(allocator, proxy_config)

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).

Parameters

  • allocator: memory allocator to use
  • proxy_config: http proxy configuration to clone

Returns

Prototype

struct aws_http_proxy_config *aws_http_proxy_config_new_clone( struct aws_allocator *allocator, const struct aws_http_proxy_config *proxy_config);
source
LibAWSCRT.aws_http_proxy_config_new_from_connection_options — Method
aws_http_proxy_config_new_from_connection_options(allocator, options)

Create a persistent proxy configuration from http connection options

Parameters

  • allocator: memory allocator to use
  • options: http connection options to source proxy configuration from

Returns

Prototype

struct aws_http_proxy_config *aws_http_proxy_config_new_from_connection_options( struct aws_allocator *allocator, const struct aws_http_client_connection_options *options);
source
LibAWSCRT.aws_http_proxy_config_new_from_manager_options — Method
aws_http_proxy_config_new_from_manager_options(allocator, options)

Create a persistent proxy configuration from http connection manager options

Parameters

  • allocator: memory allocator to use
  • options: http connection manager options to source proxy configuration from

Returns

Prototype

struct aws_http_proxy_config *aws_http_proxy_config_new_from_manager_options( struct aws_allocator *allocator, const struct aws_http_connection_manager_options *options);
source
LibAWSCRT.aws_http_proxy_config_new_from_proxy_options — Method
aws_http_proxy_config_new_from_proxy_options(allocator, options)

Create a persistent proxy configuration from non-persistent proxy options. Legacy connection type of proxy options will be rejected.

Parameters

  • allocator: memory allocator to use
  • options: http proxy options to source proxy configuration from

Returns

Prototype

struct aws_http_proxy_config *aws_http_proxy_config_new_from_proxy_options( struct aws_allocator *allocator, const struct aws_http_proxy_options *options);
source
LibAWSCRT.aws_http_proxy_config_new_from_proxy_options_with_tls_info — Method
aws_http_proxy_config_new_from_proxy_options_with_tls_info(allocator, proxy_options, is_tls_connection)

Create a persistent proxy configuration from non-persistent proxy options.

Parameters

  • allocator: memory allocator to use
  • options: http proxy options to source proxy configuration from
  • is_tls_connection: tls connection info of the main connection to determine connection_type when the connection_type is legacy.

Returns

Prototype

struct aws_http_proxy_config *aws_http_proxy_config_new_from_proxy_options_with_tls_info( struct aws_allocator *allocator, const struct aws_http_proxy_options *proxy_options, bool is_tls_connection);
source
LibAWSCRT.aws_http_proxy_config_new_tunneling_from_proxy_options — Method
aws_http_proxy_config_new_tunneling_from_proxy_options(allocator, options)

Create a persistent proxy configuration from non-persistent proxy options. The resulting proxy configuration assumes a tunneling connection type.

Parameters

  • allocator: memory allocator to use
  • options: http proxy options to source proxy configuration from

Returns

Prototype

struct aws_http_proxy_config *aws_http_proxy_config_new_tunneling_from_proxy_options( struct aws_allocator *allocator, const struct aws_http_proxy_options *options);
source
LibAWSCRT.aws_http_proxy_negotiator_acquire — Method
aws_http_proxy_negotiator_acquire(proxy_negotiator)

Take a reference to an http proxy negotiator

Parameters

  • proxy_negotiator: negotiator to take a reference to

Returns

the strategy

Prototype

struct aws_http_proxy_negotiator *aws_http_proxy_negotiator_acquire(struct aws_http_proxy_negotiator *proxy_negotiator);
source
LibAWSCRT.aws_http_proxy_negotiator_release — Method
aws_http_proxy_negotiator_release(proxy_negotiator)

Release a reference to an http proxy negotiator

Parameters

  • proxy_negotiator: negotiator to release a reference to

Prototype

void aws_http_proxy_negotiator_release(struct aws_http_proxy_negotiator *proxy_negotiator);
source
LibAWSCRT.aws_http_proxy_new_socket_channel — Method
aws_http_proxy_new_socket_channel(channel_options, proxy_options)

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.

Parameters

  • channel_options: configuration options for the socket level connection
  • proxy_options: configuration options for the proxy connection

Returns

AWS_OP_SUCCESS if the asynchronous channel kickoff succeeded, AWS_OP_ERR otherwise

Prototype

int aws_http_proxy_new_socket_channel( struct aws_socket_channel_bootstrap_options *channel_options, const struct aws_http_proxy_options *proxy_options);
source
LibAWSCRT.aws_http_proxy_options_init_from_config — Method
aws_http_proxy_options_init_from_config(options, config)

Initializes non-persistent http proxy options from a persistent http proxy configuration

Parameters

  • options: http proxy options to initialize
  • config: the http proxy config to use as an initialization source

Prototype

void aws_http_proxy_options_init_from_config( struct aws_http_proxy_options *options, const struct aws_http_proxy_config *config);
source
LibAWSCRT.aws_http_proxy_strategy_acquire — Method
aws_http_proxy_strategy_acquire(proxy_strategy)

Take a reference to an http proxy strategy

Parameters

  • proxy_strategy: strategy to take a reference to

Returns

the strategy

Prototype

struct aws_http_proxy_strategy *aws_http_proxy_strategy_acquire(struct aws_http_proxy_strategy *proxy_strategy);
source
LibAWSCRT.aws_http_proxy_strategy_create_negotiator — Method
aws_http_proxy_strategy_create_negotiator(strategy, allocator)

Creates a new proxy negotiator from a proxy strategy

Parameters

  • allocator: memory allocator to use
  • strategy: strategy to creation a new negotiator for

Returns

a new proxy negotiator if successful, otherwise NULL

Prototype

struct aws_http_proxy_negotiator *aws_http_proxy_strategy_create_negotiator( struct aws_http_proxy_strategy *strategy, struct aws_allocator *allocator);
source
LibAWSCRT.aws_http_proxy_strategy_new_basic_auth — Method
aws_http_proxy_strategy_new_basic_auth(allocator, config)

A constructor for a proxy strategy that performs basic authentication by adding the appropriate header and header value to requests or CONNECT requests.

Parameters

  • allocator: memory allocator to use
  • config: basic authentication configuration info

Returns

a new proxy strategy if successfully constructed, otherwise NULL

Prototype

struct aws_http_proxy_strategy *aws_http_proxy_strategy_new_basic_auth( struct aws_allocator *allocator, struct aws_http_proxy_strategy_basic_auth_options *config);
source
LibAWSCRT.aws_http_proxy_strategy_new_tunneling_adaptive — Method
aws_http_proxy_strategy_new_tunneling_adaptive(allocator, config)

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.

Parameters

  • allocator: memory allocator to use
  • config: configuration options for the strategy

Returns

a new proxy strategy if successfully constructed, otherwise NULL

Prototype

struct aws_http_proxy_strategy *aws_http_proxy_strategy_new_tunneling_adaptive( struct aws_allocator *allocator, struct aws_http_proxy_strategy_tunneling_adaptive_options *config);
source
LibAWSCRT.aws_http_proxy_strategy_release — Method
aws_http_proxy_strategy_release(proxy_strategy)

Release a reference to an http proxy strategy

Parameters

  • proxy_strategy: strategy to release a reference to

Prototype

void aws_http_proxy_strategy_release(struct aws_http_proxy_strategy *proxy_strategy);
source
LibAWSCRT.aws_http_server_new — Method
aws_http_server_new(options)

Create server, a listening socket that accepts incoming connections.

Prototype

struct aws_http_server *aws_http_server_new(const struct aws_http_server_options *options);
source
LibAWSCRT.aws_http_server_release — Method
aws_http_server_release(server)

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

Prototype

void aws_http_server_release(struct aws_http_server *server);
source
LibAWSCRT.aws_http_status_text — Method
aws_http_status_text(status_code)

Returns the description of common status codes. Ex: 404 -> "Not Found" An empty string is returned if the status code is not recognized.

Prototype

const char *aws_http_status_text(int status_code);
source
LibAWSCRT.aws_http_stream_acquire — Method
aws_http_stream_acquire(stream)

Acquire refcount on the stream to prevent it from being cleaned up until it is released.

Prototype

struct aws_http_stream *aws_http_stream_acquire(struct aws_http_stream *stream);
source
LibAWSCRT.aws_http_stream_get_id — Method
aws_http_stream_get_id(stream)

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()

Prototype

uint32_t aws_http_stream_get_id(const struct aws_http_stream *stream);
source
LibAWSCRT.aws_http_stream_release — Method
aws_http_stream_release(stream)

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.

Tips for language bindings: - Invoke this from the wrapper class's finalizer/destructor. - Do not let the wrapper class be destroyed until on_complete() has fired.

Prototype

void aws_http_stream_release(struct aws_http_stream *stream);
source
LibAWSCRT.aws_http_stream_send_response — Method
aws_http_stream_send_response(stream, response)

Send response (only callable from "request handler" streams) The response object must stay alive at least until the stream's on_complete is called.

Prototype

int aws_http_stream_send_response(struct aws_http_stream *stream, struct aws_http_message *response);
source
LibAWSCRT.aws_http_stream_update_window — Method
aws_http_stream_update_window(stream, increment_size)

Increment the stream's flow-control window to keep data flowing.

If the connection was created with manual_window_management set true, the flow-control window of each stream will shrink as body data is received (headers, padding, and other metadata do not affect the window). The connection's initial_window_size determines the starting size of each stream's window. If a stream's flow-control window reaches 0, no further data will be received.

If manual_window_management is false, this call will have no effect. The connection maintains its flow-control windows such that no back-pressure is applied and data arrives as fast as possible.

Prototype

void aws_http_stream_update_window(struct aws_http_stream *stream, size_t increment_size);
source
LibAWSCRT.aws_huffman_decode — Method
aws_huffman_decode(decoder, to_decode, output)

Decodes a byte buffer into the provided symbol array.

Parameters

  • decoder:[in] The decoder object to use
  • to_decode:[in] The encoded byte buffer to read from
  • output:[in] The buffer to write decoded symbols to. If decoder is set to allow growth, capacity will be increased when necessary.

Returns

AWS_OP_SUCCESS if encoding is successful, AWS_OP_ERR otherwise

Prototype

int aws_huffman_decode( struct aws_huffman_decoder *decoder, struct aws_byte_cursor *to_decode, struct aws_byte_buf *output);
source
LibAWSCRT.aws_huffman_decoder_allow_growth — Method
aws_huffman_decoder_allow_growth(decoder, allow_growth)

Set whether or not to increase capacity when the output buffer fills up while decoding. This is false by default.

Prototype

void aws_huffman_decoder_allow_growth(struct aws_huffman_decoder *decoder, bool allow_growth);
source
LibAWSCRT.aws_huffman_decoder_init — Method
aws_huffman_decoder_init(decoder, coder)

Initialize a decoder object with a symbol coder.

Prototype

void aws_huffman_decoder_init(struct aws_huffman_decoder *decoder, struct aws_huffman_symbol_coder *coder);
source
LibAWSCRT.aws_huffman_decoder_reset — Method
aws_huffman_decoder_reset(decoder)

Resets a decoder for use with a new binary stream

Prototype

void aws_huffman_decoder_reset(struct aws_huffman_decoder *decoder);
source
LibAWSCRT.aws_huffman_encode — Method
aws_huffman_encode(encoder, to_encode, output)

Encode a symbol buffer into the output buffer.

Parameters

  • encoder:[in] The encoder object to use
  • to_encode:[in] The symbol buffer to encode
  • output:[in] The buffer to write encoded bytes to

Returns

AWS_OP_SUCCESS if encoding is successful, AWS_OP_ERR otherwise

Prototype

int aws_huffman_encode( struct aws_huffman_encoder *encoder, struct aws_byte_cursor *to_encode, struct aws_byte_buf *output);
source
LibAWSCRT.aws_huffman_encoder_init — Method
aws_huffman_encoder_init(encoder, coder)

Initialize a encoder object with a symbol coder.

Prototype

void aws_huffman_encoder_init(struct aws_huffman_encoder *encoder, struct aws_huffman_symbol_coder *coder);
source
LibAWSCRT.aws_huffman_encoder_reset — Method
aws_huffman_encoder_reset(encoder)

Resets a decoder for use with a new binary stream

Prototype

void aws_huffman_encoder_reset(struct aws_huffman_encoder *encoder);
source
LibAWSCRT.aws_huffman_get_encoded_length — Method
aws_huffman_get_encoded_length(encoder, to_encode)

Get the byte length of to_encode post-encoding.

Parameters

  • encoder:[in] The encoder object to use
  • to_encode:[in] The symbol buffer to encode

Returns

The length of the encoded string.

Prototype

size_t aws_huffman_get_encoded_length(struct aws_huffman_encoder *encoder, struct aws_byte_cursor to_encode);
source
LibAWSCRT.aws_imds_client_acquire — Method
aws_imds_client_acquire(client)

Increments the ref count on the client

Parameters

  • client: imds client to acquire a reference to

Prototype

void aws_imds_client_acquire(struct aws_imds_client *client);
source
LibAWSCRT.aws_imds_client_get_ami_id — Method
aws_imds_client_get_ami_id(client, callback, user_data)

Gets the ami id of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_ami_id( struct aws_imds_client *client, aws_imds_client_on_get_resource_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_ami_launch_index — Method
aws_imds_client_get_ami_launch_index(client, callback, user_data)

Gets the ami launch index of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_ami_launch_index( struct aws_imds_client *client, aws_imds_client_on_get_resource_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_ami_manifest_path — Method
aws_imds_client_get_ami_manifest_path(client, callback, user_data)

Gets the ami manifest path of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_ami_manifest_path( struct aws_imds_client *client, aws_imds_client_on_get_resource_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_ancestor_ami_ids — Method
aws_imds_client_get_ancestor_ami_ids(client, callback, user_data)

Gets the list of ancestor ami ids of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_ancestor_ami_ids( struct aws_imds_client *client, aws_imds_client_on_get_array_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_attached_iam_role — Method
aws_imds_client_get_attached_iam_role(client, callback, user_data)

Gets the attached iam role of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_attached_iam_role( struct aws_imds_client *client, aws_imds_client_on_get_resource_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_availability_zone — Method
aws_imds_client_get_availability_zone(client, callback, user_data)

Gets the availability zone of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_availability_zone( struct aws_imds_client *client, aws_imds_client_on_get_resource_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_block_device_mapping — Method
aws_imds_client_get_block_device_mapping(client, callback, user_data)

Gets the list of block device mappings of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_block_device_mapping( struct aws_imds_client *client, aws_imds_client_on_get_array_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_credentials — Method
aws_imds_client_get_credentials(client, iam_role_name, callback, user_data)

Gets temporary credentials based on the attached iam role of the ec2 instance

Parameters

  • client: imds client to use for the query
  • iam_role_name: iam role name to get temporary credentials through
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_credentials( struct aws_imds_client *client, struct aws_byte_cursor iam_role_name, aws_imds_client_on_get_credentials_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_iam_profile — Method
aws_imds_client_get_iam_profile(client, callback, user_data)

Gets the iam profile information of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_iam_profile( struct aws_imds_client *client, aws_imds_client_on_get_iam_profile_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_instance_action — Method
aws_imds_client_get_instance_action(client, callback, user_data)

Gets the instance-action of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_instance_action( struct aws_imds_client *client, aws_imds_client_on_get_resource_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_instance_id — Method
aws_imds_client_get_instance_id(client, callback, user_data)

Gets the instance id of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_instance_id( struct aws_imds_client *client, aws_imds_client_on_get_resource_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_instance_info — Method
aws_imds_client_get_instance_info(client, callback, user_data)

Gets the instance information data block of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_instance_info( struct aws_imds_client *client, aws_imds_client_on_get_instance_info_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_instance_signature — Method
aws_imds_client_get_instance_signature(client, callback, user_data)

Gets the signature of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_instance_signature( struct aws_imds_client *client, aws_imds_client_on_get_resource_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_instance_type — Method
aws_imds_client_get_instance_type(client, callback, user_data)

Gets the instance type of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_instance_type( struct aws_imds_client *client, aws_imds_client_on_get_resource_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_mac_address — Method
aws_imds_client_get_mac_address(client, callback, user_data)

Gets the mac address of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_mac_address( struct aws_imds_client *client, aws_imds_client_on_get_resource_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_private_ip_address — Method
aws_imds_client_get_private_ip_address(client, callback, user_data)

Gets the private ip address of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_private_ip_address( struct aws_imds_client *client, aws_imds_client_on_get_resource_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_product_codes — Method
aws_imds_client_get_product_codes(client, callback, user_data)

Gets the product codes of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_product_codes( struct aws_imds_client *client, aws_imds_client_on_get_resource_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_public_key — Method
aws_imds_client_get_public_key(client, callback, user_data)

Gets the public key of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_public_key( struct aws_imds_client *client, aws_imds_client_on_get_resource_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_ramdisk_id — Method
aws_imds_client_get_ramdisk_id(client, callback, user_data)

Gets the ramdisk id of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_ramdisk_id( struct aws_imds_client *client, aws_imds_client_on_get_resource_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_reservation_id — Method
aws_imds_client_get_reservation_id(client, callback, user_data)

Gets the reservation id of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_reservation_id( struct aws_imds_client *client, aws_imds_client_on_get_resource_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_resource_async — Method
aws_imds_client_get_resource_async(client, resource_path, callback, user_data)

Queries a generic resource (string) from the ec2 instance metadata document

Parameters

  • client: imds client to use for the query
  • resource_path: path of the resource to query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_resource_async( struct aws_imds_client *client, struct aws_byte_cursor resource_path, aws_imds_client_on_get_resource_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_security_groups — Method
aws_imds_client_get_security_groups(client, callback, user_data)

Gets the list of the security groups of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_security_groups( struct aws_imds_client *client, aws_imds_client_on_get_array_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_get_user_data — Method
aws_imds_client_get_user_data(client, callback, user_data)

Gets the user data of the ec2 instance from the instance metadata document

Parameters

  • client: imds client to use for the query
  • callback: callback function to invoke on query success or failure
  • user_data: opaque data to invoke the completion callback with

Returns

AWS_OP_SUCCESS if the query was successfully started, AWS_OP_ERR otherwise

Prototype

int aws_imds_client_get_user_data( struct aws_imds_client *client, aws_imds_client_on_get_resource_callback_fn callback, void *user_data);
source
LibAWSCRT.aws_imds_client_new — Method
aws_imds_client_new(allocator, options)

Creates a new imds client

Parameters

  • allocator: memory allocator to use for creation and queries
  • options: configuration options for the imds client

Returns

a newly-constructed imds client, or NULL on failure

Prototype

struct aws_imds_client *aws_imds_client_new( struct aws_allocator *allocator, const struct aws_imds_client_options *options);
source
LibAWSCRT.aws_imds_client_release — Method
aws_imds_client_release(client)

Decrements the ref count on the client

Parameters

  • client: imds client to release a reference to

Prototype

void aws_imds_client_release(struct aws_imds_client *client);
source
LibAWSCRT.aws_input_stream_acquire — Method
aws_input_stream_acquire(stream)

Increments the reference count on the input stream, allowing the caller to take a reference to it.

Returns the same input stream passed in.

Prototype

struct aws_input_stream *aws_input_stream_acquire(struct aws_input_stream *stream);
source
LibAWSCRT.aws_input_stream_new_from_cursor — Method
aws_input_stream_new_from_cursor(allocator, cursor)

Prototype

struct aws_input_stream *aws_input_stream_new_from_cursor( struct aws_allocator *allocator, const struct aws_byte_cursor *cursor);
source
LibAWSCRT.aws_input_stream_new_from_file — Method
aws_input_stream_new_from_file(allocator, file_name)

Prototype

struct aws_input_stream *aws_input_stream_new_from_file( struct aws_allocator *allocator, const char *file_name);
source
LibAWSCRT.aws_input_stream_release — Method
aws_input_stream_release(stream)

Decrements a input stream's ref count. When the ref count drops to zero, the input stream will be destroyed.

Returns NULL always.

Prototype

struct aws_input_stream *aws_input_stream_release(struct aws_input_stream *stream);
source
LibAWSCRT.aws_input_stream_seek — Method
aws_input_stream_seek(stream, offset, basis)

Prototype

int aws_input_stream_seek(struct aws_input_stream *stream, int64_t offset, enum aws_stream_seek_basis basis);
source
LibAWSCRT.aws_io_library_init — Method
aws_io_library_init(allocator)

Initializes internal datastructures used by aws-c-io. Must be called before using any functionality in aws-c-io.

Prototype

void aws_io_library_init(struct aws_allocator *allocator);
source
LibAWSCRT.aws_iotdevice_defender_config_clean_up — Method
aws_iotdevice_defender_config_clean_up(config)

Destroys a new reporting task for Device Defender metrics

Parameters

  • config:[in] defender task configuration

Prototype

void aws_iotdevice_defender_config_clean_up(struct aws_iotdevice_defender_task_config *config);
source
LibAWSCRT.aws_iotdevice_defender_config_create — Method
aws_iotdevice_defender_config_create(config_out, allocator, thing_name, report_format)

Creates a new reporting task config for Device Defender metrics collection

Parameters

  • config_out:[in] output to write a pointer to a task configuration. Will write non-NULL if successful in creating the the task configuration. Will write NULL if there is an error during creation
  • allocator:[in] allocator to use for the task configuration's internal data, and the task itself when started
  • thing_name:[in] thing name the task config is reporting for
  • report_format:[in] report format to produce when publishing to IoT

Returns

AWS_OP_SUCCESS and config_out will be non-NULL. Returns an error code otherwise

Prototype

int aws_iotdevice_defender_config_create( struct aws_iotdevice_defender_task_config **config_out, struct aws_allocator *allocator, const struct aws_byte_cursor *thing_name, enum aws_iotdevice_defender_report_format report_format);
source
LibAWSCRT.aws_iotdevice_defender_config_register_ip_list_metric — Method
aws_iotdevice_defender_config_register_ip_list_metric(task_config, metric_name, supplier, userdata)

Adds IP list custom metric to the Device Defender task configuration. Has no impact on a defender task already started using the configuration.

Parameters

  • task_config:[in] the defender task configuration to register the metric to
  • metric_name:[in] UTF8 byte string of the metric name
  • supplier:[in] callback function to produce the metric value when requested at report generation time
  • userdata:[in] specific callback data for the supplier callback function

Prototype

void aws_iotdevice_defender_config_register_ip_list_metric( struct aws_iotdevice_defender_task_config *task_config, const struct aws_byte_cursor *metric_name, aws_iotdevice_defender_get_ip_list_fn *supplier, void *userdata);
source
LibAWSCRT.aws_iotdevice_defender_config_register_number_list_metric — Method
aws_iotdevice_defender_config_register_number_list_metric(task_config, metric_name, supplier, userdata)

Adds number list custom metric to the Device Defender task configuration. Has no impact on a defender task already started using the configuration.

Parameters

  • task_config:[in] the defender task configuration to register the metric to
  • metric_name:[in] UTF8 byte string of the metric name
  • supplier:[in] callback function to produce the metric value when requested at report generation time
  • userdata:[in] specific callback data for the supplier callback function

Prototype

void aws_iotdevice_defender_config_register_number_list_metric( struct aws_iotdevice_defender_task_config *task_config, const struct aws_byte_cursor *metric_name, aws_iotdevice_defender_get_number_list_fn *supplier, void *userdata);
source
LibAWSCRT.aws_iotdevice_defender_config_register_number_metric — Method
aws_iotdevice_defender_config_register_number_metric(task_config, metric_name, supplier, userdata)

Adds number custom metric to the Device Defender task configuration. Has no impact on a defender task already started using the configuration.

Parameters

  • task_config:[in] the defender task configuration to register the metric to
  • metric_name:[in] UTF8 byte string of the metric name
  • supplier:[in] callback function to produce the metric value when requested at report generation time
  • userdata:[in] specific callback data for the supplier callback function

Prototype

void aws_iotdevice_defender_config_register_number_metric( struct aws_iotdevice_defender_task_config *task_config, const struct aws_byte_cursor *metric_name, aws_iotdevice_defender_get_number_fn *supplier, void *userdata);
source
LibAWSCRT.aws_iotdevice_defender_config_register_string_list_metric — Method
aws_iotdevice_defender_config_register_string_list_metric(task_config, metric_name, supplier, userdata)

Adds string list custom metric to the Device Defender task configuration. Has no impact on a defender task already started using the configuration.

Parameters

  • task_config:[in] the defender task configuration to register the metric to
  • metric_name:[in] UTF8 byte string of the metric name
  • supplier:[in] callback function to produce the metric value when requested at report generation time
  • userdata:[in] specific callback data for the supplier callback function

Prototype

void aws_iotdevice_defender_config_register_string_list_metric( struct aws_iotdevice_defender_task_config *task_config, const struct aws_byte_cursor *metric_name, aws_iotdevice_defender_get_string_list_fn *supplier, void *userdata);
source
LibAWSCRT.aws_iotdevice_defender_config_set_callback_userdata — Method
aws_iotdevice_defender_config_set_callback_userdata(config, userdata)

Sets the userdata for the device defender task's callback functions

Parameters

  • config:[in] defender task configuration
  • userdata:[in] how much time in nanoseconds between defender task runs

Returns

AWS_OP_SUCCESS when the property has been set properly. Returns an error code if the value was not able to be set

Prototype

int aws_iotdevice_defender_config_set_callback_userdata( struct aws_iotdevice_defender_task_config *config, void *userdata);
source
LibAWSCRT.aws_iotdevice_defender_config_set_report_accepted_fn — Method
aws_iotdevice_defender_config_set_report_accepted_fn(config, accepted_fn)

Sets the report rejected callback function to invoke when is canceled and not going to be scheduled to run. This is a suggestion of when it is OK to close or free resources kept around while the task is running.

Parameters

  • config:[in] defender task configuration
  • accepted_fn:[in] accepted report callback function

Returns

AWS_OP_SUCCESS when the report accepted callback has been set. Returns an error if the callback was not set

Prototype

int aws_iotdevice_defender_config_set_report_accepted_fn( struct aws_iotdevice_defender_task_config *config, aws_iotdevice_defender_report_accepted_fn *accepted_fn);
source
LibAWSCRT.aws_iotdevice_defender_config_set_report_rejected_fn — Method
aws_iotdevice_defender_config_set_report_rejected_fn(config, rejected_fn)

Sets the report rejected callback function to invoke when is canceled and not going to be scheduled to run. This is a suggestion of when it is OK to close or free resources kept around while the task is running.

Parameters

  • config:[in] defender task configuration
  • rejected_fn:[in] rejected report callback function

Returns

AWS_OP_SUCCESS when the report rejected callback has been set. Returns an error if the callback was not set

Prototype

int aws_iotdevice_defender_config_set_report_rejected_fn( struct aws_iotdevice_defender_task_config *config, aws_iotdevice_defender_report_rejected_fn *rejected_fn);
source
LibAWSCRT.aws_iotdevice_defender_config_set_task_cancelation_fn — Method
aws_iotdevice_defender_config_set_task_cancelation_fn(config, cancel_fn)

Sets the task cancelation callback function to invoke when the task is canceled and not going to be scheduled to run. This is a suggestion of when it is OK to close or free resources kept around while the task is running.

Parameters

  • config:[in] defender task configuration
  • cancel_fn:[in] cancelation callback function

Returns

AWS_OP_SUCCESS when the task cancelation callback has been set. Returns an error if the callback was not set

Prototype

int aws_iotdevice_defender_config_set_task_cancelation_fn( struct aws_iotdevice_defender_task_config *config, aws_iotdevice_defender_task_canceled_fn *cancel_fn);
source
LibAWSCRT.aws_iotdevice_defender_config_set_task_failure_fn — Method
aws_iotdevice_defender_config_set_task_failure_fn(config, failure_fn)

Sets the task failure callback function to invoke when the running of the task encounters a failure. Though this is optional to specify, it is important to register a handler to at least monitor failure that stops the task from running

The most likely scenario for task not being able to continue is failure to reschedule the task

Parameters

  • config:[in] defender task configuration
  • failure_fn:[in] failure callback function

Returns

AWS_OP_SUCCESS when the task failure callback has been set. Returns an error if the callback was not set

Prototype

int aws_iotdevice_defender_config_set_task_failure_fn( struct aws_iotdevice_defender_task_config *config, aws_iotdevice_defender_task_failure_fn *failure_fn);
source
LibAWSCRT.aws_iotdevice_defender_config_set_task_period_ns — Method
aws_iotdevice_defender_config_set_task_period_ns(config, task_period_ns)

Sets the period of the device defender task

Parameters

  • config:[in] defender task configuration
  • task_period_ns:[in] how much time in nanoseconds between defender task runs

Returns

AWS_OP_SUCCESS when the property has been set properly. Returns an error code if the value was not able to be set.

Prototype

int aws_iotdevice_defender_config_set_task_period_ns( struct aws_iotdevice_defender_task_config *config, uint64_t task_period_ns);
source
LibAWSCRT.aws_iotdevice_defender_task_clean_up — Method
aws_iotdevice_defender_task_clean_up(defender_task)

Cancels the running task reporting Device Defender metrics and cleans up. If the task is currently running, it will block until the task has been canceled and cleaned up successfully

Parameters

  • defender_task:[in] running task to stop and clean up

Prototype

void aws_iotdevice_defender_task_clean_up(struct aws_iotdevice_defender_task *defender_task);
source
LibAWSCRT.aws_iotdevice_defender_task_create — Method
aws_iotdevice_defender_task_create(task_out, config, connection, event_loop)

Creates and starts a new Device Defender reporting task

Parameters

  • task_out:[out] output parameter to set to point to the defender task
  • config:[in] defender task configuration to use to start the task
  • connection:[in] mqtt connection to use to publish reports to
  • event_loop:[in] IoT device thing name used to determine the MQTT topic to publish the report to and listen for accepted or rejected responses

Returns

AWS_OP_SUCCESS if the task has been created successfully and is scheduled to run

Prototype

int aws_iotdevice_defender_task_create( struct aws_iotdevice_defender_task **task_out, const struct aws_iotdevice_defender_task_config *config, struct aws_mqtt_client_connection *connection, struct aws_event_loop *event_loop);
source
LibAWSCRT.aws_iotdevice_defender_task_create_ex — Method
aws_iotdevice_defender_task_create_ex(task_out, config, publish_fn, event_loop)

Creates and starts a new Device Defender reporting task with the ability to define a function to accept/handle each report when the task needs to publish.

Parameters

  • task_out:[out] output parameter to set to point to the defender task
  • config:[in] defender task configuration to use to start the task
  • publish_fn:[in] callback to handle reports generated by the task. The userdata comes from the task config
  • event_loop:[in] IoT device thing name used to determine the MQTT topic to publish the report to and listen for accepted or rejected responses

Returns

AWS_OP_SUCCESS if the task has been created successfully and is scheduled to run

Prototype

int aws_iotdevice_defender_task_create_ex( struct aws_iotdevice_defender_task **task_out, const struct aws_iotdevice_defender_task_config *config, aws_iotdevice_defender_publish_fn *publish_fn, struct aws_event_loop *event_loop);
source
LibAWSCRT.aws_iotdevice_library_init — Method
aws_iotdevice_library_init(allocator)

Initializes internal datastructures used by aws-c-iot. Must be called before using any functionality in aws-c-iot.

Prototype

void aws_iotdevice_library_init(struct aws_allocator *allocator);
source
LibAWSCRT.aws_is_any_directory_separator — Method
aws_is_any_directory_separator(value)

Returns true iff the character is a directory separator on ANY supported platform.

Prototype

bool aws_is_any_directory_separator(char value);
source
LibAWSCRT.aws_is_big_endian — Method
aws_is_big_endian()

Returns 1 if machine is big endian, 0 if little endian. If you compile with even -O1 optimization, this check is completely optimized out at compile time and code which calls "if (aws_is_big_endian())" will do the right thing without branching.

Prototype

AWS_STATIC_IMPL int aws_is_big_endian(void);
source
LibAWSCRT.aws_is_mem_zeroed — Method
aws_is_mem_zeroed(buf, bufsize)

Returns whether each byte is zero.

Prototype

AWS_STATIC_IMPL bool aws_is_mem_zeroed(const void *buf, size_t bufsize);
source
LibAWSCRT.aws_isalnum — Method
aws_isalnum(ch)

Like isalnum(), but ignores C locale. Returns true if ch has the value of ASCII/UTF-8: 'a'-'z', 'A'-'Z', or '0'-'9'.

Prototype

bool aws_isalnum(uint8_t ch);
source
LibAWSCRT.aws_isalpha — Method
aws_isalpha(ch)

Like isalpha(), but ignores C locale. Returns true if ch has the value of ASCII/UTF-8: 'a'-'z' or 'A'-'Z'.

Prototype

bool aws_isalpha(uint8_t ch);
source
LibAWSCRT.aws_isdigit — Method
aws_isdigit(ch)

Like isdigit(). Returns true if ch has the value of ASCII/UTF-8: '0'-'9'.

Note: C's built-in isdigit() is also supposed to ignore the C locale, but cppreference.com claims "some implementations (e.g. Microsoft in 1252 codepage) may classify additional single-byte characters as digits"

Prototype

bool aws_isdigit(uint8_t ch);
source
LibAWSCRT.aws_isspace — Method
aws_isspace(ch)

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).

Prototype

bool aws_isspace(uint8_t ch);
source
LibAWSCRT.aws_isxdigit — Method
aws_isxdigit(ch)

Like isxdigit(). Returns true if ch has the value of ASCII/UTF-8: '0'-'9', 'a'-'f', or 'A'-'F'.

Note: C's built-in isxdigit() is also supposed to ignore the C locale, but cppreference.com claims "some implementations (e.g. Microsoft in 1252 codepage) may classify additional single-byte characters as digits"

Prototype

bool aws_isxdigit(uint8_t ch);
source
LibAWSCRT.aws_json_const_iterate_array — Method
aws_json_const_iterate_array(array, on_value, user_data)

iterates through values of an array. iteration is sequential starting with 0th element.

Parameters

  • array: array to iterate over.
  • on_value: callback for when value is encountered.
  • user_data: user data to pass back in callback.

Returns

AWS_OP_SUCCESS when iteration finishes completely or exits early, AWS_OP_ERR if value is not an array.

Prototype

int aws_json_const_iterate_array( const struct aws_json_value *array, aws_json_on_value_encountered_const_fn *on_value, void *user_data);
source
LibAWSCRT.aws_json_const_iterate_object — Method
aws_json_const_iterate_object(object, on_member, user_data)

iterates through members of the object. iteration is sequential in order fields were initially parsed.

Parameters

  • object: object to iterate over.
  • on_member: callback for when member is encountered.
  • user_data: user data to pass back in callback.

Returns

AWS_OP_SUCCESS when iteration finishes completely or exits early, AWS_OP_ERR if value is not an object.

Prototype

int aws_json_const_iterate_object( const struct aws_json_value *object, aws_json_on_member_encountered_const_fn *on_member, void *user_data);
source
LibAWSCRT.aws_json_value_add_array_element — Method
aws_json_value_add_array_element(array, value)

Adds a aws_json_value to the given array aws_json_value.

Note that the aws_json_value will be destroyed when the aws_json_value array is destroyed by calling "aws_json_destroy()"

Parameters

Returns

AWS_OP_SUCCESS if adding the aws_json_value was successful. Will return AWS_OP_ERR if the array passed is invalid.

Prototype

int aws_json_value_add_array_element(struct aws_json_value *array, const struct aws_json_value *value);
source
LibAWSCRT.aws_json_value_add_to_object — Method
aws_json_value_add_to_object(object, key, value)

Adds a aws_json_value to a object aws_json_value.

Note that the aws_json_value will be destroyed when the aws_json_value object is destroyed by calling "aws_json_destroy()"

Parameters

Returns

AWS_OP_SUCCESS if adding was successful. Will return AWS_OP_ERROR if the object passed is invalid or if the passed key is already in use in the object.

Prototype

int aws_json_value_add_to_object( struct aws_json_value *object, struct aws_byte_cursor key, struct aws_json_value *value);
source
LibAWSCRT.aws_json_value_compare — Method
aws_json_value_compare(a, b, is_case_sensitive)

Checks whether two json values are equivalent.

Parameters

  • a: first value to compare.
  • b: second value to compare.
  • is_case_sensitive: case sensitive compare or not.

Returns

True is values are equal, false otherwise

Prototype

bool aws_json_value_compare(const struct aws_json_value *a, const struct aws_json_value *b, bool is_case_sensitive);
source
LibAWSCRT.aws_json_value_destroy — Method
aws_json_value_destroy(value)

Removes the aws_json_value from memory. If the aws_json_value is a object or array, it will also destroy attached aws_json_values as well.

For example, if you called "aws_json_array_add(b, a)" to add an object "a" to an array "b", if you call "aws_json_destroy(b)" then it will also free "a" automatically. All children/attached aws_json_values are freed when the parent/root aws_json_value is destroyed.

Parameters

Prototype

void aws_json_value_destroy(struct aws_json_value *value);
source
LibAWSCRT.aws_json_value_duplicate — Method
aws_json_value_duplicate(value)

Duplicates json value.

Parameters

  • value: first value to compare.

Returns

duplicated value. NULL and last error set if value cannot be duplicated.

Prototype

struct aws_json_value *aws_json_value_duplicate(const struct aws_json_value *value);
source
LibAWSCRT.aws_json_value_has_key — Method
aws_json_value_has_key(object, key)

Checks if there is a aws_json_value at the given key.

Parameters

  • object: The value aws_json_value you want to check a key in.
  • key: The key that you want to check. Is case sensitive.

Returns

True if a aws_json_value is found.

Prototype

bool aws_json_value_has_key(const struct aws_json_value *object, struct aws_byte_cursor key);
source
LibAWSCRT.aws_json_value_new_array — Method
aws_json_value_new_array(allocator)

Creates a new array aws_json_value and returns a pointer to it.

Note: You will need to free the memory for the aws_json_value using aws_json_destroy on the aws_json_value or on the object/array containing the aws_json_value. Deleting this array will also destroy any aws_json_values it contains.

Parameters

  • allocator: The allocator to use when creating the value

Returns

A new array aws_json_value

Prototype

struct aws_json_value *aws_json_value_new_array(struct aws_allocator *allocator);
source
LibAWSCRT.aws_json_value_new_boolean — Method
aws_json_value_new_boolean(allocator, boolean)

Creates a new boolean aws_json_value with the given boolean and returns a pointer to it.

Note: You will need to free the memory for the aws_json_value using aws_json_destroy on the aws_json_value or on the object/array containing the aws_json_value.

Parameters

  • boolean: The boolean you want to store in the aws_json_value
  • allocator: The allocator to use when creating the value

Returns

A new boolean aws_json_value

Prototype

struct aws_json_value *aws_json_value_new_boolean(struct aws_allocator *allocator, bool boolean);
source
LibAWSCRT.aws_json_value_new_from_string — Method
aws_json_value_new_from_string(allocator, string)

Parses the JSON string and returns a aws_json_value containing the root of the JSON.

Parameters

  • allocator: The allocator used to create the value
  • string: The string containing the JSON.

Returns

The root aws_json_value of the JSON.

Prototype

struct aws_json_value *aws_json_value_new_from_string(struct aws_allocator *allocator, struct aws_byte_cursor string);
source
LibAWSCRT.aws_json_value_new_number — Method
aws_json_value_new_number(allocator, number)

Creates a new number aws_json_value with the given number and returns a pointer to it.

Note: You will need to free the memory for the aws_json_value using aws_json_destroy on the aws_json_value or on the object/array containing the aws_json_value.

Parameters

  • number: The number you want to store in the aws_json_value
  • allocator: The allocator to use when creating the value

Returns

A new number aws_json_value

Prototype

struct aws_json_value *aws_json_value_new_number(struct aws_allocator *allocator, double number);
source
LibAWSCRT.aws_json_value_new_object — Method
aws_json_value_new_object(allocator)

Creates a new object aws_json_value and returns a pointer to it.

Note: You will need to free the memory for the aws_json_value using aws_json_destroy on the aws_json_value or on the object/array containing the aws_json_value. Deleting this object will also destroy any aws_json_values it contains.

Parameters

  • allocator: The allocator to use when creating the value

Returns

A new object aws_json_value

Prototype

struct aws_json_value *aws_json_value_new_object(struct aws_allocator *allocator);
source
LibAWSCRT.aws_json_value_new_string — Method
aws_json_value_new_string(allocator, string)

Creates a new string aws_json_value with the given string and returns a pointer to it.

Note: You will need to free the memory for the aws_json_value using aws_json_destroy on the aws_json_value or on the object/array containing the aws_json_value.

Parameters

  • string: A byte pointer to the string you want to store in the aws_json_value
  • allocator: The allocator to use when creating the value

Returns

A new string aws_json_value

Prototype

struct aws_json_value *aws_json_value_new_string(struct aws_allocator *allocator, struct aws_byte_cursor string);
source
LibAWSCRT.aws_json_value_remove_array_element — Method
aws_json_value_remove_array_element(array, index)

Removes the aws_json_value at the given index in the array aws_json_value.

Parameters

Returns

AWS_OP_SUCCESS if the aws_json_value at the index was removed. Will return AWS_OP_ERR if the array passed is invalid or if the index passed is out of range.

Prototype

int aws_json_value_remove_array_element(struct aws_json_value *array, size_t index);
source
LibAWSCRT.aws_json_value_remove_from_object — Method
aws_json_value_remove_from_object(object, key)

Removes the aws_json_value at the given key.

Parameters

Returns

AWS_OP_SUCCESS if the aws_json_value was removed. Will return AWS_OP_ERR if the object passed is invalid or if the value at the key cannot be found.

Prototype

int aws_json_value_remove_from_object(struct aws_json_value *object, struct aws_byte_cursor key);
source
LibAWSCRT.aws_linked_hash_table_clean_up — Method
aws_linked_hash_table_clean_up(table)

Cleans up the table. Elements in the table will be evicted and cleanup callbacks will be invoked.

Prototype

void aws_linked_hash_table_clean_up(struct aws_linked_hash_table *table);
source
LibAWSCRT.aws_linked_hash_table_find — Method
aws_linked_hash_table_find(table, key, p_value)

Finds element in the table by key. If found, AWS_OP_SUCCESS will be returned. If not found, AWS_OP_SUCCESS will be returned and *p_value will be NULL.

If any errors occur AWS_OP_ERR will be returned.

Prototype

int aws_linked_hash_table_find(struct aws_linked_hash_table *table, const void *key, void **p_value);
source
LibAWSCRT.aws_linked_hash_table_find_and_move_to_back — Method
aws_linked_hash_table_find_and_move_to_back(table, key, p_value)

Finds element in the table by key. If found, AWS_OP_SUCCESS will be returned and the item will be moved to the back of the list. If not found, AWS_OP_SUCCESS will be returned and *p_value will be NULL.

Note: this will change the order of elements

Prototype

int aws_linked_hash_table_find_and_move_to_back(struct aws_linked_hash_table *table, const void *key, void **p_value);
source
LibAWSCRT.aws_linked_hash_table_init — Method
aws_linked_hash_table_init(table, allocator, hash_fn, equals_fn, destroy_key_fn, destroy_value_fn, initial_item_count)

Initializes the table. Sets up the underlying hash table and linked list. For the other parameters, see aws/common/hash_table.h. Hash table semantics of these arguments are preserved.

Prototype

int aws_linked_hash_table_init( struct aws_linked_hash_table *table, struct aws_allocator *allocator, aws_hash_fn *hash_fn, aws_hash_callback_eq_fn *equals_fn, aws_hash_callback_destroy_fn *destroy_key_fn, aws_hash_callback_destroy_fn *destroy_value_fn, size_t initial_item_count);
source
LibAWSCRT.aws_linked_hash_table_put — Method
aws_linked_hash_table_put(table, key, p_value)

Puts p_value at key. If an element is already stored at key it will be replaced.

Prototype

int aws_linked_hash_table_put(struct aws_linked_hash_table *table, const void *key, void *p_value);
source
LibAWSCRT.aws_linked_hash_table_remove — Method
aws_linked_hash_table_remove(table, key)

Removes item at key from the table.

Prototype

int aws_linked_hash_table_remove(struct aws_linked_hash_table *table, const void *key);
source
LibAWSCRT.aws_linked_list_back — Method
aws_linked_list_back(list)

Returns the element in the back of the list.

Prototype

AWS_STATIC_IMPL struct aws_linked_list_node *aws_linked_list_back(const struct aws_linked_list *list);
source
LibAWSCRT.aws_linked_list_begin — Method
aws_linked_list_begin(list)

Returns an iteration pointer for the first element in the list.

Prototype

AWS_STATIC_IMPL struct aws_linked_list_node *aws_linked_list_begin(const struct aws_linked_list *list);
source
LibAWSCRT.aws_linked_list_empty — Method
aws_linked_list_empty(list)

Tests if the list is empty.

Prototype

AWS_STATIC_IMPL bool aws_linked_list_empty(const struct aws_linked_list *list);
source
LibAWSCRT.aws_linked_list_end — Method
aws_linked_list_end(list)

Returns an iteration pointer for one past the last element in the list.

Prototype

AWS_STATIC_IMPL const struct aws_linked_list_node *aws_linked_list_end(const struct aws_linked_list *list);
source
LibAWSCRT.aws_linked_list_front — Method
aws_linked_list_front(list)

Returns the element in the front of the list.

Prototype

AWS_STATIC_IMPL struct aws_linked_list_node *aws_linked_list_front(const struct aws_linked_list *list);
source
LibAWSCRT.aws_linked_list_init — Method
aws_linked_list_init(list)

Initializes the list. List will be empty after this call.

Prototype

AWS_STATIC_IMPL void aws_linked_list_init(struct aws_linked_list *list);
source
LibAWSCRT.aws_linked_list_insert_after — Method
aws_linked_list_insert_after(after, to_add)

Inserts to_add immediately after after.

Prototype

AWS_STATIC_IMPL void aws_linked_list_insert_after( struct aws_linked_list_node *after, struct aws_linked_list_node *to_add);
source
LibAWSCRT.aws_linked_list_insert_before — Method
aws_linked_list_insert_before(before, to_add)

Inserts to_add immediately before before.

Prototype

AWS_STATIC_IMPL void aws_linked_list_insert_before( struct aws_linked_list_node *before, struct aws_linked_list_node *to_add);
source
LibAWSCRT.aws_linked_list_is_valid — Method
aws_linked_list_is_valid(list)

Checks that a linked list is valid.

Prototype

AWS_STATIC_IMPL bool aws_linked_list_is_valid(const struct aws_linked_list *list);
source
LibAWSCRT.aws_linked_list_is_valid_deep — Method
aws_linked_list_is_valid_deep(list)

Checks that a linked list satisfies double linked list connectivity constraints. This check is O(n) as it traverses the whole linked list to ensure that tail is reachable from head (and vice versa) and that every connection is bidirectional.

Note: This check cannot go into an infinite loop, because we ensure that the connection to the next node is bidirectional. Therefore, if a node's [a] a.next is a previous node [b] in the list, b.prev != &a and so this check would fail, thus terminating the loop.

Prototype

AWS_STATIC_IMPL bool aws_linked_list_is_valid_deep(const struct aws_linked_list *list);
source
LibAWSCRT.aws_linked_list_move_all_back — Method
aws_linked_list_move_all_back(dst, src)

Remove all nodes from one list, and add them to the back of another.

Example: if dst={1,2} and src={3,4}, they become dst={1,2,3,4} and src={}

Prototype

AWS_STATIC_IMPL void aws_linked_list_move_all_back( struct aws_linked_list *AWS_RESTRICT dst, struct aws_linked_list *AWS_RESTRICT src);
source
LibAWSCRT.aws_linked_list_move_all_front — Method
aws_linked_list_move_all_front(dst, src)

Remove all nodes from one list, and add them to the front of another.

Example: if dst={2,1} and src={4,3}, they become dst={4,3,2,1} and src={}

Prototype

AWS_STATIC_IMPL void aws_linked_list_move_all_front( struct aws_linked_list *AWS_RESTRICT dst, struct aws_linked_list *AWS_RESTRICT src);
source
LibAWSCRT.aws_linked_list_next — Method
aws_linked_list_next(node)

Returns the next element in the list.

Prototype

AWS_STATIC_IMPL struct aws_linked_list_node *aws_linked_list_next(const struct aws_linked_list_node *node);
source
LibAWSCRT.aws_linked_list_node_next_is_valid — Method
aws_linked_list_node_next_is_valid(node)

Checks that the prev of the next pointer of a node points to the node. As this checks whether the [next] connection of a node is bidirectional, it returns false if used for the list tail.

Prototype

AWS_STATIC_IMPL bool aws_linked_list_node_next_is_valid(const struct aws_linked_list_node *node);
source
LibAWSCRT.aws_linked_list_node_prev_is_valid — Method
aws_linked_list_node_prev_is_valid(node)

Checks that the next of the prev pointer of a node points to the node. Similarly to the above, this returns false if used for the head of a list.

Prototype

AWS_STATIC_IMPL bool aws_linked_list_node_prev_is_valid(const struct aws_linked_list_node *node);
source
LibAWSCRT.aws_linked_list_node_reset — Method
aws_linked_list_node_reset(node)

Set node's next and prev pointers to NULL.

Prototype

AWS_STATIC_IMPL void aws_linked_list_node_reset(struct aws_linked_list_node *node);
source
LibAWSCRT.aws_linked_list_pop_back — Method
aws_linked_list_pop_back(list)

Returns the element in the back of the list and removes it

Prototype

AWS_STATIC_IMPL struct aws_linked_list_node *aws_linked_list_pop_back(struct aws_linked_list *list);
source
LibAWSCRT.aws_linked_list_pop_front — Method
aws_linked_list_pop_front(list)

Returns the element in the front of the list and removes it

Prototype

AWS_STATIC_IMPL struct aws_linked_list_node *aws_linked_list_pop_front(struct aws_linked_list *list);
source
LibAWSCRT.aws_linked_list_prev — Method
aws_linked_list_prev(node)

Returns the previous element in the list.

Prototype

AWS_STATIC_IMPL struct aws_linked_list_node *aws_linked_list_prev(const struct aws_linked_list_node *node);
source
LibAWSCRT.aws_linked_list_push_back — Method
aws_linked_list_push_back(list, node)

Append new_node.

Prototype

AWS_STATIC_IMPL void aws_linked_list_push_back(struct aws_linked_list *list, struct aws_linked_list_node *node);
source
LibAWSCRT.aws_linked_list_push_front — Method
aws_linked_list_push_front(list, node)

Prepend new_node.

Prototype

AWS_STATIC_IMPL void aws_linked_list_push_front(struct aws_linked_list *list, struct aws_linked_list_node *node);
source
LibAWSCRT.aws_linked_list_remove — Method
aws_linked_list_remove(node)

Removes the specified node from the list (prev/next point to each other) and returns the next node in the list.

Prototype

AWS_STATIC_IMPL void aws_linked_list_remove(struct aws_linked_list_node *node);
source
LibAWSCRT.aws_linked_list_rend — Method
aws_linked_list_rend(list)

Returns the pointer to one before the first element in the list. Used to end iterating the list in reverse.

Prototype

AWS_STATIC_IMPL const struct aws_linked_list_node *aws_linked_list_rend(const struct aws_linked_list *list);
source
LibAWSCRT.aws_linked_list_swap_contents — Method
aws_linked_list_swap_contents(a, b)

Prototype

AWS_STATIC_IMPL void aws_linked_list_swap_contents( struct aws_linked_list *AWS_RESTRICT a, struct aws_linked_list *AWS_RESTRICT b);
source
LibAWSCRT.aws_linked_list_swap_nodes — Method
aws_linked_list_swap_nodes(a, b)

Swaps the order two nodes in the linked list.

Prototype

AWS_STATIC_IMPL void aws_linked_list_swap_nodes(struct aws_linked_list_node *a, struct aws_linked_list_node *b);
source
LibAWSCRT.aws_localtime — Method
aws_localtime(time, t)

Cross platform friendly version of localtime_r

Prototype

void aws_localtime(time_t time, struct tm *t);
source
LibAWSCRT.aws_log_channel_init_background — Method
aws_log_channel_init_background(channel, allocator, writer)

Prototype

int aws_log_channel_init_background( struct aws_log_channel *channel, struct aws_allocator *allocator, struct aws_log_writer *writer);
source
LibAWSCRT.aws_log_channel_init_foreground — Method
aws_log_channel_init_foreground(channel, allocator, writer)

Prototype

int aws_log_channel_init_foreground( struct aws_log_channel *channel, struct aws_allocator *allocator, struct aws_log_writer *writer);
source
LibAWSCRT.aws_log_formatter_init_default — Method
aws_log_formatter_init_default(formatter, allocator, options)

Prototype

int aws_log_formatter_init_default( struct aws_log_formatter *formatter, struct aws_allocator *allocator, struct aws_log_formatter_standard_options *options);
source
LibAWSCRT.aws_log_level_to_string — Method
aws_log_level_to_string(log_level, level_string)

Converts a log level to a c-string constant. Intended primarily to support building log lines that include the level in them, i.e.

[ERROR] 10:34:54.642 01-31-19 - Json parse error....

Prototype

int aws_log_level_to_string(enum aws_log_level log_level, const char **level_string);
source
LibAWSCRT.aws_log_writer_init_file — Method
aws_log_writer_init_file(writer, allocator, options)

Prototype

int aws_log_writer_init_file( struct aws_log_writer *writer, struct aws_allocator *allocator, struct aws_log_writer_file_options *options);
source
LibAWSCRT.aws_logger_clean_up — Method
aws_logger_clean_up(logger)

Cleans up all resources used by the logger; simply invokes the clean_up v-function

Prototype

void aws_logger_clean_up(struct aws_logger *logger);
source
LibAWSCRT.aws_logger_get — Method
aws_logger_get()

Gets the aws logger used globally across the process.

Prototype

struct aws_logger *aws_logger_get(void);
source
LibAWSCRT.aws_logger_get_conditional — Method
aws_logger_get_conditional(subject, level)

Gets the aws logger used globally across the process if the logging level is at least the inputted level.

Parameters

  • subject: log subject to perform the level check versus, not currently used
  • level: logging level to check against in order to return the logger

Returns

the current logger if the current logging level is at or more detailed then the supplied logging level

Prototype

struct aws_logger *aws_logger_get_conditional(aws_log_subject_t subject, enum aws_log_level level);
source
LibAWSCRT.aws_logger_init_from_external — Method
aws_logger_init_from_external(logger, allocator, formatter, channel, writer, level)

Prototype

int aws_logger_init_from_external( struct aws_logger *logger, struct aws_allocator *allocator, struct aws_log_formatter *formatter, struct aws_log_channel *channel, struct aws_log_writer *writer, enum aws_log_level level);
source
LibAWSCRT.aws_logger_init_noalloc — Method
aws_logger_init_noalloc(logger, allocator, options)

Prototype

int aws_logger_init_noalloc( struct aws_logger *logger, struct aws_allocator *allocator, struct aws_logger_standard_options *options);
source
LibAWSCRT.aws_logger_init_standard — Method
aws_logger_init_standard(logger, allocator, options)

Prototype

int aws_logger_init_standard( struct aws_logger *logger, struct aws_allocator *allocator, struct aws_logger_standard_options *options);
source
LibAWSCRT.aws_logger_set — Method
aws_logger_set(logger)

Sets the aws logger used globally across the process. Not thread-safe. Must only be called once.

Prototype

void aws_logger_set(struct aws_logger *logger);
source
LibAWSCRT.aws_logger_set_log_level — Method
aws_logger_set_log_level(logger, level)

Sets the current logging level for the logger. Loggers are not require to support this.

Parameters

  • logger: logger to set the log level for
  • level: new log level for the logger

Returns

AWS_OP_SUCCESS if the level was successfully set, AWS_OP_ERR otherwise

Prototype

int aws_logger_set_log_level(struct aws_logger *logger, enum aws_log_level level);
source
LibAWSCRT.aws_lookup_table_hex_to_num_get — Method
aws_lookup_table_hex_to_num_get()

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

Prototype

const uint8_t *aws_lookup_table_hex_to_num_get(void);
source
LibAWSCRT.aws_lookup_table_to_lower_get — Method
aws_lookup_table_to_lower_get()

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.

Prototype

const uint8_t *aws_lookup_table_to_lower_get(void);
source
LibAWSCRT.aws_lru_cache_get_mru_element — Method
aws_lru_cache_get_mru_element(cache)

Accesses the most-recently-used element and returns its value.

Prototype

void *aws_lru_cache_get_mru_element(const struct aws_cache *cache);
source
LibAWSCRT.aws_lru_cache_use_lru_element — Method
aws_lru_cache_use_lru_element(cache)

Accesses the least-recently-used element, sets it to most-recently-used element, and returns the value.

Prototype

void *aws_lru_cache_use_lru_element(struct aws_cache *cache);
source
LibAWSCRT.aws_md5_compute — Method
aws_md5_compute(allocator, input, output, truncate_to)

Computes the md5 hash over input and writes the digest output to 'output'. Use this if you don't need to stream the data you're hashing and you can load the entire input to hash into memory.

Prototype

int aws_md5_compute( struct aws_allocator *allocator, const struct aws_byte_cursor *input, struct aws_byte_buf *output, size_t truncate_to);
source
LibAWSCRT.aws_md5_new — Method
aws_md5_new(allocator)

Allocates and initializes an md5 hash instance.

Prototype

struct aws_hash *aws_md5_new(struct aws_allocator *allocator);
source
LibAWSCRT.aws_mem_acquire — Method
aws_mem_acquire(allocator, size)

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.

Prototype

void *aws_mem_acquire(struct aws_allocator *allocator, size_t size);
source
LibAWSCRT.aws_mem_calloc — Method
aws_mem_calloc(allocator, num, size)

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.

Prototype

void *aws_mem_calloc(struct aws_allocator *allocator, size_t num, size_t size);
source
LibAWSCRT.aws_mem_realloc — Method
aws_mem_realloc(allocator, ptr, oldsize, newsize)

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.

In versions v0.6.8 and prior, this function was allowed to return NULL. In later versions, if allocator->mem_realloc() returns NULL, this function will assert and exit. To handle conditions where OOM is not a fatal error, allocator->mem_realloc() is responsible for finding/reclaiming/running a GC etc...before returning.

Prototype

int aws_mem_realloc(struct aws_allocator *allocator, void **ptr, size_t oldsize, size_t newsize);
source
LibAWSCRT.aws_mem_release — Method
aws_mem_release(allocator, ptr)

Releases ptr back to whatever allocated it. Nothing happens if ptr is NULL.

Prototype

void aws_mem_release(struct aws_allocator *allocator, void *ptr);
source
LibAWSCRT.aws_mem_tracer_new — Method
aws_mem_tracer_new(allocator, deprecated, level, frames_per_stack)

Prototype

struct aws_allocator *aws_mem_tracer_new( struct aws_allocator *allocator, struct aws_allocator *deprecated, enum aws_mem_trace_level level, size_t frames_per_stack);
source
LibAWSCRT.aws_memory_pool_acquire — Method
aws_memory_pool_acquire(mempool)

Acquires memory from the pool if available, otherwise, it attempts to allocate and returns the result.

Prototype

void *aws_memory_pool_acquire(struct aws_memory_pool *mempool);
source
LibAWSCRT.aws_memory_pool_init — Method
aws_memory_pool_init(mempool, alloc, ideal_segment_count, segment_size)

Prototype

int aws_memory_pool_init( struct aws_memory_pool *mempool, struct aws_allocator *alloc, uint16_t ideal_segment_count, size_t segment_size);
source
LibAWSCRT.aws_memory_pool_release — Method
aws_memory_pool_release(mempool, to_release)

Releases memory to the pool if space is available, otherwise frees to_release

Prototype

void aws_memory_pool_release(struct aws_memory_pool *mempool, void *to_release);
source
LibAWSCRT.aws_message_pool_acquire — Method
aws_message_pool_acquire(msg_pool, message_type, size_hint)

Acquires a message from the pool if available, otherwise, it attempts to allocate. If a message is acquired, note that size_hint is just a hint. the return value's capacity will be set to the actual buffer size.

Prototype

struct aws_io_message *aws_message_pool_acquire( struct aws_message_pool *msg_pool, enum aws_io_message_type message_type, size_t size_hint);
source
LibAWSCRT.aws_message_pool_init — Method
aws_message_pool_init(msg_pool, alloc, args)

Initializes message pool using 'msg_pool' as the backing pool, 'args' is copied.

Prototype

int aws_message_pool_init( struct aws_message_pool *msg_pool, struct aws_allocator *alloc, struct aws_message_pool_creation_args *args);
source
LibAWSCRT.aws_message_pool_release — Method
aws_message_pool_release(msg_pool, message)

Releases message to the pool if space is available, otherwise frees message

Parameters

  • message:

Prototype

void aws_message_pool_release(struct aws_message_pool *msg_pool, struct aws_io_message *message);
source
LibAWSCRT.aws_mqtt_client_acquire — Method
aws_mqtt_client_acquire(client)

Increments the ref count to an mqtt client, allowing the caller to take a reference to it

Parameters

  • client:[in] The client to increment the ref count on

Returns

the mqtt client

Prototype

struct aws_mqtt_client *aws_mqtt_client_acquire(struct aws_mqtt_client *client);
source
LibAWSCRT.aws_mqtt_client_connection_acquire — Method
aws_mqtt_client_connection_acquire(connection)

Increments the ref count to an mqtt client connection, allowing the caller to take a reference to it

Parameters

  • connection:[in] The connection object

Returns

the mqtt connection

Prototype

struct aws_mqtt_client_connection *aws_mqtt_client_connection_acquire(struct aws_mqtt_client_connection *connection);
source
LibAWSCRT.aws_mqtt_client_connection_connect — Method
aws_mqtt_client_connection_connect(connection, connection_options)

Opens the actual connection defined by aws_mqtt_client_connection_new. Once the connection is opened, on_connack will be called. Only called when connection is disconnected.

Parameters

  • connection:[in] The connection object
  • connection_options:[in] Configuration information for the connection attempt

Returns

AWS_OP_SUCCESS if the connection has been successfully initiated, otherwise AWS_OP_ERR and aws_last_error() will be set.

Prototype

int aws_mqtt_client_connection_connect( struct aws_mqtt_client_connection *connection, const struct aws_mqtt_connection_options *connection_options);
source
LibAWSCRT.aws_mqtt_client_connection_disconnect — Method
aws_mqtt_client_connection_disconnect(connection, on_disconnect, userdata)

Closes the connection asynchronously, calls the on_disconnect callback. All uncompleted requests (publish/subscribe/unsubscribe) will be cancelled, regardless to the status of clean_session. DISCONNECT packet will be sent, which deletes the will message from server.

Parameters

  • connection:[in] The connection to close
  • on_disconnect:[in] (nullable) Callback function to invoke when the connection is completely disconnected.
  • userdata:[in] (nullable) passed to on_disconnect

Returns

AWS_OP_SUCCESS if the connection is open and is being shutdown, otherwise AWS_OP_ERR and aws_last_error() is set.

Prototype

int aws_mqtt_client_connection_disconnect( struct aws_mqtt_client_connection *connection, aws_mqtt_client_on_disconnect_fn *on_disconnect, void *userdata);
source
LibAWSCRT.aws_mqtt_client_connection_get_stats — Method
aws_mqtt_client_connection_get_stats(connection, stats)

Queries the connection's internal statistics for incomplete/unacked operations.

Parameters

  • connection: connection to get statistics for
  • stats: set of incomplete/unacked operation statistics

Returns

AWS_OP_SUCCESS if getting the operation statistics were successful, AWS_OP_ERR otherwise

Prototype

int aws_mqtt_client_connection_get_stats( struct aws_mqtt_client_connection *connection, struct aws_mqtt_connection_operation_statistics *stats);
source
LibAWSCRT.aws_mqtt_client_connection_new — Method
aws_mqtt_client_connection_new(client)

Spawns a new connection object.

Parameters

  • client:[in] The client to spawn the connection from

Returns

a new mqtt connection on success, NULL otherwise

Prototype

struct aws_mqtt_client_connection *aws_mqtt_client_connection_new(struct aws_mqtt_client *client);
source
LibAWSCRT.aws_mqtt_client_connection_publish — Method
aws_mqtt_client_connection_publish(connection, topic, qos, retain, payload, on_complete, userdata)

Send a PUBLISH packet over connection.

Parameters

  • connection:[in] The connection to publish on
  • topic:[in] The topic to publish on
  • qos:[in] The requested QoS of the packet
  • retain:[in] True to have the server save the packet, and send to all new subscriptions matching topic
  • payload:[in] The data to send as the payload of the publish
  • on_complete:[in] (nullable) For QoS 0, called as soon as the packet is sent For QoS 1, called when PUBACK is received For QoS 2, called when PUBCOMP is received
  • user_data:[in] (nullable) Passed to on_complete

Returns

The packet id of the publish packet if successfully sent, otherwise 0.

Prototype

uint16_t aws_mqtt_client_connection_publish( struct aws_mqtt_client_connection *connection, const struct aws_byte_cursor *topic, enum aws_mqtt_qos qos, bool retain, const struct aws_byte_cursor *payload, aws_mqtt_op_complete_fn *on_complete, void *userdata);
source
LibAWSCRT.aws_mqtt_client_connection_reconnect — Method
aws_mqtt_client_connection_reconnect(connection, on_connection_complete, userdata)

DEPRECATED Opens the actual connection defined by aws_mqtt_client_connection_new. Once the connection is opened, on_connack will be called.

Must be called on a connection that has previously been open, as the parameters passed during the last connection will be reused.

Parameters

  • connection:[in] The connection object
  • on_connection_complete:[in] The callback to fire when the connection attempt completes
  • userdata:[in] (nullable) Passed to the userdata param of on_connection_complete

Returns

AWS_OP_SUCCESS if the connection has been successfully initiated, otherwise AWS_OP_ERR and aws_last_error() will be set.

Prototype

int aws_mqtt_client_connection_reconnect( struct aws_mqtt_client_connection *connection, aws_mqtt_client_on_connection_complete_fn *on_connection_complete, void *userdata);
source
LibAWSCRT.aws_mqtt_client_connection_release — Method
aws_mqtt_client_connection_release(connection)

Decrements the ref count on an mqtt connection. If the ref count drops to zero, the connection is cleaned up. Note: cannot call this with lock held, since it will start the destroy process and cause a dead lock.

Parameters

  • connection:[in] The connection object

Prototype

void aws_mqtt_client_connection_release(struct aws_mqtt_client_connection *connection);
source
LibAWSCRT.aws_mqtt_client_connection_set_connection_closed_handler — Method
aws_mqtt_client_connection_set_connection_closed_handler(connection, on_closed, on_closed_ud)

Sets the callback to call when the connection is closed normally by user request. This is different than the connection interrupted or lost, this only covers successful closure.

Parameters

  • connection:[in] The connection object
  • on_closed:[in] The function to call when a connection is closed
  • on_closed_ud:[in] Userdata for on_closed

Prototype

int aws_mqtt_client_connection_set_connection_closed_handler( struct aws_mqtt_client_connection *connection, aws_mqtt_client_on_connection_closed_fn *on_closed, void *on_closed_ud);
source
LibAWSCRT.aws_mqtt_client_connection_set_connection_interruption_handlers — Method
aws_mqtt_client_connection_set_connection_interruption_handlers(connection, on_interrupted, on_interrupted_ud, on_resumed, on_resumed_ud)

Sets the callbacks to call when a connection is interrupted and resumed.

Parameters

  • connection:[in] The connection object
  • on_interrupted:[in] The function to call when a connection is lost
  • on_interrupted_ud:[in] Userdata for on_interrupted
  • on_resumed:[in] The function to call when a connection is resumed (if clean_session is true, calling aws_mqtt_resubscribe_existing_topics is suggested)
  • on_resumed_ud:[in] Userdata for on_resumed

Prototype

int aws_mqtt_client_connection_set_connection_interruption_handlers( struct aws_mqtt_client_connection *connection, aws_mqtt_client_on_connection_interrupted_fn *on_interrupted, void *on_interrupted_ud, aws_mqtt_client_on_connection_resumed_fn *on_resumed, void *on_resumed_ud);
source
LibAWSCRT.aws_mqtt_client_connection_set_host_resolution_options — Method
aws_mqtt_client_connection_set_host_resolution_options(connection, host_resolution_config)

Set host resolution ooptions for the connection.

Prototype

int aws_mqtt_client_connection_set_host_resolution_options( struct aws_mqtt_client_connection *connection, struct aws_host_resolution_config *host_resolution_config);
source
LibAWSCRT.aws_mqtt_client_connection_set_http_proxy_options — Method
aws_mqtt_client_connection_set_http_proxy_options(connection, proxy_options)

Set http proxy options for the connection.

Prototype

int aws_mqtt_client_connection_set_http_proxy_options( struct aws_mqtt_client_connection *connection, struct aws_http_proxy_options *proxy_options);
source
LibAWSCRT.aws_mqtt_client_connection_set_login — Method
aws_mqtt_client_connection_set_login(connection, username, password)

Sets the username and/or password to send with the CONNECT packet.

Parameters

  • connection:[in] The connection object
  • username:[in] The username to connect with
  • password:[in] [optional] The password to connect with

Prototype

int aws_mqtt_client_connection_set_login( struct aws_mqtt_client_connection *connection, const struct aws_byte_cursor *username, const struct aws_byte_cursor *password);
source
LibAWSCRT.aws_mqtt_client_connection_set_on_any_publish_handler — Method
aws_mqtt_client_connection_set_on_any_publish_handler(connection, on_any_publish, on_any_publish_ud)

Sets the callback to call whenever ANY publish packet is received. Only safe to set when connection is not connected.

Parameters

  • connection:[in] The connection object
  • on_any_publish:[in] The function to call when a publish is received (pass NULL to unset)
  • on_any_publish_ud:[in] Userdata for on_any_publish

Prototype

int aws_mqtt_client_connection_set_on_any_publish_handler( struct aws_mqtt_client_connection *connection, aws_mqtt_client_publish_received_fn *on_any_publish, void *on_any_publish_ud);
source
LibAWSCRT.aws_mqtt_client_connection_set_reconnect_timeout — Method
aws_mqtt_client_connection_set_reconnect_timeout(connection, min_timeout, max_timeout)

Sets the minimum and maximum reconnect timeouts.

The time between reconnect attempts will start at min and multiply by 2 until max is reached.

Parameters

  • connection:[in] The connection object
  • min_timeout:[in] The timeout to start with
  • max_timeout:[in] The highest allowable wait time between reconnect attempts

Prototype

int aws_mqtt_client_connection_set_reconnect_timeout( struct aws_mqtt_client_connection *connection, uint64_t min_timeout, uint64_t max_timeout);
source
LibAWSCRT.aws_mqtt_client_connection_set_will — Method
aws_mqtt_client_connection_set_will(connection, topic, qos, retain, payload)

Sets the will message to send with the CONNECT packet.

Parameters

  • connection:[in] The connection object
  • topic:[in] The topic to publish the will on
  • qos:[in] The QoS to publish the will with
  • retain:[in] The retain flag to publish the will with
  • payload:[in] The data if the will message

Prototype

int aws_mqtt_client_connection_set_will( struct aws_mqtt_client_connection *connection, const struct aws_byte_cursor *topic, enum aws_mqtt_qos qos, bool retain, const struct aws_byte_cursor *payload);
source
LibAWSCRT.aws_mqtt_client_connection_subscribe — Method
aws_mqtt_client_connection_subscribe(connection, topic_filter, qos, on_publish, on_publish_ud, on_ud_cleanup, on_suback, on_suback_ud)

Subscribe to a single topic filter. on_publish will be called when a PUBLISH matching topic_filter is received.

Parameters

  • connection:[in] The connection to subscribe on
  • topic_filter:[in] The topic filter to subscribe on. This resource must persist until on_suback.
  • qos:[in] The maximum QoS of messages to receive
  • on_publish:[in] (nullable) Called when a PUBLISH packet matching topic_filter is received
  • on_publish_ud:[in] (nullable) Passed to on_publish
  • on_ud_cleanup:[in] (nullable) Called when a subscription is removed, on_publish_ud is passed.
  • on_suback:[in] (nullable) Called when a SUBACK has been received from the server and the subscription is complete
  • on_suback_ud:[in] (nullable) Passed to on_suback

Returns

The packet id of the subscribe packet if successfully sent, otherwise 0.

Prototype

uint16_t aws_mqtt_client_connection_subscribe( struct aws_mqtt_client_connection *connection, const struct aws_byte_cursor *topic_filter, enum aws_mqtt_qos qos, aws_mqtt_client_publish_received_fn *on_publish, void *on_publish_ud, aws_mqtt_userdata_cleanup_fn *on_ud_cleanup, aws_mqtt_suback_fn *on_suback, void *on_suback_ud);
source
LibAWSCRT.aws_mqtt_client_connection_subscribe_local — Method
aws_mqtt_client_connection_subscribe_local(connection, topic_filter, on_publish, on_publish_ud, on_ud_cleanup, on_suback, on_suback_ud)

Subscribe to a single topic filter WITHOUT sending a SUBSCRIBE packet. This is useful if you expect the broker to send PUBLISHES without first subscribing. on_publish will be called when a PUBLISH matching topic_filter is received.

Parameters

  • connection:[in] The connection to subscribe on
  • topic_filter:[in] The topic filter to subscribe on. This resource must persist until on_suback.
  • on_publish:[in] (nullable) Called when a PUBLISH packet matching topic_filter is received
  • on_publish_ud:[in] (nullable) Passed to on_publish
  • on_ud_cleanup:[in] (nullable) Called when a subscription is removed, on_publish_ud is passed.
  • on_suback:[in] (nullable) Called when a SUBACK has been received from the server and the subscription is complete
  • on_suback_ud:[in] (nullable) Passed to on_suback

Returns

The "packet id" of the operation if successfully initiated, otherwise 0.

Prototype

uint16_t aws_mqtt_client_connection_subscribe_local( struct aws_mqtt_client_connection *connection, const struct aws_byte_cursor *topic_filter, aws_mqtt_client_publish_received_fn *on_publish, void *on_publish_ud, aws_mqtt_userdata_cleanup_fn *on_ud_cleanup, aws_mqtt_suback_fn *on_suback, void *on_suback_ud);
source
LibAWSCRT.aws_mqtt_client_connection_subscribe_multiple — Method
aws_mqtt_client_connection_subscribe_multiple(connection, topic_filters, on_suback, on_suback_ud)

Subscribe to topic filters. on_publish will be called when a PUBLISH matching each topic_filter is received.

Parameters

  • connection:[in] The connection to subscribe on
  • topic_filters:[in] An array_list of aws_mqtt_topic_subscription (NOT pointers) describing the requests.
  • on_suback:[in] (nullable) Called when a SUBACK has been received from the server and the subscription is complete. Broker may fail one of the topics, check the qos in aws_mqtt_topic_subscription from the callback
  • on_suback_ud:[in] (nullable) Passed to on_suback

Returns

The packet id of the subscribe packet if successfully sent, otherwise 0.

Prototype

uint16_t aws_mqtt_client_connection_subscribe_multiple( struct aws_mqtt_client_connection *connection, const struct aws_array_list *topic_filters, aws_mqtt_suback_multi_fn *on_suback, void *on_suback_ud);
source
LibAWSCRT.aws_mqtt_client_connection_unsubscribe — Method
aws_mqtt_client_connection_unsubscribe(connection, topic_filter, on_unsuback, on_unsuback_ud)

Unsubscribe to a topic filter.

Parameters

  • connection:[in] The connection to unsubscribe on
  • topic_filter:[in] The topic filter to unsubscribe on. This resource must persist until on_unsuback.
  • on_unsuback:[in] (nullable) Called when a UNSUBACK has been received from the server and the subscription is removed
  • on_unsuback_ud:[in] (nullable) Passed to on_unsuback

Returns

The packet id of the unsubscribe packet if successfully sent, otherwise 0.

Prototype

uint16_t aws_mqtt_client_connection_unsubscribe( struct aws_mqtt_client_connection *connection, const struct aws_byte_cursor *topic_filter, aws_mqtt_op_complete_fn *on_unsuback, void *on_unsuback_ud);
source
LibAWSCRT.aws_mqtt_client_connection_use_websockets — Method
aws_mqtt_client_connection_use_websockets(connection, transformer, transformer_ud, validator, validator_ud)

Use MQTT over websockets when connecting. Requires the MQTT_WITH_WEBSOCKETS build option.

In this scenario, an HTTP connection is established, which is then upgraded to a websocket connection, which is then used to send MQTT data.

Parameters

  • connection:[in] The connection object.
  • transformer:[in] [optional] Function that may transform the websocket handshake request. See aws_mqtt_transform_websocket_handshake_fn for more info.
  • transformer_ud:[in] [optional] Userdata for request_transformer.
  • validator:[in] [optional] Function that may reject the websocket handshake response.
  • validator_ud:[in] [optional] Userdata for response_validator.

Prototype

int aws_mqtt_client_connection_use_websockets( struct aws_mqtt_client_connection *connection, aws_mqtt_transform_websocket_handshake_fn *transformer, void *transformer_ud, aws_mqtt_validate_websocket_handshake_fn *validator, void *validator_ud);
source
LibAWSCRT.aws_mqtt_client_new — Method
aws_mqtt_client_new(allocator, bootstrap)

Creates an instance of aws_mqtt_client.

Parameters

  • allocator:[in] The allocator the client will use for all future allocations
  • bootstrap:[in] The client bootstrap to use to initiate new socket connections

Returns

a new instance of an aws_mqtt_client if successful, NULL otherwise

Prototype

struct aws_mqtt_client *aws_mqtt_client_new(struct aws_allocator *allocator, struct aws_client_bootstrap *bootstrap);
source
LibAWSCRT.aws_mqtt_client_release — Method
aws_mqtt_client_release(client)

Decrements the ref count on an mqtt client. If the ref count drops to zero, the client is cleaned up.

Parameters

  • client:[in] The client to release a ref count on

Prototype

void aws_mqtt_client_release(struct aws_mqtt_client *client);
source
LibAWSCRT.aws_mqtt_library_init — Method
aws_mqtt_library_init(allocator)

Initializes internal datastructures used by aws-c-mqtt. Must be called before using any functionality in aws-c-mqtt.

Prototype

void aws_mqtt_library_init(struct aws_allocator *allocator);
source
LibAWSCRT.aws_mqtt_resubscribe_existing_topics — Method
aws_mqtt_resubscribe_existing_topics(connection, on_suback, on_suback_ud)

Resubscribe to all topics currently subscribed to. This is to help when resuming a connection with a clean session.

Parameters

  • connection:[in] The connection to subscribe on
  • on_suback:[in] (nullable) Called when a SUBACK has been received from the server and the subscription is complete
  • on_suback_ud:[in] (nullable) Passed to on_suback

Returns

The packet id of the subscribe packet if successfully sent, otherwise 0 (and aws_last_error() will be set).

Prototype

uint16_t aws_mqtt_resubscribe_existing_topics( struct aws_mqtt_client_connection *connection, aws_mqtt_suback_multi_fn *on_suback, void *on_suback_ud);
source
LibAWSCRT.aws_mul_size_saturating — Method
aws_mul_size_saturating(a, b)

Multiplies a * b. If the result overflows, returns SIZE_MAX.

Prototype

AWS_STATIC_IMPL size_t aws_mul_size_saturating(size_t a, size_t b);
source
LibAWSCRT.aws_mul_u32_saturating — Method
aws_mul_u32_saturating(a, b)

Multiplies a * b. If the result overflows, returns 2^32 - 1.

Prototype

AWS_STATIC_IMPL uint32_t aws_mul_u32_saturating(uint32_t a, uint32_t b);
source
LibAWSCRT.aws_mul_u64_saturating — Method
aws_mul_u64_saturating(a, b)

Multiplies a * b. If the result overflows, returns 2^64 - 1.

Prototype

AWS_STATIC_IMPL uint64_t aws_mul_u64_saturating(uint64_t a, uint64_t b);
source
LibAWSCRT.aws_mutex_init — Method
aws_mutex_init(mutex)

Initializes a new platform instance of mutex.

Prototype

int aws_mutex_init(struct aws_mutex *mutex);
source
LibAWSCRT.aws_mutex_lock — Method
aws_mutex_lock(mutex)

Blocks until it acquires the lock. While on some platforms such as Windows, this may behave as a reentrant mutex, you should not treat it like one. On platforms it is possible for it to be non-reentrant, it will be.

Prototype

int aws_mutex_lock(struct aws_mutex *mutex);
source
LibAWSCRT.aws_mutex_try_lock — Method
aws_mutex_try_lock(mutex)

Attempts to acquire the lock but returns immediately if it can not. While on some platforms such as Windows, this may behave as a reentrant mutex, you should not treat it like one. On platforms it is possible for it to be non-reentrant, it will be. Note: For windows, minimum support server version is Windows Server 2008 R2 [desktop apps | UWP apps]

Prototype

int aws_mutex_try_lock(struct aws_mutex *mutex);
source
LibAWSCRT.aws_normalize_directory_separator — Method
aws_normalize_directory_separator(path)

Normalizes the path by replacing any directory separator with the local platform's directory separator.

Parameters

  • path: path to normalize. Must be writeable.

Prototype

void aws_normalize_directory_separator(struct aws_byte_buf *path);
source
LibAWSCRT.aws_ntoh16 — Method
aws_ntoh16(x)

Convert 16 bit integer from network to host byte order.

Prototype

AWS_STATIC_IMPL uint16_t aws_ntoh16(uint16_t x);
source
LibAWSCRT.aws_ntoh32 — Method
aws_ntoh32(x)

Convert 32 bit integer from network to host byte order.

Prototype

AWS_STATIC_IMPL uint32_t aws_ntoh32(uint32_t x);
source
LibAWSCRT.aws_ntoh64 — Method
aws_ntoh64(x)

Convert 64 bit integer from network to host byte order.

Prototype

AWS_STATIC_IMPL uint64_t aws_ntoh64(uint64_t x);
source
LibAWSCRT.aws_ntohf32 — Method
aws_ntohf32(x)

Convert 32 bit float from network to host byte order.

Prototype

AWS_STATIC_IMPL float aws_ntohf32(float x);
source
LibAWSCRT.aws_ntohf64 — Method
aws_ntohf64(x)

Convert 32 bit float from network to host byte order.

Prototype

AWS_STATIC_IMPL double aws_ntohf64(double x);
source
LibAWSCRT.aws_path_exists — Method
aws_path_exists(path)

Returns true if a file or path exists, otherwise, false.

Prototype

bool aws_path_exists(const struct aws_string *path);
source
LibAWSCRT.aws_pipe_clean_up_read_end — Method
aws_pipe_clean_up_read_end(read_end)

Clean up the read-end of the pipe. This must be called on the thread of the connected event-loop.

Prototype

int aws_pipe_clean_up_read_end(struct aws_pipe_read_end *read_end);
source
LibAWSCRT.aws_pipe_clean_up_write_end — Method
aws_pipe_clean_up_write_end(write_end)

Clean up the write-end of the pipe. This must be called on the thread of the connected event-loop.

Prototype

int aws_pipe_clean_up_write_end(struct aws_pipe_write_end *write_end);
source
LibAWSCRT.aws_pipe_get_read_end_event_loop — Method
aws_pipe_get_read_end_event_loop(read_end)

Get the event-loop connected to the read-end of the pipe. This may be called on any thread.

Prototype

struct aws_event_loop *aws_pipe_get_read_end_event_loop(const struct aws_pipe_read_end *read_end);
source
LibAWSCRT.aws_pipe_get_write_end_event_loop — Method
aws_pipe_get_write_end_event_loop(write_end)

Get the event-loop connected to the write-end of the pipe. This may be called on any thread.

Prototype

struct aws_event_loop *aws_pipe_get_write_end_event_loop(const struct aws_pipe_write_end *write_end);
source
LibAWSCRT.aws_pipe_init — Method
aws_pipe_init(read_end, read_end_event_loop, write_end, write_end_event_loop, allocator)

Opens an OS specific bidirectional pipe. The read direction is stored in read_end. Write direction is stored in write_end. Each end must be connected to an event-loop, and further calls to each end must happen on that event-loop's thread.

Prototype

int aws_pipe_init( struct aws_pipe_read_end *read_end, struct aws_event_loop *read_end_event_loop, struct aws_pipe_write_end *write_end, struct aws_event_loop *write_end_event_loop, struct aws_allocator *allocator);
source
LibAWSCRT.aws_pipe_read — Method
aws_pipe_read(read_end, dst_buffer, num_bytes_read)

Read data from the pipe into the destination buffer. Attempts to read enough to fill all remaining space in the buffer, from dst\_buffer->len to dst\_buffer->capacity. dst\_buffer->len is updated to reflect the buffer's new length. num_bytes_read (optional) is set to the total number of bytes read. This function never blocks. If no bytes could be read without blocking, then AWS_OP_ERR is returned and aws_last_error() code will be AWS_IO_READ_WOULD_BLOCK. This must be called on the thread of the connected event-loop.

Prototype

int aws_pipe_read(struct aws_pipe_read_end *read_end, struct aws_byte_buf *dst_buffer, size_t *num_bytes_read);
source
LibAWSCRT.aws_pipe_subscribe_to_readable_events — Method
aws_pipe_subscribe_to_readable_events(read_end, on_readable, user_data)

Subscribe to be notified when the pipe becomes readable (edge-triggered), or an error occurs. on_readable is invoked on the event-loop's thread when the pipe has data to read, or the pipe has an error. on_readable is invoked again any time the user reads all data, and then more data arrives. Note that it will not be invoked again if the pipe still has unread data when more data arrives. This must be called on the thread of the connected event-loop.

Prototype

int aws_pipe_subscribe_to_readable_events( struct aws_pipe_read_end *read_end, aws_pipe_on_readable_fn *on_readable, void *user_data);
source
LibAWSCRT.aws_pipe_unsubscribe_from_readable_events — Method
aws_pipe_unsubscribe_from_readable_events(read_end)

Stop receiving notifications about events on the read-end of the pipe. This must be called on the thread of the connected event-loop.

Prototype

int aws_pipe_unsubscribe_from_readable_events(struct aws_pipe_read_end *read_end);
source
LibAWSCRT.aws_pipe_write — Method
aws_pipe_write(write_end, src_buffer, on_completed, user_data)

Initiates an asynchrous write from the source buffer to the pipe. The data referenced by src_buffer must remain in memory until the operation completes. on_complete is called on the event-loop thread when the operation has either completed or failed. The callback's pipe argument will be NULL if the callback is invoked after the pipe has been cleaned up. This must be called on the thread of the connected event-loop.

Prototype

int aws_pipe_write( struct aws_pipe_write_end *write_end, struct aws_byte_cursor src_buffer, aws_pipe_on_write_completed_fn *on_completed, void *user_data);
source
LibAWSCRT.aws_pkcs11_lib_acquire — Method
aws_pkcs11_lib_acquire(pkcs11_lib)

Acquire a reference to a PKCS#11 library, preventing it from being cleaned up. You must call aws_pkcs11_lib_release() when you are done with it. This function returns whatever was passed in. It cannot fail.

Prototype

struct aws_pkcs11_lib *aws_pkcs11_lib_acquire(struct aws_pkcs11_lib *pkcs11_lib);
source
LibAWSCRT.aws_pkcs11_lib_new — Method
aws_pkcs11_lib_new(allocator, options)

Load and initialize a PKCS#11 library. See aws_pkcs11_lib_options for options.

If successful a valid pointer is returned. You must call aws_pkcs11_lib_release() when you are done with it. If unsuccessful, NULL is returned and an error is set.

Prototype

struct aws_pkcs11_lib *aws_pkcs11_lib_new( struct aws_allocator *allocator, const struct aws_pkcs11_lib_options *options);
source
LibAWSCRT.aws_pkcs11_lib_release — Method
aws_pkcs11_lib_release(pkcs11_lib)

Release a reference to the PKCS#11 library. When the last reference is released, the library is cleaned up.

Prototype

void aws_pkcs11_lib_release(struct aws_pkcs11_lib *pkcs11_lib);
source
LibAWSCRT.aws_priority_queue_backpointers_valid — Method
aws_priority_queue_backpointers_valid(queue)

Checks that the backpointers of the priority queue satisfy validity constraints.

Prototype

bool aws_priority_queue_backpointers_valid(const struct aws_priority_queue *const queue);
source
LibAWSCRT.aws_priority_queue_backpointers_valid_deep — Method
aws_priority_queue_backpointers_valid_deep(queue)

Checks that the backpointers of the priority queue are either NULL or correctly allocated to point at aws_priority_queue_nodes. This check is O(n), as it accesses every backpointer in a loop, and thus shouldn't be used carelessly.

Prototype

bool aws_priority_queue_backpointers_valid_deep(const struct aws_priority_queue *const queue);
source
LibAWSCRT.aws_priority_queue_capacity — Method
aws_priority_queue_capacity(queue)

Current allocated capacity for the queue, in dynamic mode this grows over time, in static mode, this will never change.

Prototype

size_t aws_priority_queue_capacity(const struct aws_priority_queue *queue);
source
LibAWSCRT.aws_priority_queue_clean_up — Method
aws_priority_queue_clean_up(queue)

Cleans up any internally allocated memory and resets the struct for reuse or deletion.

Prototype

void aws_priority_queue_clean_up(struct aws_priority_queue *queue);
source
LibAWSCRT.aws_priority_queue_init_dynamic — Method
aws_priority_queue_init_dynamic(queue, alloc, default_size, item_size, pred)

Initializes a priority queue struct for use. This mode will grow memory automatically (exponential model) Default size is the inital size of the queue item_size is the size of each element in bytes. Mixing items types is not supported by this API. pred is the function that will be used to determine priority.

Prototype

int aws_priority_queue_init_dynamic( struct aws_priority_queue *queue, struct aws_allocator *alloc, size_t default_size, size_t item_size, aws_priority_queue_compare_fn *pred);
source
LibAWSCRT.aws_priority_queue_init_static — Method
aws_priority_queue_init_static(queue, heap, item_count, item_size, pred)

Initializes a priority queue struct for use. This mode will not allocate any additional memory. When the heap fills new enqueue operations will fail with AWS_ERROR_PRIORITY_QUEUE_FULL.

Heaps initialized using this call do not support the aws_priority_queue_push_ref call with a non-NULL backpointer parameter.

heap is the raw memory allocated for this priority_queue item_count is the maximum number of elements the raw heap can contain item_size is the size of each element in bytes. Mixing items types is not supported by this API. pred is the function that will be used to determine priority.

Prototype

void aws_priority_queue_init_static( struct aws_priority_queue *queue, void *heap, size_t item_count, size_t item_size, aws_priority_queue_compare_fn *pred);
source
LibAWSCRT.aws_priority_queue_pop — Method
aws_priority_queue_pop(queue, item)

Copies the element of the highest priority, and removes it from the queue.. Complexity: O(log(n)). If queue is empty, AWS_ERROR_PRIORITY_QUEUE_EMPTY will be raised.

Prototype

int aws_priority_queue_pop(struct aws_priority_queue *queue, void *item);
source
LibAWSCRT.aws_priority_queue_push — Method
aws_priority_queue_push(queue, item)

Copies item into the queue and places it in the proper priority order. Complexity: O(log(n)).

Prototype

int aws_priority_queue_push(struct aws_priority_queue *queue, void *item);
source
LibAWSCRT.aws_priority_queue_push_ref — Method
aws_priority_queue_push_ref(queue, item, backpointer)

Copies item into the queue and places it in the proper priority order. Complexity: O(log(n)).

If the backpointer parameter is non-null, the heap will continually update the pointed-to field with information needed to remove the node later on. *backpointer must remain valid until the node is removed from the heap, and may be updated on any mutating operation on the priority queue.

If the node is removed, the backpointer will be set to a sentinel value that indicates that the node has already been removed. It is safe (and a no-op) to call aws_priority_queue_remove with such a sentinel value.

Prototype

int aws_priority_queue_push_ref( struct aws_priority_queue *queue, void *item, struct aws_priority_queue_node *backpointer);
source
LibAWSCRT.aws_priority_queue_remove — Method
aws_priority_queue_remove(queue, item, node)

Removes a specific node from the priority queue. Complexity: O(log(n)) After removing a node (using either _remove or _pop), the backpointer set at push_ref time is set to a sentinel value. If this sentinel value is passed to aws_priority_queue_remove, AWS_ERROR_PRIORITY_QUEUE_BAD_NODE will be raised. Note, however, that passing uninitialized aws_priority_queue_nodes, or ones from different priority queues, results in undefined behavior.

Prototype

int aws_priority_queue_remove(struct aws_priority_queue *queue, void *item, const struct aws_priority_queue_node *node);
source
LibAWSCRT.aws_priority_queue_size — Method
aws_priority_queue_size(queue)

Current number of elements in the queue

Prototype

size_t aws_priority_queue_size(const struct aws_priority_queue *queue);
source
LibAWSCRT.aws_priority_queue_top — Method
aws_priority_queue_top(queue, item)

Obtains a pointer to the element of the highest priority. Complexity: constant time. If queue is empty, AWS_ERROR_PRIORITY_QUEUE_EMPTY will be raised.

Prototype

int aws_priority_queue_top(const struct aws_priority_queue *queue, void **item);
source
LibAWSCRT.aws_profile_collection_acquire — Method
aws_profile_collection_acquire(collection)

Increments the reference count on the profile collection, allowing the caller to take a reference to it.

Returns the same profile collection passed in.

Prototype

struct aws_profile_collection *aws_profile_collection_acquire(struct aws_profile_collection *collection);
source
LibAWSCRT.aws_profile_collection_get_profile — Method
aws_profile_collection_get_profile(profile_collection, profile_name)

Retrieves a reference to a profile with the specified name, if it exists, from the profile collection

Prototype

const struct aws_profile *aws_profile_collection_get_profile( const struct aws_profile_collection *profile_collection, const struct aws_string *profile_name);
source
LibAWSCRT.aws_profile_collection_get_profile_count — Method
aws_profile_collection_get_profile_count(profile_collection)

Returns the number of profiles in a collection

Prototype

size_t aws_profile_collection_get_profile_count(const struct aws_profile_collection *profile_collection);
source
LibAWSCRT.aws_profile_collection_get_section — Method
aws_profile_collection_get_section(profile_collection, section_type, section_name)

Prototype

const struct aws_profile *aws_profile_collection_get_section( const struct aws_profile_collection *profile_collection, const enum aws_profile_section_type section_type, const struct aws_string *section_name);
source
LibAWSCRT.aws_profile_collection_get_section_count — Method
aws_profile_collection_get_section_count(profile_collection, section_type)

Returns the number of elements of the specified section in a collection.

Prototype

size_t aws_profile_collection_get_section_count( const struct aws_profile_collection *profile_collection, const enum aws_profile_section_type section_type);
source
LibAWSCRT.aws_profile_collection_new_from_buffer — Method
aws_profile_collection_new_from_buffer(allocator, buffer, source)

Create a new profile collection by parsing text in a buffer. Primarily for testing.

Prototype

struct aws_profile_collection *aws_profile_collection_new_from_buffer( struct aws_allocator *allocator, const struct aws_byte_buf *buffer, enum aws_profile_source_type source);
source
LibAWSCRT.aws_profile_collection_new_from_file — Method
aws_profile_collection_new_from_file(allocator, file_path, source)

Create a new profile collection by parsing a file with the specified path

Prototype

struct aws_profile_collection *aws_profile_collection_new_from_file( struct aws_allocator *allocator, const struct aws_string *file_path, enum aws_profile_source_type source);
source
LibAWSCRT.aws_profile_collection_new_from_merge — Method
aws_profile_collection_new_from_merge(allocator, config_profiles, credentials_profiles)

Create a new profile collection by merging a config-file-based profile collection and a credentials-file-based profile collection

Prototype

struct aws_profile_collection *aws_profile_collection_new_from_merge( struct aws_allocator *allocator, const struct aws_profile_collection *config_profiles, const struct aws_profile_collection *credentials_profiles);
source
LibAWSCRT.aws_profile_collection_release — Method
aws_profile_collection_release(collection)

Decrements a profile collection's ref count. When the ref count drops to zero, the collection will be destroyed. Returns NULL.

Prototype

struct aws_profile_collection *aws_profile_collection_release(struct aws_profile_collection *collection);
source
LibAWSCRT.aws_profile_get_name — Method
aws_profile_get_name(profile)

Returns a reference to the name of the provided profile

Prototype

const struct aws_string *aws_profile_get_name(const struct aws_profile *profile);
source
LibAWSCRT.aws_profile_get_property — Method
aws_profile_get_property(profile, property_name)

Retrieves a reference to a property with the specified name, if it exists, from a profile

Prototype

const struct aws_profile_property *aws_profile_get_property( const struct aws_profile *profile, const struct aws_string *property_name);
source
LibAWSCRT.aws_profile_property_get_sub_property — Method
aws_profile_property_get_sub_property(property, sub_property_name)

Returns a reference to the value of a sub property with the given name, if it exists, in the property

Prototype

const struct aws_string *aws_profile_property_get_sub_property( const struct aws_profile_property *property, const struct aws_string *sub_property_name);
source
LibAWSCRT.aws_profile_property_get_value — Method
aws_profile_property_get_value(property)

Returns a reference to the property's string value

Prototype

const struct aws_string *aws_profile_property_get_value(const struct aws_profile_property *property);
source
LibAWSCRT.aws_promise_complete — Method
aws_promise_complete(promise, value, dtor)

Prototype

void aws_promise_complete(struct aws_promise *promise, void *value, void (*dtor)(void *));
source
LibAWSCRT.aws_ptr_eq — Method
aws_ptr_eq(a, b)

Equality function which compares pointer equality.

Prototype

bool aws_ptr_eq(const void *a, const void *b);
source
LibAWSCRT.aws_ref_count_acquire — Method
aws_ref_count_acquire(ref_count)

Increments a ref-counter's ref count

Parameters

  • ref_count: ref-counter to increment the count for

Returns

the object being ref-counted

Prototype

void *aws_ref_count_acquire(struct aws_ref_count *ref_count);
source
LibAWSCRT.aws_ref_count_init — Method
aws_ref_count_init(ref_count, object, on_zero_fn)

Initializes a ref-counter structure. After initialization, the ref count will be 1.

Parameters

  • ref_count: ref-counter to initialize
  • object: object being ref counted
  • on_zero_fn: function to invoke when the ref count reaches zero

Prototype

void aws_ref_count_init( struct aws_ref_count *ref_count, void *object, aws_simple_completion_callback *on_zero_fn);
source
LibAWSCRT.aws_ref_count_release — Method
aws_ref_count_release(ref_count)

Decrements a ref-counter's ref count. Invokes the on_zero callback if the ref count drops to zero

Parameters

  • ref_count: ref-counter to decrement the count for

Returns

the value of the decremented ref count

Prototype

size_t aws_ref_count_release(struct aws_ref_count *ref_count);
source
LibAWSCRT.aws_register_error_info — Method
aws_register_error_info(error_info)

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.

Prototype

void aws_register_error_info(const struct aws_error_info_list *error_info);
source
LibAWSCRT.aws_register_log_subject_info_list — Method
aws_register_log_subject_info_list(log_subject_list)

Connects log subject strings with log subject integer values

Prototype

void aws_register_log_subject_info_list(struct aws_log_subject_info_list *log_subject_list);
source
LibAWSCRT.aws_resource_name_init_from_cur — Method
aws_resource_name_init_from_cur(arn, input)

Given an ARN "Amazon Resource Name" represented as an in memory a structure representing the parts

Prototype

int aws_resource_name_init_from_cur(struct aws_resource_name *arn, const struct aws_byte_cursor *input);
source
LibAWSCRT.aws_resource_name_length — Method
aws_resource_name_length(arn, size)

Calculates the space needed to write an ARN to a byte buf

Prototype

int aws_resource_name_length(const struct aws_resource_name *arn, size_t *size);
source
LibAWSCRT.aws_retry_strategy_acquire — Method
aws_retry_strategy_acquire(retry_strategy)

Acquire a reference count on retry_strategy.

Prototype

void aws_retry_strategy_acquire(struct aws_retry_strategy *retry_strategy);
source
LibAWSCRT.aws_retry_strategy_acquire_retry_token — Method
aws_retry_strategy_acquire_retry_token(retry_strategy, partition_id, on_acquired, user_data, timeout_ms)

Attempts to acquire a retry token for use with retries. On success, on_acquired will be invoked when a token is available, or an error will be returned if the timeout expires. partition_id identifies operations that should be grouped together. This allows for more sophisticated strategies such as AIMD and circuit breaker patterns. Pass NULL to use the global partition.

Prototype

int aws_retry_strategy_acquire_retry_token( struct aws_retry_strategy *retry_strategy, const struct aws_byte_cursor *partition_id, aws_retry_strategy_on_retry_token_acquired_fn *on_acquired, void *user_data, uint64_t timeout_ms);
source
LibAWSCRT.aws_retry_strategy_new_exponential_backoff — Method
aws_retry_strategy_new_exponential_backoff(allocator, config)

Creates a retry strategy using exponential backoff. This strategy does not perform any bookkeeping on error types and success. There is no circuit breaker functionality in here. See the comments above for aws_exponential_backoff_retry_options.

Prototype

struct aws_retry_strategy *aws_retry_strategy_new_exponential_backoff( struct aws_allocator *allocator, const struct aws_exponential_backoff_retry_options *config);
source
LibAWSCRT.aws_retry_strategy_new_standard — Method
aws_retry_strategy_new_standard(allocator, config)

This is a retry implementation that cuts off traffic if it's detected that an endpoint partition is having availability problems. This is necessary to keep from making outages worse by scheduling work that's unlikely to succeed yet increases load on an already ailing system.

We do this by creating a bucket for each partition. A partition is an arbitrary specifier. It can be anything: a region, a service, a combination of region and service, a literal dns name.... doesn't matter.

Each bucket has a budget for maximum allowed retries. Different types of events carry different weights. Things that indicate an unhealthy partition such as transient errors (timeouts, unhealthy connection etc...) cost more. A retry for any other reason (service sending a 5xx response code) cost a bit less. When a retry is attempted this capacity is leased out to the retry. On success it is released back to the capacity pool. On failure, it remains leased. Operations that succeed without a retry slowly restore the capacity pool.

If a partition runs out of capacity it is assumed unhealthy and retries will be blocked until capacity returns to the pool. To prevent a partition from staying unhealthy after an outage has recovered, new requests that succeed without a retry will increase the capacity slowly ( a new request gets a payback lease of 1, but the lease is never actually deducted from the capacity pool).

Prototype

struct aws_retry_strategy *aws_retry_strategy_new_standard( struct aws_allocator *allocator, const struct aws_standard_retry_options *config);
source
LibAWSCRT.aws_retry_strategy_release — Method
aws_retry_strategy_release(retry_strategy)

Releases a reference count on retry_strategy.

Prototype

void aws_retry_strategy_release(struct aws_retry_strategy *retry_strategy);
source
LibAWSCRT.aws_retry_strategy_schedule_retry — Method
aws_retry_strategy_schedule_retry(token, error_type, retry_ready, user_data)

Schedules a retry based on the backoff and token based strategies. retry_ready is invoked when the retry is either ready for execution or if it has been canceled due to application shutdown.

This function can return an error to reject the retry attempt if, for example, a circuit breaker has opened. If this occurs users should fail their calls back to their callers.

error_type is used for book keeping. See the comments above for aws_retry_error_type.

Prototype

int aws_retry_strategy_schedule_retry( struct aws_retry_token *token, enum aws_retry_error_type error_type, aws_retry_strategy_on_retry_ready_fn *retry_ready, void *user_data);
source
LibAWSCRT.aws_retry_token_acquire — Method
aws_retry_token_acquire(token)

Increments reference count for token. This should be called any time you seat the token to a pointer you own.

Prototype

void aws_retry_token_acquire(struct aws_retry_token *token);
source
LibAWSCRT.aws_retry_token_record_success — Method
aws_retry_token_record_success(token)

Records a successful retry. This is used for making future decisions to open up token buckets, AIMD breakers etc... some strategies such as exponential backoff will ignore this, but you should always call it after a successful operation or your system will never recover during an outage.

Prototype

int aws_retry_token_record_success(struct aws_retry_token *token);
source
LibAWSCRT.aws_ring_buffer_acquire — Method
aws_ring_buffer_acquire(ring_buf, requested_size, dest)

Attempts to acquire requested_size buffer and stores the result in dest if successful. Returns AWS_OP_SUCCESS if the requested size was available for use, AWS_OP_ERR otherwise.

Prototype

int aws_ring_buffer_acquire( struct aws_ring_buffer *ring_buf, size_t requested_size, struct aws_byte_buf *dest);
source
LibAWSCRT.aws_ring_buffer_acquire_up_to — Method
aws_ring_buffer_acquire_up_to(ring_buf, minimum_size, requested_size, dest)

Attempts to acquire requested_size buffer and stores the result in dest if successful. If not available, it will attempt to acquire anywhere from 1 byte to requested_size. Returns AWS_OP_SUCCESS if some buffer space is available for use, AWS_OP_ERR otherwise.

Prototype

int aws_ring_buffer_acquire_up_to( struct aws_ring_buffer *ring_buf, size_t minimum_size, size_t requested_size, struct aws_byte_buf *dest);
source
LibAWSCRT.aws_ring_buffer_buf_belongs_to_pool — Method
aws_ring_buffer_buf_belongs_to_pool(ring_buffer, buf)

Returns true if the memory in buf was vended by this ring buffer, false otherwise. Make sure buf->buffer and ring\_buffer->allocation refer to the same memory region.

Prototype

bool aws_ring_buffer_buf_belongs_to_pool( const struct aws_ring_buffer *ring_buffer, const struct aws_byte_buf *buf);
source
LibAWSCRT.aws_ring_buffer_check_atomic_ptr — Method
aws_ring_buffer_check_atomic_ptr(ring_buf, atomic_ptr)

Prototype

AWS_STATIC_IMPL bool aws_ring_buffer_check_atomic_ptr( const struct aws_ring_buffer *ring_buf, const uint8_t *atomic_ptr);
source
LibAWSCRT.aws_ring_buffer_init — Method
aws_ring_buffer_init(ring_buf, allocator, size)

Initializes a ring buffer with an allocation of size size. Returns AWS_OP_SUCCESS on a successful initialization, AWS_OP_ERR otherwise.

Prototype

int aws_ring_buffer_init(struct aws_ring_buffer *ring_buf, struct aws_allocator *allocator, size_t size);
source
LibAWSCRT.aws_ring_buffer_is_empty — Method
aws_ring_buffer_is_empty(ring_buf)

Checks whether the ring buffer is empty

Prototype

AWS_STATIC_IMPL bool aws_ring_buffer_is_empty(const struct aws_ring_buffer *ring_buf);
source
LibAWSCRT.aws_ring_buffer_is_valid — Method
aws_ring_buffer_is_valid(ring_buf)

Evaluates the set of properties that define the shape of all valid aws_ring_buffer structures. It is also a cheap check, in the sense it run in constant time (i.e., no loops or recursion).

Prototype

AWS_STATIC_IMPL bool aws_ring_buffer_is_valid(const struct aws_ring_buffer *ring_buf);
source
LibAWSCRT.aws_ring_buffer_release — Method
aws_ring_buffer_release(ring_buffer, buf)

Releases buf back to the ring buffer for further use. RELEASE MUST HAPPEN in the SAME ORDER AS ACQUIRE. If you do not, your application, and possibly computers within a thousand mile radius, may die terrible deaths, and the local drinking water will be poisoned for generations with fragments of what is left of your radioactive corrupted memory.

Prototype

void aws_ring_buffer_release(struct aws_ring_buffer *ring_buffer, struct aws_byte_buf *buf);
source
LibAWSCRT.aws_round_up_to_power_of_two — Method
aws_round_up_to_power_of_two(n, result)

Function to find the smallest result that is power of 2 >= n. Returns AWS_OP_ERR if this cannot be done without overflow

Prototype

AWS_STATIC_IMPL int aws_round_up_to_power_of_two(size_t n, size_t *result);
source
LibAWSCRT.aws_run_command — Method
aws_run_command(allocator, options, result)

Currently this API is implemented using popen on Posix system and _popen on Windows to capture output from running a command. Note that popen only captures stdout, and doesn't provide an option to capture stderr. We will add more options, such as acquire stderr in the future so probably will alter the underlying implementation as well.

Prototype

int aws_run_command( struct aws_allocator *allocator, struct aws_run_command_options *options, struct aws_run_command_result *result);
source
LibAWSCRT.aws_rw_lock_init — Method
aws_rw_lock_init(lock)

Initializes a new platform instance of mutex.

Prototype

int aws_rw_lock_init(struct aws_rw_lock *lock);
source
LibAWSCRT.aws_rw_lock_rlock — Method
aws_rw_lock_rlock(lock)

Blocks until it acquires the lock. While on some platforms such as Windows, this may behave as a reentrant mutex, you should not treat it like one. On platforms it is possible for it to be non-reentrant, it will be.

Prototype

int aws_rw_lock_rlock(struct aws_rw_lock *lock);
source
LibAWSCRT.aws_rw_lock_try_rlock — Method
aws_rw_lock_try_rlock(lock)

Attempts to acquire the lock but returns immediately if it can not. While on some platforms such as Windows, this may behave as a reentrant mutex, you should not treat it like one. On platforms it is possible for it to be non-reentrant, it will be. Note: For windows, minimum support server version is Windows Server 2008 R2 [desktop apps | UWP apps]

Prototype

int aws_rw_lock_try_rlock(struct aws_rw_lock *lock);
source
LibAWSCRT.aws_s3_client_acquire — Method
aws_s3_client_acquire(client)

Add a reference, keeping this object alive. The reference must be released when you are done with it, or it's memory will never be cleaned up. You must not pass in NULL. Always returns the same pointer that was passed in.

Prototype

struct aws_s3_client *aws_s3_client_acquire(struct aws_s3_client *client);
source
LibAWSCRT.aws_s3_client_make_meta_request — Method
aws_s3_client_make_meta_request(client, options)

Prototype

struct aws_s3_meta_request *aws_s3_client_make_meta_request( struct aws_s3_client *client, const struct aws_s3_meta_request_options *options);
source
LibAWSCRT.aws_s3_client_new — Method
aws_s3_client_new(allocator, client_config)

Prototype

struct aws_s3_client *aws_s3_client_new( struct aws_allocator *allocator, const struct aws_s3_client_config *client_config);
source
LibAWSCRT.aws_s3_client_release — Method
aws_s3_client_release(client)

Release a reference. When the reference count drops to 0, this object will be cleaned up. It's OK to pass in NULL (nothing happens). Always returns NULL.

Prototype

struct aws_s3_client *aws_s3_client_release(struct aws_s3_client *client);
source
LibAWSCRT.aws_s3_endpoint_resolver_new — Method
aws_s3_endpoint_resolver_new(allocator)

Creates a new S3 endpoint resolver. Warning: Before using this header, you have to enable it by setting cmake config AWS_ENABLE_S3_ENDPOINT_RESOLVER=ON

Prototype

struct aws_endpoints_rule_engine *aws_s3_endpoint_resolver_new(struct aws_allocator *allocator);
source
LibAWSCRT.aws_s3_get_compute_platform_info_for_instance_type — Method
aws_s3_get_compute_platform_info_for_instance_type(instance_type_name)

Retrieves the pre-configured metadata for an ec2 instance type. If no such pre-configuration exists, returns NULL.

Prototype

struct aws_s3_compute_platform_info *aws_s3_get_compute_platform_info_for_instance_type( const struct aws_byte_cursor instance_type_name);
source
LibAWSCRT.aws_s3_init_default_signing_config — Method
aws_s3_init_default_signing_config(signing_config, region, credentials_provider)

Initialize the configuration for a default S3 signing.

Prototype

void aws_s3_init_default_signing_config( struct aws_signing_config_aws *signing_config, const struct aws_byte_cursor region, struct aws_credentials_provider *credentials_provider);
source
LibAWSCRT.aws_s3_library_init — Method
aws_s3_library_init(allocator)

Initializes internal datastructures used by aws-c-s3. Must be called before using any functionality in aws-c-s3.

Prototype

void aws_s3_library_init(struct aws_allocator *allocator);
source
LibAWSCRT.aws_s3_meta_request_acquire — Method
aws_s3_meta_request_acquire(meta_request)

Add a reference, keeping this object alive. The reference must be released when you are done with it, or it's memory will never be cleaned up. You must not pass in NULL. Always returns the same pointer that was passed in.

Prototype

struct aws_s3_meta_request *aws_s3_meta_request_acquire(struct aws_s3_meta_request *meta_request);
source
LibAWSCRT.aws_s3_meta_request_increment_read_window — Method
aws_s3_meta_request_increment_read_window(meta_request, bytes)

Increment the flow-control window, so that response data continues downloading.

If the client was created with enable_read_backpressure set true, each meta request has a flow-control window that shrinks as response body data is downloaded (headers do not affect the size of the window). The client's initial_read_window determines the starting size of each meta request's window. If a meta request's flow-control window reaches 0, no further data will be downloaded. If the initial_read_window is 0, the request will not start until the window is incremented. Maintain a larger window to keep up a high download throughput, parts cannot download in parallel unless the window is large enough to hold multiple parts. Maintain a smaller window to limit the amount of data buffered in memory.

If enable_read_backpressure is false this call will have no effect, no backpressure is being applied and data is being downloaded as fast as possible.

WARNING: This feature is experimental. Currently, backpressure is only applied to GetObject requests which are split into multiple parts, and you may still receive some data after the window reaches 0.

Prototype

void aws_s3_meta_request_increment_read_window(struct aws_s3_meta_request *meta_request, uint64_t bytes);
source
LibAWSCRT.aws_s3_meta_request_pause — Method
aws_s3_meta_request_pause(meta_request, out_resume_token)

Note: pause is currently only supported on upload requests. In order to pause an ongoing upload, call aws_s3_meta_request_pause() that will return resume token. Token can be used to query the state of operation at the pausing time. To resume an upload that was paused, supply resume token in the meta request options structure member aws_s3_meta_request_options.resume_token. The upload can be resumed either from the same client or a different one. Corner cases for resume upload are as follows: - upload is not MPU - fail with AWS_ERROR_UNSUPPORTED_OPERATION - pausing before MPU is created - NULL resume token returned. NULL resume token is equivalent to restarting upload - pausing in the middle of part transfer - return resume token. scheduling of new part uploads stops. - pausing after completeMPU started - return resume token. if s3 cannot find find associated MPU id when resuming with that token and num of parts uploaded equals to total num parts, then operation is a no op. Otherwise operation fails. Note: for no op case the call will succeed and finish/shutdown request callbacks will fire, but on headers callback will not fire. Note: similar to cancel pause does not cancel requests already in flight and and parts might complete after pause is requested.

Parameters

  • meta_request: pointer to the aws_s3_meta_request of the upload to be paused
  • resume_token: resume token

Returns

either AWS_OP_ERR or AWS_OP_SUCCESS

Prototype

int aws_s3_meta_request_pause( struct aws_s3_meta_request *meta_request, struct aws_s3_meta_request_resume_token **out_resume_token);
source
LibAWSCRT.aws_s3_meta_request_release — Method
aws_s3_meta_request_release(meta_request)

Release a reference. When the reference count drops to 0, this object will be cleaned up. It's OK to pass in NULL (nothing happens). Always returns NULL.

Prototype

struct aws_s3_meta_request *aws_s3_meta_request_release(struct aws_s3_meta_request *meta_request);
source
LibAWSCRT.aws_s3_meta_request_resume_token_new_upload — Method
aws_s3_meta_request_resume_token_new_upload(allocator, options)

Create upload resume token from persisted data. Note: Data required for resume token varies per operation.

Prototype

struct aws_s3_meta_request_resume_token *aws_s3_meta_request_resume_token_new_upload( struct aws_allocator *allocator, const struct aws_s3_upload_resume_token_options *options);
source
LibAWSCRT.aws_s3_request_metrics_acquire — Method
aws_s3_request_metrics_acquire(metrics)

Add a reference, keeping this object alive. The reference must be released when you are done with it, or it's memory will never be cleaned up. Always returns the same pointer that was passed in.

Prototype

struct aws_s3_request_metrics *aws_s3_request_metrics_acquire(struct aws_s3_request_metrics *metrics);
source
LibAWSCRT.aws_s3_request_metrics_get_host_address — Method
aws_s3_request_metrics_get_host_address(metrics, out_host_address)

Get the host_address of the request. If unavailable, AWS_ERROR_S3_METRIC_DATA_NOT_AVAILABLE will be raised. If available, out_host_address will be set to a string. Be warned this string's lifetime is tied to the metrics object.

Prototype

void aws_s3_request_metrics_get_host_address( const struct aws_s3_request_metrics *metrics, const struct aws_string **out_host_address);
source
LibAWSCRT.aws_s3_request_metrics_get_ip_address — Method
aws_s3_request_metrics_get_ip_address(metrics, out_ip_address)

Get the IP address of the request connected to. If unavailable, AWS_ERROR_S3_METRIC_DATA_NOT_AVAILABLE will be raised. If available, out_ip_address will be set to a string. Be warned this string's lifetime is tied to the metrics object.

Prototype

int aws_s3_request_metrics_get_ip_address( const struct aws_s3_request_metrics *metrics, const struct aws_string **out_ip_address);
source
LibAWSCRT.aws_s3_request_metrics_get_request_id — Method
aws_s3_request_metrics_get_request_id(metrics, out_request_id)

*********************************** Getters for s3 request metrics ***********************************************

Get the request ID from aws_s3_request_metrics. If unavailable, AWS_ERROR_S3_METRIC_DATA_NOT_AVAILABLE will be raised. If available, out_request_id will be set to a string. Be warned this string's lifetime is tied to the metrics object.

Prototype

int aws_s3_request_metrics_get_request_id( const struct aws_s3_request_metrics *metrics, const struct aws_string **out_request_id);
source
LibAWSCRT.aws_s3_request_metrics_get_request_path_query — Method
aws_s3_request_metrics_get_request_path_query(metrics, out_request_path_query)

Get the path and query of the request. If unavailable, AWS_ERROR_S3_METRIC_DATA_NOT_AVAILABLE will be raised. If available, out_request_path_query will be set to a string. Be warned this string's lifetime is tied to the metrics object.

Prototype

void aws_s3_request_metrics_get_request_path_query( const struct aws_s3_request_metrics *metrics, const struct aws_string **out_request_path_query);
source
LibAWSCRT.aws_s3_request_metrics_get_request_type — Method
aws_s3_request_metrics_get_request_type(metrics, out_request_type)

Prototype

void aws_s3_request_metrics_get_request_type( const struct aws_s3_request_metrics *metrics, enum aws_s3_request_type *out_request_type);
source
LibAWSCRT.aws_s3_request_metrics_get_response_headers — Method
aws_s3_request_metrics_get_response_headers(metrics, out_response_headers)

Prototype

int aws_s3_request_metrics_get_response_headers( const struct aws_s3_request_metrics *metrics, struct aws_http_headers **out_response_headers);
source
LibAWSCRT.aws_s3_request_metrics_release — Method
aws_s3_request_metrics_release(metrics)

Release a reference. When the reference count drops to 0, this object will be cleaned up. It's OK to pass in NULL (nothing happens). Always returns NULL.

Prototype

struct aws_s3_request_metrics *aws_s3_request_metrics_release(struct aws_s3_request_metrics *metrics);
source
LibAWSCRT.aws_secure_strlen — Method
aws_secure_strlen(str, max_read_len, str_len)

Computes the length of a c string in bytes assuming the character set is either ASCII or UTF-8. If no NULL character is found within max_read_len of str, AWS_ERROR_C_STRING_BUFFER_NOT_NULL_TERMINATED is raised. Otherwise, str_len will contain the string length minus the NULL character, and AWS_OP_SUCCESS will be returned.

Prototype

int aws_secure_strlen(const char *str, size_t max_read_len, size_t *str_len);
source
LibAWSCRT.aws_secure_tunnel_acquire — Method
aws_secure_tunnel_acquire(secure_tunnel)

Acquires a reference to a secure tunnel

Parameters

  • secure_tunnel: secure tunnel to acquire a reference to. May be NULL

Returns

what was passed in as the secure tunnel (a client or NULL)

Prototype

struct aws_secure_tunnel *aws_secure_tunnel_acquire(struct aws_secure_tunnel *secure_tunnel);
source
LibAWSCRT.aws_secure_tunnel_connection_start — Method
aws_secure_tunnel_connection_start(secure_tunnel, message_options)

Queue a CONNECTION_START message in a secure tunnel

Note

This function should only be used from source mode.

Parameters

  • secure_tunnel: secure tunnel to queue a message for
  • message_options: configuration options for the message operation

Returns

success/failure in the synchronous logic that kicks off the message operation

Prototype

int aws_secure_tunnel_connection_start( struct aws_secure_tunnel *secure_tunnel, const struct aws_secure_tunnel_message_view *message_options);
source
LibAWSCRT.aws_secure_tunnel_message_type_to_c_string — Method
aws_secure_tunnel_message_type_to_c_string(message_type)

Get the const char description of a message type

Parameters

  • message_type: message type used by a secure tunnel message

Returns

const char translation of the message type

Prototype

const char *aws_secure_tunnel_message_type_to_c_string(enum aws_secure_tunnel_message_type message_type);
source
LibAWSCRT.aws_secure_tunnel_new — Method
aws_secure_tunnel_new(allocator, options)

Creates a new secure tunnel

Parameters

  • options: secure tunnel configuration

Returns

a new secure tunnel or NULL

Prototype

struct aws_secure_tunnel *aws_secure_tunnel_new( struct aws_allocator *allocator, const struct aws_secure_tunnel_options *options);
source
LibAWSCRT.aws_secure_tunnel_release — Method
aws_secure_tunnel_release(secure_tunnel)

Release a reference to a secure tunnel. When the secure tunnel ref count drops to zero, the secure tunnel will automatically trigger a stop and once the stop completes, the secure tunnel will delete itself.

Parameters

  • secure_tunnel: secure tunnel to release a reference to. May be NULL

Returns

NULL

Prototype

struct aws_secure_tunnel *aws_secure_tunnel_release(struct aws_secure_tunnel *secure_tunnel);
source
LibAWSCRT.aws_secure_tunnel_send_message — Method
aws_secure_tunnel_send_message(secure_tunnel, message_options)

Queues a message operation in a secure tunnel

Parameters

  • secure_tunnel: secure tunnel to queue a message for
  • message_options: configuration options for the message operation

Returns

success/failure in the synchronous logic that kicks off the message operation

Prototype

int aws_secure_tunnel_send_message( struct aws_secure_tunnel *secure_tunnel, const struct aws_secure_tunnel_message_view *message_options);
source
LibAWSCRT.aws_secure_tunnel_start — Method
aws_secure_tunnel_start(secure_tunnel)

Asynchronous notify to the secure tunnel that you want it to attempt to connect. The secure tunnel will attempt to stay connected.

Parameters

  • secure_tunnel: secure tunnel to start

Returns

success/failure in the synchronous logic that kicks off the start process

Prototype

int aws_secure_tunnel_start(struct aws_secure_tunnel *secure_tunnel);
source
LibAWSCRT.aws_secure_tunnel_stop — Method
aws_secure_tunnel_stop(secure_tunnel)

Asynchronous notify to the secure tunnel that you want it to transition to the stopped state. When the secure tunnel reaches the stopped state, all session state is erased.

Parameters

  • secure_tunnel: secure tunnel to stop

Returns

success/failure in the synchronous logic that kicks off the start process

Prototype

int aws_secure_tunnel_stop(struct aws_secure_tunnel *secure_tunnel);
source
LibAWSCRT.aws_secure_tunnel_stream_reset — Method
aws_secure_tunnel_stream_reset(secure_tunnel, message_options)

Queue a STREAM_RESET message in a secure tunnel

\deprecated This function should not be used.

Parameters

  • secure_tunnel: secure tunnel to queue a message for
  • message_options: configuration options for the message operation

Returns

success/failure in the synchronous logic that kicks off the message operation

Prototype

int aws_secure_tunnel_stream_reset( struct aws_secure_tunnel *secure_tunnel, const struct aws_secure_tunnel_message_view *message_options);
source
LibAWSCRT.aws_secure_tunnel_stream_start — Method
aws_secure_tunnel_stream_start(secure_tunnel, message_options)

Queue a STREAM_START message in a secure tunnel

Note

This function should only be used from source mode.

Parameters

  • secure_tunnel: secure tunnel to queue a message for
  • message_options: configuration options for the message operation

Returns

success/failure in the synchronous logic that kicks off the message operation

Prototype

int aws_secure_tunnel_stream_start( struct aws_secure_tunnel *secure_tunnel, const struct aws_secure_tunnel_message_view *message_options);
source
LibAWSCRT.aws_secure_zero — Method
aws_secure_zero(pBuf, bufsize)

Securely zeroes a memory buffer. This function will attempt to ensure that the compiler will not optimize away this zeroing operation.

Prototype

void aws_secure_zero(void *pBuf, size_t bufsize);
source
LibAWSCRT.aws_server_bootstrap_acquire — Method
aws_server_bootstrap_acquire(bootstrap)

Increments a server bootstrap's ref count, allowing the caller to take a reference to it.

Returns the same server bootstrap passed in.

Prototype

struct aws_server_bootstrap *aws_server_bootstrap_acquire(struct aws_server_bootstrap *bootstrap);
source
LibAWSCRT.aws_server_bootstrap_destroy_socket_listener — Method
aws_server_bootstrap_destroy_socket_listener(bootstrap, listener)

Shuts down 'listener' and cleans up any resources associated with it. Any incoming channels on listener will still be active. destroy_callback will be invoked after the server socket listener is destroyed, and all associated connections and channels have finished shutting down.

Prototype

void aws_server_bootstrap_destroy_socket_listener( struct aws_server_bootstrap *bootstrap, struct aws_socket *listener);
source
LibAWSCRT.aws_server_bootstrap_new — Method
aws_server_bootstrap_new(allocator, el_group)

Initializes the server bootstrap with allocator and el_group. This object manages listeners, server connections, and channels.

Prototype

struct aws_server_bootstrap *aws_server_bootstrap_new( struct aws_allocator *allocator, struct aws_event_loop_group *el_group);
source
LibAWSCRT.aws_server_bootstrap_new_socket_listener — Method
aws_server_bootstrap_new_socket_listener(bootstrap_options)

Sets up a server socket listener. If you are planning on using TLS, use aws_server_bootstrap_new_tls_socket_listener instead. This creates a socket listener bound to local_endpoint using socket options options. incoming_callback will be invoked once an incoming channel is ready for use or if an error is encountered. shutdown_callback will be invoked once the channel has shutdown. destroy_callback will be invoked after the server socket listener is destroyed, and all associated connections and channels have finished shutting down. Immediately after the shutdown_callback returns, the channel is cleaned up automatically. All callbacks are invoked the thread of the event-loop that the listening socket is assigned to

Upon shutdown of your application, you'll want to call aws_server_bootstrap_destroy_socket_listener with the return value from this function.

bootstrap_options is copied.

Prototype

struct aws_socket *aws_server_bootstrap_new_socket_listener( const struct aws_server_socket_channel_bootstrap_options *bootstrap_options);
source
LibAWSCRT.aws_server_bootstrap_release — Method
aws_server_bootstrap_release(bootstrap)

Decrements a server bootstrap's ref count. When the ref count drops to zero, the bootstrap will be destroyed.

Prototype

void aws_server_bootstrap_release(struct aws_server_bootstrap *bootstrap);
source
LibAWSCRT.aws_server_bootstrap_set_alpn_callback — Method
aws_server_bootstrap_set_alpn_callback(bootstrap, on_protocol_negotiated)

When using TLS, if ALPN is used, this callback will be invoked from the channel. The returned handler will be added to the channel.

Prototype

int aws_server_bootstrap_set_alpn_callback( struct aws_server_bootstrap *bootstrap, aws_channel_on_protocol_negotiated_fn *on_protocol_negotiated);
source
LibAWSCRT.aws_set_environment_value — Method
aws_set_environment_value(variable_name, value)

Prototype

int aws_set_environment_value(const struct aws_string *variable_name, const struct aws_string *value);
source
LibAWSCRT.aws_set_md5_new_fn — Method
aws_set_md5_new_fn(fn)

Set the implementation of md5 to use. If you compiled without BYO_CRYPTO, you do not need to call this. However, if use this, we will honor it, regardless of compile options. This may be useful for testing purposes. If you did set BYO_CRYPTO, and you do not call this function you will segfault.

Prototype

void aws_set_md5_new_fn(aws_hash_new_fn *fn);
source
LibAWSCRT.aws_set_sha1_new_fn — Method
aws_set_sha1_new_fn(fn)

Set the implementation of sha1 to use. If you compiled without BYO_CRYPTO, you do not need to call this. However, if use this, we will honor it, regardless of compile options. This may be useful for testing purposes. If you did set BYO_CRYPTO, and you do not call this function you will segfault.

Prototype

void aws_set_sha1_new_fn(aws_hash_new_fn *fn);
source
LibAWSCRT.aws_set_sha256_hmac_new_fn — Method
aws_set_sha256_hmac_new_fn(fn)

Set the implementation of sha256 hmac to use. If you compiled without BYO_CRYPTO, you do not need to call this. However, if use this, we will honor it, regardless of compile options. This may be useful for testing purposes. If you did set BYO_CRYPTO, and you do not call this function you will segfault.

Prototype

void aws_set_sha256_hmac_new_fn(aws_hmac_new_fn *fn);
source
LibAWSCRT.aws_set_sha256_new_fn — Method
aws_set_sha256_new_fn(fn)

Set the implementation of sha256 to use. If you compiled without BYO_CRYPTO, you do not need to call this. However, if use this, we will honor it, regardless of compile options. This may be useful for testing purposes. If you did set BYO_CRYPTO, and you do not call this function you will segfault.

Prototype

void aws_set_sha256_new_fn(aws_hash_new_fn *fn);
source
LibAWSCRT.aws_set_soft_limit_io_handles — Method
aws_set_soft_limit_io_handles(max_handles)

Sets the new soft limit for io_handles (max fds). This can be up to the hard limit but may not exceed it.

This operation will always fail with AWS_ERROR_UNIMPLEMENTED error code on Windows.

Prototype

int aws_set_soft_limit_io_handles(size_t max_handles);
source
LibAWSCRT.aws_sha1_compute — Method
aws_sha1_compute(allocator, input, output, truncate_to)

Computes the sha1 hash over input and writes the digest output to 'output'. Use this if you don't need to stream the data you're hashing and you can load the entire input to hash into memory. If you specify truncate_to to something other than 0, the output will be truncated to that number of bytes. For example, if you want a SHA1 digest as the first 16 bytes, set truncate_to to 16. If you want the full digest size, just set this to 0.

Prototype

int aws_sha1_compute( struct aws_allocator *allocator, const struct aws_byte_cursor *input, struct aws_byte_buf *output, size_t truncate_to);
source
LibAWSCRT.aws_sha1_new — Method
aws_sha1_new(allocator)

Allocates and initializes a sha1 hash instance.

Prototype

struct aws_hash *aws_sha1_new(struct aws_allocator *allocator);
source
LibAWSCRT.aws_sha256_compute — Method
aws_sha256_compute(allocator, input, output, truncate_to)

Computes the sha256 hash over input and writes the digest output to 'output'. Use this if you don't need to stream the data you're hashing and you can load the entire input to hash into memory. If you specify truncate_to to something other than 0, the output will be truncated to that number of bytes. For example, if you want a SHA256 digest as the first 16 bytes, set truncate_to to 16. If you want the full digest size, just set this to 0.

Prototype

int aws_sha256_compute( struct aws_allocator *allocator, const struct aws_byte_cursor *input, struct aws_byte_buf *output, size_t truncate_to);
source
LibAWSCRT.aws_sha256_hmac_compute — Method
aws_sha256_hmac_compute(allocator, secret, to_hmac, output, truncate_to)

Computes the sha256 hmac over input and writes the digest output to 'output'. Use this if you don't need to stream the data you're hashing and you can load the entire input to hash into memory. If you specify truncate_to to something other than 0, the output will be truncated to that number of bytes. For example if you want a SHA256 HMAC digest as the first 16 bytes, set truncate_to to 16. If you want the full digest size, just set this to 0.

Prototype

int aws_sha256_hmac_compute( struct aws_allocator *allocator, const struct aws_byte_cursor *secret, const struct aws_byte_cursor *to_hmac, struct aws_byte_buf *output, size_t truncate_to);
source
LibAWSCRT.aws_sha256_hmac_new — Method
aws_sha256_hmac_new(allocator, secret)

Allocates and initializes a sha256 hmac instance. Secret is the key to be used for the hmac process.

Prototype

struct aws_hmac *aws_sha256_hmac_new(struct aws_allocator *allocator, const struct aws_byte_cursor *secret);
source
LibAWSCRT.aws_sha256_new — Method
aws_sha256_new(allocator)

Allocates and initializes a sha256 hash instance.

Prototype

struct aws_hash *aws_sha256_new(struct aws_allocator *allocator);
source
LibAWSCRT.aws_shared_library_find_function — Method
aws_shared_library_find_function(library, symbol_name, function_address)

Prototype

int aws_shared_library_find_function( struct aws_shared_library *library, const char *symbol_name, aws_generic_function *function_address);
source
LibAWSCRT.aws_shared_library_init — Method
aws_shared_library_init(library, library_path)

Prototype

int aws_shared_library_init(struct aws_shared_library *library, const char *library_path);
source
LibAWSCRT.aws_sign_request_aws — Method
aws_sign_request_aws(allocator, signable, base_config, on_complete, userdata)

(Asynchronous) entry point to sign something (a request, a chunk, an event) with an AWS signing process. Depending on the configuration, the signing process may or may not complete synchronously.

Parameters

  • allocator: memory allocator to use throughout the signing process
  • signable: the thing to be signed. See signable.h for common constructors for signables that wrap different types.
  • base_config: pointer to a signing configuration, currently this must be of type aws_signing_config_aws
  • on_complete: completion callback to be invoked when signing has finished
  • user_data: opaque user data that will be passed to the completion callback

Returns

AWS_OP_SUCCESS if the signing attempt was initiated successfully, AWS_OP_ERR otherwise

Prototype

int aws_sign_request_aws( struct aws_allocator *allocator, const struct aws_signable *signable, const struct aws_signing_config_base *base_config, aws_signing_complete_fn *on_complete, void *userdata);
source
LibAWSCRT.aws_signable_destroy — Method
aws_signable_destroy(signable)

Cleans up and frees all resources associated with a signable instance

Parameters

  • signable: signable object to destroy

Prototype

void aws_signable_destroy(struct aws_signable *signable);
source
LibAWSCRT.aws_signable_get_payload_stream — Method
aws_signable_get_payload_stream(signable, out_input_stream)

Retrieves the signable's message payload as a stream.

Parameters

  • signable: signable to get the payload of
  • out_input_stream: output parameter for the payload stream

Returns

AWS_OP_SUCCESS if successful, AWS_OP_ERR otherwise

Prototype

int aws_signable_get_payload_stream(const struct aws_signable *signable, struct aws_input_stream **out_input_stream);
source
LibAWSCRT.aws_signable_get_property — Method
aws_signable_get_property(signable, name, out_value)

Retrieves a property (key-value pair) from a signable. Global property name constants are included below.

Parameters

  • signable: signable object to retrieve a property from
  • name: name of the property to query
  • out_value: output parameter for the property's value

Returns

AWS_OP_SUCCESS if the property was successfully fetched, AWS_OP_ERR otherwise

Prototype

int aws_signable_get_property( const struct aws_signable *signable, const struct aws_string *name, struct aws_byte_cursor *out_value);
source
LibAWSCRT.aws_signable_get_property_list — Method
aws_signable_get_property_list(signable, name, out_property_list)

Retrieves a named property list (list of key-value pairs) from a signable. Global property list name constants are included below.

Parameters

  • signable: signable object to retrieve a property list from
  • name: name of the property list to fetch
  • out_property_list: output parameter for the fetched property list

Returns

AWS_OP_SUCCESS if the property list was successfully fetched, AWS_OP_ERR otherwise

Prototype

int aws_signable_get_property_list( const struct aws_signable *signable, const struct aws_string *name, struct aws_array_list **out_property_list);
source
LibAWSCRT.aws_signable_new_canonical_request — Method
aws_signable_new_canonical_request(allocator, canonical_request)

Creates a signable that represents a pre-computed canonical request from an http request

Parameters

  • allocator: memory allocator use to create the signable
  • canonical_request: text of the canonical request

Returns

the new signable object, or NULL if failure

Prototype

struct aws_signable *aws_signable_new_canonical_request( struct aws_allocator *allocator, struct aws_byte_cursor canonical_request);
source
LibAWSCRT.aws_signable_new_chunk — Method
aws_signable_new_chunk(allocator, chunk_data, previous_signature)

Creates a signable that represents a unit of chunked encoding within an http request. This can also be used for Transcribe event signing with encoded payload as chunk_data.

Parameters

  • allocator: memory allocator use to create the signable
  • chunk_data: stream representing the data in the chunk; it should be in its final, encoded form
  • previous_signature: the signature computed in the most recent signing that preceded this one. It can be found by copying the "signature" property from the signing_result of that most recent signing.

Returns

the new signable object, or NULL if failure

Prototype

struct aws_signable *aws_signable_new_chunk( struct aws_allocator *allocator, struct aws_input_stream *chunk_data, struct aws_byte_cursor previous_signature);
source
LibAWSCRT.aws_signable_new_http_request — Method
aws_signable_new_http_request(allocator, request)

Creates a signable wrapper around an http request.

Parameters

  • allocator: memory allocator to use to create the signable
  • request: http request to create a signable for

Returns

the new signable object, or NULL if failure

Prototype

struct aws_signable *aws_signable_new_http_request(struct aws_allocator *allocator, struct aws_http_message *request);
source
LibAWSCRT.aws_signable_new_trailing_headers — Method
aws_signable_new_trailing_headers(allocator, trailing_headers, previous_signature)

Creates a signable wrapper around a set of headers.

Parameters

  • allocator: memory allocator use to create the signable
  • trailing_headers: http headers to create a signable for
  • previous_signature: the signature computed in the most recent signing that preceded this one. It can be found by copying the "signature" property from the signing_result of that most recent signing.

Returns

the new signable object, or NULL if failure

Prototype

struct aws_signable *aws_signable_new_trailing_headers( struct aws_allocator *allocator, struct aws_http_headers *trailing_headers, struct aws_byte_cursor previous_signature);
source
LibAWSCRT.aws_signing_algorithm_to_string — Method
aws_signing_algorithm_to_string(algorithm)

Returns a c-string that describes the supplied signing algorithm

Parameters

  • algorithm: signing algorithm to get a friendly string name for

Returns

friendly string name of the supplied algorithm, or "Unknown" if the algorithm is not recognized

Prototype

const char *aws_signing_algorithm_to_string(enum aws_signing_algorithm algorithm);
source
LibAWSCRT.aws_signing_result_append_property_list — Method
aws_signing_result_append_property_list(result, list_name, property_name, property_value)

Adds a key-value pair to a named property list. If the named list does not yet exist, it will be created as an empty list before the pair is added. No uniqueness checks are made against existing pairs.

Parameters

  • result: signing result to modify
  • list_name: name of the list to add the property key-value pair to
  • property_name: key value of the key-value pair to append
  • property_value: property value of the key-value pair to append

Returns

AWS_OP_SUCCESS if the operation was successful, AWS_OP_ERR otherwise

Prototype

int aws_signing_result_append_property_list( struct aws_signing_result *result, const struct aws_string *list_name, const struct aws_byte_cursor *property_name, const struct aws_byte_cursor *property_value);
source
LibAWSCRT.aws_signing_result_clean_up — Method
aws_signing_result_clean_up(result)

Clean up all resources held by the signing result

Parameters

  • result: signing result to clean up resources for

Prototype

void aws_signing_result_clean_up(struct aws_signing_result *result);
source
LibAWSCRT.aws_signing_result_get_property — Method
aws_signing_result_get_property(result, property_name, out_property_value)

Gets the value of a property on a signing result

Parameters

  • result: signing result to query from
  • property_name: name of the property to query the value of
  • out_property_value: output parameter for the property value

Returns

AWS_OP_SUCCESS if the get was successful, AWS_OP_ERR otherwise

Prototype

int aws_signing_result_get_property( const struct aws_signing_result *result, const struct aws_string *property_name, struct aws_string **out_property_value);
source
LibAWSCRT.aws_signing_result_get_property_list — Method
aws_signing_result_get_property_list(result, list_name, out_list)

Gets a named property list on the signing result. If the list does not exist, *out_list will be set to null

Parameters

  • result: signing result to query
  • list_name: name of the list of key-value pairs to get
  • out_list: output parameter for the list of key-value pairs

Prototype

void aws_signing_result_get_property_list( const struct aws_signing_result *result, const struct aws_string *list_name, struct aws_array_list **out_list);
source
LibAWSCRT.aws_signing_result_get_property_value_in_property_list — Method
aws_signing_result_get_property_value_in_property_list(result, list_name, property_name, out_value)

Looks for a property within a named property list on the signing result. If the list does not exist, or the property does not exist within the list, *out_value will be set to NULL.

Parameters

  • result: signing result to query
  • list_name: name of the list of key-value pairs to search through for the property
  • property_name: name of the property to search for within the list
  • out_value: output parameter for the property value, if found

Prototype

void aws_signing_result_get_property_value_in_property_list( const struct aws_signing_result *result, const struct aws_string *list_name, const struct aws_string *property_name, struct aws_string **out_value);
source
LibAWSCRT.aws_signing_result_init — Method
aws_signing_result_init(result, allocator)

Initialize a signing result to its starting state

Parameters

  • result: signing result to initialize
  • allocator: allocator to use for all memory allocation

Returns

AWS_OP_SUCCESS if initialization was successful, AWS_OP_ERR otherwise

Prototype

int aws_signing_result_init(struct aws_signing_result *result, struct aws_allocator *allocator);
source
LibAWSCRT.aws_signing_result_set_property — Method
aws_signing_result_set_property(result, property_name, property_value)

Sets the value of a property on a signing result

Parameters

  • result: signing result to modify
  • property_name: name of the property to set
  • property_value: value that the property should assume

Returns

AWS_OP_SUCCESS if the set was successful, AWS_OP_ERR otherwise

Prototype

int aws_signing_result_set_property( struct aws_signing_result *result, const struct aws_string *property_name, const struct aws_byte_cursor *property_value);
source
LibAWSCRT.aws_small_block_allocator_new — Method
aws_small_block_allocator_new(allocator, multi_threaded)

Prototype

struct aws_allocator *aws_small_block_allocator_new(struct aws_allocator *allocator, bool multi_threaded);
source
LibAWSCRT.aws_socket_assign_to_event_loop — Method
aws_socket_assign_to_event_loop(socket, event_loop)

Assigns the socket to the event-loop. The socket will begin receiving read/write/error notifications after this call.

Note: If you called connect for TCP or Unix Domain Sockets and received a connection_success callback, this has already happened. You only need to call this function when:

a.) This socket is a server socket (e.g. a result of a call to start_accept()) b.) This socket is a UDP socket.

Prototype

int aws_socket_assign_to_event_loop(struct aws_socket *socket, struct aws_event_loop *event_loop);
source
LibAWSCRT.aws_socket_bind — Method
aws_socket_bind(socket, local_endpoint)

Binds the socket to a local address. In UDP mode, the socket is ready for [awssocketread](@ref)() operations. In connection oriented modes, you still must call [awssocketlisten](@ref)() and [awssocketstartaccept](@ref)() before using the socket. local\endpoint is copied.

Prototype

int aws_socket_bind(struct aws_socket *socket, const struct aws_socket_endpoint *local_endpoint);
source
LibAWSCRT.aws_socket_clean_up — Method
aws_socket_clean_up(socket)

Shuts down any pending operations on the socket, and cleans up state. The socket object can be re-initialized after this operation. This function calls aws_socket_close. If you have not already called aws_socket_close() on the socket, all of the rules for aws_socket_close() apply here. In this case it will not fail if you use the function improperly, but on some platforms you will certainly leak memory.

If the socket has already been closed, you can safely, call this from any thread.

Prototype

void aws_socket_clean_up(struct aws_socket *socket);
source
LibAWSCRT.aws_socket_close — Method
aws_socket_close(socket)

Calls close() on the socket and unregisters all io operations from the event loop. This function must be called from the event-loop's thread unless this is a listening socket. If it's a listening socket it can be called from any non-event-loop thread or the event-loop the socket is currently assigned to. If called from outside the event-loop, this function will block waiting on the socket to close. If this is called from an event-loop thread other than the one it's assigned to, it presents the possibility of a deadlock, so don't do it.

Prototype

int aws_socket_close(struct aws_socket *socket);
source
LibAWSCRT.aws_socket_connect — Method
aws_socket_connect(socket, remote_endpoint, event_loop, on_connection_result, user_data)

Connects to a remote endpoint. In UDP, this simply binds the socket to a remote address for use with [awssocketwrite](@ref)(), and if the operation is successful, the socket can immediately be used for write operations.

In TCP, LOCAL and VSOCK this function will not block. If the return value is successful, then you must wait on the on\_connection\_result() callback to be invoked before using the socket.

If an event_loop is provided for UDP sockets, a notification will be sent on on_connection_result in the event-loop's thread. Upon completion, the socket will already be assigned an event loop. If NULL is passed for UDP, it will immediately return upon success, but you must call aws_socket_assign_to_event_loop before use.

Prototype

int aws_socket_connect( struct aws_socket *socket, const struct aws_socket_endpoint *remote_endpoint, struct aws_event_loop *event_loop, aws_socket_on_connection_result_fn *on_connection_result, void *user_data);
source
LibAWSCRT.aws_socket_endpoint_init_local_address_for_test — Method
aws_socket_endpoint_init_local_address_for_test(endpoint)

Assigns a random address (UUID) for use with AWS_SOCKET_LOCAL (Unix Domain Sockets). For use in internal tests only.

Prototype

void aws_socket_endpoint_init_local_address_for_test(struct aws_socket_endpoint *endpoint);
source
LibAWSCRT.aws_socket_get_bound_address — Method
aws_socket_get_bound_address(socket, out_address)

Get the local address which the socket is bound to. Raises an error if no address is bound.

Prototype

int aws_socket_get_bound_address(const struct aws_socket *socket, struct aws_socket_endpoint *out_address);
source
LibAWSCRT.aws_socket_get_error — Method
aws_socket_get_error(socket)

Gets the latest error from the socket. If no error has occurred AWS_OP_SUCCESS will be returned. This function does not raise any errors to the installed error handlers.

Prototype

int aws_socket_get_error(struct aws_socket *socket);
source
LibAWSCRT.aws_socket_get_event_loop — Method
aws_socket_get_event_loop(socket)

Gets the event-loop the socket is assigned to.

Prototype

struct aws_event_loop *aws_socket_get_event_loop(struct aws_socket *socket);
source
LibAWSCRT.aws_socket_handler_new — Method
aws_socket_handler_new(allocator, socket, slot, max_read_size)

Socket handlers should be the first slot/handler in a channel. It interacts directly with the channel's event loop for read and write notifications. max_read_size is the maximum amount of data it will read from the socket before a context switch (a continuation task will be scheduled).

Prototype

struct aws_channel_handler *aws_socket_handler_new( struct aws_allocator *allocator, struct aws_socket *socket, struct aws_channel_slot *slot, size_t max_read_size);
source
LibAWSCRT.aws_socket_init — Method
aws_socket_init(socket, alloc, options)

Initializes a socket object with socket options. options will be copied.

Prototype

int aws_socket_init( struct aws_socket *socket, struct aws_allocator *alloc, const struct aws_socket_options *options);
source
LibAWSCRT.aws_socket_is_open — Method
aws_socket_is_open(socket)

Returns true if the socket is still open (doesn't mean connected or listening, only that it hasn't had close() called.

Prototype

bool aws_socket_is_open(struct aws_socket *socket);
source
LibAWSCRT.aws_socket_listen — Method
aws_socket_listen(socket, backlog_size)

TCP, LOCAL and VSOCK only. Sets up the socket to listen on the address bound to in [awssocketbind](@ref)().

Prototype

int aws_socket_listen(struct aws_socket *socket, int backlog_size);
source
LibAWSCRT.aws_socket_read — Method
aws_socket_read(socket, buffer, amount_read)

Reads from the socket. This call is non-blocking and will return AWS_IO_SOCKET_READ_WOULD_BLOCK if no data is available. read is the amount of data read into buffer.

Attempts to read enough to fill all remaining space in the buffer, from buffer->len to buffer->capacity. buffer->len is updated to reflect the buffer's new length.

Use aws_socket_subscribe_to_readable_events() to receive notifications of when the socket goes readable.

NOTE! This function must be called from the event-loop used in aws_socket_assign_to_event_loop

Prototype

int aws_socket_read(struct aws_socket *socket, struct aws_byte_buf *buffer, size_t *amount_read);
source
LibAWSCRT.aws_socket_set_options — Method
aws_socket_set_options(socket, options)

Sets new socket options on the underlying socket. This is mainly useful in context of accepting a new connection via: on\_incoming\_connection(). options is copied.

Prototype

int aws_socket_set_options(struct aws_socket *socket, const struct aws_socket_options *options);
source
LibAWSCRT.aws_socket_shutdown_dir — Method
aws_socket_shutdown_dir(socket, dir)

Calls shutdown() on the socket based on direction.

Prototype

int aws_socket_shutdown_dir(struct aws_socket *socket, enum aws_channel_direction dir);
source
LibAWSCRT.aws_socket_start_accept — Method
aws_socket_start_accept(socket, accept_loop, on_accept_result, user_data)

TCP, LOCAL and VSOCK only. The socket will begin accepting new connections. This is an asynchronous operation. New connections or errors will arrive via the on_accept_result callback.

aws_socket_bind() and aws_socket_listen() must be called before calling this function.

Prototype

int aws_socket_start_accept( struct aws_socket *socket, struct aws_event_loop *accept_loop, aws_socket_on_accept_result_fn *on_accept_result, void *user_data);
source
LibAWSCRT.aws_socket_stop_accept — Method
aws_socket_stop_accept(socket)

TCP, LOCAL and VSOCK only. The listening socket will stop accepting new connections. It is safe to call [awssocketstart_accept](@ref)() again after this operation. This can be called from any thread but be aware, on some platforms, if you call this from outside of the current event loop's thread, it will block until the event loop finishes processing the request for unsubscribe in it's own thread.

Prototype

int aws_socket_stop_accept(struct aws_socket *socket);
source
LibAWSCRT.aws_socket_subscribe_to_readable_events — Method
aws_socket_subscribe_to_readable_events(socket, on_readable, user_data)

Subscribes on_readable to notifications when the socket goes readable (edge-triggered). Errors will also be recieved in the callback.

Note! This function is technically not thread safe, but we do not enforce which thread you call from. It's your responsibility to either call this in safely (e.g. just don't call it in parallel from multiple threads) or schedule a task to call it. If you call it before your first call to read, it will be fine.

Prototype

int aws_socket_subscribe_to_readable_events( struct aws_socket *socket, aws_socket_on_readable_fn *on_readable, void *user_data);
source
LibAWSCRT.aws_socket_write — Method
aws_socket_write(socket, cursor, written_fn, user_data)

Writes to the socket. This call is non-blocking and will attempt to write as much as it can, but will queue any remaining portion of the data for write when available. written_fn will be invoked once the entire cursor has been written, or the write failed or was cancelled.

NOTE! This function must be called from the event-loop used in aws_socket_assign_to_event_loop

For client sockets, connect() and aws_socket_assign_to_event_loop() must be called before calling this.

For incoming sockets from a listener, aws_socket_assign_to_event_loop() must be called first.

Prototype

int aws_socket_write( struct aws_socket *socket, const struct aws_byte_cursor *cursor, aws_socket_on_write_completed_fn *written_fn, void *user_data);
source
LibAWSCRT.aws_string_bytes — Method
aws_string_bytes(str)

Equivalent to str->bytes.

Prototype

AWS_STATIC_IMPL const uint8_t *aws_string_bytes(const struct aws_string *str);
source
LibAWSCRT.aws_string_c_str — Method
aws_string_c_str(str)

Equivalent to (const char *)str->bytes.

Prototype

AWS_STATIC_IMPL const char *aws_string_c_str(const struct aws_string *str);
source
LibAWSCRT.aws_string_clone_or_reuse — Method
aws_string_clone_or_reuse(allocator, str)

If the string was dynamically allocated, clones it. If the string was statically allocated (i.e. has no allocator), returns the original string.

Prototype

struct aws_string *aws_string_clone_or_reuse(struct aws_allocator *allocator, const struct aws_string *str);
source
LibAWSCRT.aws_string_compare — Method
aws_string_compare(a, b)

Compares lexicographical ordering of two strings. This is a binary byte-by-byte comparison, treating bytes as unsigned integers. It is suitable for either textual or binary data and is unaware of unicode or any other byte encoding. If both strings are identical in the bytes of the shorter string, then the longer string is lexicographically after the shorter.

Returns a positive number if string a > string b. (i.e., string a is lexicographically after string b.) Returns zero if string a = string b. Returns negative number if string a < string b.

Prototype

int aws_string_compare(const struct aws_string *a, const struct aws_string *b);
source
LibAWSCRT.aws_string_eq — Method
aws_string_eq(a, b)

Returns true if bytes of string are the same, false otherwise.

Prototype

bool aws_string_eq(const struct aws_string *a, const struct aws_string *b);
source
LibAWSCRT.aws_string_eq_byte_buf — Method
aws_string_eq_byte_buf(str, buf)

Returns true if bytes of string and buffer are the same, false otherwise.

Prototype

bool aws_string_eq_byte_buf(const struct aws_string *str, const struct aws_byte_buf *buf);
source
LibAWSCRT.aws_string_eq_byte_buf_ignore_case — Method
aws_string_eq_byte_buf_ignore_case(str, buf)

Returns true if bytes of string and buffer are equivalent, using a case-insensitive comparison.

Prototype

bool aws_string_eq_byte_buf_ignore_case(const struct aws_string *str, const struct aws_byte_buf *buf);
source
LibAWSCRT.aws_string_eq_byte_cursor — Method
aws_string_eq_byte_cursor(str, cur)

Returns true if bytes of string and cursor are the same, false otherwise.

Prototype

bool aws_string_eq_byte_cursor(const struct aws_string *str, const struct aws_byte_cursor *cur);
source
LibAWSCRT.aws_string_eq_byte_cursor_ignore_case — Method
aws_string_eq_byte_cursor_ignore_case(str, cur)

Returns true if bytes of string and cursor are equivalent, using a case-insensitive comparison.

Prototype

bool aws_string_eq_byte_cursor_ignore_case(const struct aws_string *str, const struct aws_byte_cursor *cur);
source
LibAWSCRT.aws_string_eq_c_str_ignore_case — Method
aws_string_eq_c_str_ignore_case(str, c_str)

Returns true if bytes of strings are equivalent, using a case-insensitive comparison.

Prototype

bool aws_string_eq_c_str_ignore_case(const struct aws_string *str, const char *c_str);
source
LibAWSCRT.aws_string_eq_ignore_case — Method
aws_string_eq_ignore_case(a, b)

Returns true if bytes of string are equivalent, using a case-insensitive comparison.

Prototype

bool aws_string_eq_ignore_case(const struct aws_string *a, const struct aws_string *b);
source
LibAWSCRT.aws_string_is_valid — Method
aws_string_is_valid(str)

Evaluates the set of properties that define the shape of all valid aws_string structures. It is also a cheap check, in the sense it run in constant time (i.e., no loops or recursion).

Prototype

AWS_STATIC_IMPL bool aws_string_is_valid(const struct aws_string *str);
source
LibAWSCRT.aws_string_new_from_array — Method
aws_string_new_from_array(allocator, bytes, len)

Allocate a new string with the same contents as array.

Prototype

struct aws_string *aws_string_new_from_array(struct aws_allocator *allocator, const uint8_t *bytes, size_t len);
source
LibAWSCRT.aws_string_new_from_buf — Method
aws_string_new_from_buf(allocator, buf)

Allocate a new string with the same contents as buf.

Prototype

struct aws_string *aws_string_new_from_buf(struct aws_allocator *allocator, const struct aws_byte_buf *buf);
source
LibAWSCRT.aws_string_new_from_c_str — Method
aws_string_new_from_c_str(allocator, c_str)

Constructor functions which copy data from null-terminated C-string or array of bytes.

Prototype

struct aws_string *aws_string_new_from_c_str(struct aws_allocator *allocator, const char *c_str);
source
LibAWSCRT.aws_string_new_from_cursor — Method
aws_string_new_from_cursor(allocator, cursor)

Allocate a new string with the same contents as cursor.

Prototype

struct aws_string *aws_string_new_from_cursor(struct aws_allocator *allocator, const struct aws_byte_cursor *cursor);
source
LibAWSCRT.aws_string_new_from_string — Method
aws_string_new_from_string(allocator, str)

Allocate a new string with the same contents as another string.

Prototype

struct aws_string *aws_string_new_from_string(struct aws_allocator *allocator, const struct aws_string *str);
source
LibAWSCRT.aws_string_to_log_level — Method
aws_string_to_log_level(level_string, log_level)

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.

Prototype

int aws_string_to_log_level(const char *level_string, enum aws_log_level *log_level);
source
LibAWSCRT.aws_sub_size_saturating — Method
aws_sub_size_saturating(a, b)

Subtracts a - b. If the result overflows returns 0.

Prototype

AWS_STATIC_IMPL size_t aws_sub_size_saturating(size_t a, size_t b);
source
LibAWSCRT.aws_sub_u32_saturating — Method
aws_sub_u32_saturating(a, b)

Subtracts a - b. If the result overflows returns 0.

Prototype

AWS_STATIC_IMPL uint32_t aws_sub_u32_saturating(uint32_t a, uint32_t b);
source
LibAWSCRT.aws_sub_u64_saturating — Method
aws_sub_u64_saturating(a, b)

Subtracts a - b. If the result overflows returns 0.

Prototype

AWS_STATIC_IMPL uint64_t aws_sub_u64_saturating(uint64_t a, uint64_t b);
source
LibAWSCRT.aws_symmetric_cipher_decrypt — Method
aws_symmetric_cipher_decrypt(cipher, to_decrypt, out)

Decrypts the value in to_decrypt and writes the decrypted data into out. If out is dynamic it will be expanded. If it is not, and out is not large enough to handle the decrypted output, the call will fail. If you're trying to optimize to use a stack based array or something, make sure it's at least as large as the size of to_decrypt + an extra BLOCK to account for padding etc...

returns AWS_OP_SUCCESS on success. Call aws_last_error() to determine the failure cause if it returns AWS_OP_ERR;

Prototype

int aws_symmetric_cipher_decrypt( struct aws_symmetric_cipher *cipher, struct aws_byte_cursor to_decrypt, struct aws_byte_buf *out);
source
LibAWSCRT.aws_symmetric_cipher_destroy — Method
aws_symmetric_cipher_destroy(cipher)

Cleans up internal resources and state for cipher and then deallocates it.

Prototype

void aws_symmetric_cipher_destroy(struct aws_symmetric_cipher *cipher);
source
LibAWSCRT.aws_symmetric_cipher_encrypt — Method
aws_symmetric_cipher_encrypt(cipher, to_encrypt, out)

Encrypts the value in to_encrypt and writes the encrypted data into out. If out is dynamic it will be expanded. If it is not, and out is not large enough to handle the encrypted output, the call will fail. If you're trying to optimize to use a stack based array or something, make sure it's at least as large as the size of to_encrypt + an extra BLOCK to account for padding etc...

returns AWS_OP_SUCCESS on success. Call aws_last_error() to determine the failure cause if it returns AWS_OP_ERR;

Prototype

int aws_symmetric_cipher_encrypt( struct aws_symmetric_cipher *cipher, struct aws_byte_cursor to_encrypt, struct aws_byte_buf *out);
source
LibAWSCRT.aws_symmetric_cipher_finalize_decryption — Method
aws_symmetric_cipher_finalize_decryption(cipher, out)

Decrypts any remaining data that was reserved for final padding, loads GMACs etc... and if there is any writes any remaining decrypted data to out. If out is dynamic it will be expanded. If it is not, and out is not large enough to handle the decrypted output, the call will fail. If you're trying to optimize to use a stack based array or something, make sure it's at least as large as the size of 2 BLOCKs to account for padding etc...

After invoking this function, you MUST call aws_symmetric_cipher_reset() before invoking any encrypt/decrypt operations on this cipher again.

returns AWS_OP_SUCCESS on success. Call aws_last_error() to determine the failure cause if it returns AWS_OP_ERR;

Prototype

int aws_symmetric_cipher_finalize_decryption(struct aws_symmetric_cipher *cipher, struct aws_byte_buf *out);
source
LibAWSCRT.aws_symmetric_cipher_finalize_encryption — Method
aws_symmetric_cipher_finalize_encryption(cipher, out)

Encrypts any remaining data that was reserved for final padding, loads GMACs etc... and if there is any writes any remaining encrypted data to out. If out is dynamic it will be expanded. If it is not, and out is not large enough to handle the decrypted output, the call will fail. If you're trying to optimize to use a stack based array or something, make sure it's at least as large as the size of 2 BLOCKs to account for padding etc...

After invoking this function, you MUST call aws_symmetric_cipher_reset() before invoking any encrypt/decrypt operations on this cipher again.

returns AWS_OP_SUCCESS on success. Call aws_last_error() to determine the failure cause if it returns AWS_OP_ERR;

Prototype

int aws_symmetric_cipher_finalize_encryption(struct aws_symmetric_cipher *cipher, struct aws_byte_buf *out);
source
LibAWSCRT.aws_symmetric_cipher_get_initialization_vector — Method
aws_symmetric_cipher_get_initialization_vector(cipher)

Gets the original intialization vector as a cursor. The memory in this cursor is unsafe as it refers to the internal buffer. This was done because the use case doesn't require fetching these during an encryption or decryption operation and it dramatically simplifies the API.

Unlike some other fields, this value does not change after the inital construction of the cipher.

For some algorithms, such as AES Keywrap, this will return an empty cursor.

Prototype

struct aws_byte_cursor aws_symmetric_cipher_get_initialization_vector( const struct aws_symmetric_cipher *cipher);
source
LibAWSCRT.aws_symmetric_cipher_get_key — Method
aws_symmetric_cipher_get_key(cipher)

Gets the original key.

The memory in this cursor is unsafe as it refers to the internal buffer. This was done because the use case doesn't require fetching these during an encryption or decryption operation and it dramatically simplifies the API.

Unlike some other fields, this value does not change after the inital construction of the cipher.

Prototype

struct aws_byte_cursor aws_symmetric_cipher_get_key(const struct aws_symmetric_cipher *cipher);
source
LibAWSCRT.aws_symmetric_cipher_get_tag — Method
aws_symmetric_cipher_get_tag(cipher)

Gets the current GMAC tag. If not AES GCM, this function will just return an empty cursor. The memory in this cursor is unsafe as it refers to the internal buffer. This was done because the use case doesn't require fetching these during an encryption or decryption operation and it dramatically simplifies the API. Only use this function between other calls to this API as any function call can alter the value of this tag.

If you need to access it in a different pattern, copy the values to your own buffer first.

Prototype

struct aws_byte_cursor aws_symmetric_cipher_get_tag(const struct aws_symmetric_cipher *cipher);
source
LibAWSCRT.aws_symmetric_cipher_reset — Method
aws_symmetric_cipher_reset(cipher)

Resets the cipher state for starting a new encrypt or decrypt operation. Note encrypt/decrypt cannot be mixed on the same cipher without a call to reset in between them. However, this leaves the key, iv etc... materials setup for immediate reuse.

returns AWS_OP_SUCCESS on success. Call aws_last_error() to determine the failure cause if it returns AWS_OP_ERR;

Prototype

int aws_symmetric_cipher_reset(struct aws_symmetric_cipher *cipher);
source
LibAWSCRT.aws_sys_clock_get_ticks — Method
aws_sys_clock_get_ticks(timestamp)

Get ticks in nanoseconds (usually 100 nanosecond precision) on the system clock. Reflects actual system time via nanoseconds since unix epoch. Use with care since an inaccurately set clock will probably cause bugs. On success, timestamp will be set.

Prototype

int aws_sys_clock_get_ticks(uint64_t *timestamp);
source
LibAWSCRT.aws_task_init — Method
aws_task_init(task, fn, arg, type_tag)

Init an aws_task

Prototype

void aws_task_init(struct aws_task *task, aws_task_fn *fn, void *arg, const char *type_tag);
source
LibAWSCRT.aws_task_run — Method
aws_task_run(task, status)

Prototype

void aws_task_run(struct aws_task *task, enum aws_task_status status);
source
LibAWSCRT.aws_task_scheduler_cancel_task — Method
aws_task_scheduler_cancel_task(scheduler, task)

Removes task from the scheduler and invokes the task with the AWS_TASK_STATUS_CANCELED status.

Prototype

void aws_task_scheduler_cancel_task(struct aws_task_scheduler *scheduler, struct aws_task *task);
source
LibAWSCRT.aws_task_scheduler_clean_up — Method
aws_task_scheduler_clean_up(scheduler)

Empties and executes all queued tasks, passing the AWS_TASK_STATUS_CANCELED status to the task function. Cleans up any memory allocated, and prepares the instance for reuse or deletion.

Prototype

void aws_task_scheduler_clean_up(struct aws_task_scheduler *scheduler);
source
LibAWSCRT.aws_task_scheduler_has_tasks — Method
aws_task_scheduler_has_tasks(scheduler, next_task_time)

Returns whether the scheduler has any scheduled tasks. next_task_time (optional) will be set to time of the next task, note that 0 will be set if tasks were added via aws_task_scheduler_schedule_now() and UINT64_MAX will be set if no tasks are scheduled at all.

Prototype

bool aws_task_scheduler_has_tasks(const struct aws_task_scheduler *scheduler, uint64_t *next_task_time);
source
LibAWSCRT.aws_task_scheduler_init — Method
aws_task_scheduler_init(scheduler, alloc)

Initializes a task scheduler instance.

Prototype

int aws_task_scheduler_init(struct aws_task_scheduler *scheduler, struct aws_allocator *alloc);
source
LibAWSCRT.aws_task_scheduler_run_all — Method
aws_task_scheduler_run_all(scheduler, current_time)

Sequentially execute all tasks scheduled to run at, or before current_time. AWS_TASK_STATUS_RUN_READY will be passed to the task function as the task status.

If a task schedules another task, the new task will not be executed until the next call to this function.

Prototype

void aws_task_scheduler_run_all(struct aws_task_scheduler *scheduler, uint64_t current_time);
source
LibAWSCRT.aws_task_scheduler_schedule_future — Method
aws_task_scheduler_schedule_future(scheduler, task, time_to_run)

Schedules a task to run at time_to_run. The task should not be cleaned up or modified until its function is executed.

Prototype

void aws_task_scheduler_schedule_future( struct aws_task_scheduler *scheduler, struct aws_task *task, uint64_t time_to_run);
source
LibAWSCRT.aws_task_scheduler_schedule_now — Method
aws_task_scheduler_schedule_now(scheduler, task)

Schedules a task to run immediately. The task should not be cleaned up or modified until its function is executed.

Prototype

void aws_task_scheduler_schedule_now(struct aws_task_scheduler *scheduler, struct aws_task *task);
source
LibAWSCRT.aws_task_status_to_c_str — Method
aws_task_status_to_c_str(status)

Convert a status value to a c-string suitable for logging

Prototype

const char *aws_task_status_to_c_str(enum aws_task_status status);
source
LibAWSCRT.aws_thread_call_once — Method
aws_thread_call_once(flag, call_once, user_data)

Prototype

void aws_thread_call_once(aws_thread_once *flag, void (*call_once)(void *), void *user_data);
source
LibAWSCRT.aws_thread_clean_up — Method
aws_thread_clean_up(thread)

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.

Prototype

void aws_thread_clean_up(struct aws_thread *thread);
source
LibAWSCRT.aws_thread_current_at_exit — Method
aws_thread_current_at_exit(callback, user_data)

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.

Prototype

int aws_thread_current_at_exit(aws_thread_atexit_fn *callback, void *user_data);
source
LibAWSCRT.aws_thread_current_name — Method
aws_thread_current_name(allocator, out_name)

Gets name of the current thread. Caller is responsible for destroying returned string. If thread does not have a name, AWS_OP_SUCCESS is returned and out_name is set to NULL. If underlying OS call fails, AWS_ERROR_SYS_CALL_FAILURE will be raised If OS does not support getting thread name, AWS_ERROR_PLATFORM_NOT_SUPPORTED will be raised

Prototype

int aws_thread_current_name(struct aws_allocator *allocator, struct aws_string **out_name);
source
LibAWSCRT.aws_thread_decrement_unjoined_count — Method
aws_thread_decrement_unjoined_count()

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.

aws_thread_join_all_managed() will not return until this count has gone to zero.

Prototype

void aws_thread_decrement_unjoined_count(void);
source
LibAWSCRT.aws_thread_get_detach_state — Method
aws_thread_get_detach_state(thread)

Gets the detach state of the thread. For example, is it safe to call join on this thread? Has it been detached()?

Prototype

enum aws_thread_detach_state aws_thread_get_detach_state(struct aws_thread *thread);
source
LibAWSCRT.aws_thread_id_t_to_string — Method
aws_thread_id_t_to_string(thread_id, buffer, bufsz)

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 == [AWSTHREADIDTREPR_BUFSZ](@ref). The thread id representation is returned in buffer.

Prototype

int aws_thread_id_t_to_string(aws_thread_id_t thread_id, char *buffer, size_t bufsz);
source
LibAWSCRT.aws_thread_increment_unjoined_count — Method
aws_thread_increment_unjoined_count()

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.

aws_thread_join_all_managed() will not return until this count has gone to zero.

Prototype

void aws_thread_increment_unjoined_count(void);
source
LibAWSCRT.aws_thread_init — Method
aws_thread_init(thread, allocator)

Initializes a new platform specific thread object struct (not the os-level thread itself).

Prototype

int aws_thread_init(struct aws_thread *thread, struct aws_allocator *allocator);
source
LibAWSCRT.aws_thread_join — Method
aws_thread_join(thread)

Joins the calling thread to a thread instance. Returns when thread is finished. Calling this from the associated OS thread will cause a deadlock.

Prototype

int aws_thread_join(struct aws_thread *thread);
source
LibAWSCRT.aws_thread_join_all_managed — Method
aws_thread_join_all_managed()

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.

This gets called automatically from library cleanup.

By default the wait is unbounded, but that default can be overridden via aws_thread_set_managed_join_timeout_ns()

Prototype

int aws_thread_join_all_managed(void);
source
LibAWSCRT.aws_thread_launch — Method
aws_thread_launch(thread, func, arg, options)

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.

After launch, you may join on the thread. A successfully launched thread must have clean_up called on it in order to avoid a handle leak. If you do not join before calling clean_up, the thread will become detached.

Managed threads must not have join or clean_up called on them by external code.

Prototype

int aws_thread_launch( struct aws_thread *thread, void (*func)(void *arg), void *arg, const struct aws_thread_options *options);
source
LibAWSCRT.aws_thread_name — Method
aws_thread_name(allocator, thread_id, out_name)

Gets name of the thread. Caller is responsible for destroying returned string. If thread does not have a name, AWS_OP_SUCCESS is returned and out_name is set to NULL. If underlying OS call fails, AWS_ERROR_SYS_CALL_FAILURE will be raised If OS does not support getting thread name, AWS_ERROR_PLATFORM_NOT_SUPPORTED will be raised

Prototype

int aws_thread_name( struct aws_allocator *allocator, aws_thread_id_t thread_id, struct aws_string **out_name);
source
LibAWSCRT.aws_thread_scheduler_cancel_task — Method
aws_thread_scheduler_cancel_task(scheduler, task)

Cancel a task that has been scheduled. The cancellation callback will be invoked in the background thread. This function is slow, so please don't do it in the hot path for your code.

Prototype

void aws_thread_scheduler_cancel_task(struct aws_thread_scheduler *scheduler, struct aws_task *task);
source
LibAWSCRT.aws_thread_scheduler_new — Method
aws_thread_scheduler_new(allocator, thread_options)

Creates a new instance of a thread scheduler. This object receives scheduled tasks and executes them inside a background thread. On success, this function returns an instance with a ref-count of 1. On failure it returns NULL.

thread_options are optional.

The semantics of this interface conform to the semantics of aws_task_scheduler.

Prototype

struct aws_thread_scheduler *aws_thread_scheduler_new( struct aws_allocator *allocator, const struct aws_thread_options *thread_options);
source
LibAWSCRT.aws_thread_scheduler_release — Method
aws_thread_scheduler_release(scheduler)

Release a reference to the scheduler.

Prototype

void aws_thread_scheduler_release(const struct aws_thread_scheduler *scheduler);
source
LibAWSCRT.aws_thread_scheduler_schedule_future — Method
aws_thread_scheduler_schedule_future(scheduler, task, time_to_run)

Schedules a task to run in the future. time_to_run is the absolute time from the system hw_clock.

Prototype

void aws_thread_scheduler_schedule_future( struct aws_thread_scheduler *scheduler, struct aws_task *task, uint64_t time_to_run);
source
LibAWSCRT.aws_thread_scheduler_schedule_now — Method
aws_thread_scheduler_schedule_now(scheduler, task)

Schedules a task to run as soon as possible.

Prototype

void aws_thread_scheduler_schedule_now(struct aws_thread_scheduler *scheduler, struct aws_task *task);
source
LibAWSCRT.aws_timegm — Method
aws_timegm(t)

Cross platform friendly version of timegm

Prototype

time_t aws_timegm(struct tm *const t);
source
LibAWSCRT.aws_timestamp_convert — Method
aws_timestamp_convert(timestamp, convert_from, convert_to, remainder)

Converts 'timestamp' from unit 'convert_from' to unit 'convert_to', if the units are the same then 'timestamp' is returned. If 'remainder' is NOT NULL, it will be set to the remainder if convert_from is a more precise unit than convert_to. To avoid unnecessary branching, 'remainder' is not zero initialized in this function, be sure to set it to 0 first if you care about that kind of thing. If conversion would lead to integer overflow, the timestamp returned will be the highest possible time that is representable, i.e. UINT64_MAX.

Prototype

AWS_STATIC_IMPL uint64_t aws_timestamp_convert( uint64_t timestamp, enum aws_timestamp_unit convert_from, enum aws_timestamp_unit convert_to, uint64_t *remainder);
source
LibAWSCRT.aws_timestamp_convert_u64 — Method
aws_timestamp_convert_u64(ticks, old_frequency, new_frequency, remainder)

More general form of aws_timestamp_convert that takes arbitrary frequencies rather than the timestamp enum.

Prototype

AWS_STATIC_IMPL uint64_t aws_timestamp_convert_u64(uint64_t ticks, uint64_t old_frequency, uint64_t new_frequency, uint64_t *remainder);
source
LibAWSCRT.aws_tls_alpn_handler_new — Method
aws_tls_alpn_handler_new(allocator, on_protocol_negotiated, user_data)

Creates a channel handler, for client or server mode, that handles alpn. This isn't necessarily required since you can always call aws_tls_handler_protocol in the aws_tls_on_negotiation_result_fn callback, but this makes channel bootstrap easier to handle.

Prototype

struct aws_channel_handler *aws_tls_alpn_handler_new( struct aws_allocator *allocator, aws_tls_on_protocol_negotiated on_protocol_negotiated, void *user_data);
source
LibAWSCRT.aws_tls_client_ctx_new — Method
aws_tls_client_ctx_new(alloc, options)

Creates a new client ctx. This ctx can be used for the lifetime of the application assuming you want the same options for every outgoing connection. Options will be copied.

Prototype

struct aws_tls_ctx *aws_tls_client_ctx_new( struct aws_allocator *alloc, const struct aws_tls_ctx_options *options);
source
LibAWSCRT.aws_tls_client_handler_new — Method
aws_tls_client_handler_new(allocator, options, slot)

Creates a new tls channel handler in client mode. Options will be copied. You must call aws_tls_client_handler_start_negotiation and wait on the aws_tls_on_negotiation_result_fn callback before the handler can begin processing application data.

Prototype

struct aws_channel_handler *aws_tls_client_handler_new( struct aws_allocator *allocator, struct aws_tls_connection_options *options, struct aws_channel_slot *slot);
source
LibAWSCRT.aws_tls_connection_options_clean_up — Method
aws_tls_connection_options_clean_up(connection_options)

Cleans up resources in aws_tls_connection_options. This can be called immediately after initializing a tls handler, or if using the bootstrap api, immediately after asking for a channel.

Prototype

void aws_tls_connection_options_clean_up(struct aws_tls_connection_options *connection_options);
source
LibAWSCRT.aws_tls_connection_options_copy — Method
aws_tls_connection_options_copy(to, from)

Copies 'from' to 'to'

Prototype

int aws_tls_connection_options_copy( struct aws_tls_connection_options *to, const struct aws_tls_connection_options *from);
source
LibAWSCRT.aws_tls_connection_options_set_alpn_list — Method
aws_tls_connection_options_set_alpn_list(conn_options, allocator, alpn_list)

Sets alpn list in the form <protocol1;protocol2;...>. A maximum of 4 protocols are supported. alpn_list is copied. This value is already inherited from aws_tls_ctx, but the aws_tls_ctx is expensive, and should be used across as many connections as possible. If you want to set this per connection, set it here.

Prototype

int aws_tls_connection_options_set_alpn_list( struct aws_tls_connection_options *conn_options, struct aws_allocator *allocator, const char *alpn_list);
source
LibAWSCRT.aws_tls_connection_options_set_callbacks — Method
aws_tls_connection_options_set_callbacks(conn_options, on_negotiation_result, on_data_read, on_error, user_data)

Sets callbacks for use with a tls connection.

Prototype

void aws_tls_connection_options_set_callbacks( struct aws_tls_connection_options *conn_options, aws_tls_on_negotiation_result_fn *on_negotiation_result, aws_tls_on_data_read_fn *on_data_read, aws_tls_on_error_fn *on_error, void *user_data);
source
LibAWSCRT.aws_tls_connection_options_set_server_name — Method
aws_tls_connection_options_set_server_name(conn_options, allocator, server_name)

Sets server name to use for the SNI extension (supported everywhere), as well as x.509 validation. If you don't set this, your x.509 validation will likely fail.

Prototype

int aws_tls_connection_options_set_server_name( struct aws_tls_connection_options *conn_options, struct aws_allocator *allocator, const struct aws_byte_cursor *server_name);
source
LibAWSCRT.aws_tls_ctx_acquire — Method
aws_tls_ctx_acquire(ctx)

Increments the reference count on the tls context, allowing the caller to take a reference to it.

Returns the same tls context passed in.

Prototype

struct aws_tls_ctx *aws_tls_ctx_acquire(struct aws_tls_ctx *ctx);
source
LibAWSCRT.aws_tls_ctx_options_clean_up — Method
aws_tls_ctx_options_clean_up(options)

Cleans up resources allocated by init_* functions

Prototype

void aws_tls_ctx_options_clean_up(struct aws_tls_ctx_options *options);
source
LibAWSCRT.aws_tls_ctx_options_init_client_mtls — Method
aws_tls_ctx_options_init_client_mtls(options, allocator, cert, pkey)

Initializes options for use with mutual tls in client mode. cert and pkey are copied. cert and pkey are treated as PKCS#7 PEM armored.

NOTE: This is unsupported on iOS.

Prototype

int aws_tls_ctx_options_init_client_mtls( struct aws_tls_ctx_options *options, struct aws_allocator *allocator, const struct aws_byte_cursor *cert, const struct aws_byte_cursor *pkey);
source
LibAWSCRT.aws_tls_ctx_options_init_client_mtls_from_path — Method
aws_tls_ctx_options_init_client_mtls_from_path(options, allocator, cert_path, pkey_path)

Initializes options for use with mutual tls in client mode. cert_path and pkey_path are paths to files on disk. cert_path and pkey_path are treated as PKCS#7 PEM armored. They are loaded from disk and stored in buffers internally.

NOTE: This is unsupported on iOS.

Prototype

int aws_tls_ctx_options_init_client_mtls_from_path( struct aws_tls_ctx_options *options, struct aws_allocator *allocator, const char *cert_path, const char *pkey_path);
source
LibAWSCRT.aws_tls_ctx_options_init_client_mtls_from_system_path — Method
aws_tls_ctx_options_init_client_mtls_from_system_path(options, allocator, cert_reg_path)

Initializes options for use with mutual tls in client mode. cert_reg_path is the path to a system installed certficate/private key pair. Example: CurrentUser\MY\<thumprint>

NOTE: This only works on Windows.

Prototype

int aws_tls_ctx_options_init_client_mtls_from_system_path( struct aws_tls_ctx_options *options, struct aws_allocator *allocator, const char *cert_reg_path);
source
LibAWSCRT.aws_tls_ctx_options_init_client_mtls_pkcs12 — Method
aws_tls_ctx_options_init_client_mtls_pkcs12(options, allocator, pkcs12, pkcs_pwd)

Initializes options for use with mutual tls in client mode. pkcs12 is a buffer containing a pkcs#12 certificate and private key; it is copied. pkcs_pwd is the corresponding password for the pkcs#12 buffer; it is copied.

NOTE: This only works on Apple devices.

Prototype

int aws_tls_ctx_options_init_client_mtls_pkcs12( struct aws_tls_ctx_options *options, struct aws_allocator *allocator, struct aws_byte_cursor *pkcs12, struct aws_byte_cursor *pkcs_pwd);
source
LibAWSCRT.aws_tls_ctx_options_init_client_mtls_pkcs12_from_path — Method
aws_tls_ctx_options_init_client_mtls_pkcs12_from_path(options, allocator, pkcs12_path, pkcs_pwd)

Initializes options for use with mutual tls in client mode. pkcs12_path is a path to a file on disk containing a pkcs#12 file. The file is loaded into an internal buffer. pkcs_pwd is the corresponding password for the pkcs#12 file; it is copied.

NOTE: This only works on Apple devices.

Prototype

int aws_tls_ctx_options_init_client_mtls_pkcs12_from_path( struct aws_tls_ctx_options *options, struct aws_allocator *allocator, const char *pkcs12_path, const struct aws_byte_cursor *pkcs_pwd);
source
LibAWSCRT.aws_tls_ctx_options_init_client_mtls_with_custom_key_operations — Method
aws_tls_ctx_options_init_client_mtls_with_custom_key_operations(options, allocator, custom, cert_file_contents)

Initializes options for use with mutual TLS in client mode, where private key operations are handled by custom code.

Note: cert_file_contents will be copied into a new buffer after this function is called, so you do not need to keep that data alive after calling this function.

Parameters

  • options: aws_tls_ctx_options to be initialized.
  • allocator: Allocator to use.
  • custom: Options for custom key operations.
  • cert_file_contents: The contents of a certificate file.

Prototype

int aws_tls_ctx_options_init_client_mtls_with_custom_key_operations( struct aws_tls_ctx_options *options, struct aws_allocator *allocator, struct aws_custom_key_op_handler *custom, const struct aws_byte_cursor *cert_file_contents);
source
LibAWSCRT.aws_tls_ctx_options_init_client_mtls_with_pkcs11 — Method
aws_tls_ctx_options_init_client_mtls_with_pkcs11(options, allocator, pkcs11_options)

Initializes options for use with mutual TLS in client mode, where a PKCS#11 library provides access to the private key.

NOTE: This only works on Unix devices.

Parameters

  • options: aws_tls_ctx_options to be initialized.
  • allocator: Allocator to use.
  • pkcs11_options: Options for using PKCS#11 (contents are copied)

Prototype

int aws_tls_ctx_options_init_client_mtls_with_pkcs11( struct aws_tls_ctx_options *options, struct aws_allocator *allocator, const struct aws_tls_ctx_pkcs11_options *pkcs11_options);
source
LibAWSCRT.aws_tls_ctx_options_init_default_client — Method
aws_tls_ctx_options_init_default_client(options, allocator)

****************************** tls options init stuff **********************

Initializes options with default client options

Prototype

void aws_tls_ctx_options_init_default_client( struct aws_tls_ctx_options *options, struct aws_allocator *allocator);
source
LibAWSCRT.aws_tls_ctx_options_init_default_server — Method
aws_tls_ctx_options_init_default_server(options, allocator, cert, pkey)

Initializes options for use with in server mode. cert and pkey are copied. cert and pkey are treated as PKCS#7 PEM armored.

Prototype

int aws_tls_ctx_options_init_default_server( struct aws_tls_ctx_options *options, struct aws_allocator *allocator, struct aws_byte_cursor *cert, struct aws_byte_cursor *pkey);
source
LibAWSCRT.aws_tls_ctx_options_init_default_server_from_path — Method
aws_tls_ctx_options_init_default_server_from_path(options, allocator, cert_path, pkey_path)

Initializes options for use with in server mode. cert_path and pkey_path are paths to files on disk. cert_path and pkey_path are treated as PKCS#7 PEM armored. They are loaded from disk and stored in buffers internally.

Prototype

int aws_tls_ctx_options_init_default_server_from_path( struct aws_tls_ctx_options *options, struct aws_allocator *allocator, const char *cert_path, const char *pkey_path);
source
LibAWSCRT.aws_tls_ctx_options_init_default_server_from_system_path — Method
aws_tls_ctx_options_init_default_server_from_system_path(options, allocator, cert_reg_path)

Initializes options for use with server mode. cert_reg_path is the path to a system installed certficate/private key pair. Example: CurrentUser\MY\<thumprint>

NOTE: This only works on Windows.

Prototype

int aws_tls_ctx_options_init_default_server_from_system_path( struct aws_tls_ctx_options *options, struct aws_allocator *allocator, const char *cert_reg_path);
source
LibAWSCRT.aws_tls_ctx_options_init_server_pkcs12 — Method
aws_tls_ctx_options_init_server_pkcs12(options, allocator, pkcs12, pkcs_password)

Initializes options for use in server mode. pkcs12 is a buffer containing a pkcs#12 certificate and private key; it is copied. pkcs_pwd is the corresponding password for the pkcs#12 buffer; it is copied.

NOTE: This only works on Apple devices.

Prototype

int aws_tls_ctx_options_init_server_pkcs12( struct aws_tls_ctx_options *options, struct aws_allocator *allocator, struct aws_byte_cursor *pkcs12, struct aws_byte_cursor *pkcs_password);
source
LibAWSCRT.aws_tls_ctx_options_init_server_pkcs12_from_path — Method
aws_tls_ctx_options_init_server_pkcs12_from_path(options, allocator, pkcs12_path, pkcs_password)

Initializes options for use in server mode. pkcs12_path is a path to a file on disk containing a pkcs#12 file. The file is loaded into an internal buffer. pkcs_pwd is the corresponding password for the pkcs#12 file; it is copied.

NOTE: This only works on Apple devices.

Prototype

int aws_tls_ctx_options_init_server_pkcs12_from_path( struct aws_tls_ctx_options *options, struct aws_allocator *allocator, const char *pkcs12_path, struct aws_byte_cursor *pkcs_password);
source
LibAWSCRT.aws_tls_ctx_options_override_default_trust_store — Method
aws_tls_ctx_options_override_default_trust_store(options, ca_file)

Override the default trust store. ca_file is a buffer containing a PEM armored chain of trusted CA certificates. ca_file is copied.

Prototype

int aws_tls_ctx_options_override_default_trust_store( struct aws_tls_ctx_options *options, const struct aws_byte_cursor *ca_file);
source
LibAWSCRT.aws_tls_ctx_options_override_default_trust_store_from_path — Method
aws_tls_ctx_options_override_default_trust_store_from_path(options, ca_path, ca_file)

Override the default trust store. ca_path is a path to a directory on disk containing trusted certificates. This is only supported on Unix systems (otherwise this parameter is ignored). ca_file is a path to a file on disk containing trusted certificates. ca_file is loaded from disk and stored in an internal buffer.

Prototype

int aws_tls_ctx_options_override_default_trust_store_from_path( struct aws_tls_ctx_options *options, const char *ca_path, const char *ca_file);
source
LibAWSCRT.aws_tls_ctx_options_set_alpn_list — Method
aws_tls_ctx_options_set_alpn_list(options, alpn_list)

Sets alpn list in the form <protocol1;protocol2;...>. A maximum of 4 protocols are supported. alpn_list is copied.

Prototype

int aws_tls_ctx_options_set_alpn_list(struct aws_tls_ctx_options *options, const char *alpn_list);
source
LibAWSCRT.aws_tls_ctx_options_set_extension_data — Method
aws_tls_ctx_options_set_extension_data(options, extension_data)

When implementing BYO_CRYPTO, if you need extra data to pass to your tls implementation, set it here. The lifetime of extension_data must outlive the options object and be cleaned up after options is cleaned up.

Prototype

void aws_tls_ctx_options_set_extension_data(struct aws_tls_ctx_options *options, void *extension_data);
source
LibAWSCRT.aws_tls_ctx_options_set_keychain_path — Method
aws_tls_ctx_options_set_keychain_path(options, keychain_path_cursor)

\deprecated

Sets a custom keychain path for storing the cert and pkey with mutual tls in client mode.

NOTE: This only works on MacOS.

Prototype

int aws_tls_ctx_options_set_keychain_path( struct aws_tls_ctx_options *options, struct aws_byte_cursor *keychain_path_cursor);
source
LibAWSCRT.aws_tls_ctx_options_set_minimum_tls_version — Method
aws_tls_ctx_options_set_minimum_tls_version(options, minimum_tls_version)

Sets the minimum TLS version to allow.

Prototype

void aws_tls_ctx_options_set_minimum_tls_version( struct aws_tls_ctx_options *options, enum aws_tls_versions minimum_tls_version);
source
LibAWSCRT.aws_tls_ctx_options_set_tls_cipher_preference — Method
aws_tls_ctx_options_set_tls_cipher_preference(options, cipher_pref)

Sets preferred TLS Cipher List

Prototype

void aws_tls_ctx_options_set_tls_cipher_preference( struct aws_tls_ctx_options *options, enum aws_tls_cipher_pref cipher_pref);
source
LibAWSCRT.aws_tls_ctx_options_set_verify_peer — Method
aws_tls_ctx_options_set_verify_peer(options, verify_peer)

Enables or disables x.509 validation. Disable this only for testing. To enable mutual TLS in server mode, set verify_peer to true.

Prototype

void aws_tls_ctx_options_set_verify_peer(struct aws_tls_ctx_options *options, bool verify_peer);
source
LibAWSCRT.aws_tls_ctx_release — Method
aws_tls_ctx_release(ctx)

Decrements a tls context's ref count. When the ref count drops to zero, the object will be destroyed.

Prototype

void aws_tls_ctx_release(struct aws_tls_ctx *ctx);
source
LibAWSCRT.aws_tls_handler_protocol — Method
aws_tls_handler_protocol(handler)

Returns a byte buffer by copy of the negotiated protocols. If there is no agreed upon protocol, len will be 0 and buffer will be NULL.

Prototype

struct aws_byte_buf aws_tls_handler_protocol(struct aws_channel_handler *handler);
source
LibAWSCRT.aws_tls_handler_server_name — Method
aws_tls_handler_server_name(handler)

Client mode only. This is the server name that was used for SNI and host name validation.

Prototype

struct aws_byte_buf aws_tls_handler_server_name(struct aws_channel_handler *handler);
source
LibAWSCRT.aws_tls_handler_write — Method
aws_tls_handler_write(handler, slot, buf, on_write_completed, completion_user_data)

Not necessary if you are installing more handlers into the channel, but if you just want to have TLS for arbitrary data and use the channel handler directly, this function allows you to write data to the channel and have it encrypted.

Prototype

int aws_tls_handler_write( struct aws_channel_handler *handler, struct aws_channel_slot *slot, struct aws_byte_buf *buf, aws_channel_on_message_write_completed_fn *on_write_completed, void *completion_user_data);
source
LibAWSCRT.aws_tls_hash_algorithm_str — Method
aws_tls_hash_algorithm_str(hash)

Given enum, return string like: AWS_TLS_HASH_SHA256 -> "SHA256"

Prototype

const char *aws_tls_hash_algorithm_str(enum aws_tls_hash_algorithm hash);
source
LibAWSCRT.aws_tls_is_alpn_available — Method
aws_tls_is_alpn_available()

Returns true if alpn is available in the underlying tls implementation. This function should always be called before setting an alpn list.

Prototype

bool aws_tls_is_alpn_available(void);
source
LibAWSCRT.aws_tls_is_cipher_pref_supported — Method
aws_tls_is_cipher_pref_supported(cipher_pref)

Returns true if this Cipher Preference is available in the underlying TLS implementation. This function should always be called before setting a Cipher Preference

Prototype

bool aws_tls_is_cipher_pref_supported(enum aws_tls_cipher_pref cipher_pref);
source
LibAWSCRT.aws_tls_key_operation_complete — Method
aws_tls_key_operation_complete(operation, output)

Complete a successful TLS private key operation by providing its output. The output is copied into the TLS connection. The operation is freed by this call.

You MUST call this or aws_tls_key_operation_complete_with_error(). Failure to do so will stall the TLS connection indefinitely and leak memory.

Prototype

void aws_tls_key_operation_complete(struct aws_tls_key_operation *operation, struct aws_byte_cursor output);
source
LibAWSCRT.aws_tls_key_operation_complete_with_error — Method
aws_tls_key_operation_complete_with_error(operation, error_code)

Complete an failed TLS private key operation. The TLS connection will fail. The operation is freed by this call.

You MUST call this or aws_tls_key_operation_complete(). Failure to do so will stall the TLS connection indefinitely and leak memory.

Prototype

void aws_tls_key_operation_complete_with_error(struct aws_tls_key_operation *operation, int error_code);
source
LibAWSCRT.aws_tls_key_operation_get_input — Method
aws_tls_key_operation_get_input(operation)

Returns the input data that needs to be operated on by the custom key operation.

Prototype

struct aws_byte_cursor aws_tls_key_operation_get_input(const struct aws_tls_key_operation *operation);
source
LibAWSCRT.aws_tls_key_operation_get_type — Method
aws_tls_key_operation_get_type(operation)

Returns the type of operation that needs to be performed by the custom key operation. If the implementation cannot perform the operation, use aws_tls_key_operation_complete_with_error() to preventing stalling the TLS connection.

Prototype

enum aws_tls_key_operation_type aws_tls_key_operation_get_type(const struct aws_tls_key_operation *operation);
source
LibAWSCRT.aws_tls_key_operation_type_str — Method
aws_tls_key_operation_type_str(operation_type)

Given enum, return string like: AWS_TLS_SIGNATURE_RSA -> "RSA"

Prototype

const char *aws_tls_key_operation_type_str(enum aws_tls_key_operation_type operation_type);
source
LibAWSCRT.aws_tls_server_ctx_new — Method
aws_tls_server_ctx_new(alloc, options)

Creates a new server ctx. This ctx can be used for the lifetime of the application assuming you want the same options for every incoming connection. Options will be copied.

Prototype

struct aws_tls_ctx *aws_tls_server_ctx_new( struct aws_allocator *alloc, const struct aws_tls_ctx_options *options);
source
LibAWSCRT.aws_tls_server_handler_new — Method
aws_tls_server_handler_new(allocator, options, slot)

Creates a new tls channel handler in server mode. Options will be copied. You must wait on the aws_tls_on_negotiation_result_fn callback before the handler can begin processing application data.

Prototype

struct aws_channel_handler *aws_tls_server_handler_new( struct aws_allocator *allocator, struct aws_tls_connection_options *options, struct aws_channel_slot *slot);
source
LibAWSCRT.aws_tls_signature_algorithm_str — Method
aws_tls_signature_algorithm_str(signature)

Given enum, return string like: AWS_TLS_SIGNATURE_RSA -> "RSA"

Prototype

const char *aws_tls_signature_algorithm_str(enum aws_tls_signature_algorithm signature);
source
LibAWSCRT.aws_translate_and_raise_io_error — Method
aws_translate_and_raise_io_error(error_no)

Convert a c library io error into an aws error, and raise it. If no conversion is found, AWS_ERROR_SYS_CALL_FAILURE is raised. Always returns AWS_OP_ERR.

Prototype

int aws_translate_and_raise_io_error(int error_no);
source
LibAWSCRT.aws_trim_padded_sigv4a_signature — Method
aws_trim_padded_sigv4a_signature(signature)

Removes any padding added to the end of a sigv4a signature. Signature must be hex-encoded.

Parameters

  • signature: signature to remove padding from

Returns

cursor that ranges over only the valid hex encoding of the sigv4a signature

Prototype

struct aws_byte_cursor aws_trim_padded_sigv4a_signature(struct aws_byte_cursor signature);
source
LibAWSCRT.aws_unregister_log_subject_info_list — Method
aws_unregister_log_subject_info_list(log_subject_list)

Disconnects log subject strings with log subject integer values

Prototype

void aws_unregister_log_subject_info_list(struct aws_log_subject_info_list *log_subject_list);
source
LibAWSCRT.aws_uri_authority — Method
aws_uri_authority(uri)

Returns the authority portion of the uri (host[:port]). If it was not present, this was a request uri. In that case, the value will be empty.

Prototype

const struct aws_byte_cursor *aws_uri_authority(const struct aws_uri *uri);
source
LibAWSCRT.aws_uri_host_name — Method
aws_uri_host_name(uri)

Returns the 'host_name' portion of the authority. If no authority was present, this value will be empty.

Prototype

const struct aws_byte_cursor *aws_uri_host_name(const struct aws_uri *uri);
source
LibAWSCRT.aws_uri_init_from_builder_options — Method
aws_uri_init_from_builder_options(uri, allocator, options)

Initializes uri to values specified in options. Returns AWS_OP_SUCCESS, on success, AWS_OP_ERR on failure. After calling this function, the parts can be accessed.

Prototype

int aws_uri_init_from_builder_options( struct aws_uri *uri, struct aws_allocator *allocator, struct aws_uri_builder_options *options);
source
LibAWSCRT.aws_uri_init_parse — Method
aws_uri_init_parse(uri, allocator, uri_str)

Parses 'uri_str' and initializes uri. Returns AWS_OP_SUCCESS, on success, AWS_OP_ERR on failure. After calling this function, the parts can be accessed.

Prototype

int aws_uri_init_parse( struct aws_uri *uri, struct aws_allocator *allocator, const struct aws_byte_cursor *uri_str);
source
LibAWSCRT.aws_uri_path — Method
aws_uri_path(uri)

Returns the path portion of the uri, including any leading '/'. If not present, this value will be empty.

Prototype

const struct aws_byte_cursor *aws_uri_path(const struct aws_uri *uri);
source
LibAWSCRT.aws_uri_path_and_query — Method
aws_uri_path_and_query(uri)

Returns the path and query portion of the uri (i.e., the thing you send across the wire).

Prototype

const struct aws_byte_cursor *aws_uri_path_and_query(const struct aws_uri *uri);
source
LibAWSCRT.aws_uri_port — Method
aws_uri_port(uri)

Returns the port portion of the authority if it was present, otherwise, returns 0. If this is 0, it is the users job to determine the correct port based on scheme and protocol.

Prototype

uint16_t aws_uri_port(const struct aws_uri *uri);
source
LibAWSCRT.aws_uri_query_string — Method
aws_uri_query_string(uri)

Returns the query string portion of the uri, minus the '?'. If not present, this value will be empty.

Prototype

const struct aws_byte_cursor *aws_uri_query_string(const struct aws_uri *uri);
source
LibAWSCRT.aws_uri_query_string_next_param — Method
aws_uri_query_string_next_param(uri, param)

For iterating over the params in the uri query string. param is an in/out argument used to track progress, it MUST be zeroed out to start. If true is returned, param contains the value of the next param. If false is returned, there are no further params.

Edge cases: 1) Entries without '=' sign are treated as having a key and no value. Example: First param in query string "a&b=c" has key="a" value=""

  1. Blank entries are skipped. Example: The only param in query string "&&a=b" is key="a" value="b"

Prototype

bool aws_uri_query_string_next_param(const struct aws_uri *uri, struct aws_uri_param *param);
source
LibAWSCRT.aws_uri_query_string_params — Method
aws_uri_query_string_params(uri, out_params)

Parses query string and stores the parameters in 'out_params'. Returns AWS_OP_SUCCESS on success and AWS_OP_ERR on failure. The user is responsible for initializing out_params with item size of struct aws_query_param. The user is also responsible for cleaning up out_params when finished.

Prototype

int aws_uri_query_string_params(const struct aws_uri *uri, struct aws_array_list *out_params);
source
LibAWSCRT.aws_uri_scheme — Method
aws_uri_scheme(uri)

Returns the scheme portion of the uri (e.g. http, https, ftp, ftps, etc...). If the scheme was not present in the uri, the returned value will be empty. It is the users job to determine the appropriate defaults if this field is empty, based on protocol, port, etc...

Prototype

const struct aws_byte_cursor *aws_uri_scheme(const struct aws_uri *uri);
source
LibAWSCRT.aws_utf8_decoder_finalize — Method
aws_utf8_decoder_finalize(decoder)

Tell the decoder that you've reached the end of your text. Raises AWS_ERROR_INVALID_UTF8 if the text did not end with a complete UTF8 codepoint. This also resets the decoder.

Prototype

int aws_utf8_decoder_finalize(struct aws_utf8_decoder *decoder);
source
LibAWSCRT.aws_utf8_decoder_new — Method
aws_utf8_decoder_new(allocator, options)

Create a UTF8/ASCII decoder, which can process text incrementally as you receive it. Text is always validated according to RFC-3629 (you may perform additional validation in the on_codepoint callback). The text does not need to begin with a UTF8 BOM. To decode text all at once, simply use aws_decode_utf8().

Feed bytes into the decoder with aws_utf8_decoder_update(), and call aws_utf8_decoder_finalize() when the text is complete.

Parameters

  • allocator: Allocator
  • options: Options for decoder. If NULL is passed, the text is simply validated.

Prototype

struct aws_utf8_decoder *aws_utf8_decoder_new( struct aws_allocator *allocator, const struct aws_utf8_decoder_options *options);
source
LibAWSCRT.aws_utf8_decoder_update — Method
aws_utf8_decoder_update(decoder, bytes)

Update the decoder with more bytes of text. The on_codepoint callback will be invoked for each codepoint encountered. Raises an error if invalid UTF8 is encountered or the on_codepoint callback reports an error.

Note: You must call aws_utf8_decoder_finalize() when the text is 100% complete, to ensure the input was completely valid.

Prototype

int aws_utf8_decoder_update(struct aws_utf8_decoder *decoder, struct aws_byte_cursor bytes);
source
LibAWSCRT.aws_uuid_to_str — Method
aws_uuid_to_str(uuid, output)

Prototype

int aws_uuid_to_str(const struct aws_uuid *uuid, struct aws_byte_buf *output);
source
LibAWSCRT.aws_validate_aws_signing_config_aws — Method
aws_validate_aws_signing_config_aws(config)

Checks a signing configuration for invalid settings combinations.

Parameters

  • config: signing configuration to validate

Returns

Prototype

int aws_validate_aws_signing_config_aws(const struct aws_signing_config_aws *config);
source
LibAWSCRT.aws_validate_v4a_authorization_value — Method
aws_validate_v4a_authorization_value(allocator, ecc_key, string_to_sign_cursor, signature_value_cursor)

Another helper function to check a computed sigv4a signature.

Prototype

int aws_validate_v4a_authorization_value( struct aws_allocator *allocator, struct aws_ecc_key_pair *ecc_key, struct aws_byte_cursor string_to_sign_cursor, struct aws_byte_cursor signature_value_cursor);
source
LibAWSCRT.aws_verify_sigv4a_signing — Method
aws_verify_sigv4a_signing(allocator, signable, base_config, expected_canonical_request_cursor, signature_cursor, ecc_key_pub_x, ecc_key_pub_y)

Test-only API used for cross-library signing verification tests

Verifies: (1) The canonical request generated during sigv4a signing of the request matches what is passed in (2) The signature passed in is a valid ECDSA signature of the hashed string-to-sign derived from the canonical request

Parameters

  • allocator: memory allocator to use throughout the signing verification process
  • signable: the thing to be signed. See signable.h for common constructors for signables that wrap different types.
  • base_config: pointer to a signing configuration, currently this must be of type aws_signing_config_aws
  • expected_canonical_request_cursor: expected result when building the canonical request
  • signature_cursor: the actual signature computed from a previous signing of the signable
  • ecc_key_pub_x: the x coordinate of the public part of the ecc key to verify the signature
  • ecc_key_pub_y: the y coordinate of the public part of the ecc key to verify the signature

Returns

AWS_OP_SUCCESS if the signing attempt was initiated successfully, AWS_OP_ERR otherwise

Prototype

int aws_verify_sigv4a_signing( struct aws_allocator *allocator, const struct aws_signable *signable, const struct aws_signing_config_base *base_config, struct aws_byte_cursor expected_canonical_request_cursor, struct aws_byte_cursor signature_cursor, struct aws_byte_cursor ecc_key_pub_x, struct aws_byte_cursor ecc_key_pub_y);
source
LibAWSCRT.aws_websocket_acquire — Method
aws_websocket_acquire(websocket)

Increment the websocket's ref-count, preventing it from being destroyed.

Returns

Always returns the same pointer that is passed in.

Prototype

struct aws_websocket *aws_websocket_acquire(struct aws_websocket *websocket);
source
LibAWSCRT.aws_websocket_client_connect — Method
aws_websocket_client_connect(options)

Asynchronously establish a client websocket connection. The on_connection_setup callback is invoked when the operation has finished creating a connection, or failed.

Prototype

int aws_websocket_client_connect(const struct aws_websocket_client_connection_options *options);
source
LibAWSCRT.aws_websocket_close — Method
aws_websocket_close(websocket, free_scarce_resources_immediately)

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.

Prototype

void aws_websocket_close(struct aws_websocket *websocket, bool free_scarce_resources_immediately);
source
LibAWSCRT.aws_websocket_convert_to_midchannel_handler — Method
aws_websocket_convert_to_midchannel_handler(websocket)

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.

If successful: - Other than aws_websocket_release(), all calls to aws_websocket_x() functions are ignored. - The websocket will no longer invoke any "incoming frame" callbacks. - aws_io_messages written by a downstream handler will be wrapped in binary data frames and sent upstream. The data may be split/combined as it is sent along. - aws_io_messages read from upstream handlers will be scanned for binary data frames. The payloads of these frames will be sent downstream. The payloads may be split/combined as they are sent along. - An incoming close frame will automatically result in channel-shutdown. - aws_websocket_release() must still be called or the websocket and its channel will never be cleaned up. - The websocket will still invoke its "on connection shutdown" callback when channel shutdown completes.

If unsuccessful, NULL is returned and the websocket is unchanged.

Prototype

int aws_websocket_convert_to_midchannel_handler(struct aws_websocket *websocket);
source
LibAWSCRT.aws_websocket_get_channel — Method
aws_websocket_get_channel(websocket)

Returns the websocket's underlying I/O channel.

Prototype

struct aws_channel *aws_websocket_get_channel(const struct aws_websocket *websocket);
source
LibAWSCRT.aws_websocket_increment_read_window — Method
aws_websocket_increment_read_window(websocket, size)

Manually increment the read window to keep frames flowing.

If the websocket was created with manual_window_management set true, then whenever the read window reaches 0 you will stop receiving data. The websocket's initial_window_size determines the starting size of the read window. The read window shrinks as you receive the payload from "data" frames (TEXT, BINARY, and CONTINUATION). Use aws_websocket_increment_read_window() to increment the window again and keep frames flowing. Maintain a larger window to keep up high throughput. You only need to worry about the payload from "data" frames. The websocket automatically increments the window to account for any other incoming bytes, including other parts of a frame (opcode, payload-length, etc) and the payload of other frame types (PING, PONG, CLOSE).

If the websocket was created with manual_window_management set false, this function does nothing.

This function may be called from any thread.

Prototype

void aws_websocket_increment_read_window(struct aws_websocket *websocket, size_t size);
source
LibAWSCRT.aws_websocket_is_data_frame — Method
aws_websocket_is_data_frame(opcode)

Return true if opcode is for a data frame, false if opcode if for a control frame.

Prototype

bool aws_websocket_is_data_frame(uint8_t opcode);
source
LibAWSCRT.aws_websocket_release — Method
aws_websocket_release(websocket)

Decrement the websocket's ref-count. When the ref-count reaches zero, the connection will shut down, if it hasn't already. Users must release the websocket when they are done with it. The websocket's memory cannot be reclaimed until this is done. Callbacks may continue firing after this is called, with "shutdown" being the final callback. This function may be called from any thread.

It is safe to pass NULL, nothing will happen.

Prototype

void aws_websocket_release(struct aws_websocket *websocket);
source
LibAWSCRT.aws_websocket_send_frame — Method
aws_websocket_send_frame(websocket, options)

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.

Prototype

int aws_websocket_send_frame(struct aws_websocket *websocket, const struct aws_websocket_send_frame_options *options);
source
LibAWSCRT.aws_write_u16 — Method
aws_write_u16(value, buffer)

Prototype

AWS_STATIC_IMPL void aws_write_u16(uint16_t value, uint8_t *buffer);
source
LibAWSCRT.aws_write_u24 — Method
aws_write_u24(value, buffer)

Prototype

AWS_STATIC_IMPL void aws_write_u24(uint32_t value, uint8_t *buffer);
source
LibAWSCRT.aws_write_u32 — Method
aws_write_u32(value, buffer)

Prototype

AWS_STATIC_IMPL void aws_write_u32(uint32_t value, uint8_t *buffer);
source
LibAWSCRT.aws_write_u64 — Method
aws_write_u64(value, buffer)

Prototype

AWS_STATIC_IMPL void aws_write_u64(uint64_t value, uint8_t *buffer);
source
LibAWSCRT.aws_xml_node_as_body — Method
aws_xml_node_as_body(node, out_body)

Writes the contents of the body of node into out_body. out_body is an output parameter in this case. Upon success, out_body will contain the body of the node.

Prototype

int aws_xml_node_as_body(struct aws_xml_node *node, struct aws_byte_cursor *out_body);
source
LibAWSCRT.aws_xml_node_get_attribute — Method
aws_xml_node_get_attribute(node, attribute_index)

Prototype

struct aws_xml_attribute aws_xml_node_get_attribute(const struct aws_xml_node *node, size_t attribute_index);
source
LibAWSCRT.aws_xml_node_traverse — Method
aws_xml_node_traverse(node, on_node_encountered, user_data)

Traverse node and invoke on_node_encountered when a nested node is encountered.

Prototype

int aws_xml_node_traverse( struct aws_xml_node *node, aws_xml_parser_on_node_encountered_fn *on_node_encountered, void *user_data);
source
LibAWSCRT.aws_xml_parse — Method
aws_xml_parse(allocator, options)

Parse an XML document. WARNING: This is not a public API. It is only intended for use within the aws-c libraries.

Prototype

int aws_xml_parse(struct aws_allocator *allocator, const struct aws_xml_parser_options *options);
source