app_page: Add predial handlers for app_page.
[asterisk/asterisk.git] / include / asterisk / dial.h
index 9a24780..19b1c87 100644 (file)
@@ -33,6 +33,9 @@ struct ast_dial;
 /*! \brief Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more! */
 struct ast_dial_channel;
 
+/*! \brief Forward declaration for format capabilities, used in prerun */
+struct ast_format_cap;
+
 typedef void (*ast_dial_state_callback)(struct ast_dial *);
 
 /*! \brief List of options that are applicable either globally or per dialed channel */
@@ -41,6 +44,7 @@ enum ast_dial_option {
        AST_DIAL_OPTION_ANSWER_EXEC,             /*!< Execute application upon answer in async mode */
        AST_DIAL_OPTION_MUSIC,                   /*!< Play music on hold instead of ringing to the calling channel */
        AST_DIAL_OPTION_DISABLE_CALL_FORWARDING, /*!< Disable call forwarding on channels */
+       AST_DIAL_OPTION_PREDIAL,                 /*!< Execute a predial subroutine before dialing */
        AST_DIAL_OPTION_MAX,                     /*!< End terminator -- must always remain last */
 };
 
@@ -70,6 +74,15 @@ struct ast_dial *ast_dial_create(void);
  */
 int ast_dial_append(struct ast_dial *dial, const char *tech, const char *device);
 
+/*! \brief Request all appended channels, but do not dial
+ * \param dial Dialing structure
+ * \param chan Optional dialing channel
+ * \param cap Optional requested capabilities
+ * \retval -1 failure
+ * \reval 0 success
+ */
+int ast_dial_prerun(struct ast_dial *dial, struct ast_channel *chan, struct ast_format_cap *cap);
+
 /*! \brief Execute dialing synchronously or asynchronously
  * \note Dials channels in a dial structure.
  * \return Returns dial result code. (TRYING/INVALID/FAILED/ANSWERED/TIMEOUT/UNANSWERED).
@@ -82,6 +95,12 @@ enum ast_dial_result ast_dial_run(struct ast_dial *dial, struct ast_channel *cha
  */
 struct ast_channel *ast_dial_answered(struct ast_dial *dial);
 
+/*! \brief Steal the channel that answered
+ * \note Returns the Asterisk channel that answered and removes it from the dialing structure
+ * \param dial Dialing structure
+ */
+struct ast_channel *ast_dial_answered_steal(struct ast_dial *dial);
+
 /*! \brief Return state of dial
  * \note Returns the state of the dial attempt
  * \param dial Dialing structure
@@ -139,6 +158,20 @@ int ast_dial_option_global_disable(struct ast_dial *dial, enum ast_dial_option o
  */
 int ast_dial_option_disable(struct ast_dial *dial, int num, enum ast_dial_option option);
 
+/*! \brief Get the reason an outgoing channel has failed
+ * \param dial Dial structure
+ * \param num Channel number to get the reason from
+ * \return Numerical cause code
+ */
+int ast_dial_reason(struct ast_dial *dial, int num);
+
+/*! \brief Get the dialing channel, if prerun has been executed
+ * \param dial Dial structure
+ * \param num Channel number to get channel of
+ * \return Pointer to channel, without reference
+ */
+struct ast_channel *ast_dial_get_channel(struct ast_dial *dial, int num);
+
 /*! \brief Set a callback for state changes
  * \param dial The dial structure to watch for state changes
  * \param callback the callback
@@ -146,9 +179,22 @@ int ast_dial_option_disable(struct ast_dial *dial, int num, enum ast_dial_option
  */
 void ast_dial_set_state_callback(struct ast_dial *dial, ast_dial_state_callback callback);
 
+/*! \brief Set user data on a dial structure
+ * \param dial The dial structure to set a user data pointer on
+ * \param user_data The user data pointer
+ * \return nothing
+ */
+void ast_dial_set_user_data(struct ast_dial *dial, void *user_data);
+
+/*! \brief Return the user data on a dial structure
+ * \param dial The dial structure
+ * \return A pointer to the user data
+ */
+void *ast_dial_get_user_data(struct ast_dial *dial);
+
 /*! \brief Set the maximum time (globally) allowed for trying to ring phones
  * \param dial The dial structure to apply the time limit to
- * \param timeout Maximum time allowed
+ * \param timeout Maximum time allowed in milliseconds
  * \return nothing
  */
 void ast_dial_set_global_timeout(struct ast_dial *dial, int timeout);
@@ -156,11 +202,16 @@ void ast_dial_set_global_timeout(struct ast_dial *dial, int timeout);
 /*! \brief Set the maximum time (per channel) allowed for trying to ring the phone
  * \param dial The dial structure the channel belongs to
  * \param num Channel number to set timeout on
- * \param timeout Maximum time allowed
+ * \param timeout Maximum time allowed in milliseconds
  * \return nothing
  */
 void ast_dial_set_timeout(struct ast_dial *dial, int num, int timeout);
 
+/*! \since 12
+ * \brief Convert a hangup cause to a publishable dial status
+ */
+const char *ast_hangup_cause_to_dial_status(int hangup_cause);
+
 #if defined(__cplusplus) || defined(c_plusplus)
 }
 #endif