libs3
trunk
|
#include <stdint.h>
#include <sys/select.h>
Go to the source code of this file.
Classes | |
struct | S3NameValue |
struct | S3ResponseProperties |
struct | S3AclGrant |
struct | S3BucketContext |
struct | S3ListBucketContent |
struct | S3PutProperties |
struct | S3GetConditions |
struct | S3ErrorDetails |
struct | S3ResponseHandler |
struct | S3ListServiceHandler |
struct | S3ListBucketHandler |
struct | S3PutObjectHandler |
struct | S3GetObjectHandler |
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_ALL (S3_INIT_WINSOCK) |
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 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 struct S3ResponseHandler | S3ResponseHandler |
typedef struct S3ListServiceHandler | S3ListServiceHandler |
typedef struct S3ListBucketHandler | S3ListBucketHandler |
typedef struct S3PutObjectHandler | S3PutObjectHandler |
typedef struct S3GetObjectHandler | S3GetObjectHandler |
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) |
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_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) |
S3Status | S3_generate_authenticated_query_string (char *buffer, const S3BucketContext *bucketContext, const char *key, int64_t expires, const char *resource) |
void | S3_list_service (S3Protocol protocol, const char *accessKeyId, const char *secretAccessKey, const char *hostName, S3RequestContext *requestContext, const S3ListServiceHandler *handler, void *callbackData) |
void | S3_test_bucket (S3Protocol protocol, S3UriStyle uriStyle, const char *accessKeyId, const char *secretAccessKey, const char *hostName, const char *bucketName, int locationConstraintReturnSize, char *locationConstraintReturn, S3RequestContext *requestContext, const S3ResponseHandler *handler, void *callbackData) |
void | S3_create_bucket (S3Protocol protocol, const char *accessKeyId, const char *secretAccessKey, const char *hostName, const char *bucketName, S3CannedAcl cannedAcl, const char *locationConstraint, S3RequestContext *requestContext, const S3ResponseHandler *handler, void *callbackData) |
void | S3_delete_bucket (S3Protocol protocol, S3UriStyle uriStyle, const char *accessKeyId, const char *secretAccessKey, const char *hostName, const char *bucketName, S3RequestContext *requestContext, 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, const S3ListBucketHandler *handler, void *callbackData) |
void | S3_put_object (const S3BucketContext *bucketContext, const char *key, uint64_t contentLength, const S3PutProperties *putProperties, S3RequestContext *requestContext, 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, 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, const S3GetObjectHandler *handler, void *callbackData) |
void | S3_head_object (const S3BucketContext *bucketContext, const char *key, S3RequestContext *requestContext, const S3ResponseHandler *handler, void *callbackData) |
void | S3_delete_object (const S3BucketContext *bucketContext, const char *key, S3RequestContext *requestContext, 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, 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, const S3ResponseHandler *handler, void *callbackData) |
void | S3_get_server_access_logging (const S3BucketContext *bucketContext, char *targetBucketReturn, char *targetPrefixReturn, int *aclGrantCountReturn, S3AclGrant *aclGrants, S3RequestContext *requestContext, 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, const S3ResponseHandler *handler, void *callbackData) |
#define S3_MAX_HOSTNAME_SIZE 255 |
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 General Public License as published by the Free Software Foundation, version 3 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 General Public License version 3 along with libs3, in a file named COPYING. If not, see http://www.gnu.org/licenses/. **************************************************************************
This library provides an API for using Amazon's S3 service (see http://s3.amazonaws.com). Its design goals are:
The general usage pattern of libs3 is:
All functions which send requests to S3 return their results via a set of callback functions which must be supplied to libs3 at the time that the request is initiated. libs3 will call these functions back in the thread calling the libs3 function if blocking requests are made (i.e., if the S3RequestContext for the function invocation is passed in as NULL). If an S3RequestContext is used to drive multiple S3 requests simultaneously, then the callbacks will be made from the thread which calls S3_runall_request_context() or S3_runonce_request_context(), or possibly from the thread which calls S3_destroy_request_context(), if S3 requests are in progress at the time that this function is called.
NOTE: Response headers from Amazon S3 are limited to 4K (2K of metas is all that Amazon supports, and libs3 allows Amazon an additional 2K of headers).
NOTE: Because HTTP and the S3 REST protocol are highly under-specified, libs3 must make some assumptions about the maximum length of certain HTTP elements (such as headers) that it will accept. While efforts have been made to enforce maximums which are beyond that expected to be needed by any user of S3, it is always possible that these maximums may be too low in some rare circumstances. Bug reports should this unlikely situation occur would be most appreciated.
#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_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.
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 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 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.
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 |
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 |
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_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 |
S3Status S3_generate_authenticated_query_string | ( | char * | buffer, |
const S3BucketContext * | bucketContext, | ||
const char * | key, | ||
int64_t | expires, | ||
const char * | resource | ||
) |
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 date possible is used (currently, Jan 19, 2038). |
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". |
void S3_list_service | ( | S3Protocol | protocol, |
const char * | accessKeyId, | ||
const char * | secretAccessKey, | ||
const char * | hostName, | ||
S3RequestContext * | requestContext, | ||
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 |
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. |
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. |
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 * | hostName, | ||
const char * | bucketName, | ||
int | locationConstraintReturnSize, | ||
char * | locationConstraintReturn, | ||
S3RequestContext * | requestContext, | ||
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 |
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 |
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. |
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 * | hostName, | ||
const char * | bucketName, | ||
S3CannedAcl | cannedAcl, | ||
const char * | locationConstraint, | ||
S3RequestContext * | requestContext, | ||
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 |
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 |
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. |
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 * | hostName, | ||
const char * | bucketName, | ||
S3RequestContext * | requestContext, | ||
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 |
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 |
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. |
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, | ||
const S3ListBucketHandler * | handler, | ||
void * | callbackData | ||
) |
Lists keys within a bucket.
bucketContext | gives the bucket and associated parameters for this request |
prefix | if present, gives a prefix for matching keys |
marker | if present, only keys occuring after this value will be listed |
delimiter | if present, 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. |
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, | ||
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. |
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, | ||
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. |
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, | ||
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. |
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, | ||
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. |
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, | ||
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. |
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, | ||
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. |
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, | ||
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. |
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, | ||
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. |
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, | ||
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. |
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 |