libs3.h

Go to the documentation of this file.

#ifndef LIBS3_H
#define LIBS3_H

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


#ifdef __cplusplus
extern "C" {
#endif


#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 \
    (sizeof("https:///") + S3_MAX_HOSTNAME_SIZE + (S3_MAX_KEY_SIZE * 3) + \
     sizeof("?AWSAccessKeyId=") + 32 + sizeof("&Expires=") + 32 + \
     sizeof("&Signature=") + 28 + 1)


#define S3_INIT_WINSOCK                    1


#define S3_INIT_ALL                        (S3_INIT_WINSOCK)


typedef enum
{
    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
} S3Status;


typedef enum
{
    S3ProtocolHTTPS                     = 0,
    S3ProtocolHTTP                      = 1
} S3Protocol;


typedef enum
{
    S3UriStyleVirtualHost               = 0,
    S3UriStylePath                      = 1
} S3UriStyle;


typedef enum
{
    S3GranteeTypeAmazonCustomerByEmail  = 0,
    S3GranteeTypeCanonicalUser          = 1,
    S3GranteeTypeAllAwsUsers            = 2,
    S3GranteeTypeAllUsers               = 3,
    S3GranteeTypeLogDelivery            = 4
} S3GranteeType;


typedef enum
{
    S3PermissionRead                    = 0,
    S3PermissionWrite                   = 1,
    S3PermissionReadACP                 = 2,
    S3PermissionWriteACP                = 3,
    S3PermissionFullControl             = 4
} S3Permission;


typedef enum
{
    S3CannedAclPrivate                  = 0, /* private */
    S3CannedAclPublicRead               = 1, /* public-read */
    S3CannedAclPublicReadWrite          = 2, /* public-read-write */
    S3CannedAclAuthenticatedRead        = 3  /* authenticated-read */
} S3CannedAcl;


typedef struct S3RequestContext S3RequestContext;


typedef struct S3NameValue
{
    const char *name;

    const char *value;
} S3NameValue;


typedef struct S3ResponseProperties
{
    const char *requestId;

    const char *requestId2;

    const char *contentType;

    uint64_t contentLength;

    const char *server;

    const char *eTag;

    int64_t lastModified;

    int metaDataCount;

    const S3NameValue *metaData;
} S3ResponseProperties;


typedef struct S3AclGrant
{
    S3GranteeType granteeType;
    union
    {
        struct
        {
            char emailAddress[S3_MAX_GRANTEE_EMAIL_ADDRESS_SIZE];
        } amazonCustomerByEmail;
        struct
        {
            char id[S3_MAX_GRANTEE_USER_ID_SIZE];
            char displayName[S3_MAX_GRANTEE_DISPLAY_NAME_SIZE];
        } canonicalUser;
    } grantee;
    S3Permission permission;
} S3AclGrant;


typedef struct S3BucketContext
{
    const char *hostName;

    const char *bucketName;

    S3Protocol protocol;

    S3UriStyle uriStyle;

    const char *accessKeyId;

    const char *secretAccessKey;
} S3BucketContext;


typedef struct S3ListBucketContent
{
    const char *key;

    int64_t lastModified;

    const char *eTag;

    uint64_t size;

    const char *ownerId;

    const char *ownerDisplayName;
} S3ListBucketContent;


typedef struct S3PutProperties
{
    const char *contentType;

    const char *md5;

    const char *cacheControl;

    const char *contentDispositionFilename;

    const char *contentEncoding;

    int64_t expires;

    S3CannedAcl cannedAcl;

    int metaDataCount;

    const S3NameValue *metaData;
} S3PutProperties;


typedef struct S3GetConditions
{
    int64_t ifModifiedSince;

    int64_t ifNotModifiedSince;

    const char *ifMatchETag;

    const char *ifNotMatchETag;
} S3GetConditions;


typedef struct S3ErrorDetails
{
    const char *message;

    const char *resource;

    const char *furtherDetails;

    int extraDetailsCount;

    S3NameValue *extraDetails;
} S3ErrorDetails;


typedef S3Status (S3ResponsePropertiesCallback)
    (const S3ResponseProperties *properties, void *callbackData);


typedef void (S3ResponseCompleteCallback)(S3Status status,
                                          const S3ErrorDetails *errorDetails,
                                          void *callbackData);

                                    
typedef S3Status (S3ListServiceCallback)(const char *ownerId, 
                                         const char *ownerDisplayName,
                                         const char *bucketName,
                                         int64_t creationDateSeconds,
                                         void *callbackData);


typedef S3Status (S3ListBucketCallback)(int isTruncated,
                                        const char *nextMarker,
                                        int contentsCount, 
                                        const S3ListBucketContent *contents,
                                        int commonPrefixesCount,
                                        const char **commonPrefixes,
                                        void *callbackData);
                                       

typedef int (S3PutObjectDataCallback)(int bufferSize, char *buffer,
                                      void *callbackData);


typedef S3Status (S3GetObjectDataCallback)(int bufferSize, const char *buffer,
                                           void *callbackData);
                                       

typedef struct S3ResponseHandler
{
    S3ResponsePropertiesCallback *propertiesCallback;
    
    S3ResponseCompleteCallback *completeCallback;
} S3ResponseHandler;


typedef struct S3ListServiceHandler
{
    S3ResponseHandler responseHandler;

    S3ListServiceCallback *listServiceCallback;
} S3ListServiceHandler;


typedef struct S3ListBucketHandler
{
    S3ResponseHandler responseHandler;

    S3ListBucketCallback *listBucketCallback;
} S3ListBucketHandler;


typedef struct S3PutObjectHandler
{
    S3ResponseHandler responseHandler;

    S3PutObjectDataCallback *putObjectDataCallback;
} S3PutObjectHandler;


typedef struct S3GetObjectHandler
{
    S3ResponseHandler responseHandler;

    S3GetObjectDataCallback *getObjectDataCallback;
} S3GetObjectHandler;


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);
                                  

#ifdef __cplusplus
}
#endif

#endif /* LIBS3_H */