LibAwsS3

Documentation not found.

aws_credentials_properties_s3express

Documentation not found.

aws_s3_checksum_algorithm

Documentation not found.

aws_s3_checksum_config

Documentation not found.

aws_s3_checksum_location

Documentation not found.

Documentation not found.

aws_s3_client_config

Documentation not found.

Documentation not found.

aws_s3_cpu_group_info

Documentation not found.

aws_s3_errors

Documentation not found.

Documentation not found.

aws_s3_meta_request_compute_content_md5

Documentation not found.

Invoked when the entire meta request execution is complete.

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

Return AWS_OP_SUCCESS to continue processing the request.

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

aws_s3_meta_request_options

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

There are several ways to pass the request's body data: 1) If the data is already in memory, set the body-stream on message. 2) If the data is on disk, set send_filepath for best performance. 3) If the data is available, but copying each chunk is asynchronous, set send_async_stream. 4) If you're not sure when each chunk of data will be available, use send_using_async_writes.

aws_s3_meta_request_progress

Information sent in the meta_request progress callback.

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

Invoked to provide the response body as it is received.

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

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

Return AWS_OP_SUCCESS to continue processing the request.

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

aws_s3_meta_request_result

Documentation not found.

Documentation not found.

Documentation not found.

Invoked to report the telemetry of the meta request once a single request finishes. Note: *metrics is only valid for the duration of the callback. If you need to keep it around, use aws_s3_request_metrics_acquire

aws_s3_meta_request_tls_mode

Documentation not found.

aws_s3_meta_request_type

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

The aws_s3_meta_request_type is a hint of transformation to be applied.

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

Return AWS_OP_SUCCESS to continue processing the request.

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

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

Arguments

• meta_request: pointer to the aws_s3_meta_request of the upload.
• info: Detailed info about the upload.

aws_s3_platform_info

Documentation not found.

Documentation not found.

Documentation not found.

aws_s3_request_type

The type of a single S3 HTTP request. Used by metrics. A meta-request can make multiple S3 HTTP requests under the hood.

For example, AWS_S3_META_REQUEST_TYPE_PUT_OBJECT for a large file will do multipart upload, resulting in 3+ HTTP requests: AWS_S3_REQUEST_TYPE_CREATE_MULTIPART_UPLOAD, one or more AWS_S3_REQUEST_TYPE_UPLOAD_PART, and finally AWS_S3_REQUEST_TYPE_COMPLETE_MULTIPART_UPLOAD.

aws_s3_request_type_operation_name() returns the S3 operation name for types that map (e.g. AWS_S3_REQUEST_TYPE_HEAD_OBJECT -> "HeadObject"), or empty string for types that don't map (e.g. AWS_S3_REQUEST_TYPE_UNKNOWN -> "").

aws_s3_subject

Documentation not found.

aws_s3_tcp_keep_alive_options

Documentation not found.

aws_s3_upload_part_review

Info about a single part, for you to review before the upload completes.

aws_s3_upload_resume_token_options

Documentation not found.

aws_s3_upload_review

Info for you to review before an upload completes.

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

aws_s3express_credentials_provider

Documentation not found.

aws_s3express_credentials_provider_vtable

Documentation not found.

The factory function for S3 client to create a S3 Express credentials provider. The S3 client will be the only owner of the S3 Express credentials provider.

During S3 client destruction, S3 client will start the destruction of the provider, and wait the on_provider_shutdown_callback to be invoked before the S3 client finish destruction.

Note to implement the factory properly: - Make sure on_provider_shutdown_callback will be invoked after the provider finish shutdown, otherwise, leak will happen. - The provider must not acquire a reference to the client; otherwise, a circular reference will cause a deadlock. - The client provided CANNOT be used within the factory function call or the destructor.

Arguments

• allocator: memory allocator to create the provider.
• client: The S3 client uses and owns the provider.
• on_provider_shutdown_callback: The callback to be invoked when the provider finishes shutdown.
• shutdown_user_data: The user data to invoke shutdown callback with
• user_data: The user data with the factory

Returns

The aws_s3express_credentials_provider.

aws_s3_client_acquire(client)

Add a reference, keeping this object alive. The reference must be released when you are done with it, or it's memory will never be cleaned up. You must not pass in NULL. Always returns the same pointer that was passed in.

Prototype

struct aws_s3_client *aws_s3_client_acquire(struct aws_s3_client *client);

aws_s3_client_make_meta_request(client, options)

Documentation not found.

Prototype

struct aws_s3_meta_request *aws_s3_client_make_meta_request( struct aws_s3_client *client, const struct aws_s3_meta_request_options *options);

aws_s3_client_new(allocator, client_config)

Documentation not found.

Prototype

struct aws_s3_client *aws_s3_client_new( struct aws_allocator *allocator, const struct aws_s3_client_config *client_config);

aws_s3_client_release(client)

Release a reference. When the reference count drops to 0, this object will be cleaned up. It's OK to pass in NULL (nothing happens). Always returns NULL.

Prototype

struct aws_s3_client *aws_s3_client_release(struct aws_s3_client *client);

aws_s3_endpoint_resolver_new(allocator)

Creates a new S3 endpoint resolver. Warning: Before using this header, you have to enable it by setting cmake config AWS_ENABLE_S3_ENDPOINT_RESOLVER=ON

Prototype

struct aws_endpoints_rule_engine *aws_s3_endpoint_resolver_new(struct aws_allocator *allocator);

aws_s3_get_current_platform_ec2_intance_type(cached_only)

Documentation not found.

Prototype

struct aws_byte_cursor aws_s3_get_current_platform_ec2_intance_type(bool cached_only);

aws_s3_get_current_platform_info()

Documentation not found.

Prototype

const struct aws_s3_platform_info *aws_s3_get_current_platform_info(void);

aws_s3_get_platforms_with_recommended_config()

Documentation not found.

Prototype

struct aws_array_list aws_s3_get_platforms_with_recommended_config(void);

aws_s3_init_default_signing_config(signing_config, region, credentials_provider)

Initialize the configuration for a default S3 signing.

Prototype

void aws_s3_init_default_signing_config( struct aws_signing_config_aws *signing_config, const struct aws_byte_cursor region, struct aws_credentials_provider *credentials_provider);

aws_s3_library_clean_up()

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

Prototype

void aws_s3_library_clean_up(void);

aws_s3_library_init(allocator)

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

Prototype

void aws_s3_library_init(struct aws_allocator *allocator);

aws_s3_meta_request_acquire(meta_request)

Add a reference, keeping this object alive. The reference must be released when you are done with it, or it's memory will never be cleaned up. You must not pass in NULL. Always returns the same pointer that was passed in.

Prototype

struct aws_s3_meta_request *aws_s3_meta_request_acquire(struct aws_s3_meta_request *meta_request);

aws_s3_meta_request_cancel(meta_request)

Documentation not found.

Prototype

void aws_s3_meta_request_cancel(struct aws_s3_meta_request *meta_request);

aws_s3_meta_request_increment_read_window(meta_request, bytes)

Increment the flow-control window, so that response data continues downloading.

If the client was created with enable_read_backpressure set true, each meta request has a flow-control window that shrinks as response body data is downloaded (headers do not affect the size of the window). The client's initial_read_window determines the starting size of each meta request's window. If a meta request's flow-control window reaches 0, no further data will be downloaded. If the initial_read_window is 0, the request will not start until the window is incremented. Maintain a larger window to keep up a high download throughput, parts cannot download in parallel unless the window is large enough to hold multiple parts. Maintain a smaller window to limit the amount of data buffered in memory.

If enable_read_backpressure is false this call will have no effect, no backpressure is being applied and data is being downloaded as fast as possible.

WARNING: This feature is experimental. Currently, backpressure is only applied to GetObject requests which are split into multiple parts, and you may still receive some data after the window reaches 0.

Prototype

void aws_s3_meta_request_increment_read_window(struct aws_s3_meta_request *meta_request, uint64_t bytes);

aws_s3_meta_request_pause(meta_request, out_resume_token)

Note: pause is currently only supported on upload requests. In order to pause an ongoing upload, call aws_s3_meta_request_pause() that will return resume token. Token can be used to query the state of operation at the pausing time. To resume an upload that was paused, supply resume token in the meta request options structure member aws_s3_meta_request_options.resume_token. The upload can be resumed either from the same client or a different one. Corner cases for resume upload are as follows: - upload is not MPU - fail with AWS_ERROR_UNSUPPORTED_OPERATION - pausing before MPU is created - NULL resume token returned. NULL resume token is equivalent to restarting upload - pausing in the middle of part transfer - return resume token. scheduling of new part uploads stops. - pausing after completeMPU started - return resume token. if s3 cannot find find associated MPU id when resuming with that token and num of parts uploaded equals to total num parts, then operation is a no op. Otherwise operation fails. Note: for no op case the call will succeed and finish/shutdown request callbacks will fire, but on headers callback will not fire. Note: similar to cancel pause does not cancel requests already in flight and and parts might complete after pause is requested.

Arguments

• meta_request: pointer to the aws_s3_meta_request of the upload to be paused
• resume_token: resume token

Returns

either AWS_OP_ERR or AWS_OP_SUCCESS

Prototype

int aws_s3_meta_request_pause( struct aws_s3_meta_request *meta_request, struct aws_s3_meta_request_resume_token **out_resume_token);

aws_s3_meta_request_release(meta_request)

Release a reference. When the reference count drops to 0, this object will be cleaned up. It's OK to pass in NULL (nothing happens). Always returns NULL.

Prototype

struct aws_s3_meta_request *aws_s3_meta_request_release(struct aws_s3_meta_request *meta_request);

aws_s3_meta_request_resume_token_acquire(resume_token)

Documentation not found.

Prototype

struct aws_s3_meta_request_resume_token *aws_s3_meta_request_resume_token_acquire( struct aws_s3_meta_request_resume_token *resume_token);

aws_s3_meta_request_resume_token_new_upload(allocator, options)

Create upload resume token from persisted data. Note: Data required for resume token varies per operation.

Prototype

struct aws_s3_meta_request_resume_token *aws_s3_meta_request_resume_token_new_upload( struct aws_allocator *allocator, const struct aws_s3_upload_resume_token_options *options);

aws_s3_meta_request_resume_token_num_parts_completed(resume_token)

Documentation not found.

Prototype

size_t aws_s3_meta_request_resume_token_num_parts_completed(struct aws_s3_meta_request_resume_token *resume_token);

aws_s3_meta_request_resume_token_part_size(resume_token)

Documentation not found.

Prototype

uint64_t aws_s3_meta_request_resume_token_part_size(struct aws_s3_meta_request_resume_token *resume_token);

aws_s3_meta_request_resume_token_release(resume_token)

Documentation not found.

Prototype

struct aws_s3_meta_request_resume_token *aws_s3_meta_request_resume_token_release( struct aws_s3_meta_request_resume_token *resume_token);

aws_s3_meta_request_resume_token_total_num_parts(resume_token)

Documentation not found.

Prototype

size_t aws_s3_meta_request_resume_token_total_num_parts(struct aws_s3_meta_request_resume_token *resume_token);

aws_s3_meta_request_resume_token_type(resume_token)

Documentation not found.

Prototype

enum aws_s3_meta_request_type aws_s3_meta_request_resume_token_type( struct aws_s3_meta_request_resume_token *resume_token);

aws_s3_meta_request_resume_token_upload_id(resume_token)

Documentation not found.

Prototype

struct aws_byte_cursor aws_s3_meta_request_resume_token_upload_id( struct aws_s3_meta_request_resume_token *resume_token);

aws_s3_meta_request_write(meta_request, data, eof)

Write the next chunk of data.

You must set [awss3metarequestoptions](@ref).send\_using\_async\_writes to use this function.

This function is asynchronous, and returns a future (see <aws/io/future.h>). You may not call write() again until the future completes.

If the future completes with an error code, then write() did not succeed and you should not call it again. If the future contains any error code, the meta request is guaranteed to finish soon (you don't need to worry about canceling the meta request yourself after a failed write). A common error code is AWS_ERROR_S3_REQUEST_HAS_COMPLETED, indicating the meta request completed for reasons unrelated to the write() call (e.g. CreateMultipartUpload received a 403 Forbidden response). AWS_ERROR_INVALID_STATE usually indicates that you're calling write() incorrectly (e.g. not waiting for previous write to complete).

You MUST keep the data in memory until the future completes. If you need to free the memory early, call aws_s3_meta_request_cancel(). cancel() will synchronously complete the future from any pending write with error code AWS_ERROR_S3_REQUEST_HAS_COMPLETED.

You can wait any length of time between calls to write(). If there's not enough data to upload a part, the data will be copied to a buffer and the future will immediately complete.

This function never returns NULL.

WARNING: This feature is experimental.

Arguments

• meta_request: Meta request
• data: The data to send. The data can be any size.
• eof: Pass true to signal EOF (end of file). Do not call write() again after passing true.

Prototype

struct aws_future_void *aws_s3_meta_request_write( struct aws_s3_meta_request *meta_request, struct aws_byte_cursor data, bool eof);

aws_s3_request_metrics_acquire(metrics)

Add a reference, keeping this object alive. The reference must be released when you are done with it, or it's memory will never be cleaned up. Always returns the same pointer that was passed in.

Prototype

struct aws_s3_request_metrics *aws_s3_request_metrics_acquire(struct aws_s3_request_metrics *metrics);

aws_s3_request_metrics_get_connection_id(metrics, out_connection_id)

Documentation not found.

Prototype

int aws_s3_request_metrics_get_connection_id(const struct aws_s3_request_metrics *metrics, size_t *out_connection_id);

aws_s3_request_metrics_get_end_timestamp_ns(metrics, out_end_time)

Documentation not found.

Prototype

void aws_s3_request_metrics_get_end_timestamp_ns(const struct aws_s3_request_metrics *metrics, uint64_t *out_end_time);

aws_s3_request_metrics_get_error_code(metrics)

Documentation not found.

Prototype

int aws_s3_request_metrics_get_error_code(const struct aws_s3_request_metrics *metrics);

aws_s3_request_metrics_get_host_address(metrics, out_host_address)

Get the host_address of the request. If unavailable, AWS_ERROR_S3_METRIC_DATA_NOT_AVAILABLE will be raised. If available, out_host_address will be set to a string. Be warned this string's lifetime is tied to the metrics object.

Prototype

void aws_s3_request_metrics_get_host_address( const struct aws_s3_request_metrics *metrics, const struct aws_string **out_host_address);

aws_s3_request_metrics_get_ip_address(metrics, out_ip_address)

Get the IP address of the request connected to. If unavailable, AWS_ERROR_S3_METRIC_DATA_NOT_AVAILABLE will be raised. If available, out_ip_address will be set to a string. Be warned this string's lifetime is tied to the metrics object.

Prototype

int aws_s3_request_metrics_get_ip_address( const struct aws_s3_request_metrics *metrics, const struct aws_string **out_ip_address);

aws_s3_request_metrics_get_operation_name(metrics, out_operation_name)

Get the S3 operation name of the request (e.g. "HeadObject"). If unavailable, AWS_ERROR_S3_METRIC_DATA_NOT_AVAILABLE will be raised. If available, out_operation_name will be set to a string. Be warned this string's lifetime is tied to the metrics object.

Prototype

int aws_s3_request_metrics_get_operation_name( const struct aws_s3_request_metrics *metrics, const struct aws_string **out_operation_name);

aws_s3_request_metrics_get_receive_end_timestamp_ns(metrics, out_receive_end_time)

Documentation not found.

Prototype

int aws_s3_request_metrics_get_receive_end_timestamp_ns( const struct aws_s3_request_metrics *metrics, uint64_t *out_receive_end_time);

aws_s3_request_metrics_get_receive_start_timestamp_ns(metrics, out_receive_start_time)

Documentation not found.

Prototype

int aws_s3_request_metrics_get_receive_start_timestamp_ns( const struct aws_s3_request_metrics *metrics, uint64_t *out_receive_start_time);

aws_s3_request_metrics_get_receiving_duration_ns(metrics, out_receiving_duration)

Documentation not found.

Prototype

int aws_s3_request_metrics_get_receiving_duration_ns( const struct aws_s3_request_metrics *metrics, uint64_t *out_receiving_duration);

aws_s3_request_metrics_get_request_id(metrics, out_request_id)

*********************************** Getters for s3 request metrics ***********************************************

Get the request ID from aws_s3_request_metrics. If unavailable, AWS_ERROR_S3_METRIC_DATA_NOT_AVAILABLE will be raised. If available, out_request_id will be set to a string. Be warned this string's lifetime is tied to the metrics object.

Prototype

int aws_s3_request_metrics_get_request_id( const struct aws_s3_request_metrics *metrics, const struct aws_string **out_request_id);

aws_s3_request_metrics_get_request_path_query(metrics, out_request_path_query)

Get the path and query of the request. If unavailable, AWS_ERROR_S3_METRIC_DATA_NOT_AVAILABLE will be raised. If available, out_request_path_query will be set to a string. Be warned this string's lifetime is tied to the metrics object.

Prototype

void aws_s3_request_metrics_get_request_path_query( const struct aws_s3_request_metrics *metrics, const struct aws_string **out_request_path_query);

aws_s3_request_metrics_get_request_stream_id(metrics, out_stream_id)

Documentation not found.

Prototype

int aws_s3_request_metrics_get_request_stream_id(const struct aws_s3_request_metrics *metrics, uint32_t *out_stream_id);

aws_s3_request_metrics_get_request_type(metrics, out_request_type)

Documentation not found.

Prototype

void aws_s3_request_metrics_get_request_type( const struct aws_s3_request_metrics *metrics, enum aws_s3_request_type *out_request_type);

aws_s3_request_metrics_get_response_headers(metrics, out_response_headers)

Documentation not found.

Prototype

int aws_s3_request_metrics_get_response_headers( const struct aws_s3_request_metrics *metrics, struct aws_http_headers **out_response_headers);

aws_s3_request_metrics_get_response_status_code(metrics, out_response_status)

Documentation not found.

Prototype

int aws_s3_request_metrics_get_response_status_code( const struct aws_s3_request_metrics *metrics, int *out_response_status);

aws_s3_request_metrics_get_send_end_timestamp_ns(metrics, out_send_end_time)

Documentation not found.

Prototype

int aws_s3_request_metrics_get_send_end_timestamp_ns( const struct aws_s3_request_metrics *metrics, uint64_t *out_send_end_time);

aws_s3_request_metrics_get_send_start_timestamp_ns(metrics, out_send_start_time)

Documentation not found.

Prototype

int aws_s3_request_metrics_get_send_start_timestamp_ns( const struct aws_s3_request_metrics *metrics, uint64_t *out_send_start_time);

aws_s3_request_metrics_get_sending_duration_ns(metrics, out_sending_duration)

Documentation not found.

Prototype

int aws_s3_request_metrics_get_sending_duration_ns( const struct aws_s3_request_metrics *metrics, uint64_t *out_sending_duration);

aws_s3_request_metrics_get_start_timestamp_ns(metrics, out_start_time)

Documentation not found.

Prototype

void aws_s3_request_metrics_get_start_timestamp_ns( const struct aws_s3_request_metrics *metrics, uint64_t *out_start_time);

aws_s3_request_metrics_get_thread_id(metrics, out_thread_id)

Documentation not found.

Prototype

int aws_s3_request_metrics_get_thread_id(const struct aws_s3_request_metrics *metrics, aws_thread_id_t *out_thread_id);

aws_s3_request_metrics_get_total_duration_ns(metrics, out_total_duration)

Documentation not found.

Prototype

void aws_s3_request_metrics_get_total_duration_ns( const struct aws_s3_request_metrics *metrics, uint64_t *out_total_duration);

aws_s3_request_metrics_release(metrics)

Release a reference. When the reference count drops to 0, this object will be cleaned up. It's OK to pass in NULL (nothing happens). Always returns NULL.

Prototype

struct aws_s3_request_metrics *aws_s3_request_metrics_release(struct aws_s3_request_metrics *metrics);

aws_s3_request_type_operation_name(type)

Return operation name for aws_s3_request_type, or empty string if the type doesn't map to an actual operation. For example: AWS_S3_REQUEST_TYPE_HEAD_OBJECT -> "HeadObject" AWS_S3_REQUEST_TYPE_UNKNOWN -> "" AWS_S3_REQUEST_TYPE_MAX -> ""

Prototype

const char *aws_s3_request_type_operation_name(enum aws_s3_request_type type);

aws_s3express_credentials_provider_get_credentials(provider, original_credentials, properties, callback, user_data)

Async function for retrieving specific credentials based on properties.

callback will only be invoked if-and-only-if the return value was AWS_OP_SUCCESS.

Arguments

• provider: aws_s3express_credentials_provider provider to source from
• original_credentials: The credentials used to derive the credentials for S3 Express.
• properties: Specific properties for credentials being fetched.
• user_data: user data to pass to the completion callback

Prototype

int aws_s3express_credentials_provider_get_credentials( struct aws_s3express_credentials_provider *provider, const struct aws_credentials *original_credentials, const struct aws_credentials_properties_s3express *properties, aws_on_get_credentials_callback_fn callback, void *user_data);

aws_s3express_credentials_provider_init_base(provider, allocator, vtable, impl)

To initialize the provider with basic vtable and refcount. And hook up the refcount with vtable functions.

Arguments

• provider:
• allocator:
• vtable:
• impl: Optional, the impl for the provider

Returns

AWS_S3_API

Prototype

void aws_s3express_credentials_provider_init_base( struct aws_s3express_credentials_provider *provider, struct aws_allocator *allocator, struct aws_s3express_credentials_provider_vtable *vtable, void *impl);

aws_s3express_credentials_provider_release(provider)

Documentation not found.

Prototype

struct aws_s3express_credentials_provider *aws_s3express_credentials_provider_release( struct aws_s3express_credentials_provider *provider);