diff options
Diffstat (limited to 'include/asterisk/media_cache.h')
-rw-r--r-- | include/asterisk/media_cache.h | 175 |
1 files changed, 175 insertions, 0 deletions
diff --git a/include/asterisk/media_cache.h b/include/asterisk/media_cache.h new file mode 100644 index 000000000..f1618b87d --- /dev/null +++ b/include/asterisk/media_cache.h @@ -0,0 +1,175 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 2015, Digium, Inc. + * + * Matt Jordan <mjordan@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 An in-memory media cache + */ + +#ifndef _ASTERISK_MEDIA_CACHE_H +#define _ASTERISK_MEDIA_CACHE_H + +#if defined(__cplusplus) || defined(c_plusplus) +extern "C" { +#endif + +struct ast_variable; + +/*! + * \brief Check if an item exists in the cache + * + * \param uri The unique URI for the media item + * + * \retval 0 uri does not exist in cache + * \retval 1 uri does exist in cache + */ +int ast_media_cache_exists(const char *uri); + +/*! + * \brief Retrieve an item from the cache + * + * \param uri The unique URI for the media item + * \param preferred_file_name The preferred name for the file storing the + * media once it is retrieved. Can be NULL. + * \param file_path Buffer to store the full path to the media in the + * cache + * \param len The length of the buffer pointed to by \c file_path + * + * \retval 0 The item was retrieved successfully + * \retval -1 The item could not be retrieved + * + * Example Usage: + * \code + * char media[PATH_MAX]; + * int res; + * + * res = ast_media_cache_retrieve("http://localhost/foo.wav", NULL, + * media, sizeof(media)); + * \endcode + * + * \details + * Retrieving an item will cause the \ref bucket Bucket backend associated + * with the URI scheme in \c uri to be queried. If the Bucket backend + * does not require an update, the cached information is used to find the + * file associated with \c uri, and \c file_path is populated with the + * location of the media file associated with \c uri. + * + * If the item is not in the cache, the item will be retrieved using the + * \ref bucket backend. When this occurs, if \c preferred_file_name is given, + * it will be used as the destination file for the retrieval. When retrieval + * of the media from the backend is complete, \c file_path is then populated + * as before. + */ +int ast_media_cache_retrieve(const char *uri, const char *preferred_file_name, + char *file_path, size_t len); + +/*! + * \brief Retrieve metadata from an item in the cache + * + * \param uri The unique URI for the media item + * \param key The key of the metadata to retrieve + * \param value Buffer to store the value in + * \param len The length of the buffer pointed to by \c value + * + * \retval 0 The metadata was retrieved successfully + * \retval -1 The metadata could not be retrieved + * + * Example Usage: + * \code + * + * int res; + * char file_size[32]; + * + * res = ast_media_cache_retrieve_metadata("http://localhost/foo.wav", "size", + * file_size, sizeof(file_size)); + * \endcode + */ +int ast_media_cache_retrieve_metadata(const char *uri, const char *key, + char *value, size_t len); + +/*! + * \brief Create/update a cached media item + * + * \param uri The unique URI for the media item to store in the cache + * \param file_path Full path to the media file to be cached + * \param metadata Metadata to store with the cached item + * + * \retval 0 The item was cached + * \retval -1 An error occurred when creating/updating the item + * + * Example Usage: + * \code + * int res; + * + * res = ast_media_cache_create_or_update("http://localhost/foo.wav", + * "/tmp/foo.wav", NULL); + * \endcode + * + * \note This method will overwrite whatever has been provided by the + * \ref bucket backend. + * + * \details + * While \ref ast_media_cache_retrieve is used to retrieve media from + * some \ref bucket provider, this method allows for overwriting what + * is provided by a backend with some local media. This is useful for + * reconstructing or otherwise associating local media with a remote + * URI, deferring updating of the media from the backend to some later + * retrieval. + */ +int ast_media_cache_create_or_update(const char *uri, const char *file_path, + struct ast_variable *metadata); + +/*! + * \brief Remove an item from the media cache + * + * \param uri The unique URI for the media item to store in the cache + * + * \retval 0 success + * \retval -1 error + * + * Example Usage: + * \code + * int res; + * + * res = ast_media_cache_delete("http://localhost/foo.wav"); + * \endcode + * + * \details + * This removes an item completely from the media cache. Any files local + * on disk associated with the item are deleted as well. + * + * \note It is up to the \ref bucket implementation whether or not this + * affects any non-local storage + */ +int ast_media_cache_delete(const char *uri); + +/*! + * \brief Initialize the media cache + * + * \note This should only be called once, during Asterisk initialization + * + * \retval 0 success + * \retval -1 error + */ +int ast_media_cache_init(void); + +#if defined(__cplusplus) || defined(c_plusplus) +} +#endif + +#endif /* _ASTERISK_MEDIA_CACHE_H */ |