8 files changed, 376 insertions, 11 deletions
diff --git a/include/asterisk/ari.h b/include/asterisk/ari.h
index 00769eea5..c3df46a2b 100644
--- a/include/asterisk/ari.h
+++ b/include/asterisk/ari.h
@@ -225,6 +225,11 @@ void ast_ari_response_ok(struct ast_ari_response *response,
 void ast_ari_response_no_content(struct ast_ari_response *response);
 
 /*!
+ * \brief Fill in a <tt>Accepted</tt> (202) \a ast_ari_response.
+ */
+void ast_ari_response_accepted(struct ast_ari_response *response);
+
+/*!
  * \brief Fill in a <tt>Created</tt> (201) \a ast_ari_response.
  * \param response Response to fill in.
  * \param url URL to the created resource.
diff --git a/include/asterisk/bridge.h b/include/asterisk/bridge.h
index 8243a1ddb..8858cf02c 100644
--- a/include/asterisk/bridge.h
+++ b/include/asterisk/bridge.h
@@ -509,6 +509,8 @@ enum ast_bridge_impart_flags {
  * \param features Bridge features structure.
  * \param flags defined by enum ast_bridge_impart_flags.
  *
+ * \note The given bridge must be unlocked when calling this function.
+ *
  * \note The features parameter must be NULL or obtained by
  * ast_bridge_features_new().  You must not dereference features
  * after calling even if the call fails.
diff --git a/include/asterisk/bridge_channel_internal.h b/include/asterisk/bridge_channel_internal.h
index 71892f51a..e3fb73d7e 100644
--- a/include/asterisk/bridge_channel_internal.h
+++ b/include/asterisk/bridge_channel_internal.h
@@ -130,10 +130,47 @@ int bridge_channel_internal_push(struct ast_bridge_channel *bridge_channel);
 void bridge_channel_internal_pull(struct ast_bridge_channel *bridge_channel);
 
 /*!
+ * \brief Internal bridge channel wait condition and associated result.
+ */
+struct bridge_channel_internal_cond {
+	/*! Lock for the data structure */
+	ast_mutex_t lock;
+	/*! Wait condition */
+	ast_cond_t cond;
+	/*! Wait until done */
+	int done;
+	/*! The bridge channel */
+	struct ast_bridge_channel *bridge_channel;
+};
+
+/*!
+ * \internal
+ * \brief Wait for the expected signal.
+ * \since 13.5.0
+ *
+ * \param cond the wait object
+ *
+ * \return Nothing
+ */
+void bridge_channel_internal_wait(struct bridge_channel_internal_cond *cond);
+
+/*!
+ * \internal
+ * \brief Signal the condition wait.
+ * \since 13.5.0
+ *
+ * \param cond the wait object
+ *
+ * \return Nothing
+ */
+void bridge_channel_internal_signal(struct bridge_channel_internal_cond *cond);
+
+/*!
  * \internal
  * \brief Join the bridge_channel to the bridge (blocking)
  *
  * \param bridge_channel The Channel in the bridge
+ * \param cond data used for signaling
  *
  * \note The bridge_channel->swap holds a channel reference for the swap
  * channel going into the bridging system.  The ref ensures that the swap
@@ -148,7 +185,8 @@ void bridge_channel_internal_pull(struct ast_bridge_channel *bridge_channel);
  * \retval 0 bridge channel successfully joined the bridge
  * \retval -1 bridge channel failed to join the bridge
  */
-int bridge_channel_internal_join(struct ast_bridge_channel *bridge_channel);
+int bridge_channel_internal_join(struct ast_bridge_channel *bridge_channel,
+				 struct bridge_channel_internal_cond *cond);
 
 /*!
  * \internal
diff --git a/include/asterisk/bucket.h b/include/asterisk/bucket.h
index da83759ce..90d976a86 100644
--- a/include/asterisk/bucket.h
+++ b/include/asterisk/bucket.h
@@ -23,7 +23,7 @@
  */
 
 /*!
- * \page AstBucket Bucket File API
+ * \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
@@ -195,6 +195,17 @@ int ast_bucket_file_metadata_unset(struct ast_bucket_file *file, const char *nam
 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
@@ -218,6 +229,23 @@ struct ast_bucket *ast_bucket_alloc(const char *uri);
 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
@@ -240,6 +268,23 @@ int ast_bucket_delete(struct ast_bucket *bucket);
 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
@@ -309,6 +354,24 @@ int ast_bucket_file_create(struct ast_bucket_file *file);
 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
@@ -343,6 +406,23 @@ int ast_bucket_file_delete(struct ast_bucket_file *file);
 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
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 */
diff --git a/include/asterisk/module.h b/include/asterisk/module.h
index f42749146..9fbeb5ebc 100644
--- a/include/asterisk/module.h
+++ b/include/asterisk/module.h
@@ -161,6 +161,43 @@ int ast_update_module_list(int (*modentry)(const char *module, const char *descr
                            const char *like);
 
 /*!
+ * \brief Ask for a list of modules, descriptions, use counts and status.
+ * \param modentry A callback to an updater function
+ * \param like
+ * \param data Data passed into the callback for manipulation
+ *
+ * For each of the modules loaded, modentry will be executed with the resource,
+ * description, and usecount values of each particular module.
+ *
+ * \return the number of modules loaded
+ * \since 13.5.0
+ */
+int ast_update_module_list_data(int (*modentry)(const char *module, const char *description,
+                                                int usecnt, const char *status, const char *like,
+                                                enum ast_module_support_level support_level,
+                                                void *data),
+                                const char *like, void *data);
+
+/*!
+ * \brief Ask for a list of modules, descriptions, use counts and status.
+ * \param modentry A callback to an updater function
+ * \param like
+ * \param data Data passed into the callback for manipulation
+ * \param condition The condition to meet
+ *
+ * For each of the modules loaded, modentry will be executed with the resource,
+ * description, and usecount values of each particular module.
+ *
+ * \return the number of conditions met
+ * \since 13.5.0
+ */
+int ast_update_module_list_condition(int (*modentry)(const char *module, const char *description,
+                                                     int usecnt, const char *status, const char *like,
+                                                     enum ast_module_support_level support_level,
+                                                     void *data, const char *condition),
+                                     const char *like, void *data, const char *condition);
+
+/*!
  * \brief Check if module with the name given is loaded
  * \param name Module name, like "chan_sip.so"
  * \retval 1 if true 
diff --git a/include/asterisk/sorcery.h b/include/asterisk/sorcery.h
index 0bd22a634..d681ebb5a 100644
--- a/include/asterisk/sorcery.h
+++ b/include/asterisk/sorcery.h
@@ -312,6 +312,9 @@ struct ast_sorcery_wizard {
 
 	/*! \brief Callback for closing a wizard */
 	void (*close)(void *data);
+
+	/* \brief Callback for whether or not the wizard believes the object is stale */
+	int (*is_stale)(const struct ast_sorcery *sorcery, void *data, void *object);
 };
 
 /*! \brief Interface for a sorcery object type observer */
@@ -1202,6 +1205,20 @@ int ast_sorcery_update(const struct ast_sorcery *sorcery, void *object);
 int ast_sorcery_delete(const struct ast_sorcery *sorcery, void *object);
 
 /*!
+ * \brief Determine if a sorcery object is stale with respect to its backing datastore
+ * \since 14.0.0
+ *
+ * This function will query the wizard(s) backing the particular sorcery object to
+ * determine if the in-memory object is now stale. No action is taken to update
+ * the object. Callers of this function may use one of the ast_sorcery_retrieve
+ * functions to obtain a new instance of the object if desired.
+ *
+ * \retval 0 the object is not stale
+ * \retval 1 the object is stale
+ */
+int ast_sorcery_is_stale(const struct ast_sorcery *sorcery, void *object);
+
+/*!
  * \brief Decrease the reference count of a sorcery structure
  *
  * \param sorcery Pointer to a sorcery structure
@@ -1218,6 +1235,16 @@ void ast_sorcery_unref(struct ast_sorcery *sorcery);
 const char *ast_sorcery_object_get_id(const void *object);
 
 /*!
+ * \since 14.0.0
+ * \brief Get when the socery object was created
+ *
+ * \param object Pointer to a sorcery object
+ *
+ * \retval The time when the object was created
+ */
+const struct timeval ast_sorcery_object_get_created(const void *object);
+
+/*!
  * \brief Get the type of a sorcery object
  *
  * \param object Pointer to a sorcery object
diff --git a/include/asterisk/strings.h b/include/asterisk/strings.h
index d361293d0..af5ae6c55 100644
--- a/include/asterisk/strings.h
+++ b/include/asterisk/strings.h
@@ -312,32 +312,33 @@ char *ast_unescape_c(char *s);
 /*!
  * \brief Escape the 'to_escape' characters in the given string.
  *
- * \note The given output buffer has to have enough memory allocated to store the
- *       original string plus any escaped values.
+ * \note The given output buffer will contain a truncated escaped
+ * version of the source string if the given buffer is not large
+ * enough.
  *
  * \param dest the escaped string
  * \param s the source string to escape
- * \param num number of characters to be copied from the source
+ * \param size The size of the destination buffer
  * \param to_escape an array of characters to escape
  *
  * \return Pointer to the destination.
  */
-char* ast_escape(char *dest, const char *s, size_t num, const char *to_escape);
+char *ast_escape(char *dest, const char *s, size_t size, const char *to_escape);
 
 /*!
  * \brief Escape standard 'C' sequences in the given string.
  *
- * \note The given output buffer has to have enough memory allocated to store the
- *       original string plus any escaped values.
+ * \note The given output buffer will contain a truncated escaped
+ * version of the source string if the given buffer is not large
+ * enough.
  *
  * \param dest the escaped string
  * \param s the source string to escape
- * \param num number of characters to be copied from the source
- * \param to_escape an array of characters to escape
+ * \param size The size of the destination buffer
  *
  * \return Pointer to the escaped string.
  */
-char* ast_escape_c(char *dest, const char *s, size_t num);
+char *ast_escape_c(char *dest, const char *s, size_t size);
 
 /*!
  * \brief Escape the 'to_escape' characters in the given string.