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_MUSIC, /*!< Play music on hold instead of ringing to the calling channel */ 00043 AST_DIAL_OPTION_DISABLE_CALL_FORWARDING, /*!< Disable call forwarding on channels */ 00044 AST_DIAL_OPTION_MAX, /*!< End terminator -- must always remain last */ 00045 }; 00046 00047 /*! \brief List of return codes for dial run API calls */ 00048 enum ast_dial_result { 00049 AST_DIAL_RESULT_INVALID, /*!< Invalid options were passed to run function */ 00050 AST_DIAL_RESULT_FAILED, /*!< Attempts to dial failed before reaching critical state */ 00051 AST_DIAL_RESULT_TRYING, /*!< Currently trying to dial */ 00052 AST_DIAL_RESULT_RINGING, /*!< Dial is presently ringing */ 00053 AST_DIAL_RESULT_PROGRESS, /*!< Dial is presently progressing */ 00054 AST_DIAL_RESULT_PROCEEDING, /*!< Dial is presently proceeding */ 00055 AST_DIAL_RESULT_ANSWERED, /*!< A channel was answered */ 00056 AST_DIAL_RESULT_TIMEOUT, /*!< Timeout was tripped, nobody answered */ 00057 AST_DIAL_RESULT_HANGUP, /*!< Caller hung up */ 00058 AST_DIAL_RESULT_UNANSWERED, /*!< Nobody answered */ 00059 }; 00060 00061 /*! \brief New dialing structure 00062 * \note Create a dialing structure 00063 * \return Returns a calloc'd ast_dial structure, NULL on failure 00064 */ 00065 struct ast_dial *ast_dial_create(void); 00066 00067 /*! \brief Append a channel 00068 * \note Appends a channel to a dialing structure 00069 * \return Returns channel reference number on success, -1 on failure 00070 */ 00071 int ast_dial_append(struct ast_dial *dial, const char *tech, const char *device); 00072 00073 /*! \brief Execute dialing synchronously or asynchronously 00074 * \note Dials channels in a dial structure. 00075 * \return Returns dial result code. (TRYING/INVALID/FAILED/ANSWERED/TIMEOUT/UNANSWERED). 00076 */ 00077 enum ast_dial_result ast_dial_run(struct ast_dial *dial, struct ast_channel *chan, int async); 00078 00079 /*! \brief Return channel that answered 00080 * \note Returns the Asterisk channel that answered 00081 * \param dial Dialing structure 00082 */ 00083 struct ast_channel *ast_dial_answered(struct ast_dial *dial); 00084 00085 /*! \brief Steal the channel that answered 00086 * \note Returns the Asterisk channel that answered and removes it from the dialing structure 00087 * \param dial Dialing structure 00088 */ 00089 struct ast_channel *ast_dial_answered_steal(struct ast_dial *dial); 00090 00091 /*! \brief Return state of dial 00092 * \note Returns the state of the dial attempt 00093 * \param dial Dialing structure 00094 */ 00095 enum ast_dial_result ast_dial_state(struct ast_dial *dial); 00096 00097 /*! \brief Cancel async thread 00098 * \note Cancel a running async thread 00099 * \param dial Dialing structure 00100 */ 00101 enum ast_dial_result ast_dial_join(struct ast_dial *dial); 00102 00103 /*! \brief Hangup channels 00104 * \note Hangup all active channels 00105 * \param dial Dialing structure 00106 */ 00107 void ast_dial_hangup(struct ast_dial *dial); 00108 00109 /*! \brief Destroys a dialing structure 00110 * \note Cancels dialing and destroys (free's) the given ast_dial structure 00111 * \param dial Dialing structure to free 00112 * \return Returns 0 on success, -1 on failure 00113 */ 00114 int ast_dial_destroy(struct ast_dial *dial); 00115 00116 /*! \brief Enables an option globally 00117 * \param dial Dial structure to enable option on 00118 * \param option Option to enable 00119 * \param data Data to pass to this option (not always needed) 00120 * \return Returns 0 on success, -1 on failure 00121 */ 00122 int ast_dial_option_global_enable(struct ast_dial *dial, enum ast_dial_option option, void *data); 00123 00124 /*! \brief Enables an option per channel 00125 * \param dial Dial structure 00126 * \param num Channel number to enable option on 00127 * \param option Option to enable 00128 * \param data Data to pass to this option (not always needed) 00129 * \return Returns 0 on success, -1 on failure 00130 */ 00131 int ast_dial_option_enable(struct ast_dial *dial, int num, enum ast_dial_option option, void *data); 00132 00133 /*! \brief Disables an option globally 00134 * \param dial Dial structure 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_global_disable(struct ast_dial *dial, enum ast_dial_option option); 00139 00140 /*! \brief Disables an option per channel 00141 * \param dial Dial structure 00142 * \param num Channel number to disable option on 00143 * \param option Option to disable 00144 * \return Returns 0 on success, -1 on failure 00145 */ 00146 int ast_dial_option_disable(struct ast_dial *dial, int num, enum ast_dial_option option); 00147 00148 /*! \brief Set a callback for state changes 00149 * \param dial The dial structure to watch for state changes 00150 * \param callback the callback 00151 * \return nothing 00152 */ 00153 void ast_dial_set_state_callback(struct ast_dial *dial, ast_dial_state_callback callback); 00154 00155 /*! \brief Set the maximum time (globally) allowed for trying to ring phones 00156 * \param dial The dial structure to apply the time limit to 00157 * \param timeout Maximum time allowed 00158 * \return nothing 00159 */ 00160 void ast_dial_set_global_timeout(struct ast_dial *dial, int timeout); 00161 00162 /*! \brief Set the maximum time (per channel) allowed for trying to ring the phone 00163 * \param dial The dial structure the channel belongs to 00164 * \param num Channel number to set timeout on 00165 * \param timeout Maximum time allowed 00166 * \return nothing 00167 */ 00168 void ast_dial_set_timeout(struct ast_dial *dial, int num, int timeout); 00169 00170 #if defined(__cplusplus) || defined(c_plusplus) 00171 } 00172 #endif 00173 00174 #endif /* _ASTERISK_DIAL_H */