Thu Sep 7 01:02:59 2017

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_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 in milliseconds
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 in milliseconds
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 */

Generated on 7 Sep 2017 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1