1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
/*
* Asterisk -- An open source telephony toolkit.
*
* Copyright (C) 1999 - 2007, Digium, Inc.
*
* Joshua Colp <jcolp@digium.com>
*
* See http://www.asterisk.org for more information about
* the Asterisk project. Please do not directly contact
* any of the maintainers of this project for assistance;
* the project provides a web site, mailing lists and IRC
* channels for your use.
*
* This program is free software, distributed under the terms of
* the GNU General Public License Version 2. See the LICENSE file
* at the top of the source tree.
*/
/*! \file
* \brief Dialing API
*/
#ifndef _ASTERISK_DIAL_H
#define _ASTERISK_DIAL_H
#if defined(__cplusplus) || defined(c_plusplus)
extern "C" {
#endif
/*! \brief Main dialing structure. Contains global options, channels being dialed, and more! */
struct ast_dial;
/*! \brief Dialing channel structure. Contains per-channel dialing options, asterisk channel, and more! */
struct ast_dial_channel;
typedef void (*ast_dial_state_callback)(struct ast_dial *);
/*! \brief List of options that are applicable either globally or per dialed channel */
enum ast_dial_option {
AST_DIAL_OPTION_RINGING, /*!< Always indicate ringing to caller */
AST_DIAL_OPTION_ANSWER_EXEC, /*!< Execute application upon answer in async mode */
AST_DIAL_OPTION_MUSIC, /*!< Play music on hold instead of ringing to the calling channel */
AST_DIAL_OPTION_MAX, /*!< End terminator -- must always remain last */
};
/*! \brief List of return codes for dial run API calls */
enum ast_dial_result {
AST_DIAL_RESULT_INVALID, /*!< Invalid options were passed to run function */
AST_DIAL_RESULT_FAILED, /*!< Attempts to dial failed before reaching critical state */
AST_DIAL_RESULT_TRYING, /*!< Currently trying to dial */
AST_DIAL_RESULT_RINGING, /*!< Dial is presently ringing */
AST_DIAL_RESULT_PROGRESS, /*!< Dial is presently progressing */
AST_DIAL_RESULT_PROCEEDING, /*!< Dial is presently proceeding */
AST_DIAL_RESULT_ANSWERED, /*!< A channel was answered */
AST_DIAL_RESULT_TIMEOUT, /*!< Timeout was tripped, nobody answered */
AST_DIAL_RESULT_HANGUP, /*!< Caller hung up */
AST_DIAL_RESULT_UNANSWERED, /*!< Nobody answered */
};
/*! \brief New dialing structure
* \note Create a dialing structure
* \return Returns a calloc'd ast_dial structure, NULL on failure
*/
struct ast_dial *ast_dial_create(void);
/*! \brief Append a channel
* \note Appends a channel to a dialing structure
* \return Returns channel reference number on success, -1 on failure
*/
int ast_dial_append(struct ast_dial *dial, const char *tech, const char *device);
/*! \brief Execute dialing synchronously or asynchronously
* \note Dials channels in a dial structure.
* \return Returns dial result code. (TRYING/INVALID/FAILED/ANSWERED/TIMEOUT/UNANSWERED).
*/
enum ast_dial_result ast_dial_run(struct ast_dial *dial, struct ast_channel *chan, int async);
/*! \brief Return channel that answered
* \note Returns the Asterisk channel that answered
* \param dial Dialing structure
*/
struct ast_channel *ast_dial_answered(struct ast_dial *dial);
/*! \brief Return state of dial
* \note Returns the state of the dial attempt
* \param dial Dialing structure
*/
enum ast_dial_result ast_dial_state(struct ast_dial *dial);
/*! \brief Cancel async thread
* \note Cancel a running async thread
* \param dial Dialing structure
*/
enum ast_dial_result ast_dial_join(struct ast_dial *dial);
/*! \brief Hangup channels
* \note Hangup all active channels
* \param dial Dialing structure
*/
void ast_dial_hangup(struct ast_dial *dial);
/*! \brief Destroys a dialing structure
* \note Cancels dialing and destroys (free's) the given ast_dial structure
* \param dial Dialing structure to free
* \return Returns 0 on success, -1 on failure
*/
int ast_dial_destroy(struct ast_dial *dial);
/*! \brief Enables an option globally
* \param dial Dial structure to enable option on
* \param option Option to enable
* \param data Data to pass to this option (not always needed)
* \return Returns 0 on success, -1 on failure
*/
int ast_dial_option_global_enable(struct ast_dial *dial, enum ast_dial_option option, void *data);
/*! \brief Enables an option per channel
* \param dial Dial structure
* \param num Channel number to enable option on
* \param option Option to enable
* \param data Data to pass to this option (not always needed)
* \return Returns 0 on success, -1 on failure
*/
int ast_dial_option_enable(struct ast_dial *dial, int num, enum ast_dial_option option, void *data);
/*! \brief Disables an option globally
* \param dial Dial structure to disable option on
* \param option Option to disable
* \return Returns 0 on success, -1 on failure
*/
int ast_dial_option_global_disable(struct ast_dial *dial, enum ast_dial_option option);
/*! \brief Disables an option per channel
* \param dial Dial structure
* \param num Channel number to disable option on
* \param option Option to disable
* \return Returns 0 on success, -1 on failure
*/
int ast_dial_option_disable(struct ast_dial *dial, int num, enum ast_dial_option option);
/*! \brief Set a callback for state changes
* \param dial The dial structure to watch for state changes
* \param callback the callback
* \return nothing
*/
void ast_dial_set_state_callback(struct ast_dial *dial, ast_dial_state_callback callback);
#if defined(__cplusplus) || defined(c_plusplus)
}
#endif
#endif /* _ASTERISK_DIAL_H */
|
