libs3
trunk
|
#include <stdint.h>
#include <sys/select.h>
Go to the source code of this file.
Data Structures | |
struct | S3NameValue |
struct | S3ResponseProperties |
struct | S3AclGrant |
struct | S3BucketContext |
struct | S3ListBucketContent |
struct | S3ListMultipartUpload |
struct | S3ListPart |
struct | S3PutProperties |
struct | S3GetConditions |
struct | S3ErrorDetails |
struct | S3ResponseHandler |
struct | S3ListServiceHandler |
struct | S3ListBucketHandler |
struct | S3PutObjectHandler |
struct | S3GetObjectHandler |
struct | S3MultipartInitialHandler |
struct | S3MultipartCommitHandler |
struct | S3ListMultipartUploadsHandler |
struct | S3ListPartsHandler |
struct | S3AbortMultipartUploadHandler |
Macros | |
#define | S3_MAX_HOSTNAME_SIZE 255 |
#define | S3_DEFAULT_HOSTNAME "s3.amazonaws.com" |
#define | S3_MAX_BUCKET_NAME_SIZE 255 |
#define | S3_MAX_KEY_SIZE 1024 |
#define | S3_MAX_METADATA_SIZE 2048 |
#define | S3_METADATA_HEADER_NAME_PREFIX "x-amz-meta-" |
#define | S3_MAX_METADATA_COUNT (S3_MAX_METADATA_SIZE / (sizeof(S3_METADATA_HEADER_NAME_PREFIX "nv") - 1)) |
#define | S3_MAX_ACL_GRANT_COUNT 100 |
#define | S3_MAX_GRANTEE_EMAIL_ADDRESS_SIZE 128 |
#define | S3_MAX_GRANTEE_USER_ID_SIZE 128 |
#define | S3_MAX_GRANTEE_DISPLAY_NAME_SIZE 128 |
#define | S3_MAX_AUTHENTICATED_QUERY_STRING_SIZE |
#define | S3_INIT_WINSOCK 1 |
#define | S3_INIT_VERIFY_PEER 2 |
#define | S3_INIT_ALL (S3_INIT_WINSOCK) |
#define | S3_DEFAULT_REGION "us-east-1" |
Typedefs | |
typedef struct S3RequestContext | S3RequestContext |
typedef struct S3NameValue | S3NameValue |
typedef struct S3ResponseProperties | S3ResponseProperties |
typedef struct S3AclGrant | S3AclGrant |
typedef struct S3BucketContext | S3BucketContext |
typedef struct S3ListBucketContent | S3ListBucketContent |
typedef struct S3ListMultipartUpload | S3ListMultipartUpload |
typedef struct S3ListPart | S3ListPart |
typedef struct S3PutProperties | S3PutProperties |
typedef struct S3GetConditions | S3GetConditions |
typedef struct S3ErrorDetails | S3ErrorDetails |
typedef S3Status( | S3ResponsePropertiesCallback )(const S3ResponseProperties *properties, void *callbackData) |
typedef void( | S3ResponseCompleteCallback )(S3Status status, const S3ErrorDetails *errorDetails, void *callbackData) |
typedef S3Status( | S3ListServiceCallback )(const char *ownerId, const char *ownerDisplayName, const char *bucketName, int64_t creationDateSeconds, void *callbackData) |
typedef S3Status( | S3ListBucketCallback )(int isTruncated, const char *nextMarker, int contentsCount, const S3ListBucketContent *contents, int commonPrefixesCount, const char **commonPrefixes, void *callbackData) |
typedef int( | S3PutObjectDataCallback )(int bufferSize, char *buffer, void *callbackData) |
typedef S3Status( | S3GetObjectDataCallback )(int bufferSize, const char *buffer, void *callbackData) |
typedef S3Status( | S3MultipartInitialResponseCallback )(const char *upload_id, void *callbackData) |
typedef S3Status( | S3ListMultipartUploadsResponseCallback )(int isTruncated, const char *nextKeyMarker, const char *nextUploadIdMarker, int uploadsCount, const S3ListMultipartUpload *uploads, int commonPrefixesCount, const char **commonPrefixes, void *callbackData) |
typedef S3Status( | S3ListPartsResponseCallback )(int isTruncated, const char *nextPartNumberMarker, const char *initiatorId, const char *initiatorDisplayName, const char *ownerId, const char *ownerDisplayName, const char *storageClass, int partsCount, int lastPartNumber, const S3ListPart *parts, void *callbackData) |
typedef S3Status( | S3MultipartCommitResponseCallback )(const char *location, const char *etag, void *callbackData) |
typedef S3Status(* | S3SetupCurlCallback )(void *curlMulti, void *curlEasy, void *setupData) |
typedef struct S3ResponseHandler | S3ResponseHandler |
typedef struct S3ListServiceHandler | S3ListServiceHandler |
typedef struct S3ListBucketHandler | S3ListBucketHandler |
typedef struct S3PutObjectHandler | S3PutObjectHandler |
typedef struct S3GetObjectHandler | S3GetObjectHandler |
typedef struct S3MultipartInitialHandler | S3MultipartInitialHandler |
typedef struct S3MultipartCommitHandler | S3MultipartCommitHandler |
typedef struct S3ListMultipartUploadsHandler | S3ListMultipartUploadsHandler |
typedef struct S3ListPartsHandler | S3ListPartsHandler |
typedef struct S3AbortMultipartUploadHandler | S3AbortMultipartUploadHandler |
Functions | |
S3Status | S3_initialize (const char *userAgentInfo, int flags, const char *defaultS3HostName) |
void | S3_deinitialize () |
const char * | S3_get_status_name (S3Status status) |
S3Status | S3_validate_bucket_name (const char *bucketName, S3UriStyle uriStyle) |
S3Status | S3_convert_acl (char *aclXml, char *ownerId, char *ownerDisplayName, int *aclGrantCountReturn, S3AclGrant *aclGrants) |
int | S3_status_is_retryable (S3Status status) |
S3Status | S3_create_request_context (S3RequestContext **requestContextReturn) |
S3Status | S3_create_request_context_ex (S3RequestContext **requestContextReturn, void *curlMulti, S3SetupCurlCallback setupCurlCallback, void *setupCurlCallbackData) |
void | S3_destroy_request_context (S3RequestContext *requestContext) |
S3Status | S3_runall_request_context (S3RequestContext *requestContext) |
S3Status | S3_runonce_request_context (S3RequestContext *requestContext, int *requestsRemainingReturn) |
S3Status | S3_process_request_context (S3RequestContext *requestContext) |
S3Status | S3_get_request_context_fdsets (S3RequestContext *requestContext, fd_set *readFdSet, fd_set *writeFdSet, fd_set *exceptFdSet, int *maxFd) |
int64_t | S3_get_request_context_timeout (S3RequestContext *requestContext) |
void | S3_set_request_context_verify_peer (S3RequestContext *requestContext, int verifyPeer) |
S3Status | S3_generate_authenticated_query_string (char *buffer, const S3BucketContext *bucketContext, const char *key, int expires, const char *resource, const char *httpMethod) |
void | S3_list_service (S3Protocol protocol, const char *accessKeyId, const char *secretAccessKey, const char *securityToken, const char *hostName, const char *authRegion, S3RequestContext *requestContext, int timeoutMs, const S3ListServiceHandler *handler, void *callbackData) |
void | S3_test_bucket (S3Protocol protocol, S3UriStyle uriStyle, const char *accessKeyId, const char *secretAccessKey, const char *securityToken, const char *hostName, const char *bucketName, const char *authRegion, int locationConstraintReturnSize, char *locationConstraintReturn, S3RequestContext *requestContext, int timeoutMs, const S3ResponseHandler *handler, void *callbackData) |
void | S3_create_bucket (S3Protocol protocol, const char *accessKeyId, const char *secretAccessKey, const char *securityToken, const char *hostName, const char *bucketName, const char *authRegion, S3CannedAcl cannedAcl, const char *locationConstraint, S3RequestContext *requestContext, int timeoutMs, const S3ResponseHandler *handler, void *callbackData) |
void | S3_delete_bucket (S3Protocol protocol, S3UriStyle uriStyle, const char *accessKeyId, const char *secretAccessKey, const char *securityToken, const char *hostName, const char *bucketName, const char *authRegion, S3RequestContext *requestContext, int timeoutMs, const S3ResponseHandler *handler, void *callbackData) |
void | S3_list_bucket (const S3BucketContext *bucketContext, const char *prefix, const char *marker, const char *delimiter, int maxkeys, S3RequestContext *requestContext, int timeoutMs, const S3ListBucketHandler *handler, void *callbackData) |
void | S3_put_object (const S3BucketContext *bucketContext, const char *key, uint64_t contentLength, const S3PutProperties *putProperties, S3RequestContext *requestContext, int timeoutMs, const S3PutObjectHandler *handler, void *callbackData) |
void | S3_copy_object (const S3BucketContext *bucketContext, const char *key, const char *destinationBucket, const char *destinationKey, const S3PutProperties *putProperties, int64_t *lastModifiedReturn, int eTagReturnSize, char *eTagReturn, S3RequestContext *requestContext, int timeoutMs, const S3ResponseHandler *handler, void *callbackData) |
void | S3_copy_object_range (const S3BucketContext *bucketContext, const char *key, const char *destinationBucket, const char *destinationKey, const int partNo, const char *uploadId, const unsigned long startOffset, const unsigned long count, const S3PutProperties *putProperties, int64_t *lastModifiedReturn, int eTagReturnSize, char *eTagReturn, S3RequestContext *requestContext, int timeoutMs, const S3ResponseHandler *handler, void *callbackData) |
void | S3_get_object (const S3BucketContext *bucketContext, const char *key, const S3GetConditions *getConditions, uint64_t startByte, uint64_t byteCount, S3RequestContext *requestContext, int timeoutMs, const S3GetObjectHandler *handler, void *callbackData) |
void | S3_head_object (const S3BucketContext *bucketContext, const char *key, S3RequestContext *requestContext, int timeoutMs, const S3ResponseHandler *handler, void *callbackData) |
void | S3_delete_object (const S3BucketContext *bucketContext, const char *key, S3RequestContext *requestContext, int timeoutMs, const S3ResponseHandler *handler, void *callbackData) |
void | S3_get_acl (const S3BucketContext *bucketContext, const char *key, char *ownerId, char *ownerDisplayName, int *aclGrantCountReturn, S3AclGrant *aclGrants, S3RequestContext *requestContext, int timeoutMs, const S3ResponseHandler *handler, void *callbackData) |
void | S3_set_acl (const S3BucketContext *bucketContext, const char *key, const char *ownerId, const char *ownerDisplayName, int aclGrantCount, const S3AclGrant *aclGrants, S3RequestContext *requestContext, int timeoutMs, const S3ResponseHandler *handler, void *callbackData) |
void | S3_get_lifecycle (const S3BucketContext *bucketContext, char *lifecycleXmlDocumentReturn, int lifecycleXmlDocumentBufferSize, S3RequestContext *requestContext, int timeoutMs, const S3ResponseHandler *handler, void *callbackData) |
void | S3_set_lifecycle (const S3BucketContext *bucketContext, const char *lifecycleXmlDocument, S3RequestContext *requestContext, int timeoutMs, const S3ResponseHandler *handler, void *callbackData) |
void | S3_get_server_access_logging (const S3BucketContext *bucketContext, char *targetBucketReturn, char *targetPrefixReturn, int *aclGrantCountReturn, S3AclGrant *aclGrants, S3RequestContext *requestContext, int timeoutMs, const S3ResponseHandler *handler, void *callbackData) |
void | S3_set_server_access_logging (const S3BucketContext *bucketContext, const char *targetBucket, const char *targetPrefix, int aclGrantCount, const S3AclGrant *aclGrants, S3RequestContext *requestContext, int timeoutMs, const S3ResponseHandler *handler, void *callbackData) |
void | S3_initiate_multipart (S3BucketContext *bucketContext, const char *key, S3PutProperties *putProperties, S3MultipartInitialHandler *handler, S3RequestContext *requestContext, int timeoutMs, void *callbackData) |
void | S3_upload_part (S3BucketContext *bucketContext, const char *key, S3PutProperties *putProperties, S3PutObjectHandler *handler, int seq, const char *upload_id, int partContentLength, S3RequestContext *requestContext, int timeoutMs, void *callbackData) |
void | S3_complete_multipart_upload (S3BucketContext *bucketContext, const char *key, S3MultipartCommitHandler *handler, const char *upload_id, int contentLength, S3RequestContext *requestContext, int timeoutMs, void *callbackData) |
void | S3_list_parts (S3BucketContext *bucketContext, const char *key, const char *partnumbermarker, const char *uploadid, const char *encodingtype, int maxparts, S3RequestContext *requestContext, int timeoutMs, const S3ListPartsHandler *handler, void *callbackData) |
void | S3_abort_multipart_upload (S3BucketContext *bucketContext, const char *key, const char *uploadId, int timeoutMs, S3AbortMultipartUploadHandler *handler) |
void | S3_list_multipart_uploads (S3BucketContext *bucketContext, const char *prefix, const char *keymarker, const char *uploadidmarker, const char *encodingtype, const char *delimiter, int maxuploads, S3RequestContext *requestContext, int timeoutMs, const S3ListMultipartUploadsHandler *handler, void *callbackData) |
Copyright 2008 Bryan Ischo bryan @isc ho.co m
This file is part of libs3.
libs3 is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, version 3 or above of the License. You can also redistribute and/or modify it under the terms of the GNU General Public License, version 2 or above of the License.
In addition, as a special exception, the copyright holders give permission to link the code of this library and its programs with the OpenSSL library, and distribute linked combinations including the two.
libs3 is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU Lesser General Public License version 3 along with libs3, in a file named COPYING. If not, see http://www.gnu.org/licenses/.
You should also have received a copy of the GNU General Public License version 2 along with libs3, in a file named COPYING-GPLv2. If not, see http://www.gnu.org/licenses/.
#define S3_MAX_HOSTNAME_SIZE 255 |
Constants S3_MAX_HOSTNAME_SIZE is the maximum size we allow for a host name
#define S3_DEFAULT_HOSTNAME "s3.amazonaws.com" |
This is the default hostname that is being used for the S3 requests
#define S3_MAX_BUCKET_NAME_SIZE 255 |
S3_MAX_BUCKET_NAME_SIZE is the maximum size of a bucket name.
#define S3_MAX_KEY_SIZE 1024 |
S3_MAX_KEY_SIZE is the maximum size of keys that Amazon S3 supports.
#define S3_MAX_METADATA_SIZE 2048 |
S3_MAX_METADATA_SIZE is the maximum number of bytes allowed for x-amz-meta header names and values in any request passed to Amazon S3
#define S3_METADATA_HEADER_NAME_PREFIX "x-amz-meta-" |
S3_METADATA_HEADER_NAME_PREFIX is the prefix of an S3 "meta header"
#define S3_MAX_METADATA_COUNT (S3_MAX_METADATA_SIZE / (sizeof(S3_METADATA_HEADER_NAME_PREFIX "nv") - 1)) |
S3_MAX_METADATA_COUNT is the maximum number of x-amz-meta- headers that could be included in a request to S3. The smallest meta header is "x-amz-meta-n: v". Since S3 doesn't count the ": " against the total, the smallest amount of data to count for a header would be the length of "x-amz-meta-nv".
#define S3_MAX_ACL_GRANT_COUNT 100 |
S3_MAX_ACL_GRANT_COUNT is the maximum number of ACL grants that may be set on a bucket or object at one time. It is also the maximum number of ACL grants that the XML ACL parsing routine will parse.
#define S3_MAX_GRANTEE_EMAIL_ADDRESS_SIZE 128 |
This is the maximum number of characters (including terminating \0) that libs3 supports in an ACL grantee email address.
#define S3_MAX_GRANTEE_USER_ID_SIZE 128 |
This is the maximum number of characters (including terminating \0) that libs3 supports in an ACL grantee user id.
#define S3_MAX_GRANTEE_DISPLAY_NAME_SIZE 128 |
This is the maximum number of characters (including terminating \0) that libs3 supports in an ACL grantee user display name.
#define S3_MAX_AUTHENTICATED_QUERY_STRING_SIZE |
This is the maximum number of characters that will be stored in the return buffer for the utility function which computes an HTTP authenticated query string
#define S3_INIT_WINSOCK 1 |
This constant is used by the S3_initialize() function, to specify that the winsock library should be initialized by libs3; only relevent on Microsoft Windows platforms.
#define S3_INIT_VERIFY_PEER 2 |
This constant is used by the S3_initialize() function, to enable peer SSL certificate by default for all requests. If this is not set in the flags passed to S3_initialize(), then the SSL certificate of the peer will NOT be verified by default (but can still be enabled on a per request basis by calling S3_set_request_context_verify_peer).
#define S3_INIT_ALL (S3_INIT_WINSOCK) |
This convenience constant is used by the S3_initialize() function to indicate that all libraries required by libs3 should be initialized.
#define S3_DEFAULT_REGION "us-east-1" |
The default region identifier used to scope the signing key
typedef struct S3RequestContext S3RequestContext |
Data Types An S3RequestContext manages multiple S3 requests simultaneously; see the S3_XXX_request_context functions below for details
typedef struct S3NameValue S3NameValue |
S3NameValue represents a single Name - Value pair, used to represent either S3 metadata associated with a key, or S3 error details.
typedef struct S3ResponseProperties S3ResponseProperties |
S3ResponseProperties is passed to the properties callback function which is called when the complete response properties have been received. Some of the fields of this structure are optional and may not be provided in the response, and some will always be provided in the response.
typedef struct S3AclGrant S3AclGrant |
S3AclGrant identifies a single grant in the ACL for a bucket or object. An ACL is composed of any number of grants, which specify a grantee and the permissions given to that grantee. S3 does not normalize ACLs in any way, so a redundant ACL specification will lead to a redundant ACL stored in S3.
typedef struct S3BucketContext S3BucketContext |
A context for working with objects within a bucket. A bucket context holds all information necessary for working with a bucket, and may be used repeatedly over many consecutive (or simultaneous) calls into libs3 bucket operation functions.
typedef struct S3ListBucketContent S3ListBucketContent |
This is a single entry supplied to the list bucket callback by a call to S3_list_bucket. It identifies a single matching key from the list operation.
typedef struct S3ListMultipartUpload S3ListMultipartUpload |
This is a single entry supplied to the list bucket callback by a call to S3_list_bucket. It identifies a single matching key from the list operation.
typedef struct S3ListPart S3ListPart |
typedef struct S3PutProperties S3PutProperties |
S3PutProperties is the set of properties that may optionally be set by the user when putting objects to S3. Each field of this structure is optional and may or may not be present.
typedef struct S3GetConditions S3GetConditions |
S3GetConditions is used for the get_object operation, and specifies conditions which the object must meet in order to be successfully returned.
typedef struct S3ErrorDetails S3ErrorDetails |
S3ErrorDetails provides detailed information describing an S3 error. This is only presented when the error is an S3-generated error (i.e. one of the S3StatusErrorXXX values).
typedef S3Status( S3ResponsePropertiesCallback)(const S3ResponseProperties *properties, void *callbackData) |
Callback Signatures This callback is made whenever the response properties become available for any request.
properties | are the properties that are available from the response |
callbackData | is the callback data as specified when the request was issued. |
typedef void( S3ResponseCompleteCallback)(S3Status status, const S3ErrorDetails *errorDetails, void *callbackData) |
This callback is made when the response has been completely received, or an error has occurred which has prematurely aborted the request, or one of the other user-supplied callbacks returned a value intended to abort the request. This callback is always made for every request, as the very last callback made for that request.
status | gives the overall status of the response, indicating success or failure; use S3_status_is_retryable() as a simple way to detect whether or not the status indicates that the request failed but may be retried. |
errorDetails | if non-NULL, gives details as returned by the S3 service, describing the error |
callbackData | is the callback data as specified when the request was issued. |
typedef S3Status( S3ListServiceCallback)(const char *ownerId, const char *ownerDisplayName, const char *bucketName, int64_t creationDateSeconds, void *callbackData) |
This callback is made for each bucket resulting from a list service operation.
ownerId | is the ID of the owner of the bucket |
ownerDisplayName | is the owner display name of the owner of the bucket |
bucketName | is the name of the bucket |
creationDateSeconds | if < 0 indicates that no creation date was supplied for the bucket; if >= 0 indicates the number of seconds since UNIX Epoch of the creation date of the bucket |
callbackData | is the callback data as specified when the request was issued. |
typedef S3Status( S3ListBucketCallback)(int isTruncated, const char *nextMarker, int contentsCount, const S3ListBucketContent *contents, int commonPrefixesCount, const char **commonPrefixes, void *callbackData) |
This callback is made repeatedly as a list bucket operation progresses. The contents reported via this callback are only reported once per list bucket operation, but multiple calls to this callback may be necessary to report all items resulting from the list bucket operation.
isTruncated | is true if the list bucket request was truncated by the S3 service, in which case the remainder of the list may be obtained by querying again using the Marker parameter to start the query after this set of results |
nextMarker | if present, gives the largest (alphabetically) key returned in the response, which, if isTruncated is true, may be used as the marker in a subsequent list buckets operation to continue listing |
contentsCount | is the number of ListBucketContent structures in the contents parameter |
contents | is an array of ListBucketContent structures, each one describing an object in the bucket |
commonPrefixesCount | is the number of common prefixes strings in the commonPrefixes parameter |
commonPrefixes | is an array of strings, each specifing one of the common prefixes as returned by S3 |
callbackData | is the callback data as specified when the request was issued. |
typedef int( S3PutObjectDataCallback)(int bufferSize, char *buffer, void *callbackData) |
This callback is made during a put object operation, to obtain the next chunk of data to put to the S3 service as the contents of the object. This callback is made repeatedly, each time acquiring the next chunk of data to write to the service, until a negative or 0 value is returned.
bufferSize | gives the maximum number of bytes that may be written into the buffer parameter by this callback |
buffer | gives the buffer to fill with at most bufferSize bytes of data as the next chunk of data to send to S3 as the contents of this object |
callbackData | is the callback data as specified when the request was issued. |
typedef S3Status( S3GetObjectDataCallback)(int bufferSize, const char *buffer, void *callbackData) |
This callback is made during a get object operation, to provide the next chunk of data available from the S3 service constituting the contents of the object being fetched. This callback is made repeatedly, each time providing the next chunk of data read, until the complete object contents have been passed through the callback in this way, or the callback returns an error status.
bufferSize | gives the number of bytes in buffer |
buffer | is the data being passed into the callback |
callbackData | is the callback data as specified when the request was issued. |
typedef S3Status( S3MultipartInitialResponseCallback)(const char *upload_id, void *callbackData) |
This callback is made after initiation of a multipart upload operation. It indicates that the multi part upload has been created and provides the id that can be used to associate multi upload parts with the multi upload operation
upload_id | is the unique identifier if this multi part upload operation, to be used in calls to S3_upload_part and S3_complete_multipart_upload |
callbackData | is the callback data as specified when the request was issued. |
typedef S3Status( S3ListMultipartUploadsResponseCallback)(int isTruncated, const char *nextKeyMarker, const char *nextUploadIdMarker, int uploadsCount, const S3ListMultipartUpload *uploads, int commonPrefixesCount, const char **commonPrefixes, void *callbackData) |
This callback is made after completion of a part of a multipart upload operation. It is a status callback indicating that the multipart upload is in progress and that some sub-set of the parts have completed upload. The multipart upload is not considered fully complete in total until the commit response callback is made.
isTruncated | is ??? someone document this please |
nextKeyMarker | is ??? someone document this please |
nextUploadIdMarker | is ??? someone document this please |
uploadsCount | is the number of elements in the [uploads] array |
uploads | is an array of ??? someone document this please |
commonPrefixesCount | is the number of elements in the [commonPrefixes] array |
commonPrefixes | is ??? someone document this please |
callbackData | is the callback data as specified when the request was issued. |
typedef S3Status( S3ListPartsResponseCallback)(int isTruncated, const char *nextPartNumberMarker, const char *initiatorId, const char *initiatorDisplayName, const char *ownerId, const char *ownerDisplayName, const char *storageClass, int partsCount, int lastPartNumber, const S3ListPart *parts, void *callbackData) |
This callback is made with the result of a succesful "list parts" request to list the parts of a multi part upload (in progress???).
isTruncated | is ??? someone document this please |
nextPartNumberMarker | is ??? someone document this please |
intiatorId | is ??? someone document this please |
initiatorDisplayName | is ??? someone document this please |
ownerId | is ??? someone document this please |
ownerDisplayName | is ??? someone document this please |
storageClass | is ??? someone document this please |
partsCount | is ??? someone document this please |
lastPartNumber | is ??? someone document this please |
parts | is ??? someone document this please |
callbackData | is the callback data as specified when the request was issued. |
typedef S3Status( S3MultipartCommitResponseCallback)(const char *location, const char *etag, void *callbackData) |
This callback is made after commit of a multipart upload operation. It indicates that the data uploaded via the multipart upload operation has been committed.
location | is ??? someone please document this |
etag | is the S3 etag of the complete object after the multipart upload |
callbackData | is the callback data as specified when the request was issued. |
typedef S3Status(* S3SetupCurlCallback)(void *curlMulti, void *curlEasy, void *setupData) |
Mechanism for S3 application to customize each CURL easy request associated with the given S3 request context.
This callback can be optinally configured using S3_create_request_context_ex and will be invoked every time a new CURL request is created in the context of the given CURLM handle. Invocation will occur after libs3 has finished configuring its own options of CURL, but before CURL is started.
curl_multi | is the CURLM handle associated with this context. |
curl_easy | is the CURL request being created. |
setupData | is the setupCurlCallbackData parameter passed to S3_create_request_context_ex. |
typedef struct S3ResponseHandler S3ResponseHandler |
Callback Structures An S3ResponseHandler defines the callbacks which are made for any request.
typedef struct S3ListServiceHandler S3ListServiceHandler |
An S3ListServiceHandler defines the callbacks which are made for list_service requests.
typedef struct S3ListBucketHandler S3ListBucketHandler |
An S3ListBucketHandler defines the callbacks which are made for list_bucket requests.
typedef struct S3PutObjectHandler S3PutObjectHandler |
An S3PutObjectHandler defines the callbacks which are made for put_object requests.
typedef struct S3GetObjectHandler S3GetObjectHandler |
An S3GetObjectHandler defines the callbacks which are made for get_object requests.
typedef struct S3MultipartInitialHandler S3MultipartInitialHandler |
typedef struct S3MultipartCommitHandler S3MultipartCommitHandler |
typedef struct S3ListMultipartUploadsHandler S3ListMultipartUploadsHandler |
typedef struct S3ListPartsHandler S3ListPartsHandler |
typedef struct S3AbortMultipartUploadHandler S3AbortMultipartUploadHandler |
enum S3Status |
Enumerations S3Status is a status code as returned by a libs3 function. The meaning of each status code is defined in the comments for each function which returns that status.
enum S3Protocol |
S3Protocol represents a protocol that may be used for communicating a request to the Amazon S3 service.
In general, HTTPS is greatly preferred (and should be the default of any application using libs3) because it protects any data being sent to or from S3 using strong encryption. However, HTTPS is much more CPU intensive than HTTP, and if the caller is absolutely certain that it is OK for the data to be viewable by anyone in transit, then HTTP can be used.
Enumerator | |
---|---|
S3ProtocolHTTPS | |
S3ProtocolHTTP |
enum S3UriStyle |
S3UriStyle defines the form that an Amazon S3 URI identifying a bucket or object can take. They are of these forms:
Virtual Host: ${protocol}://${bucket}.s3.amazonaws.com/[${key}] Path: ${protocol}://s3.amazonaws.com/${bucket}/[${key}]
It is generally better to use the Virual Host URI form, because it ensures that the bucket name used is compatible with normal HTTP GETs and POSTs of data to/from the bucket. However, if DNS lookups for the bucket are too slow or unreliable for some reason, Path URI form may be used.
Enumerator | |
---|---|
S3UriStyleVirtualHost | |
S3UriStylePath |
enum S3GranteeType |
S3GranteeType defines the type of Grantee used in an S3 ACL Grant. Amazon Customer By Email - identifies the Grantee using their Amazon S3 account email address Canonical User - identifies the Grantee by S3 User ID and Display Name, which can only be obtained by making requests to S3, for example, by listing owned buckets All AWS Users - identifies all authenticated AWS users All Users - identifies all users Log Delivery - identifies the Amazon group responsible for writing server access logs into buckets
Enumerator | |
---|---|
S3GranteeTypeAmazonCustomerByEmail | |
S3GranteeTypeCanonicalUser | |
S3GranteeTypeAllAwsUsers | |
S3GranteeTypeAllUsers | |
S3GranteeTypeLogDelivery |
enum S3Permission |
This is an individual permission granted to a grantee in an S3 ACL Grant. Read permission gives the Grantee the permission to list the bucket, or read the object or its metadata Write permission gives the Grantee the permission to create, overwrite, or delete any object in the bucket, and is not supported for objects ReadACP permission gives the Grantee the permission to read the ACP for the bucket or object; the owner of the bucket or object always has this permission implicitly WriteACP permission gives the Grantee the permission to overwrite the ACP for the bucket or object; the owner of the bucket or object always has this permission implicitly FullControl permission gives the Grantee all permissions specified by the Read, Write, ReadACP, and WriteACP permissions
Enumerator | |
---|---|
S3PermissionRead | |
S3PermissionWrite | |
S3PermissionReadACP | |
S3PermissionWriteACP | |
S3PermissionFullControl |
enum S3CannedAcl |
S3CannedAcl is an ACL that can be specified when an object is created or updated. Each canned ACL has a predefined value when expanded to a full set of S3 ACL Grants. Private canned ACL gives the owner FULL_CONTROL and no other permissions are issued Public Read canned ACL gives the owner FULL_CONTROL and all users Read permission Public Read Write canned ACL gives the owner FULL_CONTROL and all users Read and Write permission AuthenticatedRead canned ACL gives the owner FULL_CONTROL and authenticated S3 users Read permission
Enumerator | |
---|---|
S3CannedAclPrivate | |
S3CannedAclPublicRead | |
S3CannedAclPublicReadWrite | |
S3CannedAclAuthenticatedRead | |
S3CannedAclBucketOwnerFullControl |
S3Status S3_initialize | ( | const char * | userAgentInfo, |
int | flags, | ||
const char * | defaultS3HostName | ||
) |
General Library Functions Initializes libs3 for use. This function must be called before any other libs3 function is called. It may be called multiple times, with the same effect as calling it once, as long as S3_deinitialize() is called an equal number of times when the program has finished. This function is NOT thread-safe and must only be called by one thread at a time.
userAgentInfo | is a string that will be included in the User-Agent header of every request made to the S3 service. You may provide NULL or the empty string if you don't care about this. The value will not be copied by this function and must remain unaltered by the caller until S3_deinitialize() is called. |
flags | is a bitmask of some combination of S3_INIT_XXX flag, or S3_INIT_ALL, indicating which of the libraries that libs3 depends upon should be initialized by S3_initialize(). Only if your program initializes one of these dependency libraries itself should anything other than S3_INIT_ALL be passed in for this bitmask. |
You should pass S3_INIT_WINSOCK if and only if your application does not initialize winsock elsewhere. On non-Microsoft Windows platforms it has no effect.
As a convenience, the macro S3_INIT_ALL is provided, which will do all necessary initialization; however, be warned that things may break if your application re-initializes the dependent libraries later.
defaultS3HostName | is a string the specifies the default S3 server hostname to use when making S3 requests; this value is used whenever the hostName of an S3BucketContext is NULL. If NULL is passed here then the default of S3_DEFAULT_HOSTNAME will be used. |
void S3_deinitialize | ( | ) |
Must be called once per program for each call to libs3_initialize(). After this call is complete, no libs3 function may be called except S3_initialize().
const char* S3_get_status_name | ( | S3Status | status | ) |
Returns a string with the textual name of an S3Status code
status | is S3Status code for which the textual name will be returned |
S3Status S3_validate_bucket_name | ( | const char * | bucketName, |
S3UriStyle | uriStyle | ||
) |
This function may be used to validate an S3 bucket name as being in the correct form for use with the S3 service. Amazon S3 limits the allowed characters in S3 bucket names, as well as imposing some additional rules on the length of bucket names and their structure. There are actually two limits; one for bucket names used only in path-style URIs, and a more strict limit used for bucket names used in virtual-host-style URIs. It is advisable to use only bucket names which meet the more strict requirements regardless of how the bucket expected to be used.
This method does NOT validate that the bucket is available for use in the S3 service, so the return value of this function cannot be used to decide whether or not a bucket with the give name already exists in Amazon S3 or is accessible by the caller. It merely validates that the bucket name is valid for use with S3.
bucketName | is the bucket name to validate |
uriStyle | gives the URI style to validate the bucket name against. It is advisable to always use S3UriStyleVirtuallHost. |
S3Status S3_convert_acl | ( | char * | aclXml, |
char * | ownerId, | ||
char * | ownerDisplayName, | ||
int * | aclGrantCountReturn, | ||
S3AclGrant * | aclGrants | ||
) |
Converts an XML representation of an ACL to a libs3 structured representation. This method is not strictly necessary for working with ACLs using libs3, but may be convenient for users of the library who read ACLs from elsewhere in XML format and need to use these ACLs with libs3.
aclXml | is the XML representation of the ACL. This must be a zero-terminated character string. |
ownerId | will be filled in with the Owner ID specified in the XML. At most MAX_GRANTEE_USER_ID_SIZE bytes will be stored at this location. |
ownerDisplayName | will be filled in with the Owner Display Name specified in the XML. At most MAX_GRANTEE_DISPLAY_NAME_SIZE bytes will be stored at this location. |
aclGrantCountReturn | returns the number of S3AclGrant structures returned in the aclGrantsReturned array |
aclGrants | must be passed in as an array of at least S3_ACL_MAXCOUNT structures, and on return from this function, the first aclGrantCountReturn structures will be filled in with the ACLs represented by the input XML. |
int S3_status_is_retryable | ( | S3Status | status | ) |
Returns nonzero if the status indicates that the request should be immediately retried, because the status indicates an error of a nature that is likely due to transient conditions on the local system or S3, such as network failures, or internal retryable errors reported by S3. Returns zero otherwise.
status | is the status to evaluate |
S3Status S3_create_request_context | ( | S3RequestContext ** | requestContextReturn | ) |
Request Context Management Functions An S3RequestContext allows muliple requests to be serviced by the same thread simultaneously. It is an optional parameter to all libs3 request functions, and if provided, the request is managed by the S3RequestContext; if not, the request is handled synchronously and is complete when the libs3 request function has returned.
requestContextReturn | returns the newly-created S3RequestContext structure, which if successfully returned, must be destroyed via a call to S3_destroy_request_context when it is no longer needed. If an error status is returned from this function, then requestContextReturn will not have been filled in, and S3_destroy_request_context should not be called on it |
S3Status S3_create_request_context_ex | ( | S3RequestContext ** | requestContextReturn, |
void * | curlMulti, | ||
S3SetupCurlCallback | setupCurlCallback, | ||
void * | setupCurlCallbackData | ||
) |
Extended version of S3_create_request_context used to create S3RequestContext for curl_multi_socket_action CURLM handles that will be managed by libs3 user. This type of handles offer better performance for applications with large number of simultaneous connections. For details, see MULTI_SOCKET chapter here: https://curl.haxx.se/libcurl/c/libcurl-multi.html
In this mode libs3 user will
requestContextReturn | returns the newly-created S3RequestContext structure, which if successfully returned, must be destroyed via a call to S3_destroy_request_context when it is no longer needed. If an error status is returned from this function, then requestContextReturn will not have been filled in, and S3_destroy_request_context should not be called on it |
curlMulti | is the CURLM handle to be associated with this context. |
setupCurlCallback | is an optional callback routine to be invoked by libs3 every time another CURL request is being created for use in this context. |
setupCurlCallbackData | is an opaque data to be passed to setupCurlCallback. |
void S3_destroy_request_context | ( | S3RequestContext * | requestContext | ) |
Destroys an S3RequestContext which was created with S3_create_request_context. Any requests which are currently being processed by the S3RequestContext will immediately be aborted and their request completed callbacks made with the status S3StatusInterrupted.
requestContext | is the S3RequestContext to destroy |
S3Status S3_runall_request_context | ( | S3RequestContext * | requestContext | ) |
Runs the S3RequestContext until all requests within it have completed, or until an error occurs.
requestContext | is the S3RequestContext to run until all requests within it have completed or until an error occurs |
S3Status S3_runonce_request_context | ( | S3RequestContext * | requestContext, |
int * | requestsRemainingReturn | ||
) |
Does some processing of requests within the S3RequestContext. One or more requests may have callbacks made on them and may complete. This function processes any requests which have immediately available I/O, and will not block waiting for I/O on any request. This function would normally be used with S3_get_request_context_fdsets.
requestContext | is the S3RequestContext to process |
requestsRemainingReturn | returns the number of requests remaining and not yet completed within the S3RequestContext after this function returns. |
S3Status S3_process_request_context | ( | S3RequestContext * | requestContext | ) |
Extract and finish requests completed by curl multi handle mechanism in curl_multi_socket_action mode. Should be called by libs3 user when curl_multi_socket_action indicates a change in running_handles.
requestContext | is the S3RequestContext to process |
S3Status S3_get_request_context_fdsets | ( | S3RequestContext * | requestContext, |
fd_set * | readFdSet, | ||
fd_set * | writeFdSet, | ||
fd_set * | exceptFdSet, | ||
int * | maxFd | ||
) |
This function, in conjunction allows callers to manually manage a set of requests using an S3RequestContext. This function returns the set of file descriptors which the caller can watch (typically using select()), along with any other file descriptors of interest to the caller, and using whatever timeout (if any) the caller wishes, until one or more file descriptors in the returned sets become ready for I/O, at which point S3_runonce_request_context can be called to process requests with available I/O.
requestContext | is the S3RequestContext to get fd_sets from |
readFdSet | is a pointer to an fd_set which will have all file descriptors to watch for read events for the requests in the S3RequestContext set into it upon return. Should be zero'd out (using FD_ZERO) before being passed into this function. |
writeFdSet | is a pointer to an fd_set which will have all file descriptors to watch for write events for the requests in the S3RequestContext set into it upon return. Should be zero'd out (using FD_ZERO) before being passed into this function. |
exceptFdSet | is a pointer to an fd_set which will have all file descriptors to watch for exception events for the requests in the S3RequestContext set into it upon return. Should be zero'd out (using FD_ZERO) before being passed into this function. |
maxFd | returns the highest file descriptor set into any of the fd_sets, or -1 if no file descriptors were set |
int64_t S3_get_request_context_timeout | ( | S3RequestContext * | requestContext | ) |
This function returns the maximum number of milliseconds that the caller of S3_runonce_request_context should wait on the fdsets obtained via a call to S3_get_request_context_fdsets. In other words, this is essentially the select() timeout that needs to be used (shorter values are OK, but no longer than this) to ensure that internal timeout code of libs3 can work properly. This function should be called right before select() each time select() on the request_context fdsets are to be performed by the libs3 user.
requestContext | is the S3RequestContext to get the timeout from |
void S3_set_request_context_verify_peer | ( | S3RequestContext * | requestContext, |
int | verifyPeer | ||
) |
This function enables SSL peer certificate verification on a per-request context basis. If this is called, the context's value of verifyPeer will be used when processing requests. Otherwise, the default set by the flags to S3_initialize() are used.
requestContext | the S3RequestContext to set the verifyPeer flag on. |
verifyPeer | a boolean value indicating whether to verify the peer certificate or not. |
S3Status S3_generate_authenticated_query_string | ( | char * | buffer, |
const S3BucketContext * | bucketContext, | ||
const char * | key, | ||
int | expires, | ||
const char * | resource, | ||
const char * | httpMethod | ||
) |
S3 Utility Functions Generates an HTTP authenticated query string, which may then be used by a browser (or other web client) to issue the request. The request is implicitly a GET request; Amazon S3 is documented to only support this type of authenticated query string request.
buffer | is the output buffer for the authenticated query string. It must be at least S3_MAX_AUTHENTICATED_QUERY_STRING_SIZE bytes in length. |
bucketContext | gives the bucket and associated parameters for the request to generate. |
key | gives the key which the authenticated request will GET. |
expires | gives the number of seconds since Unix epoch for the expiration date of the request; after this time, the request will no longer be valid. If this value is negative, the largest expiration interval possible is used (one week). |
resource | gives a sub-resource to be fetched for the request, or NULL for none. This should be of the form "?<resource>", i.e. "?torrent". |
httpMethod | the HTTP request method that will be used with the generated query string (e.g. "GET"). |
void S3_list_service | ( | S3Protocol | protocol, |
const char * | accessKeyId, | ||
const char * | secretAccessKey, | ||
const char * | securityToken, | ||
const char * | hostName, | ||
const char * | authRegion, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
const S3ListServiceHandler * | handler, | ||
void * | callbackData | ||
) |
Service Functions Lists all S3 buckets belonging to the access key id.
protocol | gives the protocol to use for this request |
accessKeyId | gives the Amazon Access Key ID for which to list owned buckets |
secretAccessKey | gives the Amazon Secret Access Key for which to list owned buckets |
securityToken | gives the security token used to generate the Temporary Security Credentials |
hostName | is the S3 host name to use; if NULL is passed in, the default S3 host as provided to S3_initialize() will be used. |
authRegion | is the AWS region to use for the authorization signature |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_test_bucket | ( | S3Protocol | protocol, |
S3UriStyle | uriStyle, | ||
const char * | accessKeyId, | ||
const char * | secretAccessKey, | ||
const char * | securityToken, | ||
const char * | hostName, | ||
const char * | bucketName, | ||
const char * | authRegion, | ||
int | locationConstraintReturnSize, | ||
char * | locationConstraintReturn, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
const S3ResponseHandler * | handler, | ||
void * | callbackData | ||
) |
Bucket Functions Tests the existence of an S3 bucket, additionally returning the bucket's location if it exists and is accessible.
protocol | gives the protocol to use for this request |
uriStyle | gives the URI style to use for this request |
accessKeyId | gives the Amazon Access Key ID for which to list owned buckets |
secretAccessKey | gives the Amazon Secret Access Key for which to list owned buckets |
securityToken | gives the security token used to generate the Temporary Security Credentials |
hostName | is the S3 host name to use; if NULL is passed in, the default S3 host as provided to S3_initialize() will be used. |
bucketName | is the bucket name to test |
authRegion | is the AWS region to use for the authorization signature |
locationConstraintReturnSize | gives the number of bytes in the locationConstraintReturn parameter |
locationConstraintReturn | provides the location into which to write the name of the location constraint naming the geographic location of the S3 bucket. This must have at least as many characters in it as specified by locationConstraintReturn, and should start out NULL-terminated. On successful completion of this request, this will be set to the name of the geographic location of S3 bucket, or will be left as a zero-length string if no location was available. |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_create_bucket | ( | S3Protocol | protocol, |
const char * | accessKeyId, | ||
const char * | secretAccessKey, | ||
const char * | securityToken, | ||
const char * | hostName, | ||
const char * | bucketName, | ||
const char * | authRegion, | ||
S3CannedAcl | cannedAcl, | ||
const char * | locationConstraint, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
const S3ResponseHandler * | handler, | ||
void * | callbackData | ||
) |
Creates a new bucket.
protocol | gives the protocol to use for this request |
accessKeyId | gives the Amazon Access Key ID for which to list owned buckets |
secretAccessKey | gives the Amazon Secret Access Key for which to list owned buckets |
securityToken | gives the security token used to generate the Temporary Security Credentials |
hostName | is the S3 host name to use; if NULL is passed in, the default S3 host as provided to S3_initialize() will be used. |
bucketName | is the name of the bucket to be created |
authRegion | is the AWS region to use for the authorization signature |
cannedAcl | gives the "REST canned ACL" to use for the created bucket |
locationConstraint | if non-NULL, gives the geographic location for the bucket to create. |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_delete_bucket | ( | S3Protocol | protocol, |
S3UriStyle | uriStyle, | ||
const char * | accessKeyId, | ||
const char * | secretAccessKey, | ||
const char * | securityToken, | ||
const char * | hostName, | ||
const char * | bucketName, | ||
const char * | authRegion, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
const S3ResponseHandler * | handler, | ||
void * | callbackData | ||
) |
Deletes a bucket. The bucket must be empty, or the status S3StatusErrorBucketNotEmpty will result.
protocol | gives the protocol to use for this request |
uriStyle | gives the URI style to use for this request |
accessKeyId | gives the Amazon Access Key ID for which to list owned buckets |
secretAccessKey | gives the Amazon Secret Access Key for which to list owned buckets |
securityToken | gives the security token used to generate the Temporary Security Credentials |
hostName | is the S3 host name to use; if NULL is passed in, the default S3 host as provided to S3_initialize() will be used. |
bucketName | is the name of the bucket to be deleted |
authRegion | is the AWS region to use for the authorization signature |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_list_bucket | ( | const S3BucketContext * | bucketContext, |
const char * | prefix, | ||
const char * | marker, | ||
const char * | delimiter, | ||
int | maxkeys, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
const S3ListBucketHandler * | handler, | ||
void * | callbackData | ||
) |
Lists keys within a bucket.
bucketContext | gives the bucket and associated parameters for this request |
prefix | if present and non-empty, gives a prefix for matching keys |
marker | if present and non-empty, only keys occuring after this value will be listed |
delimiter | if present and non-empty, causes keys that contain the same string between the prefix and the first occurrence of the delimiter to be rolled up into a single result element |
maxkeys | is the maximum number of keys to return |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_put_object | ( | const S3BucketContext * | bucketContext, |
const char * | key, | ||
uint64_t | contentLength, | ||
const S3PutProperties * | putProperties, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
const S3PutObjectHandler * | handler, | ||
void * | callbackData | ||
) |
Object Functions Puts object data to S3. This overwrites any existing object at that key; note that S3 currently only supports full-object upload. The data to upload will be acquired by calling the handler's putObjectDataCallback.
bucketContext | gives the bucket and associated parameters for this request |
key | is the key of the object to put to |
contentLength | is required and gives the total number of bytes that will be put |
putProperties | optionally provides additional properties to apply to the object that is being put to |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_copy_object | ( | const S3BucketContext * | bucketContext, |
const char * | key, | ||
const char * | destinationBucket, | ||
const char * | destinationKey, | ||
const S3PutProperties * | putProperties, | ||
int64_t * | lastModifiedReturn, | ||
int | eTagReturnSize, | ||
char * | eTagReturn, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
const S3ResponseHandler * | handler, | ||
void * | callbackData | ||
) |
Copies an object from one location to another. The object may be copied back to itself, which is useful for replacing metadata without changing the object.
bucketContext | gives the source bucket and associated parameters for this request |
key | is the source key |
destinationBucket | gives the destination bucket into which to copy the object. If NULL, the source bucket will be used. |
destinationKey | gives the destination key into which to copy the object. If NULL, the source key will be used. |
putProperties | optionally provides properties to apply to the object that is being put to. If not supplied (i.e. NULL is passed in), then the copied object will retain the metadata of the copied object. |
lastModifiedReturn | returns the last modified date of the copied object |
eTagReturnSize | specifies the number of bytes provided in the eTagReturn buffer |
eTagReturn | is a buffer into which the resulting eTag of the copied object will be written |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_copy_object_range | ( | const S3BucketContext * | bucketContext, |
const char * | key, | ||
const char * | destinationBucket, | ||
const char * | destinationKey, | ||
const int | partNo, | ||
const char * | uploadId, | ||
const unsigned long | startOffset, | ||
const unsigned long | count, | ||
const S3PutProperties * | putProperties, | ||
int64_t * | lastModifiedReturn, | ||
int | eTagReturnSize, | ||
char * | eTagReturn, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
const S3ResponseHandler * | handler, | ||
void * | callbackData | ||
) |
Copies portion of an object from one location to another. The object may be copied back to itself, which is useful for replacing metadata without changing the object. Required when doing >5GB object copies.
bucketContext | gives the source bucket and associated parameters for this request |
key | is the source key |
destinationBucket | gives the destination bucket into which to copy the object. If NULL, the source bucket will be used. |
destinationKey | gives the destination key into which to copy the object. If NULL, the source key will be used. |
partNo | is the sequence numebr of any multipart upload, 0 = non-multipart |
uploadId | is the ID returned for a multipart initialize request, ignored if partNo = 0 |
startOffset | is the starting point in original object to copy. |
count | is the number of bytes starting at startOffset in original object to copy. 0 indicates no-range (i.e. all) |
putProperties | optionally provides properties to apply to the object that is being put to. If not supplied (i.e. NULL is passed in), then the copied object will retain the metadata of the copied object. |
lastModifiedReturn | returns the last modified date of the copied object |
eTagReturnSize | specifies the number of bytes provided in the eTagReturn buffer |
eTagReturn | is a buffer into which the resulting eTag of the copied object will be written |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_get_object | ( | const S3BucketContext * | bucketContext, |
const char * | key, | ||
const S3GetConditions * | getConditions, | ||
uint64_t | startByte, | ||
uint64_t | byteCount, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
const S3GetObjectHandler * | handler, | ||
void * | callbackData | ||
) |
Gets an object from S3. The contents of the object are returned in the handler's getObjectDataCallback.
bucketContext | gives the bucket and associated parameters for this request |
key | is the key of the object to get |
getConditions | if non-NULL, gives a set of conditions which must be met in order for the request to succeed |
startByte | gives the start byte for the byte range of the contents to be returned |
byteCount | gives the number of bytes to return; a value of 0 indicates that the contents up to the end should be returned |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_head_object | ( | const S3BucketContext * | bucketContext, |
const char * | key, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
const S3ResponseHandler * | handler, | ||
void * | callbackData | ||
) |
Gets the response properties for the object, but not the object contents.
bucketContext | gives the bucket and associated parameters for this request |
key | is the key of the object to get the properties of |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_delete_object | ( | const S3BucketContext * | bucketContext, |
const char * | key, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
const S3ResponseHandler * | handler, | ||
void * | callbackData | ||
) |
Deletes an object from S3.
bucketContext | gives the bucket and associated parameters for this request |
key | is the key of the object to delete |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_get_acl | ( | const S3BucketContext * | bucketContext, |
const char * | key, | ||
char * | ownerId, | ||
char * | ownerDisplayName, | ||
int * | aclGrantCountReturn, | ||
S3AclGrant * | aclGrants, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
const S3ResponseHandler * | handler, | ||
void * | callbackData | ||
) |
Access Control List Functions Gets the ACL for the given bucket or object.
bucketContext | gives the bucket and associated parameters for this request |
key | is the key of the object to get the ACL of; or NULL to get the ACL of the bucket |
ownerId | must be supplied as a buffer of at least S3_MAX_GRANTEE_USER_ID_SIZE bytes, and will be filled in with the owner ID of the object/bucket |
ownerDisplayName | must be supplied as a buffer of at least S3_MAX_GRANTEE_DISPLAY_NAME_SIZE bytes, and will be filled in with the display name of the object/bucket |
aclGrantCountReturn | returns the number of S3AclGrant structures returned in the aclGrants parameter |
aclGrants | must be passed in as an array of at least S3_MAX_ACL_GRANT_COUNT S3AclGrant structures, which will be filled in with the grant information for the ACL |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_set_acl | ( | const S3BucketContext * | bucketContext, |
const char * | key, | ||
const char * | ownerId, | ||
const char * | ownerDisplayName, | ||
int | aclGrantCount, | ||
const S3AclGrant * | aclGrants, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
const S3ResponseHandler * | handler, | ||
void * | callbackData | ||
) |
Sets the ACL for the given bucket or object.
bucketContext | gives the bucket and associated parameters for this request |
key | is the key of the object to set the ACL for; or NULL to set the ACL for the bucket |
ownerId | is the owner ID of the object/bucket. Unfortunately, S3 requires this to be valid and thus it must have been fetched by a previous S3 request, such as a list_buckets request. |
ownerDisplayName | is the owner display name of the object/bucket. Unfortunately, S3 requires this to be valid and thus it must have been fetched by a previous S3 request, such as a list_buckets request. |
aclGrantCount | is the number of ACL grants to set for the object/bucket |
aclGrants | are the ACL grants to set for the object/bucket |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_get_lifecycle | ( | const S3BucketContext * | bucketContext, |
char * | lifecycleXmlDocumentReturn, | ||
int | lifecycleXmlDocumentBufferSize, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
const S3ResponseHandler * | handler, | ||
void * | callbackData | ||
) |
Lifecycle Control Functions Gets the lifecycle for the given bucket
bucketContext | gives the bucket and associated parameters for this request |
lifecycleXmlDocumentReturn | buffer for lifecycle XML document |
lifecycleXmlDocumentBufferSize | size of the buffer |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_set_lifecycle | ( | const S3BucketContext * | bucketContext, |
const char * | lifecycleXmlDocument, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
const S3ResponseHandler * | handler, | ||
void * | callbackData | ||
) |
Sets the lifecycle for the given bucket
bucketContext | gives the bucket and associated parameters for this request |
lifecycleXmlDocument | Lifecycle configuration as an XML document |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_get_server_access_logging | ( | const S3BucketContext * | bucketContext, |
char * | targetBucketReturn, | ||
char * | targetPrefixReturn, | ||
int * | aclGrantCountReturn, | ||
S3AclGrant * | aclGrants, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
const S3ResponseHandler * | handler, | ||
void * | callbackData | ||
) |
Server Access Log Functions Gets the service access logging settings for a bucket. The service access logging settings specify whether or not the S3 service will write service access logs for requests made for the given bucket, and if so, several settings controlling how these logs will be written.
bucketContext | gives the bucket and associated parameters for this request; this is the bucket for which service access logging is being requested |
targetBucketReturn | must be passed in as a buffer of at least (S3_MAX_BUCKET_NAME_SIZE + 1) bytes in length, and will be filled in with the target bucket name for access logging for the given bucket, which is the bucket into which access logs for the specified bucket will be written. This is returned as an empty string if service access logging is not enabled for the given bucket. |
targetPrefixReturn | must be passed in as a buffer of at least (S3_MAX_KEY_SIZE + 1) bytes in length, and will be filled in with the key prefix for server access logs for the given bucket, or the empty string if no such prefix is specified. |
aclGrantCountReturn | returns the number of ACL grants that are associated with the server access logging for the given bucket. |
aclGrants | must be passed in as an array of at least S3_MAX_ACL_GRANT_COUNT S3AclGrant structures, and these will be filled in with the target grants associated with the server access logging for the given bucket, whose number is returned in the aclGrantCountReturn parameter. These grants will be applied to the ACL of any server access logging log files generated by the S3 service for the given bucket. |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_set_server_access_logging | ( | const S3BucketContext * | bucketContext, |
const char * | targetBucket, | ||
const char * | targetPrefix, | ||
int | aclGrantCount, | ||
const S3AclGrant * | aclGrants, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
const S3ResponseHandler * | handler, | ||
void * | callbackData | ||
) |
Sets the service access logging settings for a bucket. The service access logging settings specify whether or not the S3 service will write service access logs for requests made for the given bucket, and if so, several settings controlling how these logs will be written.
bucketContext | gives the bucket and associated parameters for this request; this is the bucket for which service access logging is being set |
targetBucket | gives the target bucket name for access logging for the given bucket, which is the bucket into which access logs for the specified bucket will be written. |
targetPrefix | is an option parameter which specifies the key prefix for server access logs for the given bucket, or NULL if no such prefix is to be used. |
aclGrantCount | specifies the number of ACL grants that are to be associated with the server access logging for the given bucket. |
aclGrants | is as an array of S3AclGrant structures, whose number is given by the aclGrantCount parameter. These grants will be applied to the ACL of any server access logging log files generated by the S3 service for the given bucket. |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_initiate_multipart | ( | S3BucketContext * | bucketContext, |
const char * | key, | ||
S3PutProperties * | putProperties, | ||
S3MultipartInitialHandler * | handler, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
void * | callbackData | ||
) |
This operation initiates a multipart upload and returns an upload ID. This upload ID is used to associate all the parts in the specific multipart upload. You specify this upload ID in each of your subsequent upload part requests
bucketContext | gives the bucket and associated parameters for this request; this is the bucket for which service access logging is being set |
key | is the source key |
putProperties | optionally provides additional properties to apply to the object that is being put to |
handler | gives the callbacks to call as the request is processed and completed |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_upload_part | ( | S3BucketContext * | bucketContext, |
const char * | key, | ||
S3PutProperties * | putProperties, | ||
S3PutObjectHandler * | handler, | ||
int | seq, | ||
const char * | upload_id, | ||
int | partContentLength, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
void * | callbackData | ||
) |
This operation uploads a part in a multipart upload.
bucketContext | gives the bucket and associated parameters for this request; this is the bucket for which service access logging is being set |
key | is the source key |
putProperties | optionally provides additional properties to apply to the object that is being put to |
handler | gives the callbacks to call as the request is processed and completed |
seq | is a part number uniquely identifies a part and also defines its position within the object being created. |
upload_id | get from S3_initiate_multipart return |
partContentLength | gives the size of the part, in bytes |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_complete_multipart_upload | ( | S3BucketContext * | bucketContext, |
const char * | key, | ||
S3MultipartCommitHandler * | handler, | ||
const char * | upload_id, | ||
int | contentLength, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
void * | callbackData | ||
) |
This operation completes a multipart upload by assembling previously uploaded parts.
bucketContext | gives the bucket and associated parameters for this request; this is the bucket for which service access logging is being set |
key | is the source key |
handler | gives the callbacks to call as the request is processed and completed |
upload_id | get from S3_initiate_multipart return |
contentLength | gives the total size of the commit message, in bytes |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_list_parts | ( | S3BucketContext * | bucketContext, |
const char * | key, | ||
const char * | partnumbermarker, | ||
const char * | uploadid, | ||
const char * | encodingtype, | ||
int | maxparts, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
const S3ListPartsHandler * | handler, | ||
void * | callbackData | ||
) |
This operation lists the parts that have been uploaded for a specific multipart upload.
bucketContext | gives the bucket and associated parameters for this request; this is the bucket for which service access logging is being set |
key | is the source key |
partnumbermarker | if present and non-empty, specifies the part after which listing should begin. Only parts with higher part numbers will be listed. |
uploadid | identifying the multipart upload whose parts are being listed. |
encodingtype | if present and non-empty, requests Amazon S3 to encode the response and specifies the encoding method to use. |
maxparts | Sets the maximum number of parts to return in the response body. Default: 1,000 |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |
void S3_abort_multipart_upload | ( | S3BucketContext * | bucketContext, |
const char * | key, | ||
const char * | uploadId, | ||
int | timeoutMs, | ||
S3AbortMultipartUploadHandler * | handler | ||
) |
This operation aborts a multipart upload. After a multipart upload is aborted, no additional parts can be uploaded using that upload ID.
bucketContext | gives the bucket and associated parameters for this request; this is the bucket for which service access logging is being set |
key | is the source key |
uploadId | identifying the multipart upload whose parts are being listed. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
handler | gives the callbacks to call as the request is processed and completed |
void S3_list_multipart_uploads | ( | S3BucketContext * | bucketContext, |
const char * | prefix, | ||
const char * | keymarker, | ||
const char * | uploadidmarker, | ||
const char * | encodingtype, | ||
const char * | delimiter, | ||
int | maxuploads, | ||
S3RequestContext * | requestContext, | ||
int | timeoutMs, | ||
const S3ListMultipartUploadsHandler * | handler, | ||
void * | callbackData | ||
) |
This operation lists in-progress multipart uploads. An in-progress multipart upload is a multipart upload that has been initiated, using the Initiate Multipart Upload request, but has not yet been completed or aborted.
bucketContext | gives the bucket and associated parameters for this request; this is the bucket for which service access logging is being set |
prefix | if present and non-empty, lists in-progress uploads only for those keys that begin with the specified prefix. |
keymarker | if present and non-empty, together with upload-id-marker, this parameter specifies the multipart upload after which listing should begin. |
uploadidmarker | if present and non-empty, together with key-marker, specifies the multipart upload after which listing should begin. |
encodingtype | if present and non-empty, requests Amazon S3 to encode the response and specifies the encoding method to use. |
delimiter | if present and non-empty, is the character you use to group keys. |
maxuploads | sets the maximum number of multipart uploads, from 1 to 1,000, to return in the response body. |
requestContext | if non-NULL, gives the S3RequestContext to add this request to, and does not perform the request immediately. If NULL, performs the request immediately and synchronously. |
timeoutMs | if not 0 contains total request timeout in milliseconds |
handler | gives the callbacks to call as the request is processed and completed |
callbackData | will be passed in as the callbackData parameter to all callbacks for this request |