1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package net.sf.asterisk.fastagi;
18
19 import net.sf.asterisk.fastagi.command.AGICommand;
20 import net.sf.asterisk.fastagi.reply.AGIReply;
21
22 /***
23 * Provides the functionality to send AGICommands to Asterisk while handling an
24 * AGIRequest.<br>
25 * This interface is supposed to be used by AGIScripts for interaction with the
26 * Asterisk server.
27 *
28 * @author srt
29 * @version $Id: AGIChannel.java,v 1.7 2005/11/27 17:31:05 srt Exp $
30 */
31 public interface AGIChannel
32 {
33 /***
34 * Sends a command to asterisk and returns the corresponding reply.
35 *
36 * @param command the command to send.
37 * @return the reply of the asterisk server containing the return value.
38 * @throws AGIException if the command can't be sent to Asterisk (for
39 * example because the channel has been hung up)
40 */
41 AGIReply sendCommand(AGICommand command) throws AGIException;
42
43 /***
44 * Answers the channel.
45 *
46 * @since 0.2
47 */
48 void answer() throws AGIException;
49
50 /***
51 * Hangs the channel up.
52 *
53 * @since 0.2
54 */
55 void hangup() throws AGIException;
56
57 /***
58 * Cause the channel to automatically hangup at the given number of seconds
59 * in the future.
60 *
61 * @param time the number of seconds before this channel is automatically
62 * hung up.<br>
63 * 0 disables the autohangup feature.
64 * @since 0.2
65 */
66 void setAutoHangup(int time) throws AGIException;
67
68 /***
69 * Sets the caller id on the current channel.
70 *
71 * @param callerId the raw caller id to set, for example "John Doe<1234>".
72 * @since 0.2
73 */
74 void setCallerId(String callerId) throws AGIException;
75
76 /***
77 * Plays music on hold from the default music on hold class.
78 *
79 * @since 0.2
80 */
81 void playMusicOnHold() throws AGIException;
82
83 /***
84 * Plays music on hold from the given music on hold class.
85 *
86 * @param musicOnHoldClass the music on hold class to play music from as
87 * configures in Asterisk's <code><musiconhold.conf/code>.
88 * @since 0.2
89 */
90 void playMusicOnHold(String musicOnHoldClass) throws AGIException;
91
92 /***
93 * Stops playing music on hold.
94 *
95 * @since 0.2
96 */
97 void stopMusicOnHold() throws AGIException;
98
99 /***
100 * Returns the status of the channel.<br>
101 * Return values:
102 * <ul>
103 * <li>0 Channel is down and available
104 * <li>1 Channel is down, but reserved
105 * <li>2 Channel is off hook
106 * <li>3 Digits (or equivalent) have been dialed
107 * <li>4 Line is ringing
108 * <li>5 Remote end is ringing
109 * <li>6 Line is up
110 * <li>7 Line is busy
111 * </ul>
112 *
113 * @return the status of the channel.
114 * @since 0.2
115 */
116 int getChannelStatus() throws AGIException;
117
118 /***
119 * Plays the given file and waits for the user to enter DTMF digits until he
120 * presses '#'. The user may interrupt the streaming by starting to enter
121 * digits.
122 *
123 * @param file the name of the file to play
124 * @return a String containing the DTMF the user entered
125 * @since 0.2
126 */
127 String getData(String file) throws AGIException;
128
129 /***
130 * Plays the given file and waits for the user to enter DTMF digits until he
131 * presses '#' or the timeout occurs. The user may interrupt the streaming
132 * by starting to enter digits.
133 *
134 * @param file the name of the file to play
135 * @param timeout the timeout in milliseconds to wait for user input.<br>
136 * 0 means standard timeout value, -1 means "ludicrous time"
137 * (essentially never times out).
138 * @return a String containing the DTMF the user entered
139 * @since 0.2
140 */
141 String getData(String file, long timeout) throws AGIException;
142
143 /***
144 * Plays the given file and waits for the user to enter DTMF digits until he
145 * presses '#' or the timeout occurs or the maximum number of digits has
146 * been entered. The user may interrupt the streaming by starting to enter
147 * digits.
148 *
149 * @param file the name of the file to play
150 * @param timeout the timeout in milliseconds to wait for user input.<br>
151 * 0 means standard timeout value, -1 means "ludicrous time"
152 * (essentially never times out).
153 * @param maxDigits the maximum number of digits the user is allowed to
154 * enter
155 * @return a String containing the DTMF the user entered
156 * @since 0.2
157 */
158 String getData(String file, long timeout, int maxDigits)
159 throws AGIException;
160
161 /***
162 * Plays the given file, and waits for the user to press one of the given
163 * digits. If none of the esacpe digits is pressed while streaming the file
164 * it waits for the default timeout of 5 seconds still waiting for the user
165 * to press a digit.
166 *
167 * @param file the name of the file to stream, must not include extension.
168 * @param escapeDigits contains the digits that the user is expected to
169 * press.
170 * @return the DTMF digit pressed or 0x0 if none was pressed.
171 * @since 0.2
172 */
173 char getOption(String file, String escapeDigits) throws AGIException;
174
175 /***
176 * Plays the given file, and waits for the user to press one of the given
177 * digits. If none of the esacpe digits is pressed while streaming the file
178 * it waits for the specified timeout still waiting for the user to press a
179 * digit.
180 *
181 * @param file the name of the file to stream, must not include extension.
182 * @param escapeDigits contains the digits that the user is expected to
183 * press.
184 * @param timeout the timeout in seconds to wait if none of the defined
185 * esacpe digits was presses while streaming.
186 * @return the DTMF digit pressed or 0x0 if none was pressed.
187 * @since 0.2
188 */
189 char getOption(String file, String escapeDigits, int timeout)
190 throws AGIException;
191
192 /***
193 * Executes the given command.
194 *
195 * @param application the name of the application to execute, for example
196 * "Dial".
197 * @return the return code of the application of -2 if the application was
198 * not found.
199 * @since 0.2
200 */
201 int exec(String application) throws AGIException;
202
203 /***
204 * Executes the given command.
205 *
206 * @param application the name of the application to execute, for example
207 * "Dial".
208 * @param options the parameters to pass to the application, for example
209 * "SIP/123".
210 * @return the return code of the application of -2 if the application was
211 * not found.
212 * @since 0.2
213 */
214 int exec(String application, String options) throws AGIException;
215
216 /***
217 * Sets the context for continuation upon exiting the application.
218 *
219 * @param context the context for continuation upon exiting the application.
220 * @since 0.2
221 */
222 void setContext(String context) throws AGIException;
223
224 /***
225 * Sets the extension for continuation upon exiting the application.
226 *
227 * @param extension the extension for continuation upon exiting the
228 * application.
229 * @since 0.2
230 */
231 void setExtension(String extension) throws AGIException;
232
233 /***
234 * Sets the priority or label for continuation upon exiting the application.
235 *
236 * @param priority the priority or label for continuation upon exiting the
237 * application.
238 * @since 0.2
239 */
240 void setPriority(String priority) throws AGIException;
241
242 /***
243 * Plays the given file.
244 *
245 * @param file name of the file to play.
246 * @since 0.2
247 */
248 void streamFile(String file) throws AGIException;
249
250 /***
251 * Plays the given file and allows the user to escape by pressing one of the
252 * given digit.
253 *
254 * @param file name of the file to play.
255 * @param escapeDigits a String containing the DTMF digits that allow the
256 * user to escape.
257 * @return the DTMF digit pressed or 0x0 if none was pressed.
258 * @since 0.2
259 */
260 char streamFile(String file, String escapeDigits) throws AGIException;
261
262 /***
263 * Says the given digit string.
264 *
265 * @param digits the digit string to say.
266 * @since 0.2
267 */
268 void sayDigits(String digits) throws AGIException;
269
270 /***
271 * Says the given number, returning early if any of the given DTMF number
272 * are received on the channel.
273 *
274 * @param digits the digit string to say.
275 * @param escapeDigits a String containing the DTMF digits that allow the
276 * user to escape.
277 * @return the DTMF digit pressed or 0x0 if none was pressed.
278 * @since 0.2
279 */
280 char sayDigits(String digits, String escapeDigits) throws AGIException;
281
282 /***
283 * Says the given number.
284 *
285 * @param number the number to say.
286 * @since 0.2
287 */
288 void sayNumber(String number) throws AGIException;
289
290 /***
291 * Says the given number, returning early if any of the given DTMF number
292 * are received on the channel.
293 *
294 * @param number the number to say.
295 * @param escapeDigits a String containing the DTMF digits that allow the
296 * user to escape.
297 * @return the DTMF digit pressed or 0x0 if none was pressed.
298 * @since 0.2
299 */
300 char sayNumber(String number, String escapeDigits) throws AGIException;
301
302 /***
303 * Says the given character string with phonetics.
304 *
305 * @param text the text to say.
306 * @since 0.2
307 */
308 void sayPhonetic(String text) throws AGIException;
309
310 /***
311 * Says the given character string with phonetics, returning early if any of
312 * the given DTMF number are received on the channel.
313 *
314 * @param text the text to say.
315 * @param escapeDigits a String containing the DTMF digits that allow the
316 * user to escape.
317 * @return the DTMF digit pressed or 0x0 if none was pressed.
318 * @since 0.2
319 */
320 char sayPhonetic(String text, String escapeDigits) throws AGIException;
321
322 /***
323 * Says the given character string.
324 *
325 * @param text the text to say.
326 * @since 0.2
327 */
328 void sayAlpha(String text) throws AGIException;
329
330 /***
331 * Says the given character string, returning early if any of the given DTMF
332 * number are received on the channel.
333 *
334 * @param text the text to say.
335 * @param escapeDigits a String containing the DTMF digits that allow the
336 * user to escape.
337 * @return the DTMF digit pressed or 0x0 if none was pressed.
338 * @since 0.2
339 */
340 char sayAlpha(String text, String escapeDigits) throws AGIException;
341
342 /***
343 * Says the given time.
344 *
345 * @param time the time to say in seconds since 00:00:00 on January 1, 1970.
346 * @since 0.2
347 */
348 void sayTime(long time) throws AGIException;
349
350 /***
351 * Says the given time, returning early if any of the given DTMF number are
352 * received on the channel.
353 *
354 * @param time the time to say in seconds since 00:00:00 on January 1, 1970.
355 * @param escapeDigits a String containing the DTMF digits that allow the
356 * user to escape.
357 * @return the DTMF digit pressed or 0x0 if none was pressed.
358 * @since 0.2
359 */
360 char sayTime(long time, String escapeDigits) throws AGIException;
361
362 /***
363 * Returns the value of the current channel variable.
364 *
365 * @param name the name of the variable to retrieve.
366 * @return the value of the given variable or <code>null</code> if not
367 * set.
368 * @since 0.2
369 */
370 String getVariable(String name) throws AGIException;
371
372 /***
373 * Sets the value of the current channel variable to a new value.
374 *
375 * @param name the name of the variable to retrieve.
376 * @param value the new value to set.
377 * @since 0.2
378 */
379 void setVariable(String name, String value) throws AGIException;
380
381 /***
382 * Waits up to 'timeout' milliseconds to receive a DTMF digit.
383 *
384 * @param timeout timeout the milliseconds to wait for the channel to
385 * receive a DTMF digit, -1 will wait forever.
386 * @return the DTMF digit pressed or 0x0 if none was pressed.
387 * @since 0.2
388 */
389 char waitForDigit(int timeout) throws AGIException;
390
391 /***
392 * Returns the value of the current channel variable, unlike getVariable()
393 * this method understands complex variable names and builtin variables.<br>
394 * Available since Asterisk 1.2.
395 *
396 * @param name the name of the variable to retrieve.
397 * @return the value of the given variable or <code>null</code> if not
398 * set.
399 * @since 0.2
400 */
401 String getFullVariable(String name) throws AGIException;
402
403 /***
404 * Returns the value of the given channel variable.<br>
405 * Available since Asterisk 1.2.
406 *
407 * @param name the name of the variable to retrieve.
408 * @param channel the name of the channel.
409 * @return the value of the given variable or <code>null</code> if not
410 * set.
411 * @since 0.2
412 */
413 String getFullVariable(String name, String channel) throws AGIException;
414
415 /***
416 * Says the given time.<br>
417 * Available since Asterisk 1.2.
418 *
419 * @param time the time to say in seconds elapsed since 00:00:00 on January
420 * 1, 1970, Coordinated Universal Time (UTC)
421 * @since 0.2
422 */
423 void sayDateTime(long time) throws AGIException;
424
425 /***
426 * Says the given time and allows interruption by one of the given escape
427 * digits.<br>
428 * Available since Asterisk 1.2.
429 *
430 * @param time the time to say in seconds elapsed since 00:00:00 on January
431 * 1, 1970, Coordinated Universal Time (UTC)
432 * @param escapeDigits the digits that allow the user to interrupt this
433 * command or <code>null</code> for none.
434 * @return the DTMF digit pressed or 0x0 if none was pressed.
435 * @since 0.2
436 */
437 char sayDateTime(long time, String escapeDigits) throws AGIException;
438
439 /***
440 * Says the given time in the given format and allows interruption by one of
441 * the given escape digits.<br>
442 * Available since Asterisk 1.2.
443 *
444 * @param time the time to say in seconds elapsed since 00:00:00 on January
445 * 1, 1970, Coordinated Universal Time (UTC)
446 * @param escapeDigits the digits that allow the user to interrupt this
447 * command or <code>null</code> for none.
448 * @param format the format the time should be said in
449 * @return the DTMF digit pressed or 0x0 if none was pressed.
450 * @since 0.2
451 */
452 char sayDateTime(long time, String escapeDigits, String format)
453 throws AGIException;
454
455 /***
456 * Says the given time in the given format and timezone and allows
457 * interruption by one of the given escape digits.<br>
458 * Available since Asterisk 1.2.
459 *
460 * @param time the time to say in seconds elapsed since 00:00:00 on January
461 * 1, 1970, Coordinated Universal Time (UTC)
462 * @param escapeDigits the digits that allow the user to interrupt this
463 * command or <code>null</code> for none.
464 * @param format the format the time should be said in
465 * @param timezone the timezone to use when saying the time, for example
466 * "UTC" or "Europe/Berlin".
467 * @return the DTMF digit pressed or 0x0 if none was pressed.
468 * @since 0.2
469 */
470 char sayDateTime(long time, String escapeDigits, String format,
471 String timezone) throws AGIException;
472 }