media_cache.h File Reference

An in-memory media cache. More...

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

Go to the source code of this file.

Functions
int	ast_media_cache_create_or_update (const char *uri, const char *file_path, struct ast_variable *metadata)
	Create/update a cached media item. More...
int	ast_media_cache_delete (const char *uri)
	Remove an item from the media cache. More...
int	ast_media_cache_exists (const char *uri)
	Check if an item exists in the cache. More...
int	ast_media_cache_init (void)
	Initialize the media cache. More...
int	ast_media_cache_retrieve (const char *uri, const char *preferred_file_name, char *file_path, size_t len)
	Retrieve an item from the cache. More...
int	ast_media_cache_retrieve_metadata (const char *uri, const char *key, char *value, size_t len)
	Retrieve metadata from an item in the cache. More...

Detailed Description

An in-memory media cache.

Definition in file media_cache.h.

Function Documentation

ast_media_cache_create_or_update()

int ast_media_cache_create_or_update	(	const char *	uri,
		const char *	file_path,
		struct ast_variable *	metadata
	)

Create/update a cached media item.

Parameters

uri	The unique URI for the media item to store in the cache
file_path	Full path to the media file to be cached
metadata	Metadata to store with the cached item

Return values

0	The item was cached
-1	An error occurred when creating/updating the item

Example Usage:

int res;
 
res = ast_media_cache_create_or_update("http://localhost/foo.wav",
        "/tmp/foo.wav", NULL);

Note

This method will overwrite whatever has been provided by the Bucket File API backend.

While ast_media_cache_retrieve is used to retrieve media from some Bucket File API 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.

Definition at line 268 of file media_cache.c.

{
    struct ast_bucket_file *bucket_file;
    struct ast_variable *it_metadata;
    struct stat st;
    char tmp[128];
    char *ext;
    char *file_path_ptr;
    int created = 0;
    SCOPED_AO2LOCK(media_lock, media_cache);
 
    if (ast_strlen_zero(file_path) || ast_strlen_zero(uri)) {
        return -1;
    }
    file_path_ptr = ast_strdupa(file_path);
 
    if (stat(file_path, &st)) {
        ast_log(LOG_WARNING, "Unable to obtain information for file %s for URI %s\n",
            file_path, uri);
        return -1;
    }
 
    bucket_file = ao2_find(media_cache, uri, OBJ_SEARCH_KEY | OBJ_NOLOCK);
    if (bucket_file) {
        struct ast_bucket_file *clone;
 
        clone = ast_bucket_file_clone(bucket_file);
        if (!clone) {
            ao2_ref(bucket_file, -1);
            return -1;
        }
 
        /* Remove the old bucket_file. We'll replace it if we succeed below. */
        ao2_unlink_flags(media_cache, bucket_file, OBJ_NOLOCK);
        ao2_ref(bucket_file, -1);
 
        bucket_file = clone;
    } else {
        bucket_file = ast_bucket_file_alloc(uri);
        if (!bucket_file) {
            ast_log(LOG_WARNING, "Failed to create file storage for %s and %s\n",
                uri, file_path);
            return -1;
        }
        created = 1;
    }
 
    strcpy(bucket_file->path, file_path);
    bucket_file->created.tv_sec = st.st_ctime;
    bucket_file->modified.tv_sec = st.st_mtime;
 
    snprintf(tmp, sizeof(tmp), "%ld", (long)st.st_atime);
    ast_bucket_file_metadata_set(bucket_file, "accessed", tmp);
 
    snprintf(tmp, sizeof(tmp), "%jd", (intmax_t)st.st_size);
    ast_bucket_file_metadata_set(bucket_file, "size", tmp);
 
    ext = strrchr(file_path_ptr, '.');
    if (ext) {
        ast_bucket_file_metadata_set(bucket_file, "ext", ext + 1);
    }
 
    for (it_metadata = metadata; it_metadata; it_metadata = it_metadata->next) {
        ast_bucket_file_metadata_set(bucket_file, it_metadata->name, it_metadata->value);
    }
 
    if (created && ast_bucket_file_create(bucket_file)) {
        ast_log(LOG_WARNING, "Failed to create media for %s\n", uri);
        ao2_ref(bucket_file, -1);
        return -1;
    }
    media_cache_item_sync_to_astdb(bucket_file);
 
    ao2_link_flags(media_cache, bucket_file, OBJ_NOLOCK);
    ao2_ref(bucket_file, -1);
    return 0;
}

References ao2_find, ao2_link_flags, ao2_ref, ao2_unlink_flags, ast_bucket_file_alloc(), ast_bucket_file_clone(), ast_bucket_file_create(), ast_bucket_file_metadata_set(), ast_log, ast_strdupa, ast_strlen_zero(), ast_bucket_file::created, ext, LOG_WARNING, media_cache, media_cache_item_sync_to_astdb(), ast_bucket_file::metadata, ast_bucket_file::modified, ast_variable::name, ast_variable::next, OBJ_NOLOCK, OBJ_SEARCH_KEY, ast_bucket_file::path, SCOPED_AO2LOCK, tmp(), and ast_variable::value.

Referenced by AST_TEST_DEFINE(), and media_cache_handle_create_item().

ast_media_cache_delete()

int ast_media_cache_delete

(

const char *

uri

)

Remove an item from the media cache.

Parameters

uri	The unique URI for the media item to store in the cache

Return values

0	success
-1	error

Example Usage:

int res;
 
res = ast_media_cache_delete("http://localhost/foo.wav");

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 Bucket File API implementation whether or not this affects any non-local storage

Definition at line 347 of file media_cache.c.

{
    struct ast_bucket_file *bucket_file;
    int res;
 
    if (ast_strlen_zero(uri)) {
        return -1;
    }
 
    bucket_file = ao2_find(media_cache, uri, OBJ_SEARCH_KEY | OBJ_UNLINK);
    if (!bucket_file) {
        return -1;
    }
 
    res = ast_bucket_file_delete(bucket_file);
    media_cache_item_del_from_astdb(bucket_file);
 
    ao2_ref(bucket_file, -1);
 
    return res;
}

References ao2_find, ao2_ref, ast_bucket_file_delete(), ast_strlen_zero(), media_cache, media_cache_item_del_from_astdb(), OBJ_SEARCH_KEY, and OBJ_UNLINK.

Referenced by AST_TEST_DEFINE(), bucket_http_test_wizard_delete(), and media_cache_handle_delete_item().

ast_media_cache_exists()

int ast_media_cache_exists

(

const char *

uri

)

Check if an item exists in the cache.

Parameters

uri	The unique URI for the media item

Return values

0	uri does not exist in cache
1	uri does exist in cache

Definition at line 53 of file media_cache.c.

{
    struct ast_bucket_file *bucket_file;
 
    if (ast_strlen_zero(uri)) {
        return 0;
    }
 
    bucket_file = ao2_find(media_cache, uri, OBJ_SEARCH_KEY);
    if (bucket_file) {
        ao2_ref(bucket_file, -1);
        return 1;
    }
 
    /* Check to see if any bucket implementation could return this item */
    bucket_file = ast_bucket_file_retrieve(uri);
    if (bucket_file) {
        ao2_ref(bucket_file, -1);
        return 1;
    }
 
    return 0;
}

References ao2_find, ao2_ref, ast_bucket_file_retrieve(), ast_strlen_zero(), media_cache, and OBJ_SEARCH_KEY.

Referenced by AST_TEST_DEFINE().

ast_media_cache_init()

int ast_media_cache_init

(

void

)

Initialize the media cache.

Note

This should only be called once, during Asterisk initialization

Return values

0	success
-1	error

Definition at line 671 of file media_cache.c.

{
    ast_register_cleanup(media_cache_shutdown);
 
    media_cache = ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_MUTEX, 0, AO2_BUCKETS,
        ast_sorcery_object_id_hash, NULL, ast_sorcery_object_id_compare);
    if (!media_cache) {
        return -1;
    }
 
    if (ast_cli_register_multiple(cli_media_cache, ARRAY_LEN(cli_media_cache))) {
        return -1;
    }
 
    media_cache_populate_from_astdb();
 
    return 0;
}

References AO2_ALLOC_OPT_LOCK_MUTEX, AO2_BUCKETS, ao2_container_alloc_hash, ARRAY_LEN, ast_cli_register_multiple, ast_register_cleanup(), ast_sorcery_object_id_compare(), ast_sorcery_object_id_hash(), cli_media_cache, media_cache, media_cache_populate_from_astdb(), media_cache_shutdown(), and NULL.

Referenced by asterisk_daemon().

ast_media_cache_retrieve()

int ast_media_cache_retrieve	(	const char *	uri,
		const char *	preferred_file_name,
		char *	file_path,
		size_t	len
	)

Retrieve an item from the cache.

Parameters

uri	The unique URI for the media item
preferred_file_name	The preferred name for the file storing the media once it is retrieved. Can be NULL.
file_path	Buffer to store the full path to the media in the cache
len	The length of the buffer pointed to by file_path

Return values

0	The item was retrieved successfully
-1	The item could not be retrieved

Example Usage:

char media[PATH_MAX];
int res;
 
res = ast_media_cache_retrieve("http://localhost/foo.wav", NULL,
            media, sizeof(media));

Retrieving an item will cause the Bucket File API Bucket backend associated with the URI scheme in uri to be queried. If the Bucket backend does not require an update, the cached information is used to find the file associated with uri, and file_path is populated with the location of the media file associated with uri.

If the item is not in the cache, the item will be retrieved using the Bucket File API backend. When this occurs, if 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, file_path is then populated as before.

Definition at line 157 of file media_cache.c.

{
    struct ast_bucket_file *bucket_file;
    struct ast_bucket_file *tmp_bucket_file;
    char *ext;
    if (ast_strlen_zero(uri)) {
        return -1;
    }
 
    ao2_lock(media_cache);
    ast_debug(5, "Looking for media at local cache, file: %s\n", uri);
 
    /* First, retrieve from the ao2 cache here. If we find a bucket_file
     * matching the requested URI, ask the appropriate backend if it is
     * stale. If not; return it.
     */
    bucket_file = ao2_find(media_cache, uri, OBJ_SEARCH_KEY | OBJ_NOLOCK);
    if (bucket_file) {
        if (!ast_bucket_file_is_stale(bucket_file)
            && ast_file_is_readable(bucket_file->path)) {
            ast_copy_string(file_path, bucket_file->path, len);
            if ((ext = strrchr(file_path, '.'))) {
                *ext = '\0';
            }
            ao2_ref(bucket_file, -1);
 
            ast_debug(5, "Returning media at local file: %s\n", file_path);
            ao2_unlock(media_cache);
            return 0;
        }
 
        /* Stale! Remove the item completely, as we're going to replace it next */
        ao2_unlink_flags(media_cache, bucket_file, OBJ_NOLOCK);
        ast_bucket_file_delete(bucket_file);
        ao2_ref(bucket_file, -1);
    }
    /* We unlock to retrieve the file, because it can take a long time;
     * and we don't want to lock access to cached files while waiting
     */
    ao2_unlock(media_cache);
 
    /* Either this is new or the resource is stale; do a full retrieve
     * from the appropriate bucket_file backend
     */
    bucket_file = ast_bucket_file_retrieve(uri);
    if (!bucket_file) {
        ast_debug(2, "Failed to obtain media at '%s'\n", uri);
        return -1;
    }
 
    /* we lock again, before updating cache */
    ao2_lock(media_cache);
 
    /* We can have duplicated buckets here, we check if already exists
     * before saving
     */
    tmp_bucket_file = ao2_find(media_cache, uri, OBJ_SEARCH_KEY | OBJ_NOLOCK);
    if (tmp_bucket_file) {
        ao2_ref(tmp_bucket_file, -1);
        ast_bucket_file_delete(bucket_file);
        ao2_ref(bucket_file, -1);
        ao2_unlock(media_cache);
        return 0;
    }
 
    /* We can manipulate the 'immutable' bucket_file here, as we haven't
     * let anyone know of its existence yet
     */
    bucket_file_update_path(bucket_file, preferred_file_name);
    media_cache_item_sync_to_astdb(bucket_file);
    ast_copy_string(file_path, bucket_file->path, len);
    if ((ext = strrchr(file_path, '.'))) {
        *ext = '\0';
    }
    ao2_link_flags(media_cache, bucket_file, OBJ_NOLOCK);
    ao2_ref(bucket_file, -1);
 
    ast_debug(5, "Returning media at local file: %s\n", file_path);
    ao2_unlock(media_cache);
 
    return 0;
}

References ao2_find, ao2_link_flags, ao2_lock, ao2_ref, ao2_unlink_flags, ao2_unlock, ast_bucket_file_delete(), ast_bucket_file_is_stale(), ast_bucket_file_retrieve(), ast_copy_string(), ast_debug, ast_file_is_readable(), ast_strlen_zero(), bucket_file_update_path(), ext, len(), media_cache, media_cache_item_sync_to_astdb(), OBJ_NOLOCK, OBJ_SEARCH_KEY, and ast_bucket_file::path.

Referenced by AST_TEST_DEFINE(), fileexists_test(), and media_cache_handle_refresh_item().

ast_media_cache_retrieve_metadata()

int ast_media_cache_retrieve_metadata	(	const char *	uri,
		const char *	key,
		char *	value,
		size_t	len
	)

Retrieve metadata from an item in the cache.

Parameters

uri	The unique URI for the media item
key	The key of the metadata to retrieve
value	Buffer to store the value in
len	The length of the buffer pointed to by value

Return values

0	The metadata was retrieved successfully
-1	The metadata could not be retrieved

Example Usage:

int res;
char file_size[32];
 
res = ast_media_cache_retrieve_metadata("http://localhost/foo.wav", "size",
            file_size, sizeof(file_size));

Definition at line 241 of file media_cache.c.

{
    struct ast_bucket_file *bucket_file;
    struct ast_bucket_metadata *metadata;
 
    if (ast_strlen_zero(uri) || ast_strlen_zero(key) || !value) {
        return -1;
    }
 
    bucket_file = ao2_find(media_cache, uri, OBJ_SEARCH_KEY);
    if (!bucket_file) {
        return -1;
    }
 
    metadata = ao2_find(bucket_file->metadata, key, OBJ_SEARCH_KEY);
    if (!metadata) {
        ao2_ref(bucket_file, -1);
        return -1;
    }
    ast_copy_string(value, metadata->value, len);
 
    ao2_ref(metadata, -1);
    ao2_ref(bucket_file, -1);
    return 0;
}

References ao2_find, ao2_ref, ast_copy_string(), ast_strlen_zero(), len(), media_cache, ast_bucket_file::metadata, OBJ_SEARCH_KEY, ast_bucket_metadata::value, and value.

Referenced by AST_TEST_DEFINE().