Functions¶
ms3_library_init()¶
-
void
ms3_library_init
(void)¶ Initializes the library for use. Should be called before any threads are spawned.
ms3_library_deinit()¶
-
void
ms3_library_deinit
(void)¶ Cleans up the library, typically for the end of the application’s execution.
ms3_library_init_malloc()¶
-
uint8_t
ms3_library_init_malloc
(ms3_malloc_callback m, ms3_free_callback f, ms3_realloc_callback r, ms3_strdup_callback s, ms3_calloc_callback c)¶ Initialize the library for use with custom allocator replacement functions. These functions are also fed into libcurl. The function prototypes should be as follows:
-
void *
ms3_malloc_callback
(size_t size)¶ To replace
malloc()
.
-
void
ms3_free_callback
(void *ptr)¶ To replace
free()
.
-
void *
ms3_realloc_callback
(void *ptr, size_t size)¶ To replace
realloc()
.
-
char *
ms3_strdup_callback
(const char *str)¶ To replace
strdup()
.
-
void *
ms3_calloc_callback
(size_t nmemb, size_t size)¶ To replace
calloc()
.
Should be called before any threads are spawned. All parameters are required or the function will fail.
Remember: With great power comes great responsibility.
Parameters: - m – The malloc callback
- f – The free callback
- r – The realloc callback
- s – The strdup callback
- c – The calloc callback
Returns: 0
on success,MS3_ERR_PARAMETER
if a parameter isNULL
-
void *
ms3_init()¶
-
ms3_st *
ms3_init
(const char *s3key, const char *s3secret, const char *region, const char *base_domain)¶ Initializes a
ms3_st
object. This object should only be used in the thread that created it because it reuses connections. But it is safe to have otherms3_st
objects running at the same time in other threads.Note
You MUST call
ms3_library_init()
before spawning threads when using this access method.Parameters: - s3key – The AWS access key
- s3secret – The AWS secret key
- region – The AWS region to use (such as
us-east-1
) - base_domain – A domain name to use if AWS S3 is not the desired server (set to
NULL
for S3)
Returns: A newly allocated marias3 object
ms3_deinit()¶
ms3_server_error()¶
ms3_error()¶
ms3_debug()¶
-
void
ms3_debug
()¶ Enables and disables debugging output on stderr. Each call toggles enable / disable.
- Note::
- This enables/disables globally for the library
ms3_list()¶
-
uint8_t
ms3_list
(ms3_st *ms3, const char *bucket, const char *prefix, ms3_list_st **list)¶ Retrieves a list of files from a given S3 bucket and fills it into a
ms3_list_st
.The list generated is the eqivilent of a recursive directory listing but only has files in it, no entries for directories.
The list will automatically be freed on the next list/list_dir call or
ms3_deinit()
Parameters: - ms3 – The marias3 object
- bucket – The bucket name to use
- prefix – An optional path/file prefix to use (
NULL
for all files) - list – A pointer to a pointer that will contain the returned list
Returns: 0
on success, a positive integer on failure
Example¶
char *s3key= getenv("S3KEY");
char *s3secret= getenv("S3SECRET");
char *s3region= getenv("S3REGION");
char *s3bucket= getenv("S3BUCKET");
ms3_list_st *list= NULL, *list_it= NULL;
uint8_t res;
ms3_library_init();
ms3_st *ms3= ms3_thread_init(s3key, s3secret, s3region, NULL);
res= ms3_list(ms3, s3bucket, NULL, &list);
if (res)
{
printf("Error occurred: %d\n", res);
return;
}
list_it= list;
while(list_it)
{
printf("File: %s, size: %ld, tstamp: %ld\n", list_it->key, list_it->length, list_it->created);
list_it= list_it->next;
}
ms3_deinit(ms3);
ms3_list_dir()¶
-
uint8_t
ms3_list_dir
(ms3_st *ms3, const char *bucket, const char *prefix, ms3_list_st **list)¶ Retrieves a list of files from a given S3 bucket and fills it into a
ms3_list_st
.The list generated will automatically add the delimiter
/
and therefore filter up to the first/
after the prefix. Unlikems3_list()
it includes directory entries. This is the eqivilent of doing a regular directory listing in a current directory (as designated byprefix
).The list will automatically be freed on the next list/list_dir call or
ms3_deinit()
Parameters: - ms3 – The marias3 object
- bucket – The bucket name to use
- prefix – An optional path/file prefix to use (
NULL
for all files) - list – A pointer to a pointer that will contain the returned list
Returns: 0
on success, a positive integer on failure
ms3_list_free()¶
-
void
ms3_list_free
(ms3_list_st *list)¶ Deprecated since version 3.1.1: Now a NULL operation which be removed in 4.0
A NULL operation, previously free’d
ms3_list()
, but this is now done internally onms3_deinit()
or when a new list is requested.Parameters: - list – The list to free
ms3_put()¶
-
uint8_t
ms3_put
(ms3_st *ms3, const char *bucket, const char *key, const uint8_t *data, size_t length)¶ Puts a binary data from a given pointer into S3 at a given key/filename. If an existing key/file exists with the same name this will be overwritten.
Parameters: - ms3 – The marias3 object
- bucket – The bucket name to use
- key – The key/filename to create/overwrite
- data – A pointer to the data to write
- length – The length of the data to write
Returns: 0
on success, a positive integer on failure
Example¶
char *s3key= getenv("S3KEY");
char *s3secret= getenv("S3SECRET");
char *s3region= getenv("S3REGION");
char *s3bucket= getenv("S3BUCKET");
uint8_t res;
const char *test_string= "Another one bites the dust";
ms3_library_init();
ms3_st *ms3= ms3_thread_init(s3key, s3secret, s3region, NULL);
res= ms3_put(ms3, s3bucket, "test/ms3.txt", (const uint8_t*)test_string, strlen(test_string));
if (res)
{
printf("Error occurred: %d\n", res);
return;
}
ms3_deinit(ms3);
ms3_copy()¶
-
uint8_t
ms3_copy
(ms3_st *ms3, const char *source_bucket, const char *source_key, const char *dest_bucket, const char *dest_key)¶ S3 internally copies an object from a source bucket and key to a destination bucket and key.
Parameters: - ms3 – The marias3 object
- source_bucket – The bucket where the source object is
- source_key – The key/filename of the source object
- dest_bucket – The destination bucket (can be the same as source)
- dest_key – The destination key/filename
Returns: 0
on success, a positive integer on failure
ms3_move()¶
-
uint8_t
ms3_move
(ms3_st *ms3, const char *source_bucket, const char *source_key, const char *dest_bucket, const char *dest_key)¶ Moves an object from source to destination. Internally the library performs a copy and if successful performs a delete on the source object.
Parameters: - ms3 – The marias3 object
- source_bucket – The bucket where the source object is
- source_key – The key/filename of the source object
- dest_bucket – The destination bucket (can be the same as source)
- dest_key – The destination key/filename
Returns: 0
on success, a positive integer on failure
ms3_get()¶
-
uint8_t
ms3_get
(ms3_st *ms3, const char *bucket, const char *key, uint8_t **data, size_t *length)¶ Retrieves a given object from S3.
Note
The application is expected to free the resulting data pointer after use
Parameters: - ms3 – The marias3 object
- bucket – The bucket name to use
- key – The key/filename to retrieve
- data – A pointer to a pointer the data to be retrieved into
- length – A pointer to the data length
Returns: 0
on success, a positive integer on failure
Example¶
char *s3key= getenv("S3KEY");
char *s3secret= getenv("S3SECRET");
char *s3region= getenv("S3REGION");
char *s3bucket= getenv("S3BUCKET");
uint8_t res;
uint8_t *data= NULL;
size_t length;
ms3_library_init();
ms3_st *ms3= ms3_thread_init(s3key, s3secret, s3region, NULL);
res= ms3_get(ms3, s3bucket, "test/ms3.txt", &data, &length);
if (res)
{
printf("Error occurred: %d\n", res);
return;
}
printf("File contents: %s\n", data);
printf("File length: %ld\n", length);
ms3_free(data);
ms3_deinit(ms3);
ms3_free()¶
ms3_set_option()¶
-
uint8_t
ms3_set_option
(ms3_st *ms3, ms3_set_option_t option, void *value)¶ Sets a given connection option. See
ms3_set_option_t
for a list of options.Parameters: - ms3 – The marias3 object
- option – The option to set
- value – A pointer to the value for the option (if required,
NULL
if not)
Returns: 0
on success, a positive integer on failure
ms3_delete()¶
-
uint8_t
ms3_delete
(ms3_st *ms3, const char *bucket, const char *key)¶ Deletes an object from an S3 bucket
Parameters: - ms3 – The marias3 object
- bucket – The bucket name to use
- key – The key/filename to delete
Returns: 0
on success, a positive integer on failure
Example¶
char *s3key= getenv("S3KEY");
char *s3secret= getenv("S3SECRET");
char *s3region= getenv("S3REGION");
char *s3bucket= getenv("S3BUCKET");
uint8_t res;
ms3_library_init();
ms3_st *ms3= ms3_thread_init(s3key, s3secret, s3region, NULL);
res = ms3_delete(ms3, s3bucket, "test/ms3.txt");
if (res)
{
printf("Error occurred: %d\n", res);
return;
}
ms3_deinit(ms3);
ms3_status()¶
-
uint8_t
ms3_status
(ms3_st *ms3, const char *bucket, const char *key, ms3_status_st *status)¶ Retreives the status of a given filename/key into a
ms3_status_st
object. Will return an error if not found.Parameters: - ms3 – The marias3 object
- bucket – The bucket name to use
- key – The key/filename to status check
- status – A status object to fill
Returns: 0
on success, a positive integer on failure
Example¶
char *s3key= getenv("S3KEY");
char *s3secret= getenv("S3SECRET");
char *s3region= getenv("S3REGION");
char *s3bucket= getenv("S3BUCKET");
uint8_t res;
ms3_status_st status;
ms3_library_init();
ms3_st *ms3= ms3_thread_init(s3key, s3secret, s3region, NULL);
res= ms3_status(ms3, s3bucket, "test/ms3.txt", &status);
if (res)
{
printf("Error occurred: %d\n", res);
return;
}
printf("File length: %ld\n", status.length);
printf("File timestamp: %ld\n", status.created);
ms3_deinit(ms3);