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 AstBucket Bucket File API backend.

While ast_media_cache_retrieve is used to retrieve media from some AstBucket 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 285 of file media_cache.c.

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_item_sync_to_astdb(), 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().

{
   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;
}

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

Definition at line 364 of file media_cache.c.

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

Referenced by media_cache_handle_delete_item().

{
   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;
}

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.

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

Referenced by AST_TEST_DEFINE().

{
   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;
}

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 688 of file media_cache.c.

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(), media_cache_populate_from_astdb(), media_cache_shutdown(), and NULL.

Referenced by asterisk_daemon().

{
   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;
}

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 AstBucket 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 AstBucket 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 197 of file media_cache.c.

References ao2_find, ao2_link_flags, ao2_ref, ao2_unlink_flags, 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, media_cache_item_sync_to_astdb(), OBJ_NOLOCK, OBJ_SEARCH_KEY, ast_bucket_file::path, and SCOPED_AO2LOCK.

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

{
   struct ast_bucket_file *bucket_file;
   char *ext;
   SCOPED_AO2LOCK(media_lock, media_cache);

   if (ast_strlen_zero(uri)) {
      return -1;
   }

   /* 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);
         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);
   }

   /* 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 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);

   return 0;
}

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 258 of file media_cache.c.

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

Referenced by AST_TEST_DEFINE().

{
   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;
}