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

Defines
#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 Documentation

#define S3_MAX_HOSTNAME_SIZE 255

************************************************************************** libs3.h

This file is part of libs3.

libs3 is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License.

In addition, as a special exception, the copyright holders give permission to link the code of this library and its programs with the OpenSSL library, and distribute linked combinations including the two.

libs3 is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License version 3 along with libs3, in a file named COPYING. If not, see <http://www.gnu.org/licenses/>. ************************************************************************** Overview --------

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

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

The general usage pattern of libs3 is:

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

All functions which send requests to S3 return their results via a set of callback functions which must be supplied to libs3 at the time that the request is initiated. libs3 will call these functions back in the thread calling the libs3 function if blocking requests are made (i.e., if the S3RequestContext for the function invocation is passed in as NULL). If an S3RequestContext is used to drive multiple S3 requests simultaneously, then the callbacks will be made from the thread which calls S3_runall_request_context() or S3_runonce_request_context(), or possibly from the thread which calls S3_destroy_request_context(), if S3 requests are in progress at the time that this function is called.

NOTE: Response headers from Amazon S3 are limited to 4K (2K of metas is all that Amazon supports, and libs3 allows Amazon an additional 2K of headers).

NOTE: Because HTTP and the S3 REST protocol are highly under-specified, libs3 must make some assumptions about the maximum length of certain HTTP elements (such as headers) that it will accept. While efforts have been made to enforce maximums which are beyond that expected to be needed by any user of S3, it is always possible that these maximums may be too low in some rare circumstances. Bug reports should this unlikely situation occur would be most appreciated.

Threading Rules ---------------

1. All arguments passed to any function must not be modified directly until the function returns. 2. All S3RequestContext and S3Request arguments passed to all functions may not be passed to any other libs3 function by any other thread until the function returns. 3. All functions may be called simultaneously by multiple threads as long as (1) and (2) are observed, EXCEPT for S3_initialize(), which must be called from one thread at a time only. 4. All callbacks will be made in the thread of the caller of the function which invoked them, so the caller of all libs3 functions should not hold locks that it would try to re-acquire in a callback, as this may deadlock. ************************************************************************** Constants S3_MAX_HOSTNAME_SIZE is the maximum size we allow for a host name

#define S3_DEFAULT_HOSTNAME "s3.amazonaws.com"

This is the default hostname that is being used for the S3 requests

#define S3_MAX_BUCKET_NAME_SIZE 255

S3_MAX_BUCKET_NAME_SIZE is the maximum size of a bucket name.

#define S3_MAX_KEY_SIZE 1024

S3_MAX_KEY_SIZE is the maximum size of keys that Amazon S3 supports.

#define S3_MAX_METADATA_SIZE 2048

S3_MAX_METADATA_SIZE is the maximum number of bytes allowed for x-amz-meta header names and values in any request passed to Amazon S3

#define S3_METADATA_HEADER_NAME_PREFIX "x-amz-meta-"

S3_METADATA_HEADER_NAME_PREFIX is the prefix of an S3 "meta header"

#define S3_MAX_METADATA_COUNT (S3_MAX_METADATA_SIZE / (sizeof(S3_METADATA_HEADER_NAME_PREFIX "nv") - 1))

S3_MAX_METADATA_COUNT is the maximum number of x-amz-meta- headers that could be included in a request to S3. The smallest meta header is "x-amz-meta-n: v". Since S3 doesn't count the ": " against the total, the smallest amount of data to count for a header would be the length of "x-amz-meta-nv".

#define S3_MAX_ACL_GRANT_COUNT 100

S3_MAX_ACL_GRANT_COUNT is the maximum number of ACL grants that may be set on a bucket or object at one time. It is also the maximum number of ACL grants that the XML ACL parsing routine will parse.

#define S3_MAX_GRANTEE_EMAIL_ADDRESS_SIZE 128

This is the maximum number of characters (including terminating \0) that libs3 supports in an ACL grantee email address.

#define S3_MAX_GRANTEE_USER_ID_SIZE 128

This is the maximum number of characters (including terminating \0) that libs3 supports in an ACL grantee user id.

#define S3_MAX_GRANTEE_DISPLAY_NAME_SIZE 128

This is the maximum number of characters (including terminating \0) that libs3 supports in an ACL grantee user display name.

Defines

Define Documentation