mirror of
https://github.com/asterisk/asterisk.git
synced 2025-09-04 20:04:50 +00:00
3ea0d38396
This patch adds a new API to the Asterisk core that acts as a media cache. The core API itself is mostly a thin wrapper around some bucket API provided implementation that itself acts as the mechanism of retrieval for media. The media cache API in the core provides the following: * A very thin in-memory cache of the active bucket_file items. Unlike a more traditional cache, it provides no expiration mechanisms. Most queries that hit the in-memory cache will also call into the bucket implementations as well. The bucket implementations are responsible for determining whether or not the active record is active and valid. This makes sense for the most likely implementation of a media cache backend, i.e., HTTP. The HTTP layer itself is the actual arbiter of whether or not a record is truly active; as such, the in-memory cache in the core has to defer to it. * The ability to create new items in the media cache from local resources. This allows for re-creation of items in the cache on restart. * Synchronization of items in the media cache to the AstDB. This also includes various pieces of important metadata. The API provides sufficient access that higher level APIs, such as the file or app APIs, do not have to worry about the semantics of the bucket APIs when needing to playback a resource. In addition, this patch provides unit tests for the media cache API. The unit tests use a fake bucket backend to verify correctness. Change-Id: I11227abbf14d8929eeb140ddd101dd5c3820391e
478 lines
14 KiB
C
478 lines
14 KiB
C
/*
|
|
* Asterisk -- An open source telephony toolkit.
|
|
*
|
|
* Copyright (C) 2013, Digium, Inc.
|
|
*
|
|
* Joshua Colp <jcolp@digium.com>
|
|
*
|
|
* See http://www.asterisk.org for more information about
|
|
* the Asterisk project. Please do not directly contact
|
|
* any of the maintainers of this project for assistance;
|
|
* the project provides a web site, mailing lists and IRC
|
|
* channels for your use.
|
|
*
|
|
* This program is free software, distributed under the terms of
|
|
* the GNU General Public License Version 2. See the LICENSE file
|
|
* at the top of the source tree.
|
|
*/
|
|
|
|
/*! \file
|
|
* \brief Bucket File API
|
|
* \author Joshua Colp <jcolp@digium.com>
|
|
* \ref AstBucket
|
|
*/
|
|
|
|
/*!
|
|
* \page bucket AstBucket Bucket File API
|
|
*
|
|
* Bucket is an API which provides directory and file access in a generic fashion. It is
|
|
* implemented as a thin wrapper over the sorcery data access layer API and is written in
|
|
* a pluggable fashion to allow different backend storage mechanisms.
|
|
*
|
|
*/
|
|
|
|
#ifndef _ASTERISK_BUCKET_H
|
|
#define _ASTERISK_BUCKET_H
|
|
|
|
#if defined(__cplusplus) || defined(c_plusplus)
|
|
extern "C" {
|
|
#endif
|
|
|
|
#include "asterisk/sorcery.h"
|
|
|
|
/*! \brief Opaque structure for internal details about a scheme */
|
|
struct ast_bucket_scheme;
|
|
|
|
/*! \brief Bucket metadata structure, AO2 key value pair */
|
|
struct ast_bucket_metadata {
|
|
/*! \brief Name of the attribute */
|
|
const char *name;
|
|
/*! \brief Value of the attribute */
|
|
const char *value;
|
|
/*! \brief Storage for the above name and value */
|
|
char data[0];
|
|
};
|
|
|
|
/*! \brief Bucket structure, contains other buckets and files */
|
|
struct ast_bucket {
|
|
/*! \brief Sorcery object information */
|
|
SORCERY_OBJECT(details);
|
|
/*! \brief Scheme implementation in use */
|
|
struct ast_bucket_scheme *scheme_impl;
|
|
/*! \brief Stringfields */
|
|
AST_DECLARE_STRING_FIELDS(
|
|
/*! \brief Name of scheme in use */
|
|
AST_STRING_FIELD(scheme);
|
|
);
|
|
/*! \brief When this bucket was created */
|
|
struct timeval created;
|
|
/*! \brief When this bucket was last modified */
|
|
struct timeval modified;
|
|
/*! \brief Container of string URIs of buckets within this bucket */
|
|
struct ao2_container *buckets;
|
|
/*! \brief Container of string URIs of files within this bucket */
|
|
struct ao2_container *files;
|
|
};
|
|
|
|
/*! \brief Bucket file structure, contains reference to file and information about it */
|
|
struct ast_bucket_file {
|
|
/*! \brief Sorcery object information */
|
|
SORCERY_OBJECT(details);
|
|
/*! \brief Scheme implementation in use */
|
|
struct ast_bucket_scheme *scheme_impl;
|
|
/*! \brief Stringfields */
|
|
AST_DECLARE_STRING_FIELDS(
|
|
/*! \brief Name of scheme in use */
|
|
AST_STRING_FIELD(scheme);
|
|
);
|
|
/*! \brief When this file was created */
|
|
struct timeval created;
|
|
/*! \brief When this file was last modified */
|
|
struct timeval modified;
|
|
/*! \brief Container of metadata attributes about file */
|
|
struct ao2_container *metadata;
|
|
/*! \brief Local path to this file */
|
|
char path[PATH_MAX];
|
|
};
|
|
|
|
/*!
|
|
* \brief A callback function invoked when creating a file snapshot
|
|
*
|
|
* \param file Pointer to the file snapshot
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*/
|
|
typedef int (*bucket_file_create_cb)(struct ast_bucket_file *file);
|
|
|
|
/*!
|
|
* \brief A callback function invoked when destroying a file snapshot
|
|
*
|
|
* \param file Pointer to the file snapshot
|
|
*/
|
|
typedef void (*bucket_file_destroy_cb)(struct ast_bucket_file *file);
|
|
|
|
/*!
|
|
* \brief Initialize bucket support
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*/
|
|
int ast_bucket_init(void);
|
|
|
|
/*!
|
|
* \brief Register support for a specific scheme
|
|
*
|
|
* \param name Name of the scheme, used to find based on scheme in URIs
|
|
* \param bucket Sorcery wizard used for buckets
|
|
* \param file Sorcery wizard used for files
|
|
* \param create_cb Required file snapshot creation callback
|
|
* \param destroy_cb Optional file snapshot destruction callback
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*
|
|
* \note Once a scheme has been registered it can not be unregistered
|
|
*/
|
|
#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)
|
|
|
|
/*!
|
|
* \brief Register support for a specific scheme
|
|
*
|
|
* \param name Name of the scheme, used to find based on scheme in URIs
|
|
* \param bucket Sorcery wizard used for buckets
|
|
* \param file Sorcery wizard used for files
|
|
* \param create_cb Required file snapshot creation callback
|
|
* \param destroy_cb Optional file snapshot destruction callback
|
|
* \param module The module which implements this scheme
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*
|
|
* \note Once a scheme has been registered it can not be unregistered
|
|
*/
|
|
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);
|
|
|
|
/*!
|
|
* \brief Set a metadata attribute on a file to a specific value
|
|
*
|
|
* \param file The bucket file
|
|
* \param name Name of the attribute
|
|
* \param value Value of the attribute
|
|
*
|
|
* \retval 0 success
|
|
* \retval -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.
|
|
*/
|
|
int ast_bucket_file_metadata_set(struct ast_bucket_file *file, const char *name, const char *value);
|
|
|
|
/*!
|
|
* \brief Unset a specific metadata attribute on a file
|
|
*
|
|
* \param file The bucket file
|
|
* \param name Name of the attribute
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*/
|
|
int ast_bucket_file_metadata_unset(struct ast_bucket_file *file, const char *name);
|
|
|
|
/*!
|
|
* \brief Retrieve a metadata attribute from a file
|
|
*
|
|
* \param file The bucket file
|
|
* \param name Name of the attribute
|
|
*
|
|
* \retval non-NULL if found
|
|
* \retval NULL if not found
|
|
*
|
|
* \note The object is returned with reference count increased
|
|
*/
|
|
struct ast_bucket_metadata *ast_bucket_file_metadata_get(struct ast_bucket_file *file, const char *name);
|
|
|
|
/*!
|
|
* \brief Execute a callback function on the metadata associated with a file
|
|
* \since 14.0.0
|
|
*
|
|
* \param file The bucket file
|
|
* \param cb An ao2 callback function that will be called with each \c ast_bucket_metadata
|
|
* associated with \c file
|
|
* \param arg An optional argument to pass to \c cb
|
|
*/
|
|
void ast_bucket_file_metadata_callback(struct ast_bucket_file *file, ao2_callback_fn cb, void *arg);
|
|
|
|
/*!
|
|
* \brief Allocate a new bucket
|
|
*
|
|
* \param uri Complete URI for the bucket
|
|
*
|
|
* \param non-NULL success
|
|
* \param NULL failure
|
|
*
|
|
* \note This only creates a local bucket object, to persist in backend storage you must call
|
|
* ast_bucket_create
|
|
*/
|
|
struct ast_bucket *ast_bucket_alloc(const char *uri);
|
|
|
|
/*!
|
|
* \brief Create a new bucket in backend storage
|
|
*
|
|
* \param bucket The bucket
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*/
|
|
int ast_bucket_create(struct ast_bucket *bucket);
|
|
|
|
/*!
|
|
* \brief Clone a bucket
|
|
*
|
|
* This will create a copy of the passed in \c ast_bucket structure. While
|
|
* all properties of the \c ast_bucket structure are copied, any metadata
|
|
* in the original structure simply has its reference count increased.
|
|
*
|
|
* \param file The bucket to clone
|
|
*
|
|
* \retval non-NULL success
|
|
* \retval NULL failure
|
|
*
|
|
* \note This operation should be called prior to updating a bucket
|
|
* object, as \c ast_bucket instances are immutable
|
|
*/
|
|
struct ast_bucket *ast_bucket_clone(struct ast_bucket *bucket);
|
|
|
|
/*!
|
|
* \brief Delete a bucket from backend storage
|
|
*
|
|
* \param bucket The bucket
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*/
|
|
int ast_bucket_delete(struct ast_bucket *bucket);
|
|
|
|
/*!
|
|
* \brief Retrieve information about a bucket
|
|
*
|
|
* \param uri Complete URI of the bucket
|
|
*
|
|
* \retval non-NULL if found
|
|
* \retval NULL if not found
|
|
*
|
|
* \note The object is returned with reference count increased
|
|
*/
|
|
struct ast_bucket *ast_bucket_retrieve(const char *uri);
|
|
|
|
/*!
|
|
* \brief 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.
|
|
*
|
|
* \param bucket The bucket object to check
|
|
*
|
|
* \retval 0 if \c bucket is not stale
|
|
* \retval 1 if \c bucket is stale
|
|
*/
|
|
int ast_bucket_is_stale(struct ast_bucket *bucket);
|
|
|
|
/*!
|
|
* \brief Add an observer for bucket creation and deletion operations
|
|
*
|
|
* \param callbacks Implementation of the sorcery observer interface
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*
|
|
* \note You must be ready to accept observer invocations before this function is called
|
|
*/
|
|
int ast_bucket_observer_add(const struct ast_sorcery_observer *callbacks);
|
|
|
|
/*!
|
|
* \brief Remove an observer from bucket creation and deletion
|
|
*
|
|
* \param callbacks Implementation of the sorcery observer interface
|
|
*/
|
|
void ast_bucket_observer_remove(const struct ast_sorcery_observer *callbacks);
|
|
|
|
/*!
|
|
* \brief Get a JSON representation of a bucket
|
|
*
|
|
* \param bucket The specific bucket
|
|
*
|
|
* \retval non-NULL success
|
|
* \retval NULL failure
|
|
*
|
|
* \note The returned ast_json object must be unreferenced using ast_json_unref
|
|
*/
|
|
struct ast_json *ast_bucket_json(const struct ast_bucket *bucket);
|
|
|
|
/*!
|
|
* \brief Allocate a new bucket file
|
|
*
|
|
* \param uri Complete URI for the bucket file
|
|
*
|
|
* \param non-NULL success
|
|
* \param NULL failure
|
|
*
|
|
* \note This only creates a local bucket file object, to persist in backend storage you must call
|
|
* ast_bucket_file_create
|
|
*/
|
|
struct ast_bucket_file *ast_bucket_file_alloc(const char *uri);
|
|
|
|
/*!
|
|
* \brief Create a new bucket file in backend storage
|
|
*
|
|
* \param file The bucket file
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*/
|
|
int ast_bucket_file_create(struct ast_bucket_file *file);
|
|
|
|
/*!
|
|
* \brief Copy a bucket file to a new URI
|
|
*
|
|
* \param file The source bucket file
|
|
* \param uri The new URI
|
|
*
|
|
* \retval non-NULL success
|
|
* \retval 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
|
|
*
|
|
*/
|
|
struct ast_bucket_file *ast_bucket_file_copy(struct ast_bucket_file *file, const char *uri);
|
|
|
|
/*!
|
|
* \brief Clone a bucket file
|
|
*
|
|
* This will create a copy of the passed in \c ast_bucket_file structure. While
|
|
* all properties of the \c 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.
|
|
*
|
|
* \param file The bucket file to clone
|
|
*
|
|
* \retval non-NULL success
|
|
* \retval NULL failure
|
|
*
|
|
* \note This operation should be called prior to updating a bucket file
|
|
* object, as \c ast_bucket_file instances are immutable
|
|
*/
|
|
struct ast_bucket_file *ast_bucket_file_clone(struct ast_bucket_file *file);
|
|
|
|
/*!
|
|
* \brief Update an existing bucket file in backend storage
|
|
*
|
|
* \param file The bucket file
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*
|
|
* \note This operation will update both the actual content of the file and the metadata associated with it
|
|
*/
|
|
int ast_bucket_file_update(struct ast_bucket_file *file);
|
|
|
|
/*!
|
|
* \brief Delete a bucket file from backend storage
|
|
*
|
|
* \param file The bucket file
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*/
|
|
int ast_bucket_file_delete(struct ast_bucket_file *file);
|
|
|
|
/*!
|
|
* \brief Retrieve a bucket file
|
|
*
|
|
* \param uri Complete URI of the bucket file
|
|
*
|
|
* \retval non-NULL if found
|
|
* \retval NULL if not found
|
|
*
|
|
* \note The object is returned with reference count increased
|
|
*/
|
|
struct ast_bucket_file *ast_bucket_file_retrieve(const char *uri);
|
|
|
|
/*!
|
|
* \brief 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.
|
|
*
|
|
* \param bucket_file The bucket file object to check
|
|
*
|
|
* \retval 0 if \c bucket_file is not stale
|
|
* \retval 1 if \c bucket_file is stale
|
|
*/
|
|
int ast_bucket_file_is_stale(struct ast_bucket_file *file);
|
|
|
|
/*!
|
|
* \brief Add an observer for bucket file creation and deletion operations
|
|
*
|
|
* \param callbacks Implementation of the sorcery observer interface
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*
|
|
* \note You must be ready to accept observer invocations before this function is called
|
|
*/
|
|
int ast_bucket_file_observer_add(const struct ast_sorcery_observer *callbacks);
|
|
|
|
/*!
|
|
* \brief Remove an observer from bucket file creation and deletion
|
|
*
|
|
* \param callbacks Implementation of the sorcery observer interface
|
|
*/
|
|
void ast_bucket_file_observer_remove(const struct ast_sorcery_observer *callbacks);
|
|
|
|
/*!
|
|
* \brief Get a JSON representation of a bucket file
|
|
*
|
|
* \param file The specific bucket file
|
|
*
|
|
* \retval non-NULL success
|
|
* \retval NULL failure
|
|
*
|
|
* \note The returned ast_json object must be unreferenced using ast_json_unref
|
|
*/
|
|
struct ast_json *ast_bucket_file_json(const struct ast_bucket_file *file);
|
|
|
|
/*!
|
|
* \brief Common file snapshot creation callback for creating a temporary file
|
|
*
|
|
* \param file Pointer to the file snapshot
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*/
|
|
int ast_bucket_file_temporary_create(struct ast_bucket_file *file);
|
|
|
|
/*!
|
|
* \brief Common file snapshot destruction callback for deleting a temporary file
|
|
*
|
|
* \param file Pointer to the file snapshot
|
|
*/
|
|
void ast_bucket_file_temporary_destroy(struct ast_bucket_file *file);
|
|
|
|
#if defined(__cplusplus) || defined(c_plusplus)
|
|
}
|
|
#endif
|
|
|
|
#endif /* _ASTERISK_BUCKET_H */
|