LibAwsIO

Documentation not found.

Documentation not found.

Documentation not found.

__JL_Ctag_705

Documentation not found.

__JL_Ctag_709

Documentation not found.

__JL_Ctag_712

Documentation not found.

__JL_Ctag_721

Documentation not found.

__pthread_mutex_s

Documentation not found.

aws_address_record_type

Documentation not found.

aws_async_input_stream

Documentation not found.

aws_async_input_stream_tester

Documentation not found.

aws_async_input_stream_tester_options

Documentation not found.

aws_async_input_stream_vtable

Documentation not found.

aws_async_read_completion_strategy

Use aws_async_input_stream_tester to test edge cases in systems that take async streams. You can customize its behavior (e.g. fail on 3rd read, always complete async, always complete synchronously, etc)

aws_autogen_style

Use aws_input_stream tester to test edge cases in systems that take input streams. You can make it behave in specific weird ways (e.g. fail on 3rd read).

There are a few ways to set what gets streamed. - source_bytes: if set, stream these bytes. - source_stream: if set, wrap this stream (but insert weird behavior like failing on 3rd read). - autogen_length: autogen streaming content N bytes in length.

Documentation not found.

aws_channel_direction

Documentation not found.

aws_channel_handler

Documentation not found.

aws_channel_handler_vtable

Documentation not found.

Documentation not found.

If ALPN is being used this function will be invoked by the channel once an ALPN message is received. The returned channel_handler will be added to, and managed by, the channel.

Documentation not found.

Documentation not found.

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.

aws_channel_slot

Documentation not found.

aws_channel_task

Documentation not found.

Documentation not found.

aws_client_bootstrap

aws_client_bootstrap handles creation and setup of channels that communicate via socket with a specific endpoint.

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.

aws_client_bootstrap_options

aws_client_bootstrap creation options.

Called after client bootstrap has been completely cleaned up, after its last refcount is released.

aws_crt_io_statistics_category

Documentation not found.

aws_crt_statistics_socket

Socket channel handler statistics record

aws_crt_statistics_tls

Tls channel handler statistics record

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.

aws_custom_key_op_handler_vtable

vtable for aws_custom_key_op_handler.

aws_event_loop

Documentation not found.

aws_event_loop_group

Documentation not found.

aws_event_loop_local_object

Documentation not found.

Documentation not found.

Documentation not found.

aws_event_loop_options

Documentation not found.

aws_event_loop_vtable

Documentation not found.

aws_exponential_backoff_jitter_mode

Jitter mode for exponential backoff.

For a great writeup on these options see: https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/

aws_exponential_backoff_retry_options

Options for exponential backoff retry strategy. el_group must be set, any other option, if set to 0 will signify "use defaults"

Documentation not found.

Completion callback for aws_future<T>

Documentation not found.

Documentation not found.

Documentation not found.

Documentation not found.

Documentation not found.

Documentation not found.

Optional function to supply your own generate random implementation

Documentation not found.

aws_get_host_address_flags

Documentation not found.

aws_host_address

Documentation not found.

Documentation not found.

Documentation not found.

aws_host_resolution_config

Documentation not found.

aws_host_resolver

Documentation not found.

aws_host_resolver_default_options

Documentation not found.

aws_host_resolver_purge_host_options

Documentation not found.

aws_host_resolver_vtable

should you absolutely disdain the default implementation, feel free to implement your own.

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.

aws_input_stream_tester

Documentation not found.

aws_input_stream_tester_options

Documentation not found.

aws_input_stream_vtable

Documentation not found.

Documentation not found.

aws_io_errors

Documentation not found.

aws_io_event_type

Documentation not found.

aws_io_handle

Documentation not found.

aws_io_log_subject

Documentation not found.

aws_io_message

Documentation not found.

aws_io_message_type

Documentation not found.

aws_memory_pool

Documentation not found.

aws_message_pool

Documentation not found.

aws_message_pool_creation_args

Documentation not found.

Documentation not found.

Invoked once an address has been resolved for host. The type in host_addresses is struct aws_host_address (by-value). The caller does not own this memory and you must copy the host address before returning from this function if you plan to use it later. For convenience, we've provided the aws_host_address_copy() and aws_host_address_clean_up() functions.

Documentation not found.

aws_pem_object

Documentation not found.

aws_pem_object_type

Documentation not found.

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.

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.

aws_pipe_read_end

Documentation not found.

aws_pipe_write_end

Documentation not found.

Documentation not found.

aws_pkcs11_lib_behavior

Controls how aws_pkcs11_lib calls C_Initialize() and C_Finalize() on the PKCS#11 library.

aws_pkcs11_lib_options

Options for aws_pkcs11_lib_new()

Documentation not found.

Function signature for configuring your own resolver (the default just uses getaddrinfo()). The type in output_addresses is struct aws_host_address (by-value). We assume this function blocks, hence this absurdly complicated design.

aws_retry_error_type

Documentation not found.

aws_retry_strategy

Documentation not found.

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

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.

aws_retry_strategy_vtable

Documentation not found.

aws_retry_token

Documentation not found.

aws_server_bootstrap

aws_server_bootstrap manages listening sockets, creating and setting up channels to handle each incoming connection.

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.

Once the channel shuts down, this function will be invoked within the thread of the event-loop that the channel is assigned to.

Note: this function is only invoked if the channel was successfully setup, e.g. aws_server_bootstrap_on_accept_channel_setup_fn() was invoked without an error code.

Once the server listener socket is finished destroying, and all the existing connections are closed, this fuction will be invoked.

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.

aws_shared_library

Documentation not found.

aws_socket

Documentation not found.

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.

aws_socket_domain

Documentation not found.

aws_socket_endpoint

Documentation not found.

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.

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.

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.

Callback for when the data passed to a call to aws_socket_write() has either completed or failed. On success, error_code will be AWS_ERROR_SUCCESS.

aws_socket_options

Documentation not found.

aws_socket_type

Documentation not found.

aws_standard_retry_options

Documentation not found.

aws_stream_seek_basis

Documentation not found.

aws_stream_status

Documentation not found.

aws_testing_channel_options

Documentation not found.

aws_tls_cipher_pref

Documentation not found.

aws_tls_connection_options

Documentation not found.

aws_tls_ctx

Documentation not found.

aws_tls_ctx_options

Documentation not found.

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.

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.

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.

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.

aws_tls_negotiated_protocol_message

Documentation not found.

aws_tls_negotiation_status

An enum for the current state of tls negotiation within a tls channel handler

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.

Invoked when an error occurs in the TLS state machine AFTER the handshake has completed. This function should only be used in conjunction with the rules of aws_tls_on_data_read_fn.

Invoked upon completion of the TLS handshake. If successful error_code will be AWS_OP_SUCCESS, otherwise the negotiation failed and immediately after this function is invoked, the channel will be shutting down.

Documentation not found.

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.

aws_tls_versions

Documentation not found.

testing_channel

Documentation not found.

testing_channel_handler

Documentation not found.

Documentation not found.

testing_loop

Documentation not found.

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

aws_async_input_stream_init_base(stream, alloc, vtable, impl)

Initialize aws_async_input_stream "base class"

Prototype

void aws_async_input_stream_init_base( struct aws_async_input_stream *stream, struct aws_allocator *alloc, const struct aws_async_input_stream_vtable *vtable, void *impl);

aws_async_input_stream_new_tester(alloc, options)

Documentation not found.

Prototype

static inline struct aws_async_input_stream *aws_async_input_stream_new_tester( struct aws_allocator *alloc, const struct aws_async_input_stream_tester_options *options);

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

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

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

aws_async_input_stream_tester_total_bytes_read(async_stream)

Documentation not found.

Prototype

static inline uint64_t aws_async_input_stream_tester_total_bytes_read( const struct aws_async_input_stream *async_stream);

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

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. This cannot fail, it never returns NULL.

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

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

aws_channel_destroy(channel)

Mark the channel, along with all slots and handlers, for destruction. Must be called after shutdown has completed. Can be called from any thread assuming 'aws_channel_shutdown()' has completed. Note that memory will not be freed until all users which acquired holds on the channel via aws_channel_acquire_hold(), release them via aws_channel_release_hold().

Prototype

void aws_channel_destroy(struct aws_channel *channel);

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

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

aws_channel_get_first_slot(channel)

Documentation not found.

Prototype

struct aws_channel_slot *aws_channel_get_first_slot(struct aws_channel *channel);

aws_channel_handler_destroy(handler)

Calls destroy on handler's vtable

Prototype

void aws_channel_handler_destroy(struct aws_channel_handler *handler);

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

aws_channel_handler_initial_window_size(handler)

Calls initial_window_size on handler's vtable.

Prototype

size_t aws_channel_handler_initial_window_size(struct aws_channel_handler *handler);

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

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

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

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

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

aws_channel_release_hold(channel)

Release a hold on the channel's memory, allowing it to be freed. This may be called before or after aws_channel_destroy().

Prototype

void aws_channel_release_hold(struct aws_channel *channel);

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

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

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

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

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

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

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

aws_channel_slot_acquire_max_message_for_write(slot)

Convenience function that invokes aws_channel_acquire_message_from_pool(), asking for the largest reasonable DATA message that can be sent in the write direction, with upstream overhead accounted for. This cannot fail, it never returns NULL.

Prototype

struct aws_io_message *aws_channel_slot_acquire_max_message_for_write(struct aws_channel_slot *slot);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

aws_client_bootstrap_new_socket_channel(options)

Sets up a client socket channel.

Prototype

int aws_client_bootstrap_new_socket_channel(struct aws_socket_channel_bootstrap_options *options);

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

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

aws_crt_statistics_socket_cleanup(stats)

Cleans up socket channel handler statistics

Prototype

void aws_crt_statistics_socket_cleanup(struct aws_crt_statistics_socket *stats);

aws_crt_statistics_socket_init(stats)

Initializes socket channel handler statistics

Prototype

int aws_crt_statistics_socket_init(struct aws_crt_statistics_socket *stats);

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

aws_crt_statistics_tls_cleanup(stats)

Cleans up tls channel handler statistics

Prototype

void aws_crt_statistics_tls_cleanup(struct aws_crt_statistics_tls *stats);

aws_crt_statistics_tls_init(stats)

Initializes tls channel handler statistics

Prototype

int aws_crt_statistics_tls_init(struct aws_crt_statistics_tls *stats);

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

aws_custom_key_op_handler_acquire(key_op_handler)

Increases the reference count for the passed-in aws_custom_key_op_handler and returns it.

Prototype

struct aws_custom_key_op_handler *aws_custom_key_op_handler_acquire( struct aws_custom_key_op_handler *key_op_handler);

aws_custom_key_op_handler_perform_operation(key_op_handler, operation)

Calls the on_key_operation vtable function. See aws_custom_key_op_handler_vtable for function details.

Prototype

void aws_custom_key_op_handler_perform_operation( struct aws_custom_key_op_handler *key_op_handler, struct aws_tls_key_operation *operation);

aws_custom_key_op_handler_release(key_op_handler)

Decreases the reference count for the passed-in aws_custom_key_op_handler and returns NULL.

Prototype

struct aws_custom_key_op_handler *aws_custom_key_op_handler_release( struct aws_custom_key_op_handler *key_op_handler);

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

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

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

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

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

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

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

aws_event_loop_get_load_factor(event_loop)

Returns the current load factor (however that may be calculated). If the event-loop is not invoking aws_event_loop_register_tick_start() and aws_event_loop_register_tick_end(), this value will always be 0.

Prototype

size_t aws_event_loop_get_load_factor(struct aws_event_loop *event_loop);

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

aws_event_loop_group_get_loop_at(el_group, index)

Documentation not found.

Prototype

struct aws_event_loop *aws_event_loop_group_get_loop_at(struct aws_event_loop_group *el_group, size_t index);

aws_event_loop_group_get_loop_count(el_group)

Documentation not found.

Prototype

size_t aws_event_loop_group_get_loop_count(struct aws_event_loop_group *el_group);

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

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

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

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

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

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

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

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

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

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

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

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

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

aws_event_loop_run(event_loop)

Triggers the running of the event loop. This function must not block. The event loop is not active until this function is invoked. This function can be called again on an event loop after calling aws_event_loop_stop() and aws_event_loop_wait_for_stop_completion().

Prototype

int aws_event_loop_run(struct aws_event_loop *event_loop);

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

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

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

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

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

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

aws_event_loop_wait_for_stop_completion(event_loop)

Blocks until the event loop stops completely. If you want to call aws_event_loop_run() again, you must call this after aws_event_loop_stop(). It is not safe to call this function from inside the event loop thread.

Prototype

int aws_event_loop_wait_for_stop_completion(struct aws_event_loop *event_loop);

aws_future_bool_acquire(future)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_bool, bool, AWS_IO_API);

aws_future_bool_get_error(future)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_bool, bool, AWS_IO_API);

aws_future_bool_get_result(future)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_bool, bool, AWS_IO_API);

aws_future_bool_is_done(future)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_bool, bool, AWS_IO_API);

aws_future_bool_new(alloc)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_bool, bool, AWS_IO_API);

aws_future_bool_register_callback(future, on_done, user_data)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_bool, bool, AWS_IO_API);

aws_future_bool_register_callback_if_not_done(future, on_done, user_data)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_bool, bool, AWS_IO_API);

aws_future_bool_register_channel_callback(future, channel, on_done, user_data)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_bool, bool, AWS_IO_API);

aws_future_bool_register_event_loop_callback(future, event_loop, on_done, user_data)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_bool, bool, AWS_IO_API);

aws_future_bool_release(future)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_bool, bool, AWS_IO_API);

aws_future_bool_set_error(future, error_code)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_bool, bool, AWS_IO_API);

aws_future_bool_set_result(future, result)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_bool, bool, AWS_IO_API);

aws_future_bool_wait(future, timeout_ns)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_bool, bool, AWS_IO_API);

aws_future_impl_acquire(promise)

Documentation not found.

Prototype

struct aws_future_impl *aws_future_impl_acquire(struct aws_future_impl *promise);

aws_future_impl_get_error(future)

Documentation not found.

Prototype

int aws_future_impl_get_error(const struct aws_future_impl *future);

aws_future_impl_get_result_address(future)

Documentation not found.

Prototype

void *aws_future_impl_get_result_address(const struct aws_future_impl *future);

aws_future_impl_get_result_by_move(future, dst_address)

Documentation not found.

Prototype

void aws_future_impl_get_result_by_move(struct aws_future_impl *future, void *dst_address);

aws_future_impl_is_done(future)

Documentation not found.

Prototype

bool aws_future_impl_is_done(const struct aws_future_impl *future);

aws_future_impl_new_by_value(alloc, sizeof_result)

Documentation not found.

Prototype

struct aws_future_impl *aws_future_impl_new_by_value(struct aws_allocator *alloc, size_t sizeof_result);

aws_future_impl_new_by_value_with_clean_up(alloc, sizeof_result, result_clean_up)

Documentation not found.

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

aws_future_impl_new_pointer(alloc)

Documentation not found.

Prototype

struct aws_future_impl *aws_future_impl_new_pointer(struct aws_allocator *alloc);

aws_future_impl_new_pointer_with_destroy(alloc, result_destroy)

Documentation not found.

Prototype

struct aws_future_impl *aws_future_impl_new_pointer_with_destroy( struct aws_allocator *alloc, aws_future_impl_result_destroy_fn *result_destroy);

aws_future_impl_new_pointer_with_release(alloc, result_release)

Documentation not found.

Prototype

struct aws_future_impl *aws_future_impl_new_pointer_with_release( struct aws_allocator *alloc, aws_future_impl_result_release_fn *result_release);

aws_future_impl_register_callback(future, on_done, user_data)

Documentation not found.

Prototype

void aws_future_impl_register_callback( struct aws_future_impl *future, aws_future_callback_fn *on_done, void *user_data);

aws_future_impl_register_callback_if_not_done(future, on_done, user_data)

Documentation not found.

Prototype

bool aws_future_impl_register_callback_if_not_done( struct aws_future_impl *future, aws_future_callback_fn *on_done, void *user_data);

aws_future_impl_register_channel_callback(future, channel, on_done, user_data)

Documentation not found.

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

aws_future_impl_register_event_loop_callback(future, event_loop, on_done, user_data)

Documentation not found.

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

aws_future_impl_release(promise)

Documentation not found.

Prototype

struct aws_future_impl *aws_future_impl_release(struct aws_future_impl *promise);

aws_future_impl_set_error(promise, error_code)

Documentation not found.

Prototype

void aws_future_impl_set_error(struct aws_future_impl *promise, int error_code);

aws_future_impl_set_result_by_move(promise, src_address)

Documentation not found.

Prototype

void aws_future_impl_set_result_by_move(struct aws_future_impl *promise, void *src_address);

aws_future_impl_wait(future, timeout_ns)

Documentation not found.

Prototype

bool aws_future_impl_wait(const struct aws_future_impl *future, uint64_t timeout_ns);

aws_future_size_acquire(future)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_size, size_t, AWS_IO_API);

aws_future_size_get_error(future)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_size, size_t, AWS_IO_API);

aws_future_size_get_result(future)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_size, size_t, AWS_IO_API);

aws_future_size_is_done(future)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_size, size_t, AWS_IO_API);

aws_future_size_new(alloc)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_size, size_t, AWS_IO_API);

aws_future_size_register_callback(future, on_done, user_data)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_size, size_t, AWS_IO_API);

aws_future_size_register_callback_if_not_done(future, on_done, user_data)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_size, size_t, AWS_IO_API);

aws_future_size_register_channel_callback(future, channel, on_done, user_data)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_size, size_t, AWS_IO_API);

aws_future_size_register_event_loop_callback(future, event_loop, on_done, user_data)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_size, size_t, AWS_IO_API);

aws_future_size_release(future)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_size, size_t, AWS_IO_API);

aws_future_size_set_error(future, error_code)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_size, size_t, AWS_IO_API);

aws_future_size_set_result(future, result)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_size, size_t, AWS_IO_API);

aws_future_size_wait(future, timeout_ns)

Documentation not found.

Prototype

AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_size, size_t, AWS_IO_API);

aws_future_void_acquire(future)

Documentation not found.

Prototype

AWS_FUTURE_T_DECLARATION_END(aws_future_void, AWS_IO_API);

aws_future_void_get_error(future)

Documentation not found.

Prototype

AWS_FUTURE_T_DECLARATION_END(aws_future_void, AWS_IO_API);

aws_future_void_is_done(future)

Documentation not found.

Prototype

AWS_FUTURE_T_DECLARATION_END(aws_future_void, AWS_IO_API);

aws_future_void_new(alloc)

aws_future<void>

Prototype

struct aws_future_void *aws_future_void_new(struct aws_allocator *alloc);

aws_future_void_register_callback(future, on_done, user_data)

Documentation not found.

Prototype

AWS_FUTURE_T_DECLARATION_END(aws_future_void, AWS_IO_API);

aws_future_void_register_callback_if_not_done(future, on_done, user_data)

Documentation not found.

Prototype

AWS_FUTURE_T_DECLARATION_END(aws_future_void, AWS_IO_API);

aws_future_void_register_channel_callback(future, channel, on_done, user_data)

Documentation not found.

Prototype

AWS_FUTURE_T_DECLARATION_END(aws_future_void, AWS_IO_API);

aws_future_void_register_event_loop_callback(future, event_loop, on_done, user_data)

Documentation not found.

Prototype

AWS_FUTURE_T_DECLARATION_END(aws_future_void, AWS_IO_API);

aws_future_void_release(future)

Documentation not found.

Prototype

AWS_FUTURE_T_DECLARATION_END(aws_future_void, AWS_IO_API);

aws_future_void_set_error(future, error_code)

Documentation not found.

Prototype

AWS_FUTURE_T_DECLARATION_END(aws_future_void, AWS_IO_API);

aws_future_void_set_result(future)

Documentation not found.

Prototype

void aws_future_void_set_result(struct aws_future_void *future);

aws_future_void_wait(future, timeout_ns)

Documentation not found.

Prototype

AWS_FUTURE_T_DECLARATION_END(aws_future_void, AWS_IO_API);

aws_host_address_clean_up(address)

Cleans up the memory for address

Prototype

void aws_host_address_clean_up(struct aws_host_address *address);

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

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

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

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

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

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

aws_host_resolver_purge_cache(resolver)

Prototype

int aws_host_resolver_purge_cache(struct aws_host_resolver *resolver);

aws_host_resolver_purge_cache_with_callback(resolver, on_purge_cache_complete_callback, user_data)

Calls aws_host_resolver_purge_cache_with_callback on the vtable which will wipe out everything host resolver has cached.

Prototype

int aws_host_resolver_purge_cache_with_callback( struct aws_host_resolver *resolver, aws_simple_completion_callback *on_purge_cache_complete_callback, void *user_data);

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

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

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

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

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

aws_input_stream_destroy(stream)

Documentation not found.

Prototype

void aws_input_stream_destroy(struct aws_input_stream *stream);

aws_input_stream_get_length(stream, out_length)

Documentation not found.

Prototype

int aws_input_stream_get_length(struct aws_input_stream *stream, int64_t *out_length);

aws_input_stream_get_status(stream, status)

Documentation not found.

Prototype

int aws_input_stream_get_status(struct aws_input_stream *stream, struct aws_stream_status *status);

aws_input_stream_new_from_cursor(allocator, cursor)

Documentation not found.

Prototype

struct aws_input_stream *aws_input_stream_new_from_cursor( struct aws_allocator *allocator, const struct aws_byte_cursor *cursor);

aws_input_stream_new_from_file(allocator, file_name)

Documentation not found.

Prototype

struct aws_input_stream *aws_input_stream_new_from_file( struct aws_allocator *allocator, const char *file_name);

aws_input_stream_new_from_open_file(allocator, file)

Documentation not found.

Prototype

struct aws_input_stream *aws_input_stream_new_from_open_file(struct aws_allocator *allocator, FILE *file);

aws_input_stream_new_tester(alloc, options)

Documentation not found.

Prototype

static inline struct aws_input_stream *aws_input_stream_new_tester( struct aws_allocator *alloc, const struct aws_input_stream_tester_options *options);

aws_input_stream_read(stream, dest)

Documentation not found.

Prototype

int aws_input_stream_read(struct aws_input_stream *stream, struct aws_byte_buf *dest);

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

aws_input_stream_seek(stream, offset, basis)

Documentation not found.

Prototype

int aws_input_stream_seek(struct aws_input_stream *stream, int64_t offset, enum aws_stream_seek_basis basis);

aws_input_stream_tester_total_bytes_read(stream)

Documentation not found.

Prototype

static inline uint64_t aws_input_stream_tester_total_bytes_read(const struct aws_input_stream *stream);

aws_io_fatal_assert_library_initialized()

Documentation not found.

Prototype

void aws_io_fatal_assert_library_initialized(void);

aws_io_library_clean_up()

Shuts down the internal datastructures used by aws-c-io.

Prototype

void aws_io_library_clean_up(void);

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

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

aws_memory_pool_clean_up(mempool)

Documentation not found.

Prototype

void aws_memory_pool_clean_up(struct aws_memory_pool *mempool);

aws_memory_pool_init(mempool, alloc, ideal_segment_count, segment_size)

Documentation not found.

Prototype

int aws_memory_pool_init( struct aws_memory_pool *mempool, struct aws_allocator *alloc, uint16_t ideal_segment_count, size_t segment_size);

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

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

aws_message_pool_clean_up(msg_pool)

Documentation not found.

Prototype

void aws_message_pool_clean_up(struct aws_message_pool *msg_pool);

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

aws_message_pool_release(msg_pool, message)

Releases message to the pool if space is available, otherwise frees message

Arguments

• message:

Prototype

void aws_message_pool_release(struct aws_message_pool *msg_pool, struct aws_io_message *message);

aws_pem_objects_clean_up(pem_objects)

Cleans up elements of pem_objects list 'aws_pem_objects_init_from_file_contents()' and 'aws_pem_objects_init_from_file_path()'.

Prototype

void aws_pem_objects_clean_up(struct aws_array_list *pem_objects);

aws_pem_objects_init_from_file_contents(pem_objects, alloc, pem_cursor)

Decodes PEM data and reads objects sequentially adding them to pem_objects. If it comes across an object it cannot read, list of all object read until that point is returned. If no objects can be read from PEM or objects could not be base 64 decoded, AWS_ERROR_PEM_MALFORMED is raised. out_pem_objects stores aws_pem_object struct by value. Function will initialize pem_objects list. This code is slow, and it allocates, so please try not to call this in the middle of something that needs to be fast or resource sensitive.

Prototype

int aws_pem_objects_init_from_file_contents( struct aws_array_list *pem_objects, struct aws_allocator *alloc, struct aws_byte_cursor pem_cursor);

aws_pem_objects_init_from_file_path(pem_objects, allocator, filename)

Decodes PEM data from file and reads objects sequentially adding them to pem_objects. If it comes across an object it cannot read, list of all object read until that point is returned. If no objects can be read from PEM or objects could not be base 64 decoded, AWS_ERROR_PEM_MALFORMED is raised. out_pem_objects stores aws_pem_object struct by value. Function will initialize pem_objects list. This code is slow, and it allocates, so please try not to call this in the middle of something that needs to be fast or resource sensitive.

Prototype

int aws_pem_objects_init_from_file_path( struct aws_array_list *pem_objects, struct aws_allocator *allocator, const char *filename);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

aws_retry_token_release(token)

Releases the reference count for token. This should always be invoked after either calling aws_retry_strategy_schedule_retry() and failing, or after calling aws_retry_token_record_success().

Prototype

void aws_retry_token_release(struct aws_retry_token *token);

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

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

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

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

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

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

aws_shared_library_clean_up(library)

Documentation not found.

Prototype

void aws_shared_library_clean_up(struct aws_shared_library *library);

aws_shared_library_find_function(library, symbol_name, function_address)

Documentation not found.

Prototype

int aws_shared_library_find_function( struct aws_shared_library *library, const char *symbol_name, aws_generic_function *function_address);

aws_shared_library_init(library, library_path)

Documentation not found.

Prototype

int aws_shared_library_init(struct aws_shared_library *library, const char *library_path);

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

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

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

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

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

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

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

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

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

aws_socket_handler_get_socket(handler)

Documentation not found.

Prototype

const struct aws_socket *aws_socket_handler_get_socket(const struct aws_channel_handler *handler);

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

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

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

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

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

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

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

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

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

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

aws_socket_validate_port_for_bind(port, domain)

Raises AWS_IO_SOCKET_INVALID_ADDRESS and logs an error if binding to this port is illegal. For example, port must in range 0-65535 to bind with IPv4. These port values would fail eventually in aws_socket_bind(), but you can use this function to validate earlier.

Prototype

int aws_socket_validate_port_for_bind(uint32_t port, enum aws_socket_domain domain);

aws_socket_validate_port_for_connect(port, domain)

Raises AWS_IO_SOCKET_INVALID_ADDRESS and logs an error if connecting to this port is illegal. For example, port must be in range 1-65535 to connect with IPv4. These port values would fail eventually in aws_socket_connect(), but you can use this function to validate earlier.

Prototype

int aws_socket_validate_port_for_connect(uint32_t port, enum aws_socket_domain domain);

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

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

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

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

aws_tls_client_handler_start_negotiation(handler)

Kicks off the negotiation process. This function must be called when in client mode to initiate the TLS handshake. Once the handshake has completed the aws_tls_on_negotiation_result_fn will be invoked.

Prototype

int aws_tls_client_handler_start_negotiation(struct aws_channel_handler *handler);

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

aws_tls_connection_options_copy(to, from)

Cleans up 'to' and copies 'from' to 'to'. 'to' must be initialized.

Prototype

int aws_tls_connection_options_copy( struct aws_tls_connection_options *to, const struct aws_tls_connection_options *from);

aws_tls_connection_options_init_from_ctx(conn_options, ctx)

Initializes default connection options from an instance ot aws_tls_ctx.

Prototype

void aws_tls_connection_options_init_from_ctx( struct aws_tls_connection_options *conn_options, struct aws_tls_ctx *ctx);

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

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

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

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

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

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

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

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

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

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

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.

Arguments

• 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);

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.

Arguments

• 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);

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

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

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

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

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

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

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

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

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

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

aws_tls_ctx_options_set_keychain_path(options, keychain_path_cursor)

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

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

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

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

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

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

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

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

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

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

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

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

aws_tls_key_operation_get_digest_algorithm(operation)

Returns the algorithm the operation digest is signed with. If the implementation does not support the digest algorithm, use aws_tls_key_operation_complete_with_error() to preventing stalling the TLS connection.

Prototype

enum aws_tls_hash_algorithm aws_tls_key_operation_get_digest_algorithm(const struct aws_tls_key_operation *operation);