libs3  trunk
libs3.h File Reference
#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 S3StatusS3ResponsePropertiesCallback )(const S3ResponseProperties *properties, void *callbackData)
 
typedef void( S3ResponseCompleteCallback )(S3Status status, const S3ErrorDetails *errorDetails, void *callbackData)
 
typedef S3StatusS3ListServiceCallback )(const char *ownerId, const char *ownerDisplayName, const char *bucketName, int64_t creationDateSeconds, void *callbackData)
 
typedef S3StatusS3ListBucketCallback )(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 S3StatusS3GetObjectDataCallback )(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
 

Enumerations

enum  S3Status {
  S3StatusOK, S3StatusInternalError, S3StatusOutOfMemory, S3StatusInterrupted,
  S3StatusInvalidBucketNameTooLong, S3StatusInvalidBucketNameFirstCharacter, S3StatusInvalidBucketNameCharacter, S3StatusInvalidBucketNameCharacterSequence,
  S3StatusInvalidBucketNameTooShort, S3StatusInvalidBucketNameDotQuadNotation, S3StatusQueryParamsTooLong, S3StatusFailedToInitializeRequest,
  S3StatusMetaDataHeadersTooLong, S3StatusBadMetaData, S3StatusBadContentType, S3StatusContentTypeTooLong,
  S3StatusBadMD5, S3StatusMD5TooLong, S3StatusBadCacheControl, S3StatusCacheControlTooLong,
  S3StatusBadContentDispositionFilename, S3StatusContentDispositionFilenameTooLong, S3StatusBadContentEncoding, S3StatusContentEncodingTooLong,
  S3StatusBadIfMatchETag, S3StatusIfMatchETagTooLong, S3StatusBadIfNotMatchETag, S3StatusIfNotMatchETagTooLong,
  S3StatusHeadersTooLong, S3StatusKeyTooLong, S3StatusUriTooLong, S3StatusXmlParseFailure,
  S3StatusEmailAddressTooLong, S3StatusUserIdTooLong, S3StatusUserDisplayNameTooLong, S3StatusGroupUriTooLong,
  S3StatusPermissionTooLong, S3StatusTargetBucketTooLong, S3StatusTargetPrefixTooLong, S3StatusTooManyGrants,
  S3StatusBadGrantee, S3StatusBadPermission, S3StatusXmlDocumentTooLarge, S3StatusNameLookupError,
  S3StatusFailedToConnect, S3StatusServerFailedVerification, S3StatusConnectionFailed, S3StatusAbortedByCallback,
  S3StatusErrorAccessDenied, S3StatusErrorAccountProblem, S3StatusErrorAmbiguousGrantByEmailAddress, S3StatusErrorBadDigest,
  S3StatusErrorBucketAlreadyExists, S3StatusErrorBucketAlreadyOwnedByYou, S3StatusErrorBucketNotEmpty, S3StatusErrorCredentialsNotSupported,
  S3StatusErrorCrossLocationLoggingProhibited, S3StatusErrorEntityTooSmall, S3StatusErrorEntityTooLarge, S3StatusErrorExpiredToken,
  S3StatusErrorIncompleteBody, S3StatusErrorIncorrectNumberOfFilesInPostRequest, S3StatusErrorInlineDataTooLarge, S3StatusErrorInternalError,
  S3StatusErrorInvalidAccessKeyId, S3StatusErrorInvalidAddressingHeader, S3StatusErrorInvalidArgument, S3StatusErrorInvalidBucketName,
  S3StatusErrorInvalidDigest, S3StatusErrorInvalidLocationConstraint, S3StatusErrorInvalidPayer, S3StatusErrorInvalidPolicyDocument,
  S3StatusErrorInvalidRange, S3StatusErrorInvalidSecurity, S3StatusErrorInvalidSOAPRequest, S3StatusErrorInvalidStorageClass,
  S3StatusErrorInvalidTargetBucketForLogging, S3StatusErrorInvalidToken, S3StatusErrorInvalidURI, S3StatusErrorKeyTooLong,
  S3StatusErrorMalformedACLError, S3StatusErrorMalformedXML, S3StatusErrorMaxMessageLengthExceeded, S3StatusErrorMaxPostPreDataLengthExceededError,
  S3StatusErrorMetadataTooLarge, S3StatusErrorMethodNotAllowed, S3StatusErrorMissingAttachment, S3StatusErrorMissingContentLength,
  S3StatusErrorMissingSecurityElement, S3StatusErrorMissingSecurityHeader, S3StatusErrorNoLoggingStatusForKey, S3StatusErrorNoSuchBucket,
  S3StatusErrorNoSuchKey, S3StatusErrorNotImplemented, S3StatusErrorNotSignedUp, S3StatusErrorOperationAborted,
  S3StatusErrorPermanentRedirect, S3StatusErrorPreconditionFailed, S3StatusErrorRedirect, S3StatusErrorRequestIsNotMultiPartContent,
  S3StatusErrorRequestTimeout, S3StatusErrorRequestTimeTooSkewed, S3StatusErrorRequestTorrentOfBucketError, S3StatusErrorSignatureDoesNotMatch,
  S3StatusErrorSlowDown, S3StatusErrorTemporaryRedirect, S3StatusErrorTokenRefreshRequired, S3StatusErrorTooManyBuckets,
  S3StatusErrorUnexpectedContent, S3StatusErrorUnresolvableGrantByEmailAddress, S3StatusErrorUserKeyMustBeSpecified, S3StatusErrorUnknown,
  S3StatusHttpErrorMovedTemporarily, S3StatusHttpErrorBadRequest, S3StatusHttpErrorForbidden, S3StatusHttpErrorNotFound,
  S3StatusHttpErrorConflict, S3StatusHttpErrorUnknown
}
 
enum  S3Protocol { S3ProtocolHTTPS = 0, S3ProtocolHTTP = 1 }
 
enum  S3UriStyle { S3UriStyleVirtualHost = 0, S3UriStylePath = 1 }
 
enum  S3GranteeType {
  S3GranteeTypeAmazonCustomerByEmail = 0, S3GranteeTypeCanonicalUser = 1, S3GranteeTypeAllAwsUsers = 2, S3GranteeTypeAllUsers = 3,
  S3GranteeTypeLogDelivery = 4
}
 
enum  S3Permission {
  S3PermissionRead = 0, S3PermissionWrite = 1, S3PermissionReadACP = 2, S3PermissionWriteACP = 3,
  S3PermissionFullControl = 4
}
 
enum  S3CannedAcl { S3CannedAclPrivate = 0, S3CannedAclPublicRead = 1, S3CannedAclPublicReadWrite = 2, S3CannedAclAuthenticatedRead = 3 }
 

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)
 

Macro Definition Documentation

#define S3_MAX_HOSTNAME_SIZE   255

libs3.h

Copyright 2008 Bryan Ischo bryan.nosp@m.@isc.nosp@m.ho.co.nosp@m.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/. **************************************************************************

Overview

This library provides an API for using Amazon's S3 service (see http://s3.amazonaws.com). Its design goals are:

  • To provide a simple and straightforward API for accessing all of S3's functionality
  • To not require the developer using libs3 to need to know anything about:
    • HTTP
    • XML
    • SSL In other words, this API is meant to stand on its own, without requiring any implicit knowledge of how S3 services are accessed using HTTP protocols.
  • To be usable from multithreaded code
  • To be usable by code which wants to process multiple S3 requests simultaneously from a single thread
  • To be usable in the simple, straightforward way using sequentialized blocking requests

The general usage pattern of libs3 is:

  • Initialize libs3 once per program by calling S3_initialize() at program start up time
  • Make any number of requests to S3 for getting, putting, or listing S3 buckets or objects, or modifying the ACLs associated with buckets or objects, using one of three general approaches:
    1. Simple blocking requests, one at a time
    2. Multiple threads each making simple blocking requests
    3. From a single thread, managing multiple S3 requests simultaneously using file descriptors and a select()/poll() loop
  • Shut down libs3 at program exit time by calling S3_deinitialize()

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.

Threading Rules

  1. All arguments passed to any function must not be modified directly until the function returns.
  2. All S3RequestContext and S3Request arguments passed to all functions may not be passed to any other libs3 function by any other thread until the function returns.
  3. All functions may be called simultaneously by multiple threads as long as (1) and (2) are observed, EXCEPT for S3_initialize(), which must be called from one thread at a time only.
  4. All callbacks will be made in the thread of the caller of the function which invoked them, so the caller of all libs3 functions should not hold locks that it would try to re-acquire in a callback, as this may deadlock. ************************************************************************** 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
Value:
(sizeof("https:///") + S3_MAX_HOSTNAME_SIZE + (S3_MAX_KEY_SIZE * 3) + \
sizeof("?AWSAccessKeyId=") + 32 + sizeof("&Expires=") + 32 + \
sizeof("&Signature=") + 28 + 1)

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 Documentation


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.

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.

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.

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.

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.

S3GetConditions is used for the get_object operation, and specifies conditions which the object must meet in order to be successfully returned.

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.

Parameters
propertiesare the properties that are available from the response
callbackDatais the callback data as specified when the request was issued.
Returns
S3StatusOK to continue processing the request, anything else to immediately abort the request with a status which will be passed to the S3ResponseCompleteCallback for this request. Typically, this will return either S3StatusOK or S3StatusAbortedByCallback.
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.

Parameters
statusgives 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.
errorDetailsif non-NULL, gives details as returned by the S3 service, describing the error
callbackDatais 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.

Parameters
ownerIdis the ID of the owner of the bucket
ownerDisplayNameis the owner display name of the owner of the bucket
bucketNameis the name of the bucket
creationDateSecondsif < 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
callbackDatais the callback data as specified when the request was issued.
Returns
S3StatusOK to continue processing the request, anything else to immediately abort the request with a status which will be passed to the S3ResponseCompleteCallback for this request. Typically, this will return either S3StatusOK or S3StatusAbortedByCallback.
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.

Parameters
isTruncatedis 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
nextMarkerif 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
contentsCountis the number of ListBucketContent structures in the contents parameter
contentsis an array of ListBucketContent structures, each one describing an object in the bucket
commonPrefixesCountis the number of common prefixes strings in the commonPrefixes parameter
commonPrefixesis an array of strings, each specifing one of the common prefixes as returned by S3
callbackDatais the callback data as specified when the request was issued.
Returns
S3StatusOK to continue processing the request, anything else to immediately abort the request with a status which will be passed to the S3ResponseCompleteCallback for this request. Typically, this will return either S3StatusOK or S3StatusAbortedByCallback.
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.

Parameters
bufferSizegives the maximum number of bytes that may be written into the buffer parameter by this callback
buffergives 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
callbackDatais the callback data as specified when the request was issued.
Returns
< 0 to abort the request with the S3StatusAbortedByCallback, which will be pased to the response complete callback for this request, or 0 to indicate the end of data, or > 0 to identify the number of bytes that were written into the buffer by this callback
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.

Parameters
bufferSizegives the number of bytes in buffer
bufferis the data being passed into the callback
callbackDatais the callback data as specified when the request was issued.
Returns
S3StatusOK to continue processing the request, anything else to immediately abort the request with a status which will be passed to the S3ResponseCompleteCallback for this request. Typically, this will return either S3StatusOK or S3StatusAbortedByCallback.

Callback Structures An S3ResponseHandler defines the callbacks which are made for any request.

An S3ListServiceHandler defines the callbacks which are made for list_service requests.

An S3ListBucketHandler defines the callbacks which are made for list_bucket requests.

An S3PutObjectHandler defines the callbacks which are made for put_object requests.

An S3GetObjectHandler defines the callbacks which are made for get_object requests.

Enumeration Type Documentation

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.

Enumerator:
S3StatusOK 
S3StatusInternalError 

Errors that prevent the S3 request from being issued or response from being read

S3StatusOutOfMemory 
S3StatusInterrupted 
S3StatusInvalidBucketNameTooLong 
S3StatusInvalidBucketNameFirstCharacter 
S3StatusInvalidBucketNameCharacter 
S3StatusInvalidBucketNameCharacterSequence 
S3StatusInvalidBucketNameTooShort 
S3StatusInvalidBucketNameDotQuadNotation 
S3StatusQueryParamsTooLong 
S3StatusFailedToInitializeRequest 
S3StatusMetaDataHeadersTooLong 
S3StatusBadMetaData 
S3StatusBadContentType 
S3StatusContentTypeTooLong 
S3StatusBadMD5 
S3StatusMD5TooLong 
S3StatusBadCacheControl 
S3StatusCacheControlTooLong 
S3StatusBadContentDispositionFilename 
S3StatusContentDispositionFilenameTooLong 
S3StatusBadContentEncoding 
S3StatusContentEncodingTooLong 
S3StatusBadIfMatchETag 
S3StatusIfMatchETagTooLong 
S3StatusBadIfNotMatchETag 
S3StatusIfNotMatchETagTooLong 
S3StatusHeadersTooLong 
S3StatusKeyTooLong 
S3StatusUriTooLong 
S3StatusXmlParseFailure 
S3StatusEmailAddressTooLong 
S3StatusUserIdTooLong 
S3StatusUserDisplayNameTooLong 
S3StatusGroupUriTooLong 
S3StatusPermissionTooLong 
S3StatusTargetBucketTooLong 
S3StatusTargetPrefixTooLong 
S3StatusTooManyGrants 
S3StatusBadGrantee 
S3StatusBadPermission 
S3StatusXmlDocumentTooLarge 
S3StatusNameLookupError 
S3StatusFailedToConnect 
S3StatusServerFailedVerification 
S3StatusConnectionFailed 
S3StatusAbortedByCallback 
S3StatusErrorAccessDenied 

Errors from the S3 service

S3StatusErrorAccountProblem 
S3StatusErrorAmbiguousGrantByEmailAddress 
S3StatusErrorBadDigest 
S3StatusErrorBucketAlreadyExists 
S3StatusErrorBucketAlreadyOwnedByYou 
S3StatusErrorBucketNotEmpty 
S3StatusErrorCredentialsNotSupported 
S3StatusErrorCrossLocationLoggingProhibited 
S3StatusErrorEntityTooSmall 
S3StatusErrorEntityTooLarge 
S3StatusErrorExpiredToken 
S3StatusErrorIncompleteBody 
S3StatusErrorIncorrectNumberOfFilesInPostRequest 
S3StatusErrorInlineDataTooLarge 
S3StatusErrorInternalError 
S3StatusErrorInvalidAccessKeyId 
S3StatusErrorInvalidAddressingHeader 
S3StatusErrorInvalidArgument 
S3StatusErrorInvalidBucketName 
S3StatusErrorInvalidDigest 
S3StatusErrorInvalidLocationConstraint 
S3StatusErrorInvalidPayer 
S3StatusErrorInvalidPolicyDocument 
S3StatusErrorInvalidRange 
S3StatusErrorInvalidSecurity 
S3StatusErrorInvalidSOAPRequest 
S3StatusErrorInvalidStorageClass 
S3StatusErrorInvalidTargetBucketForLogging 
S3StatusErrorInvalidToken 
S3StatusErrorInvalidURI 
S3StatusErrorKeyTooLong 
S3StatusErrorMalformedACLError 
S3StatusErrorMalformedXML 
S3StatusErrorMaxMessageLengthExceeded 
S3StatusErrorMaxPostPreDataLengthExceededError 
S3StatusErrorMetadataTooLarge 
S3StatusErrorMethodNotAllowed 
S3StatusErrorMissingAttachment 
S3StatusErrorMissingContentLength 
S3StatusErrorMissingSecurityElement 
S3StatusErrorMissingSecurityHeader 
S3StatusErrorNoLoggingStatusForKey 
S3StatusErrorNoSuchBucket 
S3StatusErrorNoSuchKey 
S3StatusErrorNotImplemented 
S3StatusErrorNotSignedUp 
S3StatusErrorOperationAborted 
S3StatusErrorPermanentRedirect 
S3StatusErrorPreconditionFailed 
S3StatusErrorRedirect 
S3StatusErrorRequestIsNotMultiPartContent 
S3StatusErrorRequestTimeout 
S3StatusErrorRequestTimeTooSkewed 
S3StatusErrorRequestTorrentOfBucketError 
S3StatusErrorSignatureDoesNotMatch 
S3StatusErrorSlowDown 
S3StatusErrorTemporaryRedirect 
S3StatusErrorTokenRefreshRequired 
S3StatusErrorTooManyBuckets 
S3StatusErrorUnexpectedContent 
S3StatusErrorUnresolvableGrantByEmailAddress 
S3StatusErrorUserKeyMustBeSpecified 
S3StatusErrorUnknown 
S3StatusHttpErrorMovedTemporarily 

The following are HTTP errors returned by S3 without enough detail to distinguish any of the above S3StatusError conditions

S3StatusHttpErrorBadRequest 
S3StatusHttpErrorForbidden 
S3StatusHttpErrorNotFound 
S3StatusHttpErrorConflict 
S3StatusHttpErrorUnknown 
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 

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 

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 

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 

Function Documentation

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.

Parameters
userAgentInfois 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.
flagsis 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.

Parameters
defaultS3Hostnameis 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.
Returns
One of: S3StatusOK on success S3StatusUriTooLong if the defaultS3HostName is longer than S3_MAX_HOSTNAME_SIZE S3StatusInternalError if dependent libraries could not be initialized S3StatusOutOfMemory on failure due to out of memory
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

Parameters
statusis S3Status code for which the textual name will be returned
Returns
a string with the textual name of an S3Status code
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.

Parameters
bucketNameis the bucket name to validate
uriStylegives the URI style to validate the bucket name against. It is advisable to always use S3UriStyleVirtuallHost.
Returns
One of: S3StatusOK if the bucket name was validates successfully S3StatusInvalidBucketNameTooLong if the bucket name exceeded the length limitation for the URI style, which is 255 bytes for path style URIs and 63 bytes for virtual host type URIs S3StatusInvalidBucketNameTooShort if the bucket name is less than 3 characters S3StatusInvalidBucketNameFirstCharacter if the bucket name as an invalid first character, which is anything other than an alphanumeric character S3StatusInvalidBucketNameCharacterSequence if the bucket name includes an invalid character sequence, which for virtual host style buckets is ".-" or "-." S3StatusInvalidBucketNameCharacter if the bucket name includes an invalid character, which is anything other than alphanumeric, '-', '.', or for path style URIs only, '_'. S3StatusInvalidBucketNameDotQuadNotation if the bucket name is in dot-quad notation, i.e. the form of an IP address, which is not allowed by Amazon S3.
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.

Parameters
aclXmlis the XML representation of the ACL. This must be a zero-terminated character string.
ownerIdwill 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.
ownerDisplayNamewill 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.
aclGrantCountReturnreturns the number of S3AclGrant structures returned in the aclGrantsReturned array
aclGrantsmust 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.
Returns
One of: S3StatusOK on successful conversion of the ACL S3StatusInternalError on internal error representing a bug in the libs3 library S3StatusXmlParseFailure if the XML document was malformed
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.

Parameters
statusis the status to evaluate
Returns
nonzero if the status indicates a retryable error, 0 otherwise
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.

Parameters
requestContextReturnreturns 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
Returns
One of: S3StatusOK if the request context was successfully created S3StatusOutOfMemory if the request context could not be created due to an out of memory error
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.

Parameters
requestContextis 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.

Parameters
requestContextis the S3RequestContext to run until all requests within it have completed or until an error occurs
Returns
One of: S3Status if all requests were successfully run to completion S3StatusInternalError if an internal error prevented the S3RequestContext from running one or more requests S3StatusOutOfMemory if requests could not be run to completion due to an out of memory error
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.

Parameters
requestContextis the S3RequestContext to process
requestsRemainingReturnreturns the number of requests remaining and not yet completed within the S3RequestContext after this function returns.
Returns
One of: S3StatusOK if request processing proceeded without error S3StatusInternalError if an internal error prevented the S3RequestContext from running one or more requests S3StatusOutOfMemory if requests could not be processed due to an out of memory error
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.

Parameters
requestContextis the S3RequestContext to get fd_sets from
readFdSetis 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.
writeFdSetis 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.
exceptFdSetis 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.
maxFdreturns the highest file descriptor set into any of the fd_sets, or -1 if no file descriptors were set
Returns
One of: S3StatusOK if all fd_sets were successfully set S3StatusInternalError if an internal error prevented this function from completing successfully
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.

Parameters
requestContextis the S3RequestContext to get the timeout from
Returns
the maximum number of milliseconds to select() on fdsets. Callers could wait a shorter time if they wish, but not longer.
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.

Parameters
bufferis the output buffer for the authenticated query string. It must be at least S3_MAX_AUTHENTICATED_QUERY_STRING_SIZE bytes in length.
bucketContextgives the bucket and associated parameters for the request to generate.
keygives the key which the authenticated request will GET.
expiresgives 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).
resourcegives a sub-resource to be fetched for the request, or NULL for none. This should be of the form "?<resource>", i.e. "?torrent".
Returns
One of: S3StatusUriTooLong if, due to an internal error, the generated URI is longer than S3_MAX_AUTHENTICATED_QUERY_STRING_SIZE bytes in length and thus will not fit into the supplied buffer S3StatusOK on success
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.

Parameters
protocolgives the protocol to use for this request
accessKeyIdgives the Amazon Access Key ID for which to list owned buckets
secretAccessKeygives the Amazon Secret Access Key for which to list owned buckets
hostNameis the S3 host name to use; if NULL is passed in, the default S3 host as provided to S3_initialize() will be used.
requestContextif 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.
handlergives the callbacks to call as the request is processed and completed
callbackDatawill 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.

Parameters
protocolgives the protocol to use for this request
uriStylegives the URI style to use for this request
accessKeyIdgives the Amazon Access Key ID for which to list owned buckets
secretAccessKeygives the Amazon Secret Access Key for which to list owned buckets
hostNameis the S3 host name to use; if NULL is passed in, the default S3 host as provided to S3_initialize() will be used.
bucketNameis the bucket name to test
locationConstraintReturnSizegives the number of bytes in the locationConstraintReturn parameter
locationConstraintReturnprovides 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.
requestContextif 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.
handlergives the callbacks to call as the request is processed and completed
callbackDatawill 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.

Parameters
protocolgives the protocol to use for this request
accessKeyIdgives the Amazon Access Key ID for which to list owned buckets
secretAccessKeygives the Amazon Secret Access Key for which to list owned buckets
hostNameis the S3 host name to use; if NULL is passed in, the default S3 host as provided to S3_initialize() will be used.
bucketNameis the name of the bucket to be created
cannedAclgives the "REST canned ACL" to use for the created bucket
locationConstraintif non-NULL, gives the geographic location for the bucket to create.
requestContextif 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.
handlergives the callbacks to call as the request is processed and completed
callbackDatawill 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.

Parameters
protocolgives the protocol to use for this request
uriStylegives the URI style to use for this request
accessKeyIdgives the Amazon Access Key ID for which to list owned buckets
secretAccessKeygives the Amazon Secret Access Key for which to list owned buckets
hostNameis the S3 host name to use; if NULL is passed in, the default S3 host as provided to S3_initialize() will be used.
bucketNameis the name of the bucket to be deleted
requestContextif 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.
handlergives the callbacks to call as the request is processed and completed
callbackDatawill 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.

Parameters
bucketContextgives the bucket and associated parameters for this request
prefixif present, gives a prefix for matching keys
markerif present, only keys occuring after this value will be listed
delimiterif 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
maxkeysis the maximum number of keys to return
requestContextif 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.
handlergives the callbacks to call as the request is processed and completed
callbackDatawill 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.

Parameters
bucketContextgives the bucket and associated parameters for this request
keyis the key of the object to put to
contentLengthis required and gives the total number of bytes that will be put
putPropertiesoptionally provides additional properties to apply to the object that is being put to
requestContextif 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.
handlergives the callbacks to call as the request is processed and completed
callbackDatawill 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.

Parameters
bucketContextgives the source bucket and associated parameters for this request
keyis the source key
destinationBucketgives the destination bucket into which to copy the object. If NULL, the source bucket will be used.
destinationKeygives the destination key into which to copy the object. If NULL, the source key will be used.
putPropertiesoptionally 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.
lastModifiedReturnreturns the last modified date of the copied object
eTagReturnSizespecifies the number of bytes provided in the eTagReturn buffer
eTagReturnis a buffer into which the resulting eTag of the copied object will be written
handlergives the callbacks to call as the request is processed and completed
callbackDatawill be passed in as the callbackData parameter to all callbacks for this request
requestContextif 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.
handlergives the callbacks to call as the request is processed and completed
callbackDatawill 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.

Parameters
bucketContextgives the bucket and associated parameters for this request
keyis the key of the object to get
getConditionsif non-NULL, gives a set of conditions which must be met in order for the request to succeed
startBytegives the start byte for the byte range of the contents to be returned
byteCountgives the number of bytes to return; a value of 0 indicates that the contents up to the end should be returned
requestContextif 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.
handlergives the callbacks to call as the request is processed and completed
callbackDatawill 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.

Parameters
bucketContextgives the bucket and associated parameters for this request
keyis the key of the object to get the properties of
requestContextif 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.
handlergives the callbacks to call as the request is processed and completed
callbackDatawill 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.

Parameters
bucketContextgives the bucket and associated parameters for this request
keyis the key of the object to delete
requestContextif 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.
handlergives the callbacks to call as the request is processed and completed
callbackDatawill 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.

Parameters
bucketContextgives the bucket and associated parameters for this request
keyis the key of the object to get the ACL of; or NULL to get the ACL of the bucket
ownerIdmust 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
ownerDisplayNamemust 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
aclGrantCountReturnreturns the number of S3AclGrant structures returned in the aclGrants parameter
aclGrantsmust 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
requestContextif 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.
handlergives the callbacks to call as the request is processed and completed
callbackDatawill 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.

Parameters
bucketContextgives the bucket and associated parameters for this request
keyis the key of the object to set the ACL for; or NULL to set the ACL for the bucket
ownerIdis 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.
ownerDisplayNameis 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.
aclGrantCountis the number of ACL grants to set for the object/bucket
aclGrantsare the ACL grants to set for the object/bucket
requestContextif 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.
handlergives the callbacks to call as the request is processed and completed
callbackDatawill 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.

Parameters
bucketContextgives the bucket and associated parameters for this request; this is the bucket for which service access logging is being requested
targetBucketReturnmust 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.
targetPrefixReturnmust 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.
aclGrantCountReturnreturns the number of ACL grants that are associated with the server access logging for the given bucket.
aclGrantsmust 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.
requestContextif 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.
handlergives the callbacks to call as the request is processed and completed
callbackDatawill 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.

Parameters
bucketContextgives the bucket and associated parameters for this request; this is the bucket for which service access logging is being set
targetBucketgives 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.
targetPrefixis 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.
aclGrantCountspecifies the number of ACL grants that are to be associated with the server access logging for the given bucket.
aclGrantsis 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.
requestContextif 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.
handlergives the callbacks to call as the request is processed and completed
callbackDatawill be passed in as the callbackData parameter to all callbacks for this request