Support externally initiated parking requests; remove some dead code

This patch does the following:
 * It adds support for externally initiated parking requests. In particular,
   chan_skinny has a protocol level message that initiates a call park.
   This patch now supports that option, as well as the protocol specific
   mechanisms in chan_dahdi/sig_analog and chan_mgcp.
 * A parking bridge features virtual table has been added that provides
   access to the parking functionality that the Bridging API needs. This
   includes requests to park an entire 'call' (with little or no additional
   information, thank you chan_skinny), perform a blind transfer to a parking
   extension, determine if an extension is a parking extension, as well as the
   actual "do the parking" request from the Bridging API.
 * Refactoring in chan_mgcp, chan_skinny, and chan_dahdi to make use of the new
   functions
 * The removal of some - but not all - dead parking code from features.c

This also fixed blind transferring a multi-party bridge to a parking lot (which
was implemented, but had at least one code path where using the parking features
kK might not have worked)

Review: https://reviewboard.asterisk.org/r/2710

(closes issue ASTERISK-22134)
Reported by: Matt Jordan



git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@396028 65c4cc65-6c06-0410-ace0-fbb531ad65f3

2 files changed, 96 insertions, 98 deletions

diff --git a/include/asterisk/features.h b/include/asterisk/features.h
index b1400ee39..43edca07a 100644
--- a/include/asterisk/features.h
+++ b/include/asterisk/features.h
@@ -63,50 +63,6 @@ enum {
 	AST_FEATURE_FLAG_BYBOTH	 =   (3 << 3),
 };
 
-/*!
- * \brief Park a call via a masqueraded channel
- *
- * \param park_me Channel to be parked.
- * \param parker Channel parking the call.
- * \param timeout is a timeout in milliseconds
- * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
- *
- * \details
- * Masquerade the park_me channel into a new, empty channel which is then parked.
- *
- * \note Use ast_masq_park_call_exten() instead.
- *
- * \retval 0 on success.
- * \retval -1 on failure.
- */
-int ast_masq_park_call(struct ast_channel *park_me, struct ast_channel *parker, int timeout, int *extout);
-
-/*!
- * \brief Park a call via a masqueraded channel
- * \since 1.8.9
- *
- * \param park_me Channel to be parked.
- * \param parker Channel parking the call.
- * \param park_exten Parking lot access extension
- * \param park_context Parking lot context
- * \param timeout is a timeout in milliseconds
- * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
- *
- * \details
- * Masquerade the park_me channel into a new, empty channel which is then parked.
- *
- * \retval 0 on success.
- * \retval -1 on failure.
- */
-int ast_masq_park_call_exten(struct ast_channel *park_me, struct ast_channel *parker, const char *park_exten, const char *park_context, int timeout, int *extout);
-
-/*!
- * \brief Determine if parking extension exists in a given context
- * \retval 0 if extension does not exist
- * \retval 1 if extension does exist
-*/
-int ast_parking_ext_valid(const char *exten_str, struct ast_channel *chan, const char *context);
-
 /*! \brief Bridge a call, optionally allowing redirection */
 int ast_bridge_call(struct ast_channel *chan, struct ast_channel *peer,struct ast_bridge_config *config);
 
diff --git a/include/asterisk/parking.h b/include/asterisk/parking.h
index 4a721200a..a835d104a 100644
--- a/include/asterisk/parking.h
+++ b/include/asterisk/parking.h
@@ -25,6 +25,9 @@
 
 #include "asterisk/stringfields.h"
 
+/*!
+ * \brief The default parking application that Asterisk expects.
+ */
 #define PARK_APPLICATION "Park"
 
 /*!
@@ -79,6 +82,10 @@ struct ast_parked_call_payload *ast_parked_call_payload_create(enum ast_parked_c
 		struct ast_channel_snapshot *retriever_snapshot, const char *parkinglot,
 		unsigned int parkingspace, unsigned long int timeout, unsigned long int duration);
 
+/*! \addtogroup StasisTopicsAndMessages
+ * @{
+ */
+
 /*!
  * \brief accessor for the parking stasis topic
  * \since 12
@@ -97,75 +104,110 @@ struct stasis_topic *ast_parking_topic(void);
  */
 struct stasis_message_type *ast_parked_call_type(void);
 
-/*!
- * \brief invoke an installable park callback to asynchronously park a bridge_channel in a bridge
- * \since 12
- *
- * \param bridge_channel the bridge channel that initiated parking
- * \parkee_uuid channel id of the channel being parked
- * \parker_uuid channel id of the channel that initiated parking
- * \param app_data string of application data that might be applied to parking
- */
-void ast_bridge_channel_park(struct ast_bridge_channel *bridge_channel,
-	const char *parkee_uuid,
-	const char *parker_uuid,
-	const char *app_data);
+/*! @} */
 
-typedef int (*ast_park_blind_xfer_fn)(struct ast_bridge_channel *parker, struct ast_exten *park_exten);
+#define PARKING_MODULE_VERSION 1
 
 /*!
- * \brief install a callback for handling blind transfers to a parking extension
- * \since 12
- *
- * \param parking_func Function to use for transfers to 'Park' applications
+ * \brief A function table providing parking functionality to the \ref AstBridging
+ * Bridging API and other consumers
  */
-void ast_install_park_blind_xfer_func(ast_park_blind_xfer_fn park_blind_xfer_func);
+struct ast_parking_bridge_feature_fn_table {
+
+	/*!
+	 * \brief The version of this function table. If the ABI for this table
+	 * changes, the module version (/ref PARKING_MODULE_VERSION) should be
+	 * incremented.
+	 */
+	unsigned int module_version;
+
+	/*!
+	 * \brief The name of the module that provides this parking functionality
+	 */
+	const char *module_name;
+
+	/*!
+	 * \brief Determine if the context/exten is a "parking" extension
+	 *
+	 * \retval 0 if the extension is not a parking extension
+	 * \retval 1 if the extension is a parking extension
+	 */
+	int (* parking_is_exten_park)(const char *context, const char *exten);
+
+	/*!
+	 * \brief Park the bridge and/or callers that this channel is in
+	 *
+	 * \param parker The bridge_channel parking the bridge
+	 * \param exten Optional. The extension the channel or bridge was parked at if the
+	 * call succeeds.
+	 * \param length Optional. If \c exten is specified, the size of the buffer.
+	 *
+	 * \note This is safe to be called outside of the \ref AstBridging Bridging API.
+	 *
+	 * \retval 0 on success
+	 * \retval non-zero on error
+	 */
+	int (* parking_park_call)(struct ast_bridge_channel *parker, char *exten, size_t length);
+
+	/*!
+	 * \brief Perform a blind transfer to a parking extension.
+	 *
+	 * \param parker The \ref bridge_channel object that is initiating the parking
+	 * \param context The context to blind transfer to
+	 * \param exten The extension to blind transfer to
+	 *
+	 * \note If the bridge \ref parker is in has more than one other occupant, the entire
+	 * bridge will be parked using a Local channel
+	 *
+	 * \note This is safe to be called outside of the \ref AstBridging Bridging API.
+	 *
+	 * \retval 0 on success
+	 * \retval non-zero on error
+	 */
+	int (* parking_blind_transfer_park)(struct ast_bridge_channel *parker, const char *context, const char *exten);
+
+	/*!
+	 * \brief Perform a direct park on a channel in a bridge.
+	 *
+	 * \param parkee The channel in the bridge to be parked.
+	 * \param parkee_uuid The UUID of the channel being packed.
+	 * \param parker_uuid The UUID of the channel performing the park.
+	 * \param app_data Data to pass to the Park application
+	 *
+	 * \note This must be called within the context of the \ref AstBridging Bridging API.
+	 * External entities should not call this method directly, but should instead use
+	 * the direct call parking method or the blind transfer method.
+	 *
+	 * \retval 0 on success
+	 * \retval non-zero on error
+	 */
+	int (* parking_park_bridge_channel)(struct ast_bridge_channel *parkee, const char *parkee_uuid, const char *parker_uuid, const char *app_data);
+};
 
 /*!
- * \brief uninstall a callback for handling blind transfers to a parking extension
- * \since 12
+ * \brief Obtain the current parking provider
+ *
+ * \retval NULL if no provider exists
+ * \retval an ao2 ref counted object of the existing provider's function table
  */
-void ast_uninstall_park_blind_xfer_func(void);
+struct ast_parking_bridge_feature_fn_table *ast_parking_get_bridge_features(void);
 
 /*!
- * \brief use the installed park blind xfer func
- * \since 12
+ * \brief Register a parking provider
  *
- * \param parker Bridge channel initiating the park
- * \param park_exten Exten to blind transfer part to.
+ * \param fn_table The \ref ast_parking_bridge_feature_fn_table to register
  *
  * \retval 0 on success
- * \retval -1 on failure
- */
-int ast_park_blind_xfer(struct ast_bridge_channel *parker, struct ast_exten *park_exten);
-
-typedef void (*ast_bridge_channel_park_fn)(struct ast_bridge_channel *parkee, const char *parkee_uuid,
-	const char *parker_uuid, const char *app_data);
-
-/*!
- * \brief Install a function for ast_bridge_channel_park
- * \since 12
- *
- * \param bridge_channel_park_func function callback to use for ast_bridge_channel_park
+ * \retval -1 on error
  */
-void ast_install_bridge_channel_park_func(ast_bridge_channel_park_fn bridge_channel_park_func);
+int ast_parking_register_bridge_features(struct ast_parking_bridge_feature_fn_table *fn_table);
 
 /*!
- * \brief Uninstall the ast_bridge_channel_park function callback
- * \since 12
- */
-void ast_uninstall_bridge_channel_park_func(void);
-
-
-/*!
- * \brief Determines whether a certain extension is a park application extension or not.
- * \since 12
+ * \brief Unregister the current parking provider
  *
- * \param exten_str string representation of the extension sought
- * \param chan channel the extension is sought for
- * \param context context the extension is sought from
+ * \param The module name of the provider to unregister
  *
- * \retval pointer to the extension if the extension is a park extension
- * \retval NULL if the extension was not a park extension
+ * \retval 0 if the parking provider \c module_name was unregsistered
+ * \retval -1 on error
  */
-struct ast_exten *ast_get_parking_exten(const char *exten_str, struct ast_channel *chan, const char *context);
+int ast_parking_unregister_bridge_features(const char *module_name);