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 typedef void (*ast_dial_state_callback)(struct ast_dial *); 00037 00038 /*! \brief List of options that are applicable either globally or per dialed channel */ 00039 enum ast_dial_option { 00040 AST_DIAL_OPTION_RINGING, /*!< Always indicate ringing to caller */ 00041 AST_DIAL_OPTION_ANSWER_EXEC, /*!< Execute application upon answer in async mode */ 00042 AST_DIAL_OPTION_MAX, /*!< End terminator -- must always remain last */ 00043 }; 00044 00045 /*! \brief List of return codes for dial run API calls */ 00046 enum ast_dial_result { 00047 AST_DIAL_RESULT_INVALID, /*!< Invalid options were passed to run function */ 00048 AST_DIAL_RESULT_FAILED, /*!< Attempts to dial failed before reaching critical state */ 00049 AST_DIAL_RESULT_TRYING, /*!< Currently trying to dial */ 00050 AST_DIAL_RESULT_RINGING, /*!< Dial is presently ringing */ 00051 AST_DIAL_RESULT_PROGRESS, /*!< Dial is presently progressing */ 00052 AST_DIAL_RESULT_PROCEEDING, /*!< Dial is presently proceeding */ 00053 AST_DIAL_RESULT_ANSWERED, /*!< A channel was answered */ 00054 AST_DIAL_RESULT_TIMEOUT, /*!< Timeout was tripped, nobody answered */ 00055 AST_DIAL_RESULT_HANGUP, /*!< Caller hung up */ 00056 AST_DIAL_RESULT_UNANSWERED, /*!< Nobody answered */ 00057 }; 00058 00059 /*! \brief New dialing structure 00060 * \note Create a dialing structure 00061 * \return Returns a calloc'd ast_dial structure, NULL on failure 00062 */ 00063 struct ast_dial *ast_dial_create(void); 00064 00065 /*! \brief Append a channel 00066 * \note Appends a channel to a dialing structure 00067 * \return Returns channel reference number on success, -1 on failure 00068 */ 00069 int ast_dial_append(struct ast_dial *dial, const char *tech, const char *device); 00070 00071 /*! \brief Execute dialing synchronously or asynchronously 00072 * \note Dials channels in a dial structure. 00073 * \return Returns dial result code. (TRYING/INVALID/FAILED/ANSWERED/TIMEOUT/UNANSWERED). 00074 */ 00075 enum ast_dial_result ast_dial_run(struct ast_dial *dial, struct ast_channel *chan, int async); 00076 00077 /*! \brief Return channel that answered 00078 * \note Returns the Asterisk channel that answered 00079 * \param dial Dialing structure 00080 */ 00081 struct ast_channel *ast_dial_answered(struct ast_dial *dial); 00082 00083 /*! \brief Return state of dial 00084 * \note Returns the state of the dial attempt 00085 * \param dial Dialing structure 00086 */ 00087 enum ast_dial_result ast_dial_state(struct ast_dial *dial); 00088 00089 /*! \brief Cancel async thread 00090 * \note Cancel a running async thread 00091 * \param dial Dialing structure 00092 */ 00093 enum ast_dial_result ast_dial_join(struct ast_dial *dial); 00094 00095 /*! \brief Hangup channels 00096 * \note Hangup all active channels 00097 * \param dial Dialing structure 00098 */ 00099 void ast_dial_hangup(struct ast_dial *dial); 00100 00101 /*! \brief Destroys a dialing structure 00102 * \note Cancels dialing and destroys (free's) the given ast_dial structure 00103 * \param dial Dialing structure to free 00104 * \return Returns 0 on success, -1 on failure 00105 */ 00106 int ast_dial_destroy(struct ast_dial *dial); 00107 00108 /*! \brief Enables an option globally 00109 * \param dial Dial structure to enable option on 00110 * \param option Option to enable 00111 * \param data Data to pass to this option (not always needed) 00112 * \return Returns 0 on success, -1 on failure 00113 */ 00114 int ast_dial_option_global_enable(struct ast_dial *dial, enum ast_dial_option option, void *data); 00115 00116 /*! \brief Enables an option per channel 00117 * \param dial Dial structure 00118 * \param num Channel number to enable option on 00119 * \param option Option to enable 00120 * \param data Data to pass to this option (not always needed) 00121 * \return Returns 0 on success, -1 on failure 00122 */ 00123 int ast_dial_option_enable(struct ast_dial *dial, int num, enum ast_dial_option option, void *data); 00124 00125 /*! \brief Disables an option globally 00126 * \param dial Dial structure to disable option on 00127 * \param option Option to disable 00128 * \return Returns 0 on success, -1 on failure 00129 */ 00130 int ast_dial_option_global_disable(struct ast_dial *dial, enum ast_dial_option option); 00131 00132 /*! \brief Disables an option per channel 00133 * \param dial Dial structure 00134 * \param num Channel number to disable option on 00135 * \param option Option to disable 00136 * \return Returns 0 on success, -1 on failure 00137 */ 00138 int ast_dial_option_disable(struct ast_dial *dial, int num, enum ast_dial_option option); 00139 00140 /*! \brief Set a callback for state changes 00141 * \param dial The dial structure to watch for state changes 00142 * \param callback the callback 00143 * \return nothing 00144 */ 00145 void ast_dial_set_state_callback(struct ast_dial *dial, ast_dial_state_callback callback); 00146 00147 #if defined(__cplusplus) || defined(c_plusplus) 00148 } 00149 #endif 00150 00151 #endif /* _ASTERISK_DIAL_H */