Introduction

The public AWS4C functions are divided into four groups:

• Configuration Functions
• S3 Interface Functions
• SQS Interface Functions
• I/O Buffer Functions

Configuration Functions

aws_init

void aws_init ( )

Initialize the library. This function must be the first AWS4C function called.

aws_read_config

int aws_read_config ( char * const id )

Read AWS authentication records.

Parameters:

• id - user ID

This function loads AWS authentication credentials corresponding to the user identified by the user ID from ~/.awsAuth file. All subsequent S3 and SQS operations will use these credentials. This function must be called before the first SQS or S3 operation. It can be called again when the credential switch is required.

See the Developer's Guide for details about the ~/.awsAuth file.

aws_set_debug

void aws_set_debug ( int d )

Enable debugging output.

Parameters:

• d - non-zero parameter causes debugging output to be printed

This function controls whether debugging output is printed out. Calling it with a non-zero parameter results in the printing of the debug messages.

aws_set_rrs

void aws_set_rrs ( int rrs )

Enable Reduced Redundancy Storage

Parameters:

• rrs - non-zero parameter causes all subsequent PUTs to use RRS

This function controls whether normal or reduced redundancy storage class is used for the put operations. Calling this function with non-zero parameter will force all subsequent PUT operations to use reduced redundancy storage. Reduced redundancy objects are not replicated as many times as the standard S3 objects, hence they are slightly cheaper to store.

aws_set_id

aws_set_key

aws_set_keyid

IO Buffer Functions

IOBuf

IOBuf is a data structure that holds the data to be sent to the AWS service or results of AWS operation. The structure has the following fields of interest:

• int code - operation result code. Standard HTTP result codes
• char * result - textual representation of HTTP result code such as "404 Not found"
• char * lastMod - date and time of the last modification applied to the object
• char * eTag - object signature eTag
• int contentLen - length of the object returned by the service
• int len - actual length of data retrieved from the service

aws_iobuf_new

IOBuf* aws_iobuf_new ( )

Create a new I/O buffer.

Returns:

a newly allocated I/O buffer

aws_iobuf_append

void aws_iobuf_append ( IOBuf * B, char * d, int len )

Append data to I/O buffer.

Parameters:

• B - I/O buffer
• d - pointer to the data to be appended
• len - length of the data to be appended

aws_iobuf_getline

int aws_iobuf_getline ( IOBuf * B, char * Line, int size)

Read the next line from the buffer.

Parameters:

• B - I/O buffer
• Line - character array to store the next line from the buffer
• size - size of the character array line

Returns:

Number of characters read or 0

aws_iobuf_free

void aws_iobuf_free ( IOBuf * bf )

Release IO Buffer.

Parameters:

• bf - I/O buffer to be deleted

S3 Interface Functions

s3_set_host

void s3_set_host ( char *const str )

Sets S3 host. The AWS4C sets the default host to ‘s3.amazonaws.com`; you only need to call this function if you want to use a different Simple Storage Services host.

Parameters:

• str - hostname

s3_set_bucket

void s3_set_bucket ( char *const str )

Select current S3 bucket. All subsequent S3 operations will be performed on this bucket.

Parameters:

• str - bucket ID

s3_set_mime

void s3_set_mime ( char * const str )

Set the mime type for the S3 put operation. All subsequent S3 PUT operations will use this mime type.

s3_set_acl

Set access control policy for the S3 put operations. The access control policy should be one of the Amazon's canned access control policies such as 'public-read', 'public-read-write' or 'authenticated-read'

s3_get

int s3_get ( IOBuf * b, char * const file)

Downloads the file from the current bucket and places the data into the I/O buffer.

Parameters:

• b - I/O buffer
• file - filename

Returns:

0 on success or an error code on failure. Also check the return code in I/O buffer. For more information see Checking results of AWS operation.

s3_get

int s3_delete ( IOBuf * b, char * const file)

Deletes the specified file from the current bucket.

Parameters:

• b - I/O buffer
• file - filename

Returns:

0 on success or an error code on failure. Also check the return code in I/O buffer. If operation was performed successfully the HTTP return code should be "204 No Content". For more information see Checking results of AWS operation.

Note: If the specified file doesn't not exist in the bucket the operation still will complete successfully with the return code 0 and HTTP return code 204.

s3_put

int s3_put ( IOBuf * b, char * const file )

Uploads the file into currently selected bucket and takes the data from I/O buffer.

Parameters:

• b - I/O buffer
• file - filename

Returns:

0 on success or an error code on failure. Also check the return code in I/O buffer. For more information see Checking results of AWS operation.

SQS Interface Functions

sqs_create_queue

int sqs_create_queue ( IOBuf * b, char * const name )

Create an SQS queue.

Parameters:

• b - I/O buffer
• name - queue name

Returns:

0 on success, or an error code on failure

sqs_list_queues

int sqs_list_queues ( IOBuf b ,char * const prefix )

Retrieves URL of the queue.

Parameters:

• b - I/O buffer
• prefix - queue prefix. better use the whole name

Returns:

0 on success, or an error code on failure

URL is placed into the I/O buffer. Use aws_iobuf_get_line to retrieve it

sqs_get_queueattributes

int sqs_get_queueattributes ( IOBuf * b, char * url, int * timeOut, int * nMesg )

Retrieve queue’s default visibility timeout and approximate number of messages.

Parameters:

• b - I/O buffer
• url - queue url. Use sqs_list_queues to retrieve
• timeOut - points to a variable that will get the value of queue visibility timeout
• nMesg - points to a variable that will get the value of approximate number of messages in the queue

Returns:

0 on success, or an error code on failure

Note that given the distributed nature of the SQS service it is not possible to get the exact number of messages in the queue. This function tries its best to get an approximate number, which is good enough for capacity estimation.

sqs_set_queuevisibilitytimeout

int sqs_set_queuevisibilitytimeout ( IOBuf * b, char * url, int sec )

Set the queue's visibility timeout.

Parameters:

• b - I/O buffer
• url - queue url. Use sqs_list_queues to retrieve
• sec - queue visibility timeout in seconds

Returns:

0 on success, or an error code on failure

sqs_send_message

int sqs_send_message ( IOBuf * b, char * const url, char *const msg )

Send a message to the queue.

Parameters:

• b - I/O buffer
• url - queue url. Use sqs_list_queues to retrieve
• msg - a message to send

Returns:

0 on success, or an error code on failure

sqs_get_message

int sqs_get_message ( IOBuf * b, char const url, char * id )

Retrieve a message from the queue.

Parameters:

• b - I/O buffer
• url - queue url. Use sqs_list_queues to retrieve
• id - message receipt handle.

Returns:

0 on success, or an error code on failure

Message contents are placed into the I/O buffer Caller must allocate at least 1024 bytes of memory for the receipt.

sqs_delete_message

int sqs_delete_message ( IOBuf * bf, char *const url, char * receipt )

Delete a processed message from the queue.

Parameters:

• bf - I/O buffer
• url - queue url. Use sqs_list_queues to retrieve
• receipt - message receipt handle.

Returns:

0 on success, or an error code on failure