bucket.h File Reference

Bucket File API. More...

#include "asterisk/sorcery.h"

Include dependency graph for bucket.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ast_bucket
	Bucket structure, contains other buckets and files. More...
struct	ast_bucket_file
	Bucket file structure, contains reference to file and information about it. More...
struct	ast_bucket_metadata
	Bucket metadata structure, AO2 key value pair. More...

Macros
#define	ast_bucket_scheme_register(name, bucket, file, create_cb, destroy_cb)   __ast_bucket_scheme_register(name, bucket, file, create_cb, destroy_cb, AST_MODULE_SELF)
	Register support for a specific scheme. More...

Typedefs
typedef int(*	bucket_file_create_cb) (struct ast_bucket_file *file)
	A callback function invoked when creating a file snapshot. More...
typedef void(*	bucket_file_destroy_cb) (struct ast_bucket_file *file)
	A callback function invoked when destroying a file snapshot. More...

Functions
int	__ast_bucket_scheme_register (const char *name, struct ast_sorcery_wizard *bucket, struct ast_sorcery_wizard *file, bucket_file_create_cb create_cb, bucket_file_destroy_cb destroy_cb, struct ast_module *module)
	Register support for a specific scheme. More...
struct ast_bucket *	ast_bucket_alloc (const char *uri)
	Allocate a new bucket. More...
struct ast_bucket *	ast_bucket_clone (struct ast_bucket *bucket)
	Clone a bucket. More...
int	ast_bucket_create (struct ast_bucket *bucket)
	Create a new bucket in backend storage. More...
int	ast_bucket_delete (struct ast_bucket *bucket)
	Delete a bucket from backend storage. More...
struct ast_bucket_file *	ast_bucket_file_alloc (const char *uri)
	Allocate a new bucket file. More...
struct ast_bucket_file *	ast_bucket_file_clone (struct ast_bucket_file *file)
	Clone a bucket file. More...
struct ast_bucket_file *	ast_bucket_file_copy (struct ast_bucket_file *file, const char *uri)
	Copy a bucket file to a new URI. More...
int	ast_bucket_file_create (struct ast_bucket_file *file)
	Create a new bucket file in backend storage. More...
int	ast_bucket_file_delete (struct ast_bucket_file *file)
	Delete a bucket file from backend storage. More...
int	ast_bucket_file_is_stale (struct ast_bucket_file *file)
	Retrieve whether or not the backing datastore views the bucket file as stale. More...
struct ast_json *	ast_bucket_file_json (const struct ast_bucket_file *file)
	Get a JSON representation of a bucket file. More...
void	ast_bucket_file_metadata_callback (struct ast_bucket_file *file, ao2_callback_fn cb, void *arg)
	Execute a callback function on the metadata associated with a file. More...
struct ast_bucket_metadata *	ast_bucket_file_metadata_get (struct ast_bucket_file *file, const char *name)
	Retrieve a metadata attribute from a file. More...
int	ast_bucket_file_metadata_set (struct ast_bucket_file *file, const char *name, const char *value)
	Set a metadata attribute on a file to a specific value. More...
int	ast_bucket_file_metadata_unset (struct ast_bucket_file *file, const char *name)
	Unset a specific metadata attribute on a file. More...
int	ast_bucket_file_observer_add (const struct ast_sorcery_observer *callbacks)
	Add an observer for bucket file creation and deletion operations. More...
void	ast_bucket_file_observer_remove (const struct ast_sorcery_observer *callbacks)
	Remove an observer from bucket file creation and deletion. More...
struct ast_bucket_file *	ast_bucket_file_retrieve (const char *uri)
	Retrieve a bucket file. More...
int	ast_bucket_file_temporary_create (struct ast_bucket_file *file)
	Common file snapshot creation callback for creating a temporary file. More...
void	ast_bucket_file_temporary_destroy (struct ast_bucket_file *file)
	Common file snapshot destruction callback for deleting a temporary file. More...
int	ast_bucket_file_update (struct ast_bucket_file *file)
	Update an existing bucket file in backend storage. More...
int	ast_bucket_init (void)
	Initialize bucket support. More...
int	ast_bucket_is_stale (struct ast_bucket *bucket)
	Retrieve whether or not the backing datastore views the bucket as stale. More...
struct ast_json *	ast_bucket_json (const struct ast_bucket *bucket)
	Get a JSON representation of a bucket. More...
int	ast_bucket_observer_add (const struct ast_sorcery_observer *callbacks)
	Add an observer for bucket creation and deletion operations. More...
void	ast_bucket_observer_remove (const struct ast_sorcery_observer *callbacks)
	Remove an observer from bucket creation and deletion. More...
struct ast_bucket *	ast_bucket_retrieve (const char *uri)
	Retrieve information about a bucket. More...

Detailed Description

Bucket File API.

Author

Joshua Colp jcolp.nosp@m.@dig.nosp@m.ium.c.nosp@m.om AstBucket

Definition in file bucket.h.

Macro Definition Documentation

ast_bucket_scheme_register

#define ast_bucket_scheme_register	(		name,
			bucket,
			file,
			create_cb,
			destroy_cb
	)		__ast_bucket_scheme_register(name, bucket, file, create_cb, destroy_cb, AST_MODULE_SELF)

Register support for a specific scheme.

Parameters

name	Name of the scheme, used to find based on scheme in URIs
bucket	Sorcery wizard used for buckets
file	Sorcery wizard used for files
create_cb	Required file snapshot creation callback
destroy_cb	Optional file snapshot destruction callback

Return values

0	success
-1	failure

Note

Once a scheme has been registered it can not be unregistered

Definition at line 137 of file bucket.h.

Referenced by AST_TEST_DEFINE(), and load_module().

Typedef Documentation

bucket_file_create_cb

typedef int(* bucket_file_create_cb) (struct ast_bucket_file *file)

A callback function invoked when creating a file snapshot.

Parameters

file	Pointer to the file snapshot

Return values

0	success
-1	failure

Definition at line 106 of file bucket.h.

bucket_file_destroy_cb

typedef void(* bucket_file_destroy_cb) (struct ast_bucket_file *file)

A callback function invoked when destroying a file snapshot.

Parameters

file	Pointer to the file snapshot

Definition at line 113 of file bucket.h.

Function Documentation

__ast_bucket_scheme_register()

int __ast_bucket_scheme_register	(	const char *	name,
		struct ast_sorcery_wizard *	bucket,
		struct ast_sorcery_wizard *	file,
		bucket_file_create_cb	create_cb,
		bucket_file_destroy_cb	destroy_cb,
		struct ast_module *	module
	)

Register support for a specific scheme.

Parameters

name	Name of the scheme, used to find based on scheme in URIs
bucket	Sorcery wizard used for buckets
file	Sorcery wizard used for files
create_cb	Required file snapshot creation callback
destroy_cb	Optional file snapshot destruction callback
module	The module which implements this scheme

Return values

0	success
-1	failure

Note

Once a scheme has been registered it can not be unregistered

Definition at line 277 of file bucket.c.

References ao2_alloc, ao2_cleanup, ao2_find, ao2_link_flags, ast_module_shutdown_ref, ast_strlen_zero, ast_verb, ast_bucket_scheme::bucket, ast_sorcery_wizard::create, ast_sorcery_wizard::delete, ast_bucket_scheme::file, lock, NULL, OBJ_KEY, OBJ_NOLOCK, RAII_VAR, ast_sorcery_wizard::retrieve_id, and SCOPED_AO2WRLOCK.

{
   SCOPED_AO2WRLOCK(lock, schemes);
   RAII_VAR(struct ast_bucket_scheme *, scheme, NULL, ao2_cleanup);

   if (ast_strlen_zero(name) || !bucket || !file ||
       !bucket->create || !bucket->delete || !bucket->retrieve_id ||
       (!bucket->create && !create_cb)) {
      return -1;
   }

   scheme = ao2_find(schemes, name, OBJ_KEY | OBJ_NOLOCK);
   if (scheme) {
      return -1;
   }

   scheme = ao2_alloc(sizeof(*scheme) + strlen(name) + 1, NULL);
   if (!scheme) {
      return -1;
   }

   strcpy(scheme->name, name);
   scheme->bucket = bucket;
   scheme->file = file;
   scheme->create = create_cb;
   scheme->destroy = destroy_cb;

   ao2_link_flags(schemes, scheme, OBJ_NOLOCK);

   ast_verb(2, "Registered bucket scheme '%s'\n", name);

   ast_module_shutdown_ref(module);

   return 0;
}

ast_bucket_alloc()

struct ast_bucket* ast_bucket_alloc

(

const char *

uri

)

Allocate a new bucket.

Parameters

uri	Complete URI for the bucket
non-NULL	success
NULL	failure

Note

This only creates a local bucket object, to persist in backend storage you must call ast_bucket_create

Definition at line 431 of file bucket.c.

References ao2_cleanup, ao2_find, ao2_ref, ast_alloca, ast_copy_string(), ast_sorcery_alloc(), ast_strdupa, ast_string_field_set, ast_strlen_zero, ast_bucket_scheme::bucket, len(), NULL, OBJ_KEY, RAII_VAR, ast_bucket::scheme, ast_bucket::scheme_impl, state, and tmp().

Referenced by AST_TEST_DEFINE(), and bucket_test_wizard_retrieve_id().

{
#ifdef HAVE_URIPARSER
   UriParserStateA state;
   UriUriA full_uri;
   size_t len;
#else
   char *tmp = ast_strdupa(uri);
#endif
   char *uri_scheme;
   RAII_VAR(struct ast_bucket_scheme *, scheme, NULL, ao2_cleanup);
   struct ast_bucket *bucket;

   if (ast_strlen_zero(uri)) {
      return NULL;
   }

#ifdef HAVE_URIPARSER
   state.uri = &full_uri;
   if (uriParseUriA(&state, uri) != URI_SUCCESS ||
      !full_uri.scheme.first || !full_uri.scheme.afterLast ||
      !full_uri.pathTail) {
      uriFreeUriMembersA(&full_uri);
      return NULL;
   }

   len = (full_uri.scheme.afterLast - full_uri.scheme.first) + 1;
   uri_scheme = ast_alloca(len);
   ast_copy_string(uri_scheme, full_uri.scheme.first, len);

   uriFreeUriMembersA(&full_uri);
#else
   uri_scheme = tmp;
   if (!(tmp = strchr(uri_scheme, ':'))) {
      return NULL;
   }
   *tmp = '\0';
#endif

   scheme = ao2_find(schemes, uri_scheme, OBJ_KEY);
   if (!scheme) {
      return NULL;
   }

   bucket = ast_sorcery_alloc(bucket_sorcery, "bucket", uri);
   if (!bucket) {
      return NULL;
   }

   ao2_ref(scheme, +1);
   bucket->scheme_impl = scheme;

   ast_string_field_set(bucket, scheme, uri_scheme);

   return bucket;
}

ast_bucket_clone()

struct ast_bucket* ast_bucket_clone

(

struct ast_bucket *

bucket

)

Clone a bucket.

This will create a copy of the passed in ast_bucket structure. While all properties of the ast_bucket structure are copied, any metadata in the original structure simply has its reference count increased.

Parameters

file	The bucket to clone

Return values

non-NULL	success
NULL	failure

Note

This operation should be called prior to updating a bucket object, as ast_bucket instances are immutable

Definition at line 510 of file bucket.c.

References ast_sorcery_copy().

Referenced by AST_TEST_DEFINE().

{
   return ast_sorcery_copy(bucket_sorcery, bucket);
}

ast_bucket_create()

int ast_bucket_create

(

struct ast_bucket *

bucket

)

Create a new bucket in backend storage.

Parameters

bucket

The bucket

Return values

0	success
-1	failure

Definition at line 488 of file bucket.c.

References ast_sorcery_create().

Referenced by AST_TEST_DEFINE().

{
   return ast_sorcery_create(bucket_sorcery, bucket);
}

ast_bucket_delete()

int ast_bucket_delete

(

struct ast_bucket *

bucket

)

Delete a bucket from backend storage.

Parameters

bucket

The bucket

Return values

0	success
-1	failure

Definition at line 539 of file bucket.c.

References ast_sorcery_delete().

Referenced by AST_TEST_DEFINE().

{
   return ast_sorcery_delete(bucket_sorcery, bucket);
}

ast_bucket_file_alloc()

struct ast_bucket_file* ast_bucket_file_alloc

(

const char *

uri

)

Allocate a new bucket file.

Parameters

uri	Complete URI for the bucket file
non-NULL	success
NULL	failure

Note

This only creates a local bucket file object, to persist in backend storage you must call ast_bucket_file_create

Definition at line 663 of file bucket.c.

References ao2_cleanup, ao2_find, ao2_ref, ast_alloca, ast_copy_string(), ast_sorcery_alloc(), ast_strdupa, ast_string_field_set, ast_strlen_zero, ast_bucket_scheme::file, len(), NULL, OBJ_KEY, RAII_VAR, ast_bucket_file::scheme, ast_bucket_file::scheme_impl, state, and tmp().

Referenced by ast_bucket_file_copy(), ast_media_cache_create_or_update(), AST_TEST_DEFINE(), bucket_http_test_wizard_retrieve_id(), bucket_http_wizard_retrieve_id(), bucket_test_wizard_retrieve_id(), and media_cache_item_populate_from_astdb().

{
#ifdef HAVE_URIPARSER
   UriParserStateA state;
   UriUriA full_uri;
   size_t len;
#else
   char *tmp = ast_strdupa(uri);
#endif
   char *uri_scheme;
   RAII_VAR(struct ast_bucket_scheme *, scheme, NULL, ao2_cleanup);
   struct ast_bucket_file *file;

   if (ast_strlen_zero(uri)) {
      return NULL;
   }

#ifdef HAVE_URIPARSER
   state.uri = &full_uri;
   if (uriParseUriA(&state, uri) != URI_SUCCESS ||
      !full_uri.scheme.first || !full_uri.scheme.afterLast ||
      !full_uri.pathTail) {
      uriFreeUriMembersA(&full_uri);
      return NULL;
   }

   len = (full_uri.scheme.afterLast - full_uri.scheme.first) + 1;
   uri_scheme = ast_alloca(len);
   ast_copy_string(uri_scheme, full_uri.scheme.first, len);

   uriFreeUriMembersA(&full_uri);
#else
   uri_scheme = tmp;
   if (!(tmp = strchr(uri_scheme, ':'))) {
      return NULL;
   }
   *tmp = '\0';
#endif

   scheme = ao2_find(schemes, uri_scheme, OBJ_KEY);
   if (!scheme) {
      return NULL;
   }

   file = ast_sorcery_alloc(bucket_sorcery, "file", uri);
   if (!file) {
      return NULL;
   }

   ao2_ref(scheme, +1);
   file->scheme_impl = scheme;

   ast_string_field_set(file, scheme, uri_scheme);

   if (scheme->create && scheme->create(file)) {
      ao2_ref(file, -1);
      return NULL;
   }

   return file;
}

ast_bucket_file_clone()

struct ast_bucket_file* ast_bucket_file_clone

(

struct ast_bucket_file *

file

)

Clone a bucket file.

This will create a copy of the passed in ast_bucket_file structure. While all properties of the ast_bucket_file structure are copied, any metadata in the original structure simply has its reference count increased. Note that this copies the structure, not the underlying file.

Parameters

file	The bucket file to clone

Return values

non-NULL	success
NULL	failure

Note

This operation should be called prior to updating a bucket file object, as ast_bucket_file instances are immutable

Definition at line 810 of file bucket.c.

References ast_sorcery_copy().

Referenced by ast_media_cache_create_or_update(), and AST_TEST_DEFINE().

{
   return ast_sorcery_copy(bucket_sorcery, file);
}

ast_bucket_file_copy()

struct ast_bucket_file* ast_bucket_file_copy	(	struct ast_bucket_file *	file,
		const char *	uri
	)

Copy a bucket file to a new URI.

Parameters

file	The source bucket file
uri	The new URI

Return values

non-NULL	success
NULL	failure

Note

This operation stages things locally, you must call ast_bucket_file_create on the file that is returned to commit the copy to backend storage

Definition at line 791 of file bucket.c.

References ao2_cleanup, ao2_container_clone, ao2_ref, ast_bucket_file_alloc(), bucket_copy(), copy(), ast_bucket_file::metadata, NULL, ast_bucket_file::path, and RAII_VAR.

Referenced by AST_TEST_DEFINE().

{
   RAII_VAR(struct ast_bucket_file *, copy, ast_bucket_file_alloc(uri), ao2_cleanup);

   if (!copy) {
      return NULL;
   }

   ao2_cleanup(copy->metadata);
   copy->metadata = ao2_container_clone(file->metadata, 0);
   if (!copy->metadata ||
      bucket_copy(file->path, copy->path)) {
      return NULL;
   }

   ao2_ref(copy, +1);
   return copy;
}

ast_bucket_file_create()

int ast_bucket_file_create

(

struct ast_bucket_file *

file

)

Create a new bucket file in backend storage.

Parameters

file	The bucket file

Return values

0	success
-1	failure

Definition at line 725 of file bucket.c.

References ast_sorcery_create().

Referenced by ast_media_cache_create_or_update(), and AST_TEST_DEFINE().

{
   return ast_sorcery_create(bucket_sorcery, file);
}

ast_bucket_file_delete()

int ast_bucket_file_delete

(

struct ast_bucket_file *

file

)

Delete a bucket file from backend storage.

Parameters

file	The bucket file

Return values

0	success
-1	failure

Definition at line 844 of file bucket.c.

References ast_sorcery_delete().

Referenced by ast_media_cache_delete(), ast_media_cache_retrieve(), AST_TEST_DEFINE(), and bucket_file_cleanup().

{
   return ast_sorcery_delete(bucket_sorcery, file);
}

ast_bucket_file_is_stale()

int ast_bucket_file_is_stale

(

struct ast_bucket_file *

file

)

Retrieve whether or not the backing datastore views the bucket file as stale.

Since

14.0.0

This function will ask whatever data storage backs the bucket file's schema type if the current instance of the object is stale. It will not update the bucket file object itself, as said objects are immutable. If the caller of this function would like to update the object, it should perform a retrieve operation.

Parameters

bucket_file

The bucket file object to check

Return values

0	if bucket_file is not stale
1	if bucket_file is stale

Definition at line 824 of file bucket.c.

References ast_sorcery_is_stale().

Referenced by ast_media_cache_retrieve(), and AST_TEST_DEFINE().

{
   return ast_sorcery_is_stale(bucket_sorcery, file);
}

ast_bucket_file_json()

struct ast_json* ast_bucket_file_json

(

const struct ast_bucket_file *

file

)

Get a JSON representation of a bucket file.

Parameters

file	The specific bucket file

Return values

non-NULL	success
NULL	failure

Note

The returned ast_json object must be unreferenced using ast_json_unref

Definition at line 849 of file bucket.c.

References ao2_iterator_destroy(), ao2_iterator_init(), ao2_iterator_next, ao2_ref, ast_json_object_create(), ast_json_object_set(), ast_json_ref(), ast_json_string_create(), ast_json_unref(), ast_sorcery_object_get_id(), ast_sorcery_objectset_json_create(), id, ast_bucket_file::metadata, ast_bucket_metadata::name, NULL, RAII_VAR, value, and ast_bucket_metadata::value.

Referenced by AST_TEST_DEFINE().

{
   RAII_VAR(struct ast_json *, json, NULL, ast_json_unref);
   struct ast_json *id, *metadata;
   struct ao2_iterator i;
   struct ast_bucket_metadata *attribute;
   int res = 0;

   json = ast_sorcery_objectset_json_create(bucket_sorcery, file);
   if (!json) {
      return NULL;
   }

   id = ast_json_string_create(ast_sorcery_object_get_id(file));
   if (!id) {
      return NULL;
   }

   if (ast_json_object_set(json, "id", id)) {
      return NULL;
   }

   metadata = ast_json_object_create();
   if (!metadata) {
      return NULL;
   }

   if (ast_json_object_set(json, "metadata", metadata)) {
      return NULL;
   }

   i = ao2_iterator_init(file->metadata, 0);
   for (; (attribute = ao2_iterator_next(&i)); ao2_ref(attribute, -1)) {
      struct ast_json *value = ast_json_string_create(attribute->value);

      if (!value || ast_json_object_set(metadata, attribute->name, value)) {
         res = -1;
         break;
      }
   }
   ao2_iterator_destroy(&i);

   if (res) {
      return NULL;
   }

   ast_json_ref(json);
   return json;
}

ast_bucket_file_metadata_callback()

void ast_bucket_file_metadata_callback	(	struct ast_bucket_file *	file,
		ao2_callback_fn	cb,
		void *	arg
	)

Execute a callback function on the metadata associated with a file.

Since

14.0.0

Parameters

file	The bucket file
cb	An ao2 callback function that will be called with each ast_bucket_metadata associated with file
arg	An optional argument to pass to cb

Definition at line 364 of file bucket.c.

References ao2_callback, and ast_bucket_file::metadata.

Referenced by media_cache_item_sync_to_astdb().

{
   ao2_callback(file->metadata, 0, cb, arg);
}

ast_bucket_file_metadata_get()

struct ast_bucket_metadata* ast_bucket_file_metadata_get	(	struct ast_bucket_file *	file,
		const char *	name
	)

Retrieve a metadata attribute from a file.

Parameters

file	The bucket file
name	Name of the attribute

Return values

non-NULL	if found
NULL	if not found

Note

The object is returned with reference count increased

Definition at line 359 of file bucket.c.

References ao2_find, ast_bucket_file::metadata, and OBJ_KEY.

Referenced by AST_TEST_DEFINE(), bucket_file_always_revalidate(), bucket_file_expired(), bucket_file_set_expiration(), bucket_file_update_path(), and bucket_http_wizard_is_stale().

{
   return ao2_find(file->metadata, name, OBJ_KEY);
}

ast_bucket_file_metadata_set()

int ast_bucket_file_metadata_set	(	struct ast_bucket_file *	file,
		const char *	name,
		const char *	value
	)

Set a metadata attribute on a file to a specific value.

Parameters

file	The bucket file
name	Name of the attribute
value	Value of the attribute

Return values

0	success
-1	failure

Note

This function will overwrite an existing attribute of the same name, unless an error occurs. If an error occurs the existing attribute is left alone.

Definition at line 334 of file bucket.c.

References ao2_cleanup, ao2_find, ao2_link, bucket_metadata_alloc(), ast_bucket_file::metadata, OBJ_KEY, OBJ_NODATA, OBJ_UNLINK, and RAII_VAR.

Referenced by ast_media_cache_create_or_update(), AST_TEST_DEFINE(), bucket_file_set_expiration(), bucket_file_update_path(), curl_header_callback(), and media_cache_item_populate_from_astdb().

{
   RAII_VAR(struct ast_bucket_metadata *, metadata, bucket_metadata_alloc(name, value), ao2_cleanup);

   if (!metadata) {
      return -1;
   }

   ao2_find(file->metadata, name, OBJ_NODATA | OBJ_UNLINK | OBJ_KEY);
   ao2_link(file->metadata, metadata);

   return 0;
}

ast_bucket_file_metadata_unset()

int ast_bucket_file_metadata_unset	(	struct ast_bucket_file *	file,
		const char *	name
	)

Unset a specific metadata attribute on a file.

Parameters

file	The bucket file
name	Name of the attribute

Return values

0	success
-1	failure

Definition at line 348 of file bucket.c.

References ao2_cleanup, ao2_find, ast_bucket_file::metadata, OBJ_KEY, OBJ_UNLINK, and RAII_VAR.

Referenced by AST_TEST_DEFINE().

{
   RAII_VAR(struct ast_bucket_metadata *, metadata, ao2_find(file->metadata, name, OBJ_UNLINK | OBJ_KEY), ao2_cleanup);

   if (!metadata) {
      return -1;
   }

   return 0;
}

ast_bucket_file_observer_add()

int ast_bucket_file_observer_add

(

const struct ast_sorcery_observer *

callbacks

)

Add an observer for bucket file creation and deletion operations.

Parameters

callbacks

Implementation of the sorcery observer interface

Return values

0	success
-1	failure

Note

You must be ready to accept observer invocations before this function is called

Definition at line 829 of file bucket.c.

References ast_sorcery_observer_add().

{
   return ast_sorcery_observer_add(bucket_sorcery, "file", callbacks);
}

ast_bucket_file_observer_remove()

void ast_bucket_file_observer_remove

(

const struct ast_sorcery_observer *

callbacks

)

Remove an observer from bucket file creation and deletion.

Parameters

callbacks

Implementation of the sorcery observer interface

Definition at line 834 of file bucket.c.

References ast_sorcery_observer_remove().

{
   ast_sorcery_observer_remove(bucket_sorcery, "file", callbacks);
}

ast_bucket_file_retrieve()

struct ast_bucket_file* ast_bucket_file_retrieve

(

const char *

uri

)

Retrieve a bucket file.

Parameters

uri	Complete URI of the bucket file

Return values

non-NULL	if found
NULL	if not found

Note

The object is returned with reference count increased

Definition at line 815 of file bucket.c.

References ast_sorcery_retrieve_by_id(), ast_strlen_zero, and NULL.

Referenced by ast_media_cache_exists(), ast_media_cache_retrieve(), and AST_TEST_DEFINE().

{
   if (ast_strlen_zero(uri)) {
      return NULL;
   }

   return ast_sorcery_retrieve_by_id(bucket_sorcery, "file", uri);
}

ast_bucket_file_temporary_create()

int ast_bucket_file_temporary_create

(

struct ast_bucket_file *

file

)

Common file snapshot creation callback for creating a temporary file.

Parameters

file	Pointer to the file snapshot

Return values

0	success
-1	failure

Definition at line 899 of file bucket.c.

References ast_config_AST_CACHE_DIR, and ast_bucket_file::path.

Referenced by AST_TEST_DEFINE(), bucket_http_test_wizard_retrieve_id(), bucket_http_wizard_retrieve_id(), and load_module().

{
   int fd;

   snprintf(file->path, sizeof(file->path), "%s/bucket-XXXXXX", ast_config_AST_CACHE_DIR);

   fd = mkstemp(file->path);
   if (fd < 0) {
      return -1;
   }

   close(fd);
   return 0;
}

ast_bucket_file_temporary_destroy()

void ast_bucket_file_temporary_destroy

(

struct ast_bucket_file *

file

)

Common file snapshot destruction callback for deleting a temporary file.

Parameters

file	Pointer to the file snapshot

Definition at line 914 of file bucket.c.

References AO2_STRING_FIELD_CMP_FN, AO2_STRING_FIELD_HASH_FN, ast_strlen_zero, ast_bucket_scheme::name, and ast_bucket_file::path.

Referenced by load_module().

{
   if (!ast_strlen_zero(file->path)) {
      unlink(file->path);
   }
}

ast_bucket_file_update()

int ast_bucket_file_update

(

struct ast_bucket_file *

file

)

Update an existing bucket file in backend storage.

Parameters

file	The bucket file

Return values

0	success
-1	failure

Note

This operation will update both the actual content of the file and the metadata associated with it

Definition at line 839 of file bucket.c.

References ast_sorcery_update().

Referenced by AST_TEST_DEFINE().

{
   return ast_sorcery_update(bucket_sorcery, file);
}

ast_bucket_init()

int ast_bucket_init

(

void

)

Initialize bucket support.

Return values

0	success
-1	failure

Definition at line 954 of file bucket.c.

References __ast_sorcery_wizard_register(), AO2_ALLOC_OPT_LOCK_RWLOCK, ao2_container_alloc_hash, ast_log, ast_register_cleanup(), ast_sorcery_apply_default, AST_SORCERY_APPLY_FAIL, ast_sorcery_object_field_register, ast_sorcery_object_field_register_custom, ast_sorcery_object_register, ast_sorcery_object_set_copy_handler(), ast_sorcery_open, bucket_alloc(), bucket_cleanup(), bucket_copy_handler(), bucket_file_alloc(), bucket_file_copy_handler(), FLDSET, LOG_ERROR, NULL, OPT_STRINGFIELD_T, SCHEME_BUCKETS, STRFLDSET, timeval_str2struct(), and timeval_struct2str().

Referenced by asterisk_daemon().

{
   ast_register_cleanup(&bucket_cleanup);

   schemes = ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_RWLOCK, 0, SCHEME_BUCKETS,
      ast_bucket_scheme_hash_fn, NULL, ast_bucket_scheme_cmp_fn);
   if (!schemes) {
      ast_log(LOG_ERROR, "Failed to create container for Bucket schemes\n");
      return -1;
   }

   if (__ast_sorcery_wizard_register(&bucket_wizard, NULL)) {
      ast_log(LOG_ERROR, "Failed to register sorcery wizard for 'bucket' intermediary\n");
      return -1;
   }

   if (__ast_sorcery_wizard_register(&bucket_file_wizard, NULL)) {
      ast_log(LOG_ERROR, "Failed to register sorcery wizard for 'file' intermediary\n");
      return -1;
   }

   if (!(bucket_sorcery = ast_sorcery_open())) {
      ast_log(LOG_ERROR, "Failed to create sorcery instance for Bucket support\n");
      return -1;
   }

   if (ast_sorcery_apply_default(bucket_sorcery, "bucket", "bucket", NULL) == AST_SORCERY_APPLY_FAIL) {
      ast_log(LOG_ERROR, "Failed to apply intermediary for 'bucket' object type in Bucket sorcery\n");
      return -1;
   }

   if (ast_sorcery_object_register(bucket_sorcery, "bucket", bucket_alloc, NULL, NULL)) {
      ast_log(LOG_ERROR, "Failed to register 'bucket' object type in Bucket sorcery\n");
      return -1;
   }

   ast_sorcery_object_field_register(bucket_sorcery, "bucket", "scheme", "", OPT_STRINGFIELD_T, 0, STRFLDSET(struct ast_bucket, scheme));
   ast_sorcery_object_field_register_custom(bucket_sorcery, "bucket", "created", "", timeval_str2struct, timeval_struct2str, NULL, 0, FLDSET(struct ast_bucket, created));
   ast_sorcery_object_field_register_custom(bucket_sorcery, "bucket", "modified", "", timeval_str2struct, timeval_struct2str, NULL, 0, FLDSET(struct ast_bucket, modified));
   ast_sorcery_object_set_copy_handler(bucket_sorcery, "bucket", bucket_copy_handler);

   if (ast_sorcery_apply_default(bucket_sorcery, "file", "bucket_file", NULL) == AST_SORCERY_APPLY_FAIL) {
      ast_log(LOG_ERROR, "Failed to apply intermediary for 'file' object type in Bucket sorcery\n");
      return -1;
   }

   if (ast_sorcery_object_register(bucket_sorcery, "file", bucket_file_alloc, NULL, NULL)) {
      ast_log(LOG_ERROR, "Failed to register 'file' object type in Bucket sorcery\n");
      return -1;
   }

   ast_sorcery_object_field_register(bucket_sorcery, "file", "scheme", "", OPT_STRINGFIELD_T, 0, STRFLDSET(struct ast_bucket_file, scheme));
   ast_sorcery_object_field_register_custom(bucket_sorcery, "file", "created", "", timeval_str2struct, timeval_struct2str, NULL, 0, FLDSET(struct ast_bucket_file, created));
   ast_sorcery_object_field_register_custom(bucket_sorcery, "file", "modified", "", timeval_str2struct, timeval_struct2str, NULL, 0, FLDSET(struct ast_bucket_file, modified));
   ast_sorcery_object_set_copy_handler(bucket_sorcery, "file", bucket_file_copy_handler);

   return 0;
}

ast_bucket_is_stale()

int ast_bucket_is_stale

(

struct ast_bucket *

bucket

)

Retrieve whether or not the backing datastore views the bucket as stale.

Since

14.0.0

This function will ask whatever data storage backs the bucket's schema type if the current instance of the object is stale. It will not update the bucket object itself, as said objects are immutable. If the caller of this function would like to update the object, it should perform a retrieve operation.

Parameters

bucket

The bucket object to check

Return values

0	if bucket is not stale
1	if bucket is stale

Definition at line 524 of file bucket.c.

References ast_sorcery_is_stale().

Referenced by AST_TEST_DEFINE().

{
   return ast_sorcery_is_stale(bucket_sorcery, bucket);
}

ast_bucket_json()

struct ast_json* ast_bucket_json

(

const struct ast_bucket *

bucket

)

Get a JSON representation of a bucket.

Parameters

bucket

The specific bucket

Return values

non-NULL	success
NULL	failure

Note

The returned ast_json object must be unreferenced using ast_json_unref

Definition at line 544 of file bucket.c.

References ao2_iterator_destroy(), ao2_iterator_init(), ao2_iterator_next, ao2_ref, AO2_STRING_FIELD_CMP_FN, AO2_STRING_FIELD_HASH_FN, ast_json_array_append(), ast_json_array_create(), ast_json_object_set(), ast_json_ref(), ast_json_string_create(), ast_json_unref(), ast_sorcery_object_get_id(), ast_sorcery_objectset_json_create(), ast_bucket::buckets, ast_bucket::files, id, ast_bucket_scheme::name, NULL, and RAII_VAR.

Referenced by AST_TEST_DEFINE().

{
   RAII_VAR(struct ast_json *, json, NULL, ast_json_unref);
   struct ast_json *id, *files, *buckets;
   struct ao2_iterator i;
   char *uri;
   int res = 0;

   json = ast_sorcery_objectset_json_create(bucket_sorcery, bucket);
   if (!json) {
      return NULL;
   }

   id = ast_json_string_create(ast_sorcery_object_get_id(bucket));
   if (!id) {
      return NULL;
   }

   if (ast_json_object_set(json, "id", id)) {
      return NULL;
   }

   buckets = ast_json_array_create();
   if (!buckets) {
      return NULL;
   }

   if (ast_json_object_set(json, "buckets", buckets)) {
      return NULL;
   }

   i = ao2_iterator_init(bucket->buckets, 0);
   for (; (uri = ao2_iterator_next(&i)); ao2_ref(uri, -1)) {
      struct ast_json *bucket_uri = ast_json_string_create(uri);

      if (!bucket_uri || ast_json_array_append(buckets, bucket_uri)) {
         res = -1;
         ao2_ref(uri, -1);
         break;
      }
   }
   ao2_iterator_destroy(&i);

   if (res) {
      return NULL;
   }

   files = ast_json_array_create();
   if (!files) {
      return NULL;
   }

   if (ast_json_object_set(json, "files", files)) {
      return NULL;
   }

   i = ao2_iterator_init(bucket->files, 0);
   for (; (uri = ao2_iterator_next(&i)); ao2_ref(uri, -1)) {
      struct ast_json *file_uri = ast_json_string_create(uri);

      if (!file_uri || ast_json_array_append(files, file_uri)) {
         res = -1;
         ao2_ref(uri, -1);
         break;
      }
   }
   ao2_iterator_destroy(&i);

   if (res) {
      return NULL;
   }

   ast_json_ref(json);
   return json;
}

ast_bucket_observer_add()

int ast_bucket_observer_add

(

const struct ast_sorcery_observer *

callbacks

)

Add an observer for bucket creation and deletion operations.

Parameters

callbacks

Implementation of the sorcery observer interface

Return values

0	success
-1	failure

Note

You must be ready to accept observer invocations before this function is called

Definition at line 529 of file bucket.c.

References ast_sorcery_observer_add().

{
   return ast_sorcery_observer_add(bucket_sorcery, "bucket", callbacks);
}

ast_bucket_observer_remove()

void ast_bucket_observer_remove

(

const struct ast_sorcery_observer *

callbacks

)

Remove an observer from bucket creation and deletion.

Parameters

callbacks

Implementation of the sorcery observer interface

Definition at line 534 of file bucket.c.

References ast_sorcery_observer_remove().

{
   ast_sorcery_observer_remove(bucket_sorcery, "bucket", callbacks);
}

ast_bucket_retrieve()

struct ast_bucket* ast_bucket_retrieve

(

const char *

uri

)

Retrieve information about a bucket.

Parameters

uri	Complete URI of the bucket

Return values

non-NULL	if found
NULL	if not found

Note

The object is returned with reference count increased

Definition at line 515 of file bucket.c.

References ast_sorcery_retrieve_by_id(), ast_strlen_zero, and NULL.

Referenced by AST_TEST_DEFINE().

{
   if (ast_strlen_zero(uri)) {
      return NULL;
   }

   return ast_sorcery_retrieve_by_id(bucket_sorcery, "bucket", uri);
}