Ignore lockmem executable.
[bluesky.git] / libs3-1.4 / inc / libs3.h
1 /** **************************************************************************
2  * libs3.h
3  * 
4  * Copyright 2008 Bryan Ischo <bryan@ischo.com>
5  * 
6  * This file is part of libs3.
7  * 
8  * libs3 is free software: you can redistribute it and/or modify it under the
9  * terms of the GNU General Public License as published by the Free Software
10  * Foundation, version 3 of the License.
11  *
12  * In addition, as a special exception, the copyright holders give
13  * permission to link the code of this library and its programs with the
14  * OpenSSL library, and distribute linked combinations including the two.
15  *
16  * libs3 is distributed in the hope that it will be useful, but WITHOUT ANY
17  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
18  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
19  * details.
20  *
21  * You should have received a copy of the GNU General Public License version 3
22  * along with libs3, in a file named COPYING.  If not, see
23  * <http://www.gnu.org/licenses/>.
24  *
25  ************************************************************************** **/
26
27 #ifndef LIBS3_H
28 #define LIBS3_H
29
30 #include <stdint.h>
31 #include <sys/select.h>
32
33
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37
38
39 /** **************************************************************************
40  * Overview
41  * --------
42  *
43  * This library provides an API for using Amazon's S3 service (see
44  * http://s3.amazonaws.com).  Its design goals are:
45  *
46  * - To provide a simple and straightforward API for accessing all of S3's
47  *   functionality
48  * - To not require the developer using libs3 to need to know anything about:
49  *     - HTTP
50  *     - XML
51  *     - SSL
52  *   In other words, this API is meant to stand on its own, without requiring
53  *   any implicit knowledge of how S3 services are accessed using HTTP
54  *   protocols.
55  * - To be usable from multithreaded code
56  * - To be usable by code which wants to process multiple S3 requests
57  *   simultaneously from a single thread
58  * - To be usable in the simple, straightforward way using sequentialized
59  *   blocking requests
60  *
61  * The general usage pattern of libs3 is:
62  *
63  * - Initialize libs3 once per program by calling S3_initialize() at program
64  *   start up time
65  * - Make any number of requests to S3 for getting, putting, or listing
66  *   S3 buckets or objects, or modifying the ACLs associated with buckets
67  *   or objects, using one of three general approaches:
68  *   1. Simple blocking requests, one at a time
69  *   2. Multiple threads each making simple blocking requests
70  *   3. From a single thread, managing multiple S3 requests simultaneously
71  *      using file descriptors and a select()/poll() loop
72  * - Shut down libs3 at program exit time by calling S3_deinitialize()
73  *
74  * All functions which send requests to S3 return their results via a set of
75  * callback functions which must be supplied to libs3 at the time that the
76  * request is initiated.  libs3 will call these functions back in the thread
77  * calling the libs3 function if blocking requests are made (i.e., if the
78  * S3RequestContext for the function invocation is passed in as NULL).
79  * If an S3RequestContext is used to drive multiple S3 requests
80  * simultaneously, then the callbacks will be made from the thread which
81  * calls S3_runall_request_context() or S3_runonce_request_context(), or
82  * possibly from the thread which calls S3_destroy_request_context(), if
83  * S3 requests are in progress at the time that this function is called.
84  *
85  * NOTE: Response headers from Amazon S3 are limited to 4K (2K of metas is all
86  * that Amazon supports, and libs3 allows Amazon an additional 2K of headers).
87  *
88  * NOTE: Because HTTP and the S3 REST protocol are highly under-specified,
89  * libs3 must make some assumptions about the maximum length of certain HTTP
90  * elements (such as headers) that it will accept.  While efforts have been
91  * made to enforce maximums which are beyond that expected to be needed by any
92  * user of S3, it is always possible that these maximums may be too low in
93  * some rare circumstances.  Bug reports should this unlikely situation occur
94  * would be most appreciated.
95  * 
96  * Threading Rules
97  * ---------------
98  * 
99  * 1. All arguments passed to any function must not be modified directly until
100  *    the function returns.
101  * 2. All S3RequestContext and S3Request arguments passed to all functions may
102  *    not be passed to any other libs3 function by any other thread until the
103  *    function returns.
104  * 3. All functions may be called simultaneously by multiple threads as long
105  *    as (1) and (2) are observed, EXCEPT for S3_initialize(), which must be
106  *    called from one thread at a time only.
107  * 4. All callbacks will be made in the thread of the caller of the function
108  *    which invoked them, so the caller of all libs3 functions should not hold
109  *    locks that it would try to re-acquire in a callback, as this may
110  *    deadlock.
111  ************************************************************************** **/
112
113
114 /** **************************************************************************
115  * Constants
116  ************************************************************************** **/
117
118 /**
119  * This is the hostname that all S3 requests will go through; virtual-host
120  * style requests will prepend the bucket name to this host name, and
121  * path-style requests will use this hostname directly
122  **/
123 #define S3_HOSTNAME                        "s3.amazonaws.com"
124
125
126 /**
127  * S3_MAX_BUCKET_NAME_SIZE is the maximum size of a bucket name.
128  **/
129
130 #define S3_MAX_BUCKET_NAME_SIZE            255
131
132 /**
133  * S3_MAX_KEY_SIZE is the maximum size of keys that Amazon S3 supports.
134  **/
135 #define S3_MAX_KEY_SIZE                    1024
136
137
138 /**
139  * S3_MAX_METADATA_SIZE is the maximum number of bytes allowed for
140  * x-amz-meta header names and values in any request passed to Amazon S3
141  **/
142 #define S3_MAX_METADATA_SIZE               2048
143
144
145 /**
146  * S3_METADATA_HEADER_NAME_PREFIX is the prefix of an S3 "meta header"
147  **/
148 #define S3_METADATA_HEADER_NAME_PREFIX     "x-amz-meta-"
149
150
151 /**
152  * S3_MAX_METADATA_COUNT is the maximum number of x-amz-meta- headers that
153  * could be included in a request to S3.  The smallest meta header is
154  * "x-amz-meta-n: v".  Since S3 doesn't count the ": " against the total, the
155  * smallest amount of data to count for a header would be the length of
156  * "x-amz-meta-nv".
157  **/
158 #define S3_MAX_METADATA_COUNT \
159     (S3_MAX_METADATA_SIZE / (sizeof(S3_METADATA_HEADER_NAME_PREFIX "nv") - 1))
160
161
162 /**
163  * S3_MAX_ACL_GRANT_COUNT is the maximum number of ACL grants that may be
164  * set on a bucket or object at one time.  It is also the maximum number of
165  * ACL grants that the XML ACL parsing routine will parse.
166  **/
167 #define S3_MAX_ACL_GRANT_COUNT             100
168
169
170 /**
171  * This is the maximum number of characters (including terminating \0) that
172  * libs3 supports in an ACL grantee email address.
173  **/
174 #define S3_MAX_GRANTEE_EMAIL_ADDRESS_SIZE  128
175
176
177 /**
178  * This is the maximum number of characters (including terminating \0) that
179  * libs3 supports in an ACL grantee user id.
180  **/
181 #define S3_MAX_GRANTEE_USER_ID_SIZE        128
182
183
184 /**
185  * This is the maximum number of characters (including terminating \0) that
186  * libs3 supports in an ACL grantee user display name.
187  **/
188 #define S3_MAX_GRANTEE_DISPLAY_NAME_SIZE   128
189
190
191 /**
192  * This is the maximum number of characters that will be stored in the
193  * return buffer for the utility function which computes an HTTP authenticated
194  * query string
195  **/
196 #define S3_MAX_AUTHENTICATED_QUERY_STRING_SIZE \
197     (sizeof("https://" S3_HOSTNAME "/") + (S3_MAX_KEY_SIZE * 3) + \
198      sizeof("?AWSAccessKeyId=") + 32 + sizeof("&Expires=") + 32 + \
199      sizeof("&Signature=") + 28 + 1)
200
201
202 /**
203  * This constant is used by the S3_initialize() function, to specify that
204  * the winsock library should be initialized by libs3; only relevent on 
205  * Microsoft Windows platforms.
206  **/
207 #define S3_INIT_WINSOCK                    1
208
209
210 /**
211  * This convenience constant is used by the S3_initialize() function to
212  * indicate that all libraries required by libs3 should be initialized.
213  **/
214 #define S3_INIT_ALL                        (S3_INIT_WINSOCK)
215
216
217 /** **************************************************************************
218  * Enumerations
219  ************************************************************************** **/
220
221 /**
222  * S3Status is a status code as returned by a libs3 function.  The meaning of
223  * each status code is defined in the comments for each function which returns
224  * that status.
225  **/
226 typedef enum
227 {
228     S3StatusOK                                              ,
229
230     /**
231      * Errors that prevent the S3 request from being issued or response from
232      * being read
233      **/
234     S3StatusInternalError                                   ,
235     S3StatusOutOfMemory                                     ,
236     S3StatusInterrupted                                     ,
237     S3StatusInvalidBucketNameTooLong                        ,
238     S3StatusInvalidBucketNameFirstCharacter                 ,
239     S3StatusInvalidBucketNameCharacter                      ,
240     S3StatusInvalidBucketNameCharacterSequence              ,
241     S3StatusInvalidBucketNameTooShort                       ,
242     S3StatusInvalidBucketNameDotQuadNotation                ,
243     S3StatusQueryParamsTooLong                              ,
244     S3StatusFailedToInitializeRequest                       ,
245     S3StatusMetaDataHeadersTooLong                          ,
246     S3StatusBadMetaData                                     ,
247     S3StatusBadContentType                                  ,
248     S3StatusContentTypeTooLong                              ,
249     S3StatusBadMD5                                          ,
250     S3StatusMD5TooLong                                      ,
251     S3StatusBadCacheControl                                 ,
252     S3StatusCacheControlTooLong                             ,
253     S3StatusBadContentDispositionFilename                   ,
254     S3StatusContentDispositionFilenameTooLong               ,
255     S3StatusBadContentEncoding                              ,
256     S3StatusContentEncodingTooLong                          ,
257     S3StatusBadIfMatchETag                                  ,
258     S3StatusIfMatchETagTooLong                              ,
259     S3StatusBadIfNotMatchETag                               ,
260     S3StatusIfNotMatchETagTooLong                           ,
261     S3StatusHeadersTooLong                                  ,
262     S3StatusKeyTooLong                                      ,
263     S3StatusUriTooLong                                      ,
264     S3StatusXmlParseFailure                                 ,
265     S3StatusEmailAddressTooLong                             ,
266     S3StatusUserIdTooLong                                   ,
267     S3StatusUserDisplayNameTooLong                          ,
268     S3StatusGroupUriTooLong                                 ,
269     S3StatusPermissionTooLong                               ,
270     S3StatusTargetBucketTooLong                             ,
271     S3StatusTargetPrefixTooLong                             ,
272     S3StatusTooManyGrants                                   ,
273     S3StatusBadGrantee                                      ,
274     S3StatusBadPermission                                   ,
275     S3StatusXmlDocumentTooLarge                             ,
276     S3StatusNameLookupError                                 ,
277     S3StatusFailedToConnect                                 ,
278     S3StatusServerFailedVerification                        ,
279     S3StatusConnectionFailed                                ,
280     S3StatusAbortedByCallback                               ,
281     
282     /**
283      * Errors from the S3 service
284      **/
285     S3StatusErrorAccessDenied                               ,
286     S3StatusErrorAccountProblem                             ,
287     S3StatusErrorAmbiguousGrantByEmailAddress               ,
288     S3StatusErrorBadDigest                                  ,
289     S3StatusErrorBucketAlreadyExists                        ,
290     S3StatusErrorBucketAlreadyOwnedByYou                    ,
291     S3StatusErrorBucketNotEmpty                             ,
292     S3StatusErrorCredentialsNotSupported                    ,
293     S3StatusErrorCrossLocationLoggingProhibited             ,
294     S3StatusErrorEntityTooSmall                             ,
295     S3StatusErrorEntityTooLarge                             ,
296     S3StatusErrorExpiredToken                               ,
297     S3StatusErrorIncompleteBody                             ,
298     S3StatusErrorIncorrectNumberOfFilesInPostRequest        ,
299     S3StatusErrorInlineDataTooLarge                         ,
300     S3StatusErrorInternalError                              ,
301     S3StatusErrorInvalidAccessKeyId                         ,
302     S3StatusErrorInvalidAddressingHeader                    ,
303     S3StatusErrorInvalidArgument                            ,
304     S3StatusErrorInvalidBucketName                          ,
305     S3StatusErrorInvalidDigest                              ,
306     S3StatusErrorInvalidLocationConstraint                  ,
307     S3StatusErrorInvalidPayer                               ,
308     S3StatusErrorInvalidPolicyDocument                      ,
309     S3StatusErrorInvalidRange                               ,
310     S3StatusErrorInvalidSecurity                            ,
311     S3StatusErrorInvalidSOAPRequest                         ,
312     S3StatusErrorInvalidStorageClass                        ,
313     S3StatusErrorInvalidTargetBucketForLogging              ,
314     S3StatusErrorInvalidToken                               ,
315     S3StatusErrorInvalidURI                                 ,
316     S3StatusErrorKeyTooLong                                 ,
317     S3StatusErrorMalformedACLError                          ,
318     S3StatusErrorMalformedXML                               ,
319     S3StatusErrorMaxMessageLengthExceeded                   ,
320     S3StatusErrorMaxPostPreDataLengthExceededError          ,
321     S3StatusErrorMetadataTooLarge                           ,
322     S3StatusErrorMethodNotAllowed                           ,
323     S3StatusErrorMissingAttachment                          ,
324     S3StatusErrorMissingContentLength                       ,
325     S3StatusErrorMissingSecurityElement                     ,
326     S3StatusErrorMissingSecurityHeader                      ,
327     S3StatusErrorNoLoggingStatusForKey                      ,
328     S3StatusErrorNoSuchBucket                               ,
329     S3StatusErrorNoSuchKey                                  ,
330     S3StatusErrorNotImplemented                             ,
331     S3StatusErrorNotSignedUp                                ,
332     S3StatusErrorOperationAborted                           ,
333     S3StatusErrorPermanentRedirect                          ,
334     S3StatusErrorPreconditionFailed                         ,
335     S3StatusErrorRedirect                                   ,
336     S3StatusErrorRequestIsNotMultiPartContent               ,
337     S3StatusErrorRequestTimeout                             ,
338     S3StatusErrorRequestTimeTooSkewed                       ,
339     S3StatusErrorRequestTorrentOfBucketError                ,
340     S3StatusErrorSignatureDoesNotMatch                      ,
341     S3StatusErrorSlowDown                                   ,
342     S3StatusErrorTemporaryRedirect                          ,
343     S3StatusErrorTokenRefreshRequired                       ,
344     S3StatusErrorTooManyBuckets                             ,
345     S3StatusErrorUnexpectedContent                          ,
346     S3StatusErrorUnresolvableGrantByEmailAddress            ,
347     S3StatusErrorUserKeyMustBeSpecified                     ,
348     S3StatusErrorUnknown                                    ,
349
350     /**
351      * The following are HTTP errors returned by S3 without enough detail to
352      * distinguish any of the above S3StatusError conditions
353      **/
354     S3StatusHttpErrorMovedTemporarily                       ,
355     S3StatusHttpErrorBadRequest                             ,
356     S3StatusHttpErrorForbidden                              ,
357     S3StatusHttpErrorNotFound                               ,
358     S3StatusHttpErrorConflict                               ,
359     S3StatusHttpErrorUnknown
360 } S3Status;
361
362
363 /**
364  * S3Protocol represents a protocol that may be used for communicating a
365  * request to the Amazon S3 service.
366  *
367  * In general, HTTPS is greatly preferred (and should be the default of any
368  * application using libs3) because it protects any data being sent to or
369  * from S3 using strong encryption.  However, HTTPS is much more CPU intensive
370  * than HTTP, and if the caller is absolutely certain that it is OK for the
371  * data to be viewable by anyone in transit, then HTTP can be used.
372  **/
373 typedef enum
374 {
375     S3ProtocolHTTPS                     = 0,
376     S3ProtocolHTTP                      = 1
377 } S3Protocol;
378
379
380 /**
381  * S3UriStyle defines the form that an Amazon S3 URI identifying a bucket or
382  * object can take.  They are of these forms:
383  *
384  * Virtual Host: ${protocol}://${bucket}.s3.amazonaws.com/[${key}]
385  * Path: ${protocol}://s3.amazonaws.com/${bucket}/[${key}]
386  *
387  * It is generally better to use the Virual Host URI form, because it ensures
388  * that the bucket name used is compatible with normal HTTP GETs and POSTs of
389  * data to/from the bucket.  However, if DNS lookups for the bucket are too
390  * slow or unreliable for some reason, Path URI form may be used.
391  **/
392 typedef enum
393 {
394     S3UriStyleVirtualHost               = 0,
395     S3UriStylePath                      = 1
396 } S3UriStyle;
397
398
399 /**
400  * S3GranteeType defines the type of Grantee used in an S3 ACL Grant.
401  * Amazon Customer By Email - identifies the Grantee using their Amazon S3
402  *     account email address
403  * Canonical User - identifies the Grantee by S3 User ID and Display Name,
404  *     which can only be obtained by making requests to S3, for example, by
405  *     listing owned buckets
406  * All AWS Users - identifies all authenticated AWS users
407  * All Users - identifies all users
408  * Log Delivery - identifies the Amazon group responsible for writing
409  *                server access logs into buckets
410  **/
411 typedef enum
412 {
413     S3GranteeTypeAmazonCustomerByEmail  = 0,
414     S3GranteeTypeCanonicalUser          = 1,
415     S3GranteeTypeAllAwsUsers            = 2,
416     S3GranteeTypeAllUsers               = 3,
417     S3GranteeTypeLogDelivery            = 4
418 } S3GranteeType;
419
420
421 /**
422  * This is an individual permission granted to a grantee in an S3 ACL Grant.
423  * Read permission gives the Grantee the permission to list the bucket, or
424  *     read the object or its metadata
425  * Write permission gives the Grantee the permission to create, overwrite, or
426  *     delete any object in the bucket, and is not supported for objects
427  * ReadACP permission gives the Grantee the permission to read the ACP for
428  *     the bucket or object; the owner of the bucket or object always has
429  *     this permission implicitly
430  * WriteACP permission gives the Grantee the permission to overwrite the ACP
431  *     for the bucket or object; the owner of the bucket or object always has
432  *     this permission implicitly
433  * FullControl permission gives the Grantee all permissions specified by the
434  *     Read, Write, ReadACP, and WriteACP permissions
435  **/
436 typedef enum
437 {
438     S3PermissionRead                    = 0,
439     S3PermissionWrite                   = 1,
440     S3PermissionReadACP                 = 2,
441     S3PermissionWriteACP                = 3,
442     S3PermissionFullControl             = 4
443 } S3Permission;
444
445
446 /**
447  * S3CannedAcl is an ACL that can be specified when an object is created or
448  * updated.  Each canned ACL has a predefined value when expanded to a full
449  * set of S3 ACL Grants.
450  * Private canned ACL gives the owner FULL_CONTROL and no other permissions
451  *     are issued
452  * Public Read canned ACL gives the owner FULL_CONTROL and all users Read
453  *     permission 
454  * Public Read Write canned ACL gives the owner FULL_CONTROL and all users
455  *     Read and Write permission
456  * AuthenticatedRead canned ACL gives the owner FULL_CONTROL and authenticated
457  *     S3 users Read permission
458  **/
459 typedef enum
460 {
461     S3CannedAclPrivate                  = 0, /* private */
462     S3CannedAclPublicRead               = 1, /* public-read */
463     S3CannedAclPublicReadWrite          = 2, /* public-read-write */
464     S3CannedAclAuthenticatedRead        = 3  /* authenticated-read */
465 } S3CannedAcl;
466
467
468 /** **************************************************************************
469  * Data Types
470  ************************************************************************** **/
471
472 /**
473  * An S3RequestContext manages multiple S3 requests simultaneously; see the
474  * S3_XXX_request_context functions below for details
475  **/
476 typedef struct S3RequestContext S3RequestContext;
477
478
479 /**
480  * S3NameValue represents a single Name - Value pair, used to represent either
481  * S3 metadata associated with a key, or S3 error details.
482  **/
483 typedef struct S3NameValue
484 {
485     /**
486      * The name part of the Name - Value pair
487      **/
488     const char *name;
489
490     /**
491      * The value part of the Name - Value pair
492      **/
493     const char *value;
494 } S3NameValue;
495
496
497 /**
498  * S3ResponseProperties is passed to the properties callback function which is
499  * called when the complete response properties have been received.  Some of
500  * the fields of this structure are optional and may not be provided in the
501  * response, and some will always be provided in the response.
502  **/
503 typedef struct S3ResponseProperties
504 {
505     /**
506      * This optional field identifies the request ID and may be used when
507      * reporting problems to Amazon.
508      **/
509     const char *requestId;
510
511     /**
512      * This optional field identifies the request ID and may be used when
513      * reporting problems to Amazon.
514      **/
515     const char *requestId2;
516
517     /**
518      * This optional field is the content type of the data which is returned
519      * by the request.  If not provided, the default can be assumed to be
520      * "binary/octet-stream".
521      **/
522     const char *contentType;
523
524     /**
525      * This optional field is the content length of the data which is returned
526      * in the response.  A negative value means that this value was not
527      * provided in the response.  A value of 0 means that there is no content
528      * provided.  A positive value gives the number of bytes in the content of
529      * the response.
530      **/
531     uint64_t contentLength;
532
533     /**
534      * This optional field names the server which serviced the request.
535      **/
536     const char *server;
537
538     /**
539      * This optional field provides a string identifying the unique contents
540      * of the resource identified by the request, such that the contents can
541      * be assumed not to be changed if the same eTag is returned at a later
542      * time decribing the same resource.  This is an MD5 sum of the contents.
543      **/
544     const char *eTag;
545
546     /**
547      * This optional field provides the last modified time, relative to the
548      * Unix epoch, of the contents.  If this value is < 0, then the last
549      * modified time was not provided in the response.  If this value is >= 0,
550      * then the last modified date of the contents are available as a number
551      * of seconds since the UNIX epoch.
552      * 
553      **/
554     int64_t lastModified;
555
556     /**
557      * This is the number of user-provided meta data associated with the
558      * resource.
559      **/
560     int metaDataCount;
561
562     /**
563      * These are the meta data associated with the resource.  In each case,
564      * the name will not include any S3-specific header prefixes
565      * (i.e. x-amz-meta- will have been removed from the beginning), and
566      * leading and trailing whitespace will have been stripped from the value.
567      **/
568     const S3NameValue *metaData;
569 } S3ResponseProperties;
570
571
572 /**
573  * S3AclGrant identifies a single grant in the ACL for a bucket or object.  An
574  * ACL is composed of any number of grants, which specify a grantee and the
575  * permissions given to that grantee.  S3 does not normalize ACLs in any way,
576  * so a redundant ACL specification will lead to a redundant ACL stored in S3.
577  **/
578 typedef struct S3AclGrant
579 {
580     /**
581      * The granteeType gives the type of grantee specified by this grant.
582      **/
583     S3GranteeType granteeType;
584     /**
585      * The identifier of the grantee that is set is determined by the
586      * granteeType:
587      *
588      * S3GranteeTypeAmazonCustomerByEmail - amazonCustomerByEmail.emailAddress
589      * S3GranteeTypeCanonicalUser - canonicalUser.id, canonicalUser.displayName
590      * S3GranteeTypeAllAwsUsers - none
591      * S3GranteeTypeAllUsers - none
592      **/
593     union
594     {
595         /**
596          * This structure is used iff the granteeType is 
597          * S3GranteeTypeAmazonCustomerByEmail.
598          **/
599         struct
600         {
601             /**
602              * This is the email address of the Amazon Customer being granted
603              * permissions by this S3AclGrant.
604              **/
605             char emailAddress[S3_MAX_GRANTEE_EMAIL_ADDRESS_SIZE];
606         } amazonCustomerByEmail;
607         /**
608          * This structure is used iff the granteeType is
609          * S3GranteeTypeCanonicalUser.
610          **/
611         struct
612         {
613             /**
614              * This is the CanonicalUser ID of the grantee
615              **/
616             char id[S3_MAX_GRANTEE_USER_ID_SIZE];
617             /**
618              * This is the display name of the grantee
619              **/
620             char displayName[S3_MAX_GRANTEE_DISPLAY_NAME_SIZE];
621         } canonicalUser;
622     } grantee;
623     /**
624      * This is the S3Permission to be granted to the grantee
625      **/
626     S3Permission permission;
627 } S3AclGrant;
628
629
630 /**
631  * A context for working with objects within a bucket.  A bucket context holds
632  * all information necessary for working with a bucket, and may be used
633  * repeatedly over many consecutive (or simultaneous) calls into libs3 bucket
634  * operation functions.
635  **/
636 typedef struct S3BucketContext
637 {
638     /**
639      * The name of the bucket to use in the bucket context
640      **/
641     const char *bucketName;
642
643     /**
644      * The protocol to use when accessing the bucket
645      **/
646     S3Protocol protocol;
647
648     /**
649      * The URI style to use for all URIs sent to Amazon S3 while working with
650      * this bucket context
651      **/
652     S3UriStyle uriStyle;
653
654     /**
655      * The Amazon Access Key ID to use for access to the bucket
656      **/
657     const char *accessKeyId;
658
659     /**
660      *  The Amazon Secret Access Key to use for access to the bucket
661      **/
662     const char *secretAccessKey;
663 } S3BucketContext;
664
665
666 /**
667  * This is a single entry supplied to the list bucket callback by a call to
668  * S3_list_bucket.  It identifies a single matching key from the list
669  * operation.
670  **/
671 typedef struct S3ListBucketContent
672 {
673     /**
674      * This is the next key in the list bucket results.
675      **/
676     const char *key;
677
678     /**
679      * This is the number of seconds since UNIX epoch of the last modified
680      * date of the object identified by the key. 
681      **/
682     int64_t lastModified;
683
684     /**
685      * This gives a tag which gives a signature of the contents of the object,
686      * which is the MD5 of the contents of the object.
687      **/
688     const char *eTag;
689
690     /**
691      * This is the size of the object in bytes.
692      **/
693     uint64_t size;
694
695     /**
696      * This is the ID of the owner of the key; it is present only if access
697      * permissions allow it to be viewed.
698      **/
699     const char *ownerId;
700
701     /**
702      * This is the display name of the owner of the key; it is present only if
703      * access permissions allow it to be viewed.
704      **/
705     const char *ownerDisplayName;
706 } S3ListBucketContent;
707
708
709 /**
710  * S3PutProperties is the set of properties that may optionally be set by the
711  * user when putting objects to S3.  Each field of this structure is optional
712  * and may or may not be present.
713  **/
714 typedef struct S3PutProperties
715 {
716     /**
717      * If present, this is the Content-Type that should be associated with the
718      * object.  If not provided, S3 defaults to "binary/octet-stream".
719      **/
720     const char *contentType;
721
722     /**
723      * If present, this provides the MD5 signature of the contents, and is
724      * used to validate the contents.  This is highly recommended by Amazon
725      * but not required.  Its format is as a base64-encoded MD5 sum.
726      **/
727     const char *md5;
728
729     /**
730      * If present, this gives a Cache-Control header string to be supplied to
731      * HTTP clients which download this
732      **/
733     const char *cacheControl;
734
735     /**
736      * If present, this gives the filename to save the downloaded file to,
737      * whenever the object is downloaded via a web browser.  This is only
738      * relevent for objects which are intended to be shared to users via web
739      * browsers and which is additionally intended to be downloaded rather
740      * than viewed.
741      **/
742     const char *contentDispositionFilename;
743
744     /**
745      * If present, this identifies the content encoding of the object.  This
746      * is only applicable to encoded (usually, compressed) content, and only
747      * relevent if the object is intended to be downloaded via a browser.
748      **/
749     const char *contentEncoding;
750
751     /**
752      * If >= 0, this gives an expiration date for the content.  This
753      * information is typically only delivered to users who download the
754      * content via a web browser.
755      **/
756     int64_t expires;
757
758     /**
759      * This identifies the "canned ACL" that should be used for this object.
760      * The default (0) gives only the owner of the object access to it.
761      **/
762     S3CannedAcl cannedAcl;
763
764     /**
765      * This is the number of values in the metaData field.
766      **/
767     int metaDataCount;
768
769     /**
770      * These are the meta data to pass to S3.  In each case, the name part of
771      * the Name - Value pair should not include any special S3 HTTP header
772      * prefix (i.e., should be of the form 'foo', NOT 'x-amz-meta-foo').
773      **/
774     const S3NameValue *metaData;
775 } S3PutProperties;
776
777
778 /**
779  * S3GetConditions is used for the get_object operation, and specifies
780  * conditions which the object must meet in order to be successfully returned.
781  **/
782 typedef struct S3GetConditions
783 {
784     /**
785      * The request will be processed if the Last-Modification header of the
786      * object is greater than or equal to this value, specified as a number of
787      * seconds since Unix epoch.  If this value is less than zero, it will not
788      * be used in the conditional.
789      **/
790     int64_t ifModifiedSince;
791
792     /**
793      * The request will be processed if the Last-Modification header of the
794      * object is less than this value, specified as a number of seconds since
795      * Unix epoch.  If this value is less than zero, it will not be used in
796      * the conditional.
797      **/
798     int64_t ifNotModifiedSince;
799
800     /**
801      * If non-NULL, this gives an eTag header value which the object must
802      * match in order to be returned.  Note that altough the eTag is simply an
803      * MD5, this must be presented in the S3 eTag form, which typically
804      * includes double-quotes.
805      **/
806     const char *ifMatchETag;
807
808     /**
809      * If non-NULL, this gives an eTag header value which the object must not
810      * match in order to be returned.  Note that altough the eTag is simply an
811      * MD5, this must be presented in the S3 eTag form, which typically
812      * includes double-quotes.
813      **/
814     const char *ifNotMatchETag;
815 } S3GetConditions;
816
817
818 /**
819  * S3ErrorDetails provides detailed information describing an S3 error.  This
820  * is only presented when the error is an S3-generated error (i.e. one of the
821  * S3StatusErrorXXX values).
822  **/
823 typedef struct S3ErrorDetails
824 {
825     /**
826      * This is the human-readable message that Amazon supplied describing the
827      * error
828      **/
829     const char *message;
830
831     /**
832      * This identifies the resource for which the error occurred
833      **/
834     const char *resource;
835
836     /**
837      * This gives human-readable further details describing the specifics of
838      * this error
839      **/
840     const char *furtherDetails;
841
842     /**
843      * This gives the number of S3NameValue pairs present in the extraDetails
844      * array
845      **/
846     int extraDetailsCount;
847
848     /**
849      * S3 can provide extra details in a freeform Name - Value pair format.
850      * Each error can have any number of these, and this array provides these
851      * additional extra details.
852      **/
853     S3NameValue *extraDetails;
854 } S3ErrorDetails;
855
856
857 /** **************************************************************************
858  * Callback Signatures
859  ************************************************************************** **/
860
861 /**
862  * This callback is made whenever the response properties become available for
863  * any request.
864  *
865  * @param properties are the properties that are available from the response
866  * @param callbackData is the callback data as specified when the request
867  *        was issued.
868  * @return S3StatusOK to continue processing the request, anything else to
869  *         immediately abort the request with a status which will be
870  *         passed to the S3ResponseCompleteCallback for this request.
871  *         Typically, this will return either S3StatusOK or
872  *         S3StatusAbortedByCallback.
873  **/
874 typedef S3Status (S3ResponsePropertiesCallback)
875     (const S3ResponseProperties *properties, void *callbackData);
876
877
878 /**
879  * This callback is made when the response has been completely received, or an
880  * error has occurred which has prematurely aborted the request, or one of the
881  * other user-supplied callbacks returned a value intended to abort the
882  * request.  This callback is always made for every request, as the very last
883  * callback made for that request.
884  *
885  * @param status gives the overall status of the response, indicating success
886  *        or failure; use S3_status_is_retryable() as a simple way to detect
887  *        whether or not the status indicates that the request failed but may
888  *        be retried.
889  * @param errorDetails if non-NULL, gives details as returned by the S3
890  *        service, describing the error
891  * @param callbackData is the callback data as specified when the request
892  *        was issued.
893  **/
894 typedef void (S3ResponseCompleteCallback)(S3Status status,
895                                           const S3ErrorDetails *errorDetails,
896                                           void *callbackData);
897
898                                     
899 /**
900  * This callback is made for each bucket resulting from a list service
901  * operation.
902  *
903  * @param ownerId is the ID of the owner of the bucket
904  * @param ownerDisplayName is the owner display name of the owner of the bucket
905  * @param bucketName is the name of the bucket
906  * @param creationDateSeconds if < 0 indicates that no creation date was
907  *        supplied for the bucket; if >= 0 indicates the number of seconds
908  *        since UNIX Epoch of the creation date of the bucket
909  * @param callbackData is the callback data as specified when the request
910  *        was issued.
911  * @return S3StatusOK to continue processing the request, anything else to
912  *         immediately abort the request with a status which will be
913  *         passed to the S3ResponseCompleteCallback for this request.
914  *         Typically, this will return either S3StatusOK or
915  *         S3StatusAbortedByCallback.
916  **/
917 typedef S3Status (S3ListServiceCallback)(const char *ownerId, 
918                                          const char *ownerDisplayName,
919                                          const char *bucketName,
920                                          int64_t creationDateSeconds,
921                                          void *callbackData);
922
923
924 /**
925  * This callback is made repeatedly as a list bucket operation progresses.
926  * The contents reported via this callback are only reported once per list
927  * bucket operation, but multiple calls to this callback may be necessary to
928  * report all items resulting from the list bucket operation.
929  *
930  * @param isTruncated is true if the list bucket request was truncated by the
931  *        S3 service, in which case the remainder of the list may be obtained
932  *        by querying again using the Marker parameter to start the query
933  *        after this set of results
934  * @param nextMarker if present, gives the largest (alphabetically) key
935  *        returned in the response, which, if isTruncated is true, may be used
936  *        as the marker in a subsequent list buckets operation to continue
937  *        listing
938  * @param contentsCount is the number of ListBucketContent structures in the
939  *        contents parameter
940  * @param contents is an array of ListBucketContent structures, each one
941  *        describing an object in the bucket
942  * @param commonPrefixesCount is the number of common prefixes strings in the
943  *        commonPrefixes parameter
944  * @param commonPrefixes is an array of strings, each specifing one of the
945  *        common prefixes as returned by S3
946  * @param callbackData is the callback data as specified when the request
947  *        was issued.
948  * @return S3StatusOK to continue processing the request, anything else to
949  *         immediately abort the request with a status which will be
950  *         passed to the S3ResponseCompleteCallback for this request.
951  *         Typically, this will return either S3StatusOK or
952  *         S3StatusAbortedByCallback.
953  **/
954 typedef S3Status (S3ListBucketCallback)(int isTruncated,
955                                         const char *nextMarker,
956                                         int contentsCount, 
957                                         const S3ListBucketContent *contents,
958                                         int commonPrefixesCount,
959                                         const char **commonPrefixes,
960                                         void *callbackData);
961                                        
962
963 /**
964  * This callback is made during a put object operation, to obtain the next
965  * chunk of data to put to the S3 service as the contents of the object.  This
966  * callback is made repeatedly, each time acquiring the next chunk of data to
967  * write to the service, until a negative or 0 value is returned.
968  *
969  * @param bufferSize gives the maximum number of bytes that may be written
970  *        into the buffer parameter by this callback
971  * @param buffer gives the buffer to fill with at most bufferSize bytes of
972  *        data as the next chunk of data to send to S3 as the contents of this
973  *        object
974  * @param callbackData is the callback data as specified when the request
975  *        was issued.
976  * @return < 0 to abort the request with the S3StatusAbortedByCallback, which
977  *        will be pased to the response complete callback for this request, or
978  *        0 to indicate the end of data, or > 0 to identify the number of
979  *        bytes that were written into the buffer by this callback
980  **/
981 typedef int (S3PutObjectDataCallback)(int bufferSize, char *buffer,
982                                       void *callbackData);
983
984
985 /**
986  * This callback is made during a get object operation, to provide the next
987  * chunk of data available from the S3 service constituting the contents of
988  * the object being fetched.  This callback is made repeatedly, each time
989  * providing the next chunk of data read, until the complete object contents
990  * have been passed through the callback in this way, or the callback
991  * returns an error status.
992  *
993  * @param bufferSize gives the number of bytes in buffer
994  * @param buffer is the data being passed into the callback
995  * @param callbackData is the callback data as specified when the request
996  *        was issued.
997  * @return S3StatusOK to continue processing the request, anything else to
998  *         immediately abort the request with a status which will be
999  *         passed to the S3ResponseCompleteCallback for this request.
1000  *         Typically, this will return either S3StatusOK or
1001  *         S3StatusAbortedByCallback.
1002  **/
1003 typedef S3Status (S3GetObjectDataCallback)(int bufferSize, const char *buffer,
1004                                            void *callbackData);
1005                                        
1006
1007 /** **************************************************************************
1008  * Callback Structures
1009  ************************************************************************** **/
1010
1011
1012 /**
1013  * An S3ResponseHandler defines the callbacks which are made for any
1014  * request.
1015  **/
1016 typedef struct S3ResponseHandler
1017 {
1018     /**
1019      * The propertiesCallback is made when the response properties have
1020      * successfully been returned from S3.  This function may not be called
1021      * if the response properties were not successfully returned from S3.
1022      **/
1023     S3ResponsePropertiesCallback *propertiesCallback;
1024     
1025     /**
1026      * The completeCallback is always called for every request made to S3,
1027      * regardless of the outcome of the request.  It provides the status of
1028      * the request upon its completion, as well as extra error details in the
1029      * event of an S3 error.
1030      **/
1031     S3ResponseCompleteCallback *completeCallback;
1032 } S3ResponseHandler;
1033
1034
1035 /**
1036  * An S3ListServiceHandler defines the callbacks which are made for
1037  * list_service requests.
1038  **/
1039 typedef struct S3ListServiceHandler
1040 {
1041     /**
1042      * responseHandler provides the properties and complete callback
1043      **/
1044     S3ResponseHandler responseHandler;
1045
1046     /**
1047      * The listServiceCallback is called as items are reported back from S3 as
1048      * responses to the request
1049      **/
1050     S3ListServiceCallback *listServiceCallback;
1051 } S3ListServiceHandler;
1052
1053
1054 /**
1055  * An S3ListBucketHandler defines the callbacks which are made for
1056  * list_bucket requests.
1057  **/
1058 typedef struct S3ListBucketHandler
1059 {
1060     /**
1061      * responseHandler provides the properties and complete callback
1062      **/
1063     S3ResponseHandler responseHandler;
1064
1065     /**
1066      * The listBucketCallback is called as items are reported back from S3 as
1067      * responses to the request.  This may be called more than one time per
1068      * list bucket request, each time providing more items from the list
1069      * operation.
1070      **/
1071     S3ListBucketCallback *listBucketCallback;
1072 } S3ListBucketHandler;
1073
1074
1075 /**
1076  * An S3PutObjectHandler defines the callbacks which are made for
1077  * put_object requests.
1078  **/
1079 typedef struct S3PutObjectHandler
1080 {
1081     /**
1082      * responseHandler provides the properties and complete callback
1083      **/
1084     S3ResponseHandler responseHandler;
1085
1086     /**
1087      * The putObjectDataCallback is called to acquire data to send to S3 as
1088      * the contents of the put_object request.  It is made repeatedly until it
1089      * returns a negative number (indicating that the request should be
1090      * aborted), or 0 (indicating that all data has been supplied).
1091      **/
1092     S3PutObjectDataCallback *putObjectDataCallback;
1093 } S3PutObjectHandler;
1094
1095
1096 /**
1097  * An S3GetObjectHandler defines the callbacks which are made for
1098  * get_object requests.
1099  **/
1100 typedef struct S3GetObjectHandler
1101 {
1102     /**
1103      * responseHandler provides the properties and complete callback
1104      **/
1105     S3ResponseHandler responseHandler;
1106
1107     /**
1108      * The getObjectDataCallback is called as data is read from S3 as the
1109      * contents of the object being read in the get_object request.  It is
1110      * called repeatedly until there is no more data provided in the request,
1111      * or until the callback returns an error status indicating that the
1112      * request should be aborted.
1113      **/
1114     S3GetObjectDataCallback *getObjectDataCallback;
1115 } S3GetObjectHandler;
1116
1117
1118 /** **************************************************************************
1119  * General Library Functions
1120  ************************************************************************** **/
1121
1122 /**
1123  * Initializes libs3 for use.  This function must be called before any other
1124  * libs3 function is called.  It may be called multiple times, with the same
1125  * effect as calling it once, as long as S3_deinitialize() is called an
1126  * equal number of times when the program has finished.  This function is NOT
1127  * thread-safe and must only be called by one thread at a time.
1128  *
1129  * @param userAgentInfo is a string that will be included in the User-Agent
1130  *        header of every request made to the S3 service.  You may provide
1131  *        NULL or the empty string if you don't care about this.  The value
1132  *        will not be copied by this function and must remain unaltered by the
1133  *        caller until S3_deinitialize() is called.
1134  * @param flags is a bitmask of some combination of S3_INIT_XXX flag, or
1135  *        S3_INIT_ALL, indicating which of the libraries that libs3 depends
1136  *        upon should be initialized by S3_initialize().  Only if your program
1137  *        initializes one of these dependency libraries itself should anything
1138  *        other than S3_INIT_ALL be passed in for this bitmask.
1139  *
1140  *        You should pass S3_INIT_WINSOCK if and only if your application does
1141  *        not initialize winsock elsewhere.  On non-Microsoft Windows
1142  *        platforms it has no effect.
1143  *
1144  *        As a convenience, the macro S3_INIT_ALL is provided, which will do
1145  *        all necessary initialization; however, be warned that things may
1146  *        break if your application re-initializes the dependent libraries
1147  *        later.
1148  * @return One of:
1149  *         S3StatusOK on success
1150  *         S3StatusInternalError if dependent libraries could not be
1151  *             initialized
1152  *         S3StatusOutOfMemory on failure due to out of memory
1153  **/
1154 S3Status S3_initialize(const char *userAgentInfo, int flags);
1155
1156
1157 /**
1158  * Must be called once per program for each call to libs3_initialize().  After
1159  * this call is complete, no libs3 function may be called except
1160  * S3_initialize().
1161  **/
1162 void S3_deinitialize();
1163
1164
1165 /**
1166  * Returns a string with the textual name of an S3Status code
1167  *
1168  * @param status is S3Status code for which the textual name will be returned
1169  * @return a string with the textual name of an S3Status code
1170  **/
1171 const char *S3_get_status_name(S3Status status);
1172
1173
1174 /**
1175  * This function may be used to validate an S3 bucket name as being in the
1176  * correct form for use with the S3 service.  Amazon S3 limits the allowed
1177  * characters in S3 bucket names, as well as imposing some additional rules on
1178  * the length of bucket names and their structure.  There are actually two
1179  * limits; one for bucket names used only in path-style URIs, and a more
1180  * strict limit used for bucket names used in virtual-host-style URIs.  It is
1181  * advisable to use only bucket names which meet the more strict requirements
1182  * regardless of how the bucket expected to be used.
1183  *
1184  * This method does NOT validate that the bucket is available for use in the
1185  * S3 service, so the return value of this function cannot be used to decide
1186  * whether or not a bucket with the give name already exists in Amazon S3 or
1187  * is accessible by the caller.  It merely validates that the bucket name is
1188  * valid for use with S3.
1189  *
1190  * @param bucketName is the bucket name to validate
1191  * @param uriStyle gives the URI style to validate the bucket name against.
1192  *        It is advisable to always use S3UriStyleVirtuallHost.
1193  * @return One of:
1194  *         S3StatusOK if the bucket name was validates successfully
1195  *         S3StatusInvalidBucketNameTooLong if the bucket name exceeded the
1196  *             length limitation for the URI style, which is 255 bytes for
1197  *             path style URIs and 63 bytes for virtual host type URIs
1198  *         S3StatusInvalidBucketNameTooShort if the bucket name is less than
1199  *             3 characters
1200  *         S3StatusInvalidBucketNameFirstCharacter if the bucket name as an
1201  *             invalid first character, which is anything other than
1202  *             an alphanumeric character
1203  *         S3StatusInvalidBucketNameCharacterSequence if the bucket name
1204  *             includes an invalid character sequence, which for virtual host
1205  *             style buckets is ".-" or "-."
1206  *         S3StatusInvalidBucketNameCharacter if the bucket name includes an
1207  *             invalid character, which is anything other than alphanumeric,
1208  *             '-', '.', or for path style URIs only, '_'.
1209  *         S3StatusInvalidBucketNameDotQuadNotation if the bucket name is in
1210  *             dot-quad notation, i.e. the form of an IP address, which is
1211  *             not allowed by Amazon S3.
1212  **/
1213 S3Status S3_validate_bucket_name(const char *bucketName, S3UriStyle uriStyle);
1214
1215
1216 /**
1217  * Converts an XML representation of an ACL to a libs3 structured
1218  * representation.  This method is not strictly necessary for working with
1219  * ACLs using libs3, but may be convenient for users of the library who read
1220  * ACLs from elsewhere in XML format and need to use these ACLs with libs3.
1221  *
1222  * @param aclXml is the XML representation of the ACL.  This must be a
1223  *        zero-terminated character string.
1224  * @param ownerId will be filled in with the Owner ID specified in the XML.
1225  *        At most MAX_GRANTEE_USER_ID_SIZE bytes will be stored at this
1226  *        location.
1227  * @param ownerDisplayName will be filled in with the Owner Display Name
1228  *        specified in the XML.  At most MAX_GRANTEE_DISPLAY_NAME_SIZE bytes
1229  *        will be stored at this location.
1230  * @param aclGrantCountReturn returns the number of S3AclGrant structures
1231  *        returned in the aclGrantsReturned array
1232  * @param aclGrants must be passed in as an array of at least S3_ACL_MAXCOUNT
1233  *        structures, and on return from this function, the first
1234  *        aclGrantCountReturn structures will be filled in with the ACLs
1235  *        represented by the input XML.
1236  * @return One of:
1237  *         S3StatusOK on successful conversion of the ACL
1238  *         S3StatusInternalError on internal error representing a bug in the
1239  *             libs3 library
1240  *         S3StatusXmlParseFailure if the XML document was malformed
1241  **/
1242 S3Status S3_convert_acl(char *aclXml, char *ownerId, char *ownerDisplayName,
1243                         int *aclGrantCountReturn, S3AclGrant *aclGrants);
1244                         
1245
1246 /**
1247  * Returns nonzero if the status indicates that the request should be
1248  * immediately retried, because the status indicates an error of a nature that
1249  * is likely due to transient conditions on the local system or S3, such as
1250  * network failures, or internal retryable errors reported by S3.  Returns
1251  * zero otherwise.
1252  *
1253  * @param status is the status to evaluate
1254  * @return nonzero if the status indicates a retryable error, 0 otherwise
1255  **/
1256 int S3_status_is_retryable(S3Status status);
1257
1258
1259 /** **************************************************************************
1260  * Request Context Management Functions
1261  ************************************************************************** **/
1262
1263 /**
1264  * An S3RequestContext allows muliple requests to be serviced by the same
1265  * thread simultaneously.  It is an optional parameter to all libs3 request
1266  * functions, and if provided, the request is managed by the S3RequestContext;
1267  * if not, the request is handled synchronously and is complete when the libs3
1268  * request function has returned.
1269  *
1270  * @param requestContextReturn returns the newly-created S3RequestContext
1271  *        structure, which if successfully returned, must be destroyed via a
1272  *        call to S3_destroy_request_context when it is no longer needed.  If
1273  *        an error status is returned from this function, then
1274  *        requestContextReturn will not have been filled in, and
1275  *        S3_destroy_request_context should not be called on it
1276  * @return One of:
1277  *         S3StatusOK if the request context was successfully created
1278  *         S3StatusOutOfMemory if the request context could not be created due
1279  *             to an out of memory error
1280  **/
1281 S3Status S3_create_request_context(S3RequestContext **requestContextReturn);
1282
1283
1284 /**
1285  * Destroys an S3RequestContext which was created with
1286  * S3_create_request_context.  Any requests which are currently being
1287  * processed by the S3RequestContext will immediately be aborted and their
1288  * request completed callbacks made with the status S3StatusInterrupted.
1289  *
1290  * @param requestContext is the S3RequestContext to destroy
1291  **/
1292 void S3_destroy_request_context(S3RequestContext *requestContext);
1293
1294
1295 /**
1296  * Runs the S3RequestContext until all requests within it have completed,
1297  * or until an error occurs.
1298  *
1299  * @param requestContext is the S3RequestContext to run until all requests
1300  *            within it have completed or until an error occurs
1301  * @return One of:
1302  *         S3Status if all requests were successfully run to completion
1303  *         S3StatusInternalError if an internal error prevented the
1304  *             S3RequestContext from running one or more requests
1305  *         S3StatusOutOfMemory if requests could not be run to completion
1306  *             due to an out of memory error
1307  **/
1308 S3Status S3_runall_request_context(S3RequestContext *requestContext);
1309
1310
1311 /**
1312  * Does some processing of requests within the S3RequestContext.  One or more
1313  * requests may have callbacks made on them and may complete.  This function
1314  * processes any requests which have immediately available I/O, and will not
1315  * block waiting for I/O on any request.  This function would normally be used
1316  * with S3_get_request_context_fdsets.
1317  *
1318  * @param requestContext is the S3RequestContext to process
1319  * @param requestsRemainingReturn returns the number of requests remaining
1320  *            and not yet completed within the S3RequestContext after this
1321  *            function returns.
1322  * @return One of:
1323  *         S3StatusOK if request processing proceeded without error
1324  *         S3StatusInternalError if an internal error prevented the
1325  *             S3RequestContext from running one or more requests
1326  *         S3StatusOutOfMemory if requests could not be processed due to
1327  *             an out of memory error
1328  **/
1329 S3Status S3_runonce_request_context(S3RequestContext *requestContext, 
1330                                     int *requestsRemainingReturn);
1331
1332
1333 /**
1334  * This function, in conjunction allows callers to manually manage a set of
1335  * requests using an S3RequestContext.  This function returns the set of file
1336  * descriptors which the caller can watch (typically using select()), along
1337  * with any other file descriptors of interest to the caller, and using
1338  * whatever timeout (if any) the caller wishes, until one or more file
1339  * descriptors in the returned sets become ready for I/O, at which point
1340  * S3_runonce_request_context can be called to process requests with available
1341  * I/O.
1342  *
1343  * @param requestContext is the S3RequestContext to get fd_sets from
1344  * @param readFdSet is a pointer to an fd_set which will have all file
1345  *        descriptors to watch for read events for the requests in the
1346  *        S3RequestContext set into it upon return.  Should be zero'd out
1347  *        (using FD_ZERO) before being passed into this function.
1348  * @param writeFdSet is a pointer to an fd_set which will have all file
1349  *        descriptors to watch for write events for the requests in the
1350  *        S3RequestContext set into it upon return.  Should be zero'd out
1351  *        (using FD_ZERO) before being passed into this function.
1352  * @param exceptFdSet is a pointer to an fd_set which will have all file
1353  *        descriptors to watch for exception events for the requests in the
1354  *        S3RequestContext set into it upon return.  Should be zero'd out
1355  *        (using FD_ZERO) before being passed into this function.
1356  * @param maxFd returns the highest file descriptor set into any of the
1357  *        fd_sets, or -1 if no file descriptors were set
1358  * @return One of:
1359  *         S3StatusOK if all fd_sets were successfully set
1360  *         S3StatusInternalError if an internal error prevented this function
1361  *             from completing successfully
1362  **/
1363 S3Status S3_get_request_context_fdsets(S3RequestContext *requestContext,
1364                                        fd_set *readFdSet, fd_set *writeFdSet,
1365                                        fd_set *exceptFdSet, int *maxFd);
1366
1367
1368 /**
1369  * This function returns the maximum number of milliseconds that the caller of
1370  * S3_runonce_request_context should wait on the fdsets obtained via a call to
1371  * S3_get_request_context_fdsets.  In other words, this is essentially the
1372  * select() timeout that needs to be used (shorter values are OK, but no
1373  * longer than this) to ensure that internal timeout code of libs3 can work
1374  * properly.  This function should be called right before select() each time
1375  * select() on the request_context fdsets are to be performed by the libs3
1376  * user.
1377  *
1378  * @param requestContext is the S3RequestContext to get the timeout from
1379  * @return the maximum number of milliseconds to select() on fdsets.  Callers
1380  *         could wait a shorter time if they wish, but not longer.
1381  **/
1382 int64_t S3_get_request_context_timeout(S3RequestContext *requestContext);
1383
1384
1385 /** **************************************************************************
1386  * S3 Utility Functions
1387  ************************************************************************** **/
1388
1389 /**
1390  * Generates an HTTP authenticated query string, which may then be used by
1391  * a browser (or other web client) to issue the request.  The request is
1392  * implicitly a GET request; Amazon S3 is documented to only support this type
1393  * of authenticated query string request.
1394  *
1395  * @param buffer is the output buffer for the authenticated query string.
1396  *        It must be at least S3_MAX_AUTHENTICATED_QUERY_STRING_SIZE bytes in 
1397  *        length.
1398  * @param bucketContext gives the bucket and associated parameters for the
1399  *        request to generate.
1400  * @param key gives the key which the authenticated request will GET.
1401  * @param expires gives the number of seconds since Unix epoch for the
1402  *        expiration date of the request; after this time, the request will
1403  *        no longer be valid.  If this value is negative, the largest
1404  *        expiration date possible is used (currently, Jan 19, 2038).
1405  * @param resource gives a sub-resource to be fetched for the request, or NULL
1406  *        for none.  This should be of the form "?<resource>", i.e. 
1407  *        "?torrent".
1408  * @return One of:
1409  *         S3StatusUriTooLong if, due to an internal error, the generated URI
1410  *             is longer than S3_MAX_AUTHENTICATED_QUERY_STRING_SIZE bytes in
1411  *             length and thus will not fit into the supplied buffer
1412  *         S3StatusOK on success
1413  **/
1414 S3Status S3_generate_authenticated_query_string
1415     (char *buffer, const S3BucketContext *bucketContext,
1416      const char *key, int64_t expires, const char *resource);
1417
1418
1419 /** **************************************************************************
1420  * Service Functions
1421  ************************************************************************** **/
1422
1423 /**
1424  * Lists all S3 buckets belonging to the access key id.
1425  *
1426  * @param protocol gives the protocol to use for this request
1427  * @param accessKeyId gives the Amazon Access Key ID for which to list owned
1428  *        buckets
1429  * @param secretAccessKey gives the Amazon Secret Access Key for which to list
1430  *        owned buckets
1431  * @param requestContext if non-NULL, gives the S3RequestContext to add this
1432  *        request to, and does not perform the request immediately.  If NULL,
1433  *        performs the request immediately and synchronously.
1434  * @param handler gives the callbacks to call as the request is processed and
1435  *        completed 
1436  * @param callbackData will be passed in as the callbackData parameter to
1437  *        all callbacks for this request
1438  **/
1439 void S3_list_service(S3Protocol protocol, const char *accessKeyId,
1440                      const char *secretAccessKey,
1441                      S3RequestContext *requestContext,
1442                      const S3ListServiceHandler *handler,
1443                      void *callbackData);
1444                          
1445
1446 /** **************************************************************************
1447  * Bucket Functions
1448  ************************************************************************** **/
1449
1450 /**
1451  * Tests the existence of an S3 bucket, additionally returning the bucket's
1452  * location if it exists and is accessible.
1453  *
1454  * @param protocol gives the protocol to use for this request
1455  * @param uriStyle gives the URI style to use for this request
1456  * @param accessKeyId gives the Amazon Access Key ID for which to list owned
1457  *        buckets
1458  * @param secretAccessKey gives the Amazon Secret Access Key for which to list
1459  *        owned buckets
1460  * @param bucketName is the bucket name to test
1461  * @param locationConstraintReturnSize gives the number of bytes in the
1462  *        locationConstraintReturn parameter
1463  * @param locationConstraintReturn provides the location into which to write
1464  *        the name of the location constraint naming the geographic location
1465  *        of the S3 bucket.  This must have at least as many characters in it
1466  *        as specified by locationConstraintReturn, and should start out
1467  *        NULL-terminated.  On successful completion of this request, this
1468  *        will be set to the name of the geographic location of S3 bucket, or
1469  *        will be left as a zero-length string if no location was available.
1470  * @param requestContext if non-NULL, gives the S3RequestContext to add this
1471  *        request to, and does not perform the request immediately.  If NULL,
1472  *        performs the request immediately and synchronously.
1473  * @param handler gives the callbacks to call as the request is processed and
1474  *        completed 
1475  * @param callbackData will be passed in as the callbackData parameter to
1476  *        all callbacks for this request
1477  **/
1478 void S3_test_bucket(S3Protocol protocol, S3UriStyle uriStyle,
1479                     const char *accessKeyId, const char *secretAccessKey,
1480                     const char *bucketName, int locationConstraintReturnSize,
1481                     char *locationConstraintReturn,
1482                     S3RequestContext *requestContext,
1483                     const S3ResponseHandler *handler, void *callbackData);
1484
1485                            
1486 /**
1487  * Creates a new bucket.
1488  *
1489  * @param protocol gives the protocol to use for this request
1490  * @param accessKeyId gives the Amazon Access Key ID for which to list owned
1491  *        buckets
1492  * @param secretAccessKey gives the Amazon Secret Access Key for which to list
1493  *        owned buckets
1494  * @param bucketName is the name of the bucket to be created
1495  * @param cannedAcl gives the "REST canned ACL" to use for the created bucket
1496  * @param locationConstraint if non-NULL, gives the geographic location for
1497  *        the bucket to create.
1498  * @param requestContext if non-NULL, gives the S3RequestContext to add this
1499  *        request to, and does not perform the request immediately.  If NULL,
1500  *        performs the request immediately and synchronously.
1501  * @param handler gives the callbacks to call as the request is processed and
1502  *        completed 
1503  * @param callbackData will be passed in as the callbackData parameter to
1504  *        all callbacks for this request
1505  **/
1506 void S3_create_bucket(S3Protocol protocol, const char *accessKeyId,
1507                       const char *secretAccessKey, const char *bucketName, 
1508                       S3CannedAcl cannedAcl, const char *locationConstraint,
1509                       S3RequestContext *requestContext,
1510                       const S3ResponseHandler *handler, void *callbackData);
1511
1512
1513 /**
1514  * Deletes a bucket.  The bucket must be empty, or the status
1515  * S3StatusErrorBucketNotEmpty will result.
1516  *
1517  * @param protocol gives the protocol to use for this request
1518  * @param uriStyle gives the URI style to use for this request
1519  * @param accessKeyId gives the Amazon Access Key ID for which to list owned
1520  *        buckets
1521  * @param secretAccessKey gives the Amazon Secret Access Key for which to list
1522  *        owned buckets
1523  * @param bucketName is the name of the bucket to be deleted
1524  * @param requestContext if non-NULL, gives the S3RequestContext to add this
1525  *        request to, and does not perform the request immediately.  If NULL,
1526  *        performs the request immediately and synchronously.
1527  * @param handler gives the callbacks to call as the request is processed and
1528  *        completed 
1529  * @param callbackData will be passed in as the callbackData parameter to
1530  *        all callbacks for this request
1531  **/
1532 void S3_delete_bucket(S3Protocol protocol, S3UriStyle uriStyle,
1533                       const char *accessKeyId, const char *secretAccessKey,
1534                       const char *bucketName, S3RequestContext *requestContext,
1535                       const S3ResponseHandler *handler, void *callbackData);
1536
1537
1538 /**
1539  * Lists keys within a bucket.
1540  *
1541  * @param bucketContext gives the bucket and associated parameters for this
1542  *        request
1543  * @param prefix if present, gives a prefix for matching keys
1544  * @param marker if present, only keys occuring after this value will be
1545  *        listed
1546  * @param delimiter if present, causes keys that contain the same string
1547  *        between the prefix and the first occurrence of the delimiter to be
1548  *        rolled up into a single result element
1549  * @param maxkeys is the maximum number of keys to return
1550  * @param requestContext if non-NULL, gives the S3RequestContext to add this
1551  *        request to, and does not perform the request immediately.  If NULL,
1552  *        performs the request immediately and synchronously.
1553  * @param handler gives the callbacks to call as the request is processed and
1554  *        completed 
1555  * @param callbackData will be passed in as the callbackData parameter to
1556  *        all callbacks for this request
1557  **/
1558 void S3_list_bucket(const S3BucketContext *bucketContext,
1559                     const char *prefix, const char *marker, 
1560                     const char *delimiter, int maxkeys,
1561                     S3RequestContext *requestContext,
1562                     const S3ListBucketHandler *handler, void *callbackData);
1563
1564
1565 /** **************************************************************************
1566  * Object Functions
1567  ************************************************************************** **/
1568
1569 /**
1570  * Puts object data to S3.  This overwrites any existing object at that key;
1571  * note that S3 currently only supports full-object upload.  The data to
1572  * upload will be acquired by calling the handler's putObjectDataCallback.
1573  *
1574  * @param bucketContext gives the bucket and associated parameters for this
1575  *        request
1576  * @param key is the key of the object to put to
1577  * @param contentLength is required and gives the total number of bytes that
1578  *        will be put
1579  * @param putProperties optionally provides additional properties to apply to
1580  *        the object that is being put to
1581  * @param requestContext if non-NULL, gives the S3RequestContext to add this
1582  *        request to, and does not perform the request immediately.  If NULL,
1583  *        performs the request immediately and synchronously.
1584  * @param handler gives the callbacks to call as the request is processed and
1585  *        completed 
1586  * @param callbackData will be passed in as the callbackData parameter to
1587  *        all callbacks for this request
1588  **/
1589 void S3_put_object(const S3BucketContext *bucketContext, const char *key,
1590                    uint64_t contentLength,
1591                    const S3PutProperties *putProperties,
1592                    S3RequestContext *requestContext,
1593                    const S3PutObjectHandler *handler, void *callbackData);
1594                         
1595
1596 /**
1597  * Copies an object from one location to another.  The object may be copied
1598  * back to itself, which is useful for replacing metadata without changing
1599  * the object.
1600  *
1601  * @param bucketContext gives the source bucket and associated parameters for
1602  *        this request
1603  * @param key is the source key
1604  * @param destinationBucket gives the destination bucket into which to copy
1605  *        the object.  If NULL, the source bucket will be used.
1606  * @param destinationKey gives the destination key into which to copy the
1607  *        object.  If NULL, the source key will be used.
1608  * @param putProperties optionally provides properties to apply to the object
1609  *        that is being put to.  If not supplied (i.e. NULL is passed in),
1610  *        then the copied object will retain the metadata of the copied
1611  *        object.
1612  * @param lastModifiedReturn returns the last modified date of the copied
1613  *        object
1614  * @param eTagReturnSize specifies the number of bytes provided in the
1615  *        eTagReturn buffer
1616  * @param eTagReturn is a buffer into which the resulting eTag of the copied
1617  *        object will be written
1618  * @param handler gives the callbacks to call as the request is processed and
1619  *        completed 
1620  * @param callbackData will be passed in as the callbackData parameter to
1621  *        all callbacks for this request
1622  * @param requestContext if non-NULL, gives the S3RequestContext to add this
1623  *        request to, and does not perform the request immediately.  If NULL,
1624  *        performs the request immediately and synchronously.
1625  * @param handler gives the callbacks to call as the request is processed and
1626  *        completed 
1627  * @param callbackData will be passed in as the callbackData parameter to
1628  *        all callbacks for this request
1629  **/
1630 void S3_copy_object(const S3BucketContext *bucketContext,
1631                     const char *key, const char *destinationBucket,
1632                     const char *destinationKey,
1633                     const S3PutProperties *putProperties,
1634                     int64_t *lastModifiedReturn, int eTagReturnSize,
1635                     char *eTagReturn, S3RequestContext *requestContext,
1636                     const S3ResponseHandler *handler, void *callbackData);
1637
1638
1639 /**
1640  * Gets an object from S3.  The contents of the object are returned in the
1641  * handler's getObjectDataCallback.
1642  *
1643  * @param bucketContext gives the bucket and associated parameters for this
1644  *        request
1645  * @param key is the key of the object to get
1646  * @param getConditions if non-NULL, gives a set of conditions which must be
1647  *        met in order for the request to succeed
1648  * @param startByte gives the start byte for the byte range of the contents
1649  *        to be returned
1650  * @param byteCount gives the number of bytes to return; a value of 0
1651  *        indicates that the contents up to the end should be returned
1652  * @param requestContext if non-NULL, gives the S3RequestContext to add this
1653  *        request to, and does not perform the request immediately.  If NULL,
1654  *        performs the request immediately and synchronously.
1655  * @param handler gives the callbacks to call as the request is processed and
1656  *        completed 
1657  * @param callbackData will be passed in as the callbackData parameter to
1658  *        all callbacks for this request
1659  **/
1660 void S3_get_object(const S3BucketContext *bucketContext, const char *key,
1661                    const S3GetConditions *getConditions,
1662                    uint64_t startByte, uint64_t byteCount,
1663                    S3RequestContext *requestContext,
1664                    const S3GetObjectHandler *handler, void *callbackData);
1665
1666
1667 /**
1668  * Gets the response properties for the object, but not the object contents.
1669  *
1670  * @param bucketContext gives the bucket and associated parameters for this
1671  *        request
1672  * @param key is the key of the object to get the properties of
1673  * @param requestContext if non-NULL, gives the S3RequestContext to add this
1674  *        request to, and does not perform the request immediately.  If NULL,
1675  *        performs the request immediately and synchronously.
1676  * @param handler gives the callbacks to call as the request is processed and
1677  *        completed 
1678  * @param callbackData will be passed in as the callbackData parameter to
1679  *        all callbacks for this request
1680  **/
1681 void S3_head_object(const S3BucketContext *bucketContext, const char *key,
1682                     S3RequestContext *requestContext,
1683                     const S3ResponseHandler *handler, void *callbackData);
1684                          
1685 /**
1686  * Deletes an object from S3.
1687  *
1688  * @param bucketContext gives the bucket and associated parameters for this
1689  *        request
1690  * @param key is the key of the object to delete
1691  * @param requestContext if non-NULL, gives the S3RequestContext to add this
1692  *        request to, and does not perform the request immediately.  If NULL,
1693  *        performs the request immediately and synchronously.
1694  * @param handler gives the callbacks to call as the request is processed and
1695  *        completed 
1696  * @param callbackData will be passed in as the callbackData parameter to
1697  *        all callbacks for this request
1698  **/
1699 void S3_delete_object(const S3BucketContext *bucketContext, const char *key,
1700                       S3RequestContext *requestContext,
1701                       const S3ResponseHandler *handler, void *callbackData);
1702
1703
1704 /** **************************************************************************
1705  * Access Control List Functions
1706  ************************************************************************** **/
1707
1708 /**
1709  * Gets the ACL for the given bucket or object.
1710  *
1711  * @param bucketContext gives the bucket and associated parameters for this
1712  *        request
1713  * @param key is the key of the object to get the ACL of; or NULL to get the
1714  *        ACL of the bucket
1715  * @param ownerId must be supplied as a buffer of at least
1716  *        S3_MAX_GRANTEE_USER_ID_SIZE bytes, and will be filled in with the
1717  *        owner ID of the object/bucket
1718  * @param ownerDisplayName must be supplied as a buffer of at least
1719  *        S3_MAX_GRANTEE_DISPLAY_NAME_SIZE bytes, and will be filled in with
1720  *        the display name of the object/bucket
1721  * @param aclGrantCountReturn returns the number of S3AclGrant structures
1722  *        returned in the aclGrants parameter
1723  * @param aclGrants must be passed in as an array of at least
1724  *        S3_MAX_ACL_GRANT_COUNT S3AclGrant structures, which will be filled
1725  *        in with the grant information for the ACL
1726  * @param requestContext if non-NULL, gives the S3RequestContext to add this
1727  *        request to, and does not perform the request immediately.  If NULL,
1728  *        performs the request immediately and synchronously.
1729  * @param handler gives the callbacks to call as the request is processed and
1730  *        completed 
1731  * @param callbackData will be passed in as the callbackData parameter to
1732  *        all callbacks for this request
1733  **/
1734 void S3_get_acl(const S3BucketContext *bucketContext, const char *key, 
1735                 char *ownerId, char *ownerDisplayName,
1736                 int *aclGrantCountReturn, S3AclGrant *aclGrants, 
1737                 S3RequestContext *requestContext,
1738                 const S3ResponseHandler *handler, void *callbackData);
1739
1740
1741 /**
1742  * Sets the ACL for the given bucket or object.
1743  *
1744  * @param bucketContext gives the bucket and associated parameters for this
1745  *        request
1746  * @param key is the key of the object to set the ACL for; or NULL to set the
1747  *        ACL for the bucket
1748  * @param ownerId is the owner ID of the object/bucket.  Unfortunately, S3
1749  *        requires this to be valid and thus it must have been fetched by a
1750  *        previous S3 request, such as a list_buckets request.
1751  * @param ownerDisplayName is the owner display name of the object/bucket.
1752  *        Unfortunately, S3 requires this to be valid and thus it must have
1753  *        been fetched by a previous S3 request, such as a list_buckets
1754  *        request.
1755  * @param aclGrantCount is the number of ACL grants to set for the
1756  *        object/bucket
1757  * @param aclGrants are the ACL grants to set for the object/bucket
1758  * @param requestContext if non-NULL, gives the S3RequestContext to add this
1759  *        request to, and does not perform the request immediately.  If NULL,
1760  *        performs the request immediately and synchronously.
1761  * @param handler gives the callbacks to call as the request is processed and
1762  *        completed 
1763  * @param callbackData will be passed in as the callbackData parameter to
1764  *        all callbacks for this request
1765  **/
1766 void S3_set_acl(const S3BucketContext *bucketContext, const char *key, 
1767                 const char *ownerId, const char *ownerDisplayName,
1768                 int aclGrantCount, const S3AclGrant *aclGrants, 
1769                 S3RequestContext *requestContext,
1770                 const S3ResponseHandler *handler, void *callbackData);
1771
1772
1773 /** **************************************************************************
1774  * Server Access Log Functions
1775  ************************************************************************** **/
1776
1777 /**
1778  * Gets the service access logging settings for a bucket.  The service access
1779  * logging settings specify whether or not the S3 service will write service
1780  * access logs for requests made for the given bucket, and if so, several
1781  * settings controlling how these logs will be written.
1782  *
1783  * @param bucketContext gives the bucket and associated parameters for this
1784  *        request; this is the bucket for which service access logging is
1785  *        being requested
1786  * @param targetBucketReturn must be passed in as a buffer of at least
1787  *        (S3_MAX_BUCKET_NAME_SIZE + 1) bytes in length, and will be filled
1788  *        in with the target bucket name for access logging for the given
1789  *        bucket, which is the bucket into which access logs for the specified
1790  *        bucket will be written.  This is returned as an empty string if
1791  *        service access logging is not enabled for the given bucket.
1792  * @param targetPrefixReturn must be passed in as a buffer of at least
1793  *        (S3_MAX_KEY_SIZE + 1) bytes in length, and will be filled in
1794  *        with the key prefix for server access logs for the given bucket,
1795  *        or the empty string if no such prefix is specified.
1796  * @param aclGrantCountReturn returns the number of ACL grants that are
1797  *        associated with the server access logging for the given bucket.
1798  * @param aclGrants must be passed in as an array of at least
1799  *        S3_MAX_ACL_GRANT_COUNT S3AclGrant structures, and these will be
1800  *        filled in with the target grants associated with the server access
1801  *        logging for the given bucket, whose number is returned in the
1802  *        aclGrantCountReturn parameter.  These grants will be applied to the
1803  *        ACL of any server access logging log files generated by the S3
1804  *        service for the given bucket.
1805  * @param requestContext if non-NULL, gives the S3RequestContext to add this
1806  *        request to, and does not perform the request immediately.  If NULL,
1807  *        performs the request immediately and synchronously.
1808  * @param handler gives the callbacks to call as the request is processed and
1809  *        completed 
1810  * @param callbackData will be passed in as the callbackData parameter to
1811  *        all callbacks for this request
1812  **/
1813 void S3_get_server_access_logging(const S3BucketContext *bucketContext,
1814                                   char *targetBucketReturn,
1815                                   char *targetPrefixReturn,
1816                                   int *aclGrantCountReturn, 
1817                                   S3AclGrant *aclGrants,
1818                                   S3RequestContext *requestContext,
1819                                   const S3ResponseHandler *handler,
1820                                   void *callbackData);
1821                                   
1822
1823 /**
1824  * Sets the service access logging settings for a bucket.  The service access
1825  * logging settings specify whether or not the S3 service will write service
1826  * access logs for requests made for the given bucket, and if so, several
1827  * settings controlling how these logs will be written.
1828  *
1829  * @param bucketContext gives the bucket and associated parameters for this
1830  *        request; this is the bucket for which service access logging is
1831  *        being set
1832  * @param targetBucket gives the target bucket name for access logging for the
1833  *        given bucket, which is the bucket into which access logs for the
1834  *        specified bucket will be written.
1835  * @param targetPrefix is an option parameter which specifies the key prefix
1836  *        for server access logs for the given bucket, or NULL if no such
1837  *        prefix is to be used.
1838  * @param aclGrantCount specifies the number of ACL grants that are to be
1839  *        associated with the server access logging for the given bucket.
1840  * @param aclGrants is as an array of S3AclGrant structures, whose number is
1841  *        given by the aclGrantCount parameter.  These grants will be applied
1842  *        to the ACL of any server access logging log files generated by the
1843  *        S3 service for the given bucket.
1844  * @param requestContext if non-NULL, gives the S3RequestContext to add this
1845  *        request to, and does not perform the request immediately.  If NULL,
1846  *        performs the request immediately and synchronously.
1847  * @param handler gives the callbacks to call as the request is processed and
1848  *        completed 
1849  * @param callbackData will be passed in as the callbackData parameter to
1850  *        all callbacks for this request
1851  **/
1852 void S3_set_server_access_logging(const S3BucketContext *bucketContext,
1853                                   const char *targetBucket, 
1854                                   const char *targetPrefix, int aclGrantCount, 
1855                                   const S3AclGrant *aclGrants, 
1856                                   S3RequestContext *requestContext,
1857                                   const S3ResponseHandler *handler,
1858                                   void *callbackData);
1859                                   
1860
1861 #ifdef __cplusplus
1862 }
1863 #endif
1864
1865 #endif /* LIBS3_H */