path: root/inc/libs3.h

/** **************************************************************************
 * libs3.h
 * 
 * Copyright 2008 Bryan Ischo <bryan@ischo.com>
 * 
 * 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/>.
 *
 ************************************************************************** **/

#ifndef LIBS3_H
#define LIBS3_H

#include <stdint.h>
#include <sys/time.h>


/** **************************************************************************
 * 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()
 *
 * In order to use libs3 with multiple threads, your program must provide
 * threading callbacks to the S3_initialize() function (if your program is
 * single threaded, you can pass NULL for these callback arguments to
 * S3_initialize()).
 *
 * 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.
 * 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
 ************************************************************************** **/

/**
 * This is the hostname that all S3 requests will go through; virtual-host
 * style requests will prepend the bucket name to this host name, and
 * path-style requests will use this hostname directly
 **/
#define S3_HOSTNAME                        "s3.amazonaws.com"


/**
 * S3_MAX_KEY_SIZE is the maximum size of keys that Amazon S3 supports.
 **/
#define S3_MAX_KEY_SIZE                    1024


/**
 * 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_MAX_METADATA_SIZE               2048


/**
 * S3_METADATA_HEADER_NAME_PREFIX is the prefix of an S3 "meta header"
 **/
#define S3_METADATA_HEADER_NAME_PREFIX     "x-amz-meta-"


/**
 * 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_METADATA_COUNT \
    (S3_MAX_METADATA_SIZE / (sizeof(S3_METADATA_HEADER_NAME_PREFIX "nv") - 1))


/**
 * 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_ACL_GRANT_COUNT             100


/**
 * This is the maximum number of characters (including terminating \0) that
 * libs3 supports in an ACL grantee email address.
 **/
#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 user id.
 **/
#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 display name.
 **/
#define S3_MAX_GRANTEE_DISPLAY_NAME_SIZE   128


/** **************************************************************************
 * 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.
 **/
typedef enum
{
    S3StatusOK                                              ,

    /**
     * Errors that prevent the S3 request from being issued or response from
     * being read
     **/
    S3StatusInternalError                                   ,
    S3StatusOutOfMemory                                     ,
    S3StatusInterrupted                                     ,
    S3StatusFailedToCreateMutex                             ,
    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                                 ,
    S3StatusBadAclEmailAddressTooLong                       ,
    S3StatusBadAclUserIdTooLong                             ,
    S3StatusBadAclUserDisplayNameTooLong                    ,
    S3StatusBadAclGroupUriTooLong                           ,
    S3StatusBadAclPermissionTooLong                         ,
    S3StatusTooManyAclGrants                                ,
    S3StatusBadAclGrantee                                   ,
    S3StatusBadAclPermission                                ,
    S3StatusAclXmlDocumentTooLarge                          ,
    S3StatusNameLookupError                                 ,
    S3StatusFailedToConnect                                 ,
    S3StatusServerFailedVerification                        ,
    S3StatusConnectionFailed                                ,
    S3StatusAbortedByCallback                               ,
    
    /**
     * Errors from the S3 service
     **/
    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                                    ,

    /**
     * The following are HTTP errors returned by S3 without enough detail to
     * distinguish any of the above S3StatusError conditions
     **/
    S3StatusHttpErrorMovedTemporarily                       ,
    S3StatusHttpErrorBadRequest                             ,
    S3StatusHttpErrorForbidden                              ,
    S3StatusHttpErrorNotFound                               ,
    S3StatusHttpErrorConflict                               ,
    S3StatusHttpErrorUnknown
} S3Status;


/**
 * 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.
 **/
typedef enum
{
    S3ProtocolHTTPS                     = 0,
    S3ProtocolHTTP                      = 1
} S3Protocol;


/**
 * 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.
 **/
typedef enum
{
    S3UriStyleVirtualHost               = 0,
    S3UriStylePath                      = 1
} S3UriStyle;


/**
 * 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
 **/
typedef enum
{
    S3GranteeTypeAmazonCustomerByEmail  = 0,
    S3GranteeTypeCanonicalUser          = 1,
    S3GranteeTypeAllAwsUsers            = 2,
    S3GranteeTypeAllUsers               = 3
} S3GranteeType;


/**
 * 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
 **/
typedef enum
{
    S3PermissionRead                    = 0,
    S3PermissionWrite                   = 1,
    S3PermissionReadACP                 = 2,
    S3PermissionWriteACP                = 3,
    S3PermissionFullControl             = 4
} S3Permission;


/**
 * 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
 **/
typedef enum
{
    S3CannedAclPrivate                  = 0, /* private */
    S3CannedAclPublicRead               = 1, /* public-read */
    S3CannedAclPublicReadWrite          = 2, /* public-read-write */
    S3CannedAclAuthenticatedRead        = 3  /* authenticated-read */
} S3CannedAcl;


/** **************************************************************************
 * Data Types
 ************************************************************************** **/

/**
 * This is a type which must be defined by the user of the S3 library.  It
 * defines a Mutex type with standard Mutex semantics.
 **/
struct S3Mutex;


/**
 * An S3RequestContext manages multiple S3 requests simultaneously; see the
 * S3_XXX_request_context functions below for details
 **/
typedef struct S3RequestContext S3RequestContext;


/**
 * S3NameValue represents a single Name - Value pair, used to represent either
 * S3 metadata associated with a key, or S3 error details.
 **/
typedef struct S3NameValue
{
    /**
     * The name part of the Name - Value pair
     **/
    const char *name;

    /**
     * The value part of the Name - Value pair
     **/
    const char *value;
} S3NameValue;


/**
 * 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 S3ResponseProperties
{
    /**
     * This optional field identifies the request ID and may be used when
     * reporting problems to Amazon.
     **/
    const char *requestId;

    /**
     * This optional field identifies the request ID and may be used when
     * reporting problems to Amazon.
     **/
    const char *requestId2;

    /**
     * This optional field is the content type of the data which is returned
     * by the request.  If not provided, the default can be assumed to be
     * "binary/octet-stream".
     **/
    const char *contentType;

    /**
     * This optional field is the content length of the data which is returned
     * in the response.  A negative value means that this value was not
     * provided in the response.  A value of 0 means that there is no content
     * provided.  A positive value gives the number of bytes in the content of
     * the response.
     **/
    uint64_t contentLength;

    /**
     * This optional field names the server which serviced the request.
     **/
    const char *server;

    /**
     * This optional field provides a string identifying the unique contents
     * of the resource identified by the request, such that the contents can
     * be assumed not to be changed if the same eTag is returned at a later
     * time decribing the same resource.  This is an MD5 sum of the contents.
     **/
    const char *eTag;

    /**
     * This optional field provides the last modified time, relative to the
     * Unix epoch, of the contents.  If this value is < 0, then the last
     * modified time was not provided in the response.  If this value is >= 0,
     * then the last modified date of the contents are available as a number
     * of seconds since the UNIX epoch.
     * 
     **/
    time_t lastModified;

    /**
     * This is the number of user-provided meta data associated with the
     * resource.
     **/
    int metaDataCount;

    /**
     * These are the meta data associated with the resource.  In each case,
     * the name will not include any S3-specific header prefixes
     * (i.e. x-amz-meta- will have been removed from the beginning), and
     * leading and trailing whitespace will have been stripped from the value.
     **/
    const S3NameValue *metaData;
} S3ResponseProperties;


/**
 * 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 S3AclGrant
{
    /**
     * The granteeType gives the type of grantee specified by this grant.
     **/
    S3GranteeType granteeType;
    /**
     * The identifier of the grantee that is set is determined by the
     * granteeType:
     *
     * S3GranteeTypeAmazonCustomerByEmail - amazonCustomerByEmail.emailAddress
     * S3GranteeTypeCanonicalUser - canonicalUser.id, canonicalUser.displayName
     * S3GranteeTypeAllAwsUsers - none
     * S3GranteeTypeAllUsers - none
     **/
    union
    {
        /**
         * This structure is used iff the granteeType is 
         * S3GranteeTypeAmazonCustomerByEmail.
         **/
        struct
        {
            /**
             * This is the email address of the Amazon Customer being granted
             * permissions by this S3AclGrant.
             **/
            char emailAddress[S3_MAX_GRANTEE_EMAIL_ADDRESS_SIZE];
        } amazonCustomerByEmail;
        /**
         * This structure is used iff the granteeType is
         * S3GranteeTypeCanonicalUser.
         **/
        struct
        {
            /**
             * This is the CanonicalUser ID of the grantee
             **/
            char id[S3_MAX_GRANTEE_USER_ID_SIZE];
            /**
             * This is the display name of the grantee
             **/
            char displayName[S3_MAX_GRANTEE_DISPLAY_NAME_SIZE];
        } canonicalUser;
    } grantee;
    /**
     * This is the S3Permission to be granted to the grantee
     **/
    S3Permission permission;
} S3AclGrant;


/**
 * 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 S3BucketContext
{
    /**
     * The name of the bucket to use in the bucket context
     **/
    const char *bucketName;

    /**
     * The protocol to use when accessing the bucket
     **/
    S3Protocol protocol;

    /**
     * The URI style to use for all URIs sent to Amazon S3 while working with
     * this bucket context
     **/
    S3UriStyle uriStyle;

    /**
     * The Amazon Access Key ID to use for access to the bucket
     **/
    const char *accessKeyId;

    /**
     *  The Amazon Secret Access Key to use for access to the bucket
     **/
    const char *secretAccessKey;
} S3BucketContext;


/**
 * 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 S3ListBucketContent
{
    /**
     * This is the next key in the list bucket results.
     **/
    const char *key;

    /**
     * This is the number of seconds since UNIX epoch of the last modified
     * date of the object identified by the key. 
     **/
    time_t lastModified;

    /**
     * This gives a tag which gives a signature of the contents of the object,
     * which is the MD5 of the contents of the object.
     **/
    const char *eTag;

    /**
     * This is the size of the object in bytes.
     **/
    uint64_t size;

    /**
     * This is the ID of the owner of the key; it is present only if access
     * permissions allow it to be viewed.
     **/
    const char *ownerId;

    /**
     * This is the display name of the owner of the key; it is present only if
     * access permissions allow it to be viewed.
     **/
    const char *ownerDisplayName;
} S3ListBucketContent;


/**
 * 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 S3PutProperties
{
    /**
     * If present, this is the Content-Type that should be associated with the
     * object.  If not provided, S3 defaults to "binary/octet-stream".
     **/
    const char *contentType;

    /**
     * If present, this provides the MD5 signature of the contents, and is
     * used to validate the contents.  This is highly recommended by Amazon
     * but not required.
     **/
    const char *md5;

    /**
     * If present, this gives a Cache-Control header string to be supplied to
     * HTTP clients which download this
     **/
    const char *cacheControl;

    /**
     * If present, this gives the filename to save the downloaded file to,
     * whenever the object is downloaded via a web browser.  This is only
     * relevent for objects which are intended to be shared to users via web
     * browsers and which is additionally intended to be downloaded rather
     * than viewed.
     **/
    const char *contentDispositionFilename;

    /**
     * If present, this identifies the content encoding of the object.  This
     * is only applicable to encoded (usually, compressed) content, and only
     * relevent if the object is intended to be downloaded via a browser.
     **/
    const char *contentEncoding;

    /**
     * If >= 0, this gives an expiration date for the content.  This
     * information is typically only delivered to users who download the
     * content via a web browser.
     **/
    time_t expires;

    /**
     * This identifies the "canned ACL" that should be used for this object.
     * The default (0) gives only the owner of the object access to it.
     **/
    S3CannedAcl cannedAcl;

    /**
     * This is the number of values in the metaData field.
     **/
    int metaDataCount;

    /**
     * These are the meta data to pass to S3.  In each case, the name part of
     * the Name - Value pair should not include any special S3 HTTP header
     * prefix (i.e., should be of the form 'foo', NOT 'x-amz-meta-foo').
     **/
    const S3NameValue *metaData;
} S3PutProperties;


/**
 * S3GetConditions is used for the get_object operation, and specifies
 * conditions which the object must meet in order to be successfully returned.
 **/
typedef struct S3GetConditions
{
    /**
     * The request will be processed if the Last-Modification header of the
     * object is greater than or equal to this value, specified as a number of
     * seconds since Unix epoch.  If this value is less than zero, it will not
     * be used in the conditional.
     **/
    time_t ifModifiedSince;

    /**
     * The request will be processed if the Last-Modification header of the
     * object is less than this value, specified as a number of seconds since
     * Unix epoch.  If this value is less than zero, it will not be used in
     * the conditional.
     **/
    time_t ifNotModifiedSince;

    /**
     * If non-NULL, this gives an eTag header value which the object must
     * match in order to be returned.  Note that altough the eTag is simply an
     * MD5, this must be presented in the S3 eTag form, which typically
     * includes double-quotes.
     **/
    const char *ifMatchETag;

    /**
     * If non-NULL, this gives an eTag header value which the object must not
     * match in order to be returned.  Note that altough the eTag is simply an
     * MD5, this must be presented in the S3 eTag form, which typically
     * includes double-quotes.
     **/
    const char *ifNotMatchETag;
} S3GetConditions;


/**
 * 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 struct S3ErrorDetails
{
    /**
     * This is the human-readable message that Amazon supplied describing the
     * error
     **/
    const char *message;

    /**
     * This identifies the resource for which the error occurred
     **/
    const char *resource;

    /**
     * This gives human-readable further details describing the specifics of
     * this error
     **/
    const char *furtherDetails;

    /**
     * This gives the number of S3NameValue pairs present in the extraDetails
     * array
     **/
    int extraDetailsCount;

    /**
     * S3 can provide extra details in a freeform Name - Value pair format.
     * Each error can have any number of these, and this array provides these
     * additional extra details.
     **/
    S3NameValue *extraDetails;
} S3ErrorDetails;


/** **************************************************************************
 * Callback Signatures
 ************************************************************************** **/

/**
 * This is the signature of a "thread self" callback, that must be provided to
 * the S3_initialize() method, and implemented by the user of the libs3
 * library.  This function returns the thread id of the thread which calls it.
 *
 * @return the thread id of the thread which calls it
 **/
typedef unsigned long (S3ThreadSelfCallback)();


/**
 * This is the signature of a "mutex create" callback, that must be provided
 * to the S3_initialize() method, and implemented by the user of the libs3
 * library.  This function returns a newly-created and initialized S3Mutex
 * structure (itself defined by the libs3 user).
 *
 * @return a newly-created and initialized S3Mutex structure
 **/
typedef struct S3Mutex *(S3MutexCreateCallback)();


/**
 * This is the signature of a "mutex lock" callback, that must be provided to
 * the S3_initialize() method, and implemented by the user of the libs3
 * library.  This function locks a mutex.
 *
 * @param mutex is the S3Mutex to lock
 **/ 
typedef void (S3MutexLockCallback)(struct S3Mutex *mutex);


/**
 * This is the signature of a "mutex unlock" callback, that must be provided
 * to the S3_initialize() method, and implemented by the user of the libs3
 * library.  This function unlocks a mutex.
 *
 * @param mutex is the S3Mutex to unlock
 **/ 
typedef void (S3MutexUnlockCallback)(struct S3Mutex *mutex);


/**
 * This is the signature of a "mutex destroy" callback, that must be provided
 * to the S3_initialize() method, and implemented by the user of the libs3
 * library.  This function destroys a mutex previously created by a call to
 * S3MutexCreateCallback().
 *
 * @param mutex is the S3Mutex to destroy
 **/ 
typedef void (S3MutexDestroyCallback)(struct S3Mutex *mutex);


/**
 * This callback is made whenever the response properties become available for
 * any request.
 *
 * @param properties are the properties that are available from the response
 * @param callbackData is the callback data as specified when the request
 *        was issued.
 * @return 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 (S3ResponsePropertiesCallback)
    (const S3ResponseProperties *properties, 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.
 *
 * @param 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.
 * @param errorDetails if non-NULL, gives details as returned by the S3
 *        service, describing the error
 * @param 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 for each bucket resulting from a list service
 * operation.
 *
 * @param ownerId is the ID of the owner of the bucket
 * @param ownerDisplayName is the owner display name of the owner of the bucket
 * @param bucketName is the name of the bucket
 * @param 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
 * @param callbackData is the callback data as specified when the request
 *        was issued.
 * @return 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 (S3ListServiceCallback)(const char *ownerId, 
                                         const char *ownerDisplayName,
                                         const char *bucketName,
                                         time_t creationDateSeconds,
                                         void *callbackData);


/**
 * This callback is made once for each object resulting from a list bucket
 * operation.
 *
 * @param 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
 * @param 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
 * @param contentsCount is the number of ListBucketContent structures in the
 *        contents parameter
 * @param contents is an array of ListBucketContent structures, each one
 *        describing an object in the bucket
 * @param commonPrefixesCount is the number of common prefixes strings in the
 *        commonPrefixes parameter
 * @param commonPrefixes is an array of strings, each specifing one of the
 *        common prefixes as returned by S3
 * @param callbackData is the callback data as specified when the request
 *        was issued.
 * @return 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 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.
 *
 * @param bufferSize gives the maximum number of bytes that may be written
 *        into the buffer parameter by this callback
 * @param 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
 * @param callbackData is the callback data as specified when the request
 *        was issued.
 * @return < 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 int (S3PutObjectDataCallback)(int bufferSize, 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.
 *
 * @param bufferSize gives the number of bytes in buffer
 * @param buffer is the data being passed into the callback
 * @param callbackData is the callback data as specified when the request
 *        was issued.
 * @return 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 (S3GetObjectDataCallback)(int bufferSize, const char *buffer,
                                           void *callbackData);
                                       

/** **************************************************************************
 * Callback Structures
 ************************************************************************** **/


/**
 * An S3ResponseHandler defines the callbacks which are made for any
 * request.
 **/
typedef struct S3ResponseHandler
{
    /**
     * The propertiesCallback is made when the response properties have
     * successfully been returned from S3.  This function may not be called
     * if the response properties were not successfully returned from S3.
     **/
    S3ResponsePropertiesCallback *propertiesCallback;
    
    /**
     * The completeCallback is always called for every request made to S3,
     * regardless of the outcome of the request.  It provides the status of
     * the request upon its completion, as well as extra error details in the
     * event of an S3 error.
     **/
    S3ResponseCompleteCallback *completeCallback;
} S3ResponseHandler;


/**
 * An S3ListServiceHandler defines the callbacks which are made for
 * list_service requests.
 **/
typedef struct S3ListServiceHandler
{
    /**
     * responseHandler provides the properties and complete callback
     **/
    S3ResponseHandler responseHandler;

    /**
     * The listServiceCallback is called as items are reported back from S3 as
     * responses to the request
     **/
    S3ListServiceCallback *listServiceCallback;
} S3ListServiceHandler;


/**
 * An S3ListBucketHandler defines the callbacks which are made for
 * list_bucket requests.
 **/
typedef struct S3ListBucketHandler
{
    /**
     * responseHandler provides the properties and complete callback
     **/
    S3ResponseHandler responseHandler;

    /**
     * The listBucketCallback is called as items are reported back from S3 as
     * responses to the request
     **/
    S3ListBucketCallback *listBucketCallback;
} S3ListBucketHandler;


/**
 * An S3PutObjectHandler defines the callbacks which are made for
 * put_object requests.
 **/
typedef struct S3PutObjectHandler
{
    /**
     * responseHandler provides the properties and complete callback
     **/
    S3ResponseHandler responseHandler;

    /**
     * The putObjectDataCallback is called to acquire data to send to S3 as
     * the contents of the put_object request.  It is made repeatedly until it
     * returns a negative number (indicating that the request should be
     * aborted), or 0 (indicating that all data has been supplied).
     **/
    S3PutObjectDataCallback *putObjectDataCallback;
} S3PutObjectHandler;


/**
 * An S3GetObjectHandler defines the callbacks which are made for
 * get_object requests.
 **/
typedef struct S3GetObjectHandler
{
    /**
     * responseHandler provides the properties and complete callback
     **/
    S3ResponseHandler responseHandler;

    /**
     * The getObjectDataCallback is called as data is read from S3 as the
     * contents of the object being read in the get_object request.  It is
     * called repeatedly until there is no more data provided in the request,
     * or until the callback returns an error status indicating that the
     * request should be aborted.
     **/
    S3GetObjectDataCallback *getObjectDataCallback;
} S3GetObjectHandler;


/** **************************************************************************
 * General Library Functions
 ************************************************************************** **/

/**
 * Initializes libs3 for use.  This function must be called before any other
 * libs3 function is called.  It must be called once and only once before
 * S3_deinitialize() is called.
 *
 * @param 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.
 * @param threadSelfCallback provides the callback for the S3 library to call
 *        to identify the calling thread, or NULL if the caller is not a
 *        multithreaded program.
 * @param mutexCreateCallback provides the callback for the S3 library to call
 *        to create a mutex, or NULL if the caller is not a multithreaded
 *        program.
 * @param mutexLockCallback provides the callback for the S3 library to call
 *        to lock a mutex, or NULL if the caller is not a multithreaded
 *        program.
 * @param mutexUnlockCallback provides the callback for the S3 library to call
 *        to unlock a mutex, or NULL if the caller is not a multithreaded
 *        program.
 * @param mutexDestroyCallback provides the callback for the S3 library to
 *        call to destroy a mutex, or NULL if the caller is not a
 *        multithreaded program.
 * @return One of:
 *         S3StatusOK on success
 *         S3StatusOutOfMemory on failure due to out of memory
 *         S3StatusFailedToCreateMutex if the mutex creation function returned
 *             NULL for one of the mutexes that are created during the
 *             initialization process 
 **/
S3Status S3_initialize(const char *userAgentInfo,
                       S3ThreadSelfCallback *threadSelfCallback,
                       S3MutexCreateCallback *mutexCreateCallback,
                       S3MutexLockCallback *mutexLockCallback,
                       S3MutexUnlockCallback *mutexUnlockCallback,
                       S3MutexDestroyCallback *mutexDestroyCallback);


/**
 * 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().
 **/
void S3_deinitialize();


/**
 * Returns a string with the textual name of an S3Status code
 *
 * @param status is S3Status code for which the textual name will be returned
 * @return a string with the textual name of an S3Status code
 **/
const char *S3_get_status_name(S3Status status);


/**
 * 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.
 *
 * @param bucketName is the bucket name to validate
 * @param uriStyle gives the URI style to validate the bucket name against.
 *        It is advisable to always use S3UriStyleVirtuallHost.
 * @return 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_validate_bucket_name(const char *bucketName, S3UriStyle uriStyle);


/**
 * 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.
 *
 * @param aclXml is the XML representation of the ACL.  This must be a
 *        zero-terminated character string.
 * @param 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.
 * @param 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.
 * @param aclGrantCountReturn returns the number of S3AclGrant structures
 *        returned in the aclGrantsReturned array
 * @param 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.
 * @return 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
 **/
S3Status S3_convert_acl(char *aclXml, char *ownerId, char *ownerDisplayName,
                        int *aclGrantCountReturn, S3AclGrant *aclGrants);
                        

/**
 * 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.
 *
 * @param status is the status to evaluate
 * @return nonzero if the status indicates a retryable error, 0 otherwise
 **/
int S3_status_is_retryable(S3Status status);


/** **************************************************************************
 * 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.
 *
 * @param 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
 * @return 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
 **/
S3Status S3_create_request_context(S3RequestContext **requestContextReturn);


/**
 * 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.
 *
 * @param requestContext is the S3RequestContext to destroy
 **/
void S3_destroy_request_context(S3RequestContext *requestContext);


/**
 * Runs the S3RequestContext until all requests within it have completed,
 * or until an error occurs.
 *
 * @param requestContext is the S3RequestContext to run until all requests
 *            within it have completed or until an error occurs
 * @return 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_runall_request_context(S3RequestContext *requestContext);


/**
 * 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.
 *
 * @param requestContext is the S3RequestContext to process
 * @param requestsRemainingReturn returns the number of requests remaining
 *            and not yet completed within the S3RequestContext after this
 *            function returns.
 * @return 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_runonce_request_context(S3RequestContext *requestContext, 
                                    int *requestsRemainingReturn);


/**
 * 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.
 *
 * @param requestContext is the S3RequestContext to get fd_sets from
 * @param 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.
 * @param 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.
 * @param 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.
 * @param maxFd returns the highest file descriptor set into any of the
 *        fd_sets, or -1 if no file descriptors were set
 * @return One of:
 *         S3StatusOK if all fd_sets were successfully set
 *         S3StatusInternalError if an internal error prevented this function
 *             from completing successfully
 **/
S3Status S3_get_request_context_fdsets(S3RequestContext *requestContext,
                                       fd_set *readFdSet, fd_set *writeFdSet,
                                       fd_set *exceptFdSet, int *maxFd);


/** **************************************************************************
 * Service Functions
 ************************************************************************** **/

/**
 * Lists all S3 buckets belonging to the access key id.
 *
 * @param protocol gives the protocol to use for this request
 * @param accessKeyId gives the Amazon Access Key ID for which to list owned
 *        buckets
 * @param secretAccessKey gives the Amazon Secret Access Key for which to list
 *        owned buckets
 * @param 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.
 * @param handler gives the callbacks to call as the request is processed and
 *        completed 
 * @param callbackData will be passed in as the callbackData parameter to
 *        all callbacks for this request
 **/
void S3_list_service(S3Protocol protocol, const char *accessKeyId,
                     const char *secretAccessKey,
                     S3RequestContext *requestContext,
                     const S3ListServiceHandler *handler,
                     void *callbackData);
                         
                            
/** **************************************************************************
 * Bucket Functions
 ************************************************************************** **/

/**
 * Tests the existence of an S3 bucket, additionally returning the bucket's
 * location if it exists and is accessible.
 *
 * @param protocol gives the protocol to use for this request
 * @param uriStyle gives the URI style to use for this request
 * @param accessKeyId gives the Amazon Access Key ID for which to list owned
 *        buckets
 * @param secretAccessKey gives the Amazon Secret Access Key for which to list
 *        owned buckets
 * @param bucketName is the bucket name to test
 * @param locationConstraintReturnSize gives the number of bytes in the
 *        locationConstraintReturn parameter
 * @param 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.
 * @param 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.
 * @param handler gives the callbacks to call as the request is processed and
 *        completed 
 * @param 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 *bucketName, int locationConstraintReturnSize,
                    char *locationConstraintReturn,
                    S3RequestContext *requestContext,
                    const S3ResponseHandler *handler, void *callbackData);

                           
/**
 * Creates a new bucket.
 *
 * @param protocol gives the protocol to use for this request
 * @param accessKeyId gives the Amazon Access Key ID for which to list owned
 *        buckets
 * @param secretAccessKey gives the Amazon Secret Access Key for which to list
 *        owned buckets
 * @param bucketName is the name of the bucket to be created
 * @param cannedAcl gives the "REST canned ACL" to use for the created bucket
 * @param locationConstraint if non-NULL, gives the geographic location for
 *        the bucket to create.
 * @param 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.
 * @param handler gives the callbacks to call as the request is processed and
 *        completed 
 * @param 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 *bucketName, 
                      S3CannedAcl cannedAcl, const char *locationConstraint,
                      S3RequestContext *requestContext,
                      const S3ResponseHandler *handler, void *callbackData);


/**
 * Deletes a bucket.  The bucket must be empty, or the status
 * S3StatusErrorBucketNotEmpty will result.
 *
 * @param protocol gives the protocol to use for this request
 * @param uriStyle gives the URI style to use for this request
 * @param accessKeyId gives the Amazon Access Key ID for which to list owned
 *        buckets
 * @param secretAccessKey gives the Amazon Secret Access Key for which to list
 *        owned buckets
 * @param bucketName is the name of the bucket to be deleted
 * @param 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.
 * @param handler gives the callbacks to call as the request is processed and
 *        completed 
 * @param 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 *bucketName, S3RequestContext *requestContext,
                      const S3ResponseHandler *handler, void *callbackData);


/**
 * Lists keys within a bucket.
 *
 * @param bucketContext gives the bucket and associated parameters for this
 *        request
 * @param prefix if present, gives a prefix for matching keys
 * @param marker if present, only keys occuring after this value will be
 *        listed
 * @param 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
 * @param maxkeys is the maximum number of keys to return
 * @param 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.
 * @param handler gives the callbacks to call as the request is processed and
 *        completed 
 * @param 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);


/** **************************************************************************
 * 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.
 *
 * @param bucketContext gives the bucket and associated parameters for this
 *        request
 * @param key is the key of the object to put to
 * @param contentLength is required and gives the total number of bytes that
 *        will be put
 * @param putProperties optionally provides additional properties to apply to
 *        the object that is being put to
 * @param 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.
 * @param handler gives the callbacks to call as the request is processed and
 *        completed 
 * @param 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);
                        

/**
 * 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.
 *
 * @param bucketContext gives the source bucket and associated parameters for
 *        this request
 * @param key is the source key
 * @param destinationBucket gives the destination bucket into which to copy
 *        the object.  If NULL, the source bucket will be used.
 * @param destinationKey gives the destination key into which to copy the
 *        object.  If NULL, the source key will be used.
 * @param 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.
 * @param lastModifiedReturn returns the last modified date of the copied
 *        object
 * @param eTagReturnSize specifies the number of bytes provided in the
 *        eTagReturn buffer
 * @param eTagReturn is a buffer into which the resulting eTag of the copied
 *        object will be written
 * @param handler gives the callbacks to call as the request is processed and
 *        completed 
 * @param callbackData will be passed in as the callbackData parameter to
 *        all callbacks for this request
 * @param 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.
 * @param handler gives the callbacks to call as the request is processed and
 *        completed 
 * @param 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,
                    time_t *lastModifiedReturn, int eTagReturnSize,
                    char *eTagReturn, S3RequestContext *requestContext,
                    const S3ResponseHandler *handler, void *callbackData);


/**
 * Gets an object from S3.  The contents of the object are returned in the
 * handler's getObjectDataCallback.
 *
 * @param bucketContext gives the bucket and associated parameters for this
 *        request
 * @param key is the key of the object to get
 * @param getConditions if non-NULL, gives a set of conditions which must be
 *        met in order for the request to succeed
 * @param startByte gives the start byte for the byte range of the contents
 *        to be returned
 * @param byteCount gives the number of bytes to return; a value of 0
 *        indicates that the contents up to the end should be returned
 * @param 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.
 * @param handler gives the callbacks to call as the request is processed and
 *        completed 
 * @param 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 the response properties for the object, but not the object contents.
 *
 * @param bucketContext gives the bucket and associated parameters for this
 *        request
 * @param key is the key of the object to get the properties of
 * @param 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.
 * @param handler gives the callbacks to call as the request is processed and
 *        completed 
 * @param 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);
                         
/**
 * Deletes an object from S3.
 *
 * @param bucketContext gives the bucket and associated parameters for this
 *        request
 * @param key is the key of the object to delete
 * @param 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.
 * @param handler gives the callbacks to call as the request is processed and
 *        completed 
 * @param 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);


/** **************************************************************************
 * Access Control List Functions
 ************************************************************************** **/

/**
 * Gets the ACL for the given bucket or object.
 *
 * @param bucketContext gives the bucket and associated parameters for this
 *        request
 * @param key is the key of the object to get the ACL of; or NULL to get the
 *        ACL of the bucket
 * @param 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
 * @param 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
 * @param aclGrantCountReturn returns the number of S3AclGrant structures
 *        returned in the aclGrants parameter
 * @param 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
 * @param 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.
 * @param handler gives the callbacks to call as the request is processed and
 *        completed 
 * @param 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);


/**
 * Sets the ACL for the given bucket or object.
 *
 * @param bucketContext gives the bucket and associated parameters for this
 *        request
 * @param key is the key of the object to set the ACL for; or NULL to set the
 *        ACL for the bucket
 * @param 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.
 * @param 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.
 * @param aclGrantCount is the number of ACL grants to set for the
 *        object/bucket
 * @param aclGrants are the ACL grants to set for the object/bucket
 * @param 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.
 * @param handler gives the callbacks to call as the request is processed and
 *        completed 
 * @param 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);


/**
 * xxx todo
 * Service Logging ...
 **/


/**
 * xxx todo
 * function for generating an HTTP authenticated query string
 **/


/**
 * xxx todo
 * functions for generating form stuff for posting to s3
 **/


#endif /* LIBS3_H */