Sat Aug 6 00:39:28 2011

Asterisk developer's documentation


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 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 */

Generated on Sat Aug 6 00:39:28 2011 for Asterisk - the Open Source PBX by  doxygen 1.4.7