mirror of https://github.com/mariadb-corporation/libmarias3.git synced 2025-09-11 02:31:50 +03:00

Files

Andrew Hutchings d23e1ad9df Fix ms3_get_content_type() (#128 )

Now uses the legacy curl method of header callbacks. #ifdef guard
removed.

2024-09-27 10:23:30 +01:00

13 KiB

Raw Permalink Blame History

Functions

ms3_library_init()

Initializes the library for use. Should be called before any threads are spawned.

ms3_library_deinit()

Cleans up the library, typically for the end of the application's execution.

ms3_library_init_malloc()

Initialize the library for use with custom allocator replacement functions. These functions are also fed into libcurl. The function prototypes should be as follows:

To replace malloc().

To replace free().

To replace realloc().

To replace strdup().

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.

param m

The malloc callback

param f

The free callback

param r

The realloc callback

param s

The strdup callback

param c

The calloc callback

returns

0 on success, MS3_ERR_PARAMETER if a parameter is NULL

ms3_init()

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 other ms3_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.

param s3key

The AWS access key

param s3secret

The AWS secret key

param region

The AWS region to use (such as us-east-1)

param 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()

Cleans up and frees a ms3_st object.

param ms3

The marias3 object

ms3_server_error()

Returns the last error message from the S3 server or underlying Curl library.

param ms3

The marias3 object

returns

The error message string or NULL if there is no message.

ms3_error()

Returns an error message for a given error code

param errcode

The error code to translate

returns

The error message

ms3_debug()

Enables and disables debugging output on stderr.

param debug_state

Set to 1 to enable debugging, zero to disable.

Note::

This enables/disables globally for the library

ms3_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

param ms3

The marias3 object

param bucket

The bucket name to use

param prefix

An optional path/file prefix to use (NULL for all files)

param 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()

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. Unlike ms3_list it includes directory entries. This is the eqivilent of doing a regular directory listing in a current directory (as designated by prefix).

The list will automatically be freed on the next list/list_dir call or ms3_deinit

param ms3

The marias3 object

param bucket

The bucket name to use

param prefix

An optional path/file prefix to use (NULL for all files)

param list

A pointer to a pointer that will contain the returned list

returns

0 on success, a positive integer on failure

ms3_list_free()

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 on ms3_deinit or when a new list is requested.

param list

The list to free

ms3_put()

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.

param ms3

The marias3 object

param bucket

The bucket name to use

param key

The key/filename to create/overwrite

param data

A pointer to the data to write

param 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()

S3 internally copies an object from a source bucket and key to a destination bucket and key.

param ms3

The marias3 object

param source_bucket

The bucket where the source object is

param source_key

The key/filename of the source object

param dest_bucket

The destination bucket (can be the same as source)

param dest_key

The destination key/filename

returns

0 on success, a positive integer on failure

ms3_move()

Moves an object from source to destination. Internally the library performs a copy and if successful performs a delete on the source object.

param ms3

The marias3 object

param source_bucket

The bucket where the source object is

param source_key

The key/filename of the source object

param dest_bucket

The destination bucket (can be the same as source)

param dest_key

The destination key/filename

returns

0 on success, a positive integer on failure

ms3_get()

Retrieves a given object from S3.

Note

The application is expected to free the resulting data pointer after use

param ms3

The marias3 object

param bucket

The bucket name to use

param key

The key/filename to retrieve

param data

A pointer to a pointer the data to be retrieved into

param 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()

Used to free the data allocated by ms3_get.

param data

The data to free

ms3_set_option()

Sets a given connection option. See ms3_set_option_t for a list of options.

param ms3

The marias3 object

param option

The option to set

param 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()

Deletes an object from an S3 bucket

param ms3

The marias3 object

param bucket

The bucket name to use

param 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()

Retreives the status of a given filename/key into a ms3_status_st object. Will return an error if not found.

param ms3

The marias3 object

param bucket

The bucket name to use

param key

The key/filename to status check

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

ms3_set_content_type()

Sets the Content-Type: header for subsequent PUT requests. Note that this is not copied, so it should remain in scope for each ms3_put() call. Setting this to NULL will clear the Content-Type header to the default.

param ms3

The marias3 object

param content_type

The mime type to set

ms3_get_content_type()

Gets the Content-Type: header for the previous GET request response from the S3 server. The memory for this is part of the ms3_st object and should not be freed by the application. The contents will be reset on each GET request.

param ms3

The marias3 object

param content_type

The mime type for the previous request

13 KiB Raw Permalink Blame History

Functions

ms3_library_init()

ms3_library_deinit()

ms3_library_init_malloc()

ms3_init()

ms3_deinit()

ms3_server_error()

ms3_error()

ms3_debug()

ms3_list()

Example

ms3_list_dir()

ms3_list_free()

ms3_put()

Example

ms3_copy()

ms3_move()

ms3_get()

Example

ms3_free()

ms3_set_option()

ms3_delete()

Example

ms3_status()

Example

ms3_set_content_type()

ms3_get_content_type()

13 KiB

Raw Permalink Blame History