dial.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2007, Digium, Inc.
00005  *
00006  * Joshua Colp <jcolp@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  * \brief Dialing API
00021  */
00022 
00023 #ifndef _ASTERISK_DIAL_H
00024 #define _ASTERISK_DIAL_H
00025 
00026 #if defined(__cplusplus) || defined(c_plusplus)
00027 extern "C" {
00028 #endif
00029 
00030 /*! \brief Main dialing structure. Contains global options, channels being dialed, and more! */
00031 struct ast_dial;
00032 
00033 /*! \brief Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more! */
00034 struct ast_dial_channel;
00035 
00036 /*! \brief Forward declaration for format capabilities, used in prerun */
00037 struct ast_format_cap;
00038 
00039 typedef void (*ast_dial_state_callback)(struct ast_dial *);
00040 
00041 /*! \brief List of options that are applicable either globally or per dialed channel */
00042 enum ast_dial_option {
00043    AST_DIAL_OPTION_RINGING,                 /*!< Always indicate ringing to caller */
00044    AST_DIAL_OPTION_ANSWER_EXEC,             /*!< Execute application upon answer in async mode */
00045    AST_DIAL_OPTION_MUSIC,                   /*!< Play music on hold instead of ringing to the calling channel */
00046    AST_DIAL_OPTION_DISABLE_CALL_FORWARDING, /*!< Disable call forwarding on channels */
00047    AST_DIAL_OPTION_PREDIAL,                 /*!< Execute a predial subroutine before dialing */
00048    AST_DIAL_OPTION_DIAL_REPLACES_SELF,      /*!< The dial operation is a replacement for the requester */
00049    AST_DIAL_OPTION_SELF_DESTROY,            /*!< Destroy self at end of ast_dial_run */
00050    AST_DIAL_OPTION_MAX,                     /*!< End terminator -- must always remain last */
00051 };
00052 
00053 /*! \brief List of return codes for dial run API calls */
00054 enum ast_dial_result {
00055    AST_DIAL_RESULT_INVALID,     /*!< Invalid options were passed to run function */
00056    AST_DIAL_RESULT_FAILED,      /*!< Attempts to dial failed before reaching critical state */
00057    AST_DIAL_RESULT_TRYING,      /*!< Currently trying to dial */
00058    AST_DIAL_RESULT_RINGING,     /*!< Dial is presently ringing */
00059    AST_DIAL_RESULT_PROGRESS,    /*!< Dial is presently progressing */
00060    AST_DIAL_RESULT_PROCEEDING,  /*!< Dial is presently proceeding */
00061    AST_DIAL_RESULT_ANSWERED,    /*!< A channel was answered */
00062    AST_DIAL_RESULT_TIMEOUT,     /*!< Timeout was tripped, nobody answered */
00063    AST_DIAL_RESULT_HANGUP,      /*!< Caller hung up */
00064    AST_DIAL_RESULT_UNANSWERED,  /*!< Nobody answered */
00065 };
00066 
00067 /*! \brief New dialing structure
00068  * \note Create a dialing structure
00069  * \return Returns a calloc'd ast_dial structure, NULL on failure
00070  */
00071 struct ast_dial *ast_dial_create(void);
00072 
00073 /*! \brief Append a channel
00074  * \note Appends a channel to a dialing structure
00075  * \return Returns channel reference number on success, -1 on failure
00076  */
00077 int ast_dial_append(struct ast_dial *dial, const char *tech, const char *device, const struct ast_assigned_ids *assignedids);
00078 
00079 /*! \brief Request all appended channels, but do not dial
00080  * \param dial Dialing structure
00081  * \param chan Optional dialing channel
00082  * \param cap Optional requested capabilities
00083  * \retval -1 failure
00084  * \reval 0 success
00085  */
00086 int ast_dial_prerun(struct ast_dial *dial, struct ast_channel *chan, struct ast_format_cap *cap);
00087 
00088 /*! \brief Execute dialing synchronously or asynchronously
00089  * \note Dials channels in a dial structure.
00090  * \return Returns dial result code. (TRYING/INVALID/FAILED/ANSWERED/TIMEOUT/UNANSWERED).
00091  */
00092 enum ast_dial_result ast_dial_run(struct ast_dial *dial, struct ast_channel *chan, int async);
00093 
00094 /*! \brief Return channel that answered
00095  * \note Returns the Asterisk channel that answered
00096  * \param dial Dialing structure
00097  */
00098 struct ast_channel *ast_dial_answered(struct ast_dial *dial);
00099 
00100 /*! \brief Steal the channel that answered
00101  * \note Returns the Asterisk channel that answered and removes it from the dialing structure
00102  * \param dial Dialing structure
00103  */
00104 struct ast_channel *ast_dial_answered_steal(struct ast_dial *dial);
00105 
00106 /*! \brief Return state of dial
00107  * \note Returns the state of the dial attempt
00108  * \param dial Dialing structure
00109  */
00110 enum ast_dial_result ast_dial_state(struct ast_dial *dial);
00111 
00112 /*! \brief Cancel async thread
00113  * \note Cancel a running async thread
00114  * \param dial Dialing structure
00115  */
00116 enum ast_dial_result ast_dial_join(struct ast_dial *dial);
00117 
00118 /*! \brief Hangup channels
00119  * \note Hangup all active channels
00120  * \param dial Dialing structure
00121  */
00122 void ast_dial_hangup(struct ast_dial *dial);
00123 
00124 /*! \brief Destroys a dialing structure
00125  * \note Cancels dialing and destroys (free's) the given ast_dial structure
00126  * \param dial Dialing structure to free
00127  * \return Returns 0 on success, -1 on failure
00128  */
00129 int ast_dial_destroy(struct ast_dial *dial);
00130 
00131 /*! \brief Enables an option globally
00132  * \param dial Dial structure to enable option on
00133  * \param option Option to enable
00134  * \param data Data to pass to this option (not always needed)
00135  * \return Returns 0 on success, -1 on failure
00136  */
00137 int ast_dial_option_global_enable(struct ast_dial *dial, enum ast_dial_option option, void *data);
00138 
00139 /*! \brief Enables an option per channel
00140  * \param dial Dial structure
00141  * \param num Channel number to enable option on
00142  * \param option Option to enable
00143  * \param data Data to pass to this option (not always needed)
00144  * \return Returns 0 on success, -1 on failure
00145  */
00146 int ast_dial_option_enable(struct ast_dial *dial, int num, enum ast_dial_option option, void *data);
00147 
00148 /*! \brief Disables an option globally
00149  * \param dial Dial structure to disable option on
00150  * \param option Option to disable
00151  * \return Returns 0 on success, -1 on failure
00152  */
00153 int ast_dial_option_global_disable(struct ast_dial *dial, enum ast_dial_option option);
00154 
00155 /*! \brief Disables an option per channel
00156  * \param dial Dial structure
00157  * \param num Channel number to disable option on
00158  * \param option Option to disable
00159  * \return Returns 0 on success, -1 on failure
00160  */
00161 int ast_dial_option_disable(struct ast_dial *dial, int num, enum ast_dial_option option);
00162 
00163 /*! \brief Get the reason an outgoing channel has failed
00164  * \param dial Dial structure
00165  * \param num Channel number to get the reason from
00166  * \return Numerical cause code
00167  */
00168 int ast_dial_reason(struct ast_dial *dial, int num);
00169 
00170 /*! \brief Get the dialing channel, if prerun has been executed
00171  * \param dial Dial structure
00172  * \param num Channel number to get channel of
00173  * \return Pointer to channel, without reference
00174  */
00175 struct ast_channel *ast_dial_get_channel(struct ast_dial *dial, int num);
00176 
00177 /*! \brief Set a callback for state changes
00178  * \param dial The dial structure to watch for state changes
00179  * \param callback the callback
00180  * \return nothing
00181  */
00182 void ast_dial_set_state_callback(struct ast_dial *dial, ast_dial_state_callback callback);
00183 
00184 /*! \brief Set user data on a dial structure
00185  * \param dial The dial structure to set a user data pointer on
00186  * \param user_data The user data pointer
00187  * \return nothing
00188  */
00189 void ast_dial_set_user_data(struct ast_dial *dial, void *user_data);
00190 
00191 /*! \brief Return the user data on a dial structure
00192  * \param dial The dial structure
00193  * \return A pointer to the user data
00194  */
00195 void *ast_dial_get_user_data(struct ast_dial *dial);
00196 
00197 /*! \brief Set the maximum time (globally) allowed for trying to ring phones
00198  * \param dial The dial structure to apply the time limit to
00199  * \param timeout Maximum time allowed in milliseconds
00200  * \return nothing
00201  */
00202 void ast_dial_set_global_timeout(struct ast_dial *dial, int timeout);
00203 
00204 /*! \brief Set the maximum time (per channel) allowed for trying to ring the phone
00205  * \param dial The dial structure the channel belongs to
00206  * \param num Channel number to set timeout on
00207  * \param timeout Maximum time allowed in milliseconds
00208  * \return nothing
00209  */
00210 void ast_dial_set_timeout(struct ast_dial *dial, int num, int timeout);
00211 
00212 /*! \since 12
00213  * \brief Convert a hangup cause to a publishable dial status
00214  */
00215 const char *ast_hangup_cause_to_dial_status(int hangup_cause);
00216 
00217 #if defined(__cplusplus) || defined(c_plusplus)
00218 }
00219 #endif
00220 
00221 #endif /* _ASTERISK_DIAL_H */

Generated on Thu Apr 16 06:27:33 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6