1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package org.asteriskjava.live;
18
19 import java.util.Date;
20 import java.util.List;
21
22 /***
23 * Represents an Asterisk channel.
24 * <p>
25 * PropertyChangeEvents are fired for the following properties:
26 * <ul>
27 * <li>name
28 * <li>callerId
29 * <li>state
30 * <li>account
31 * <li>currentExtension
32 * <li>callDetailRecord
33 * <li>dialedChannel
34 * <li>dialingChannel
35 * <li>linkedChannel
36 * <li>meetMeUser
37 * </ul>
38 *
39 * @author srt
40 */
41 public interface AsteriskChannel extends LiveObject
42 {
43 String PROPERTY_NAME = "name";
44 String PROPERTY_CALLER_ID = "callerId";
45 String PROPERTY_STATE = "state";
46 String PROPERTY_ACCOUNT = "account";
47 String PROPERTY_CURRENT_EXTENSION = "currentExtension";
48 String PROPERTY_CALL_DETAIL_RECORD = "callDetailRecord";
49 String PROPERTY_DIALED_CHANNEL = "dialedChannel";
50 String PROPERTY_DIALING_CHANNEL = "dialingChannel";
51 String PROPERTY_LINKED_CHANNEL = "linkedChannel";
52 String PROPERTY_MEET_ME_USER = "meetMeUser";
53
54 String VARIABLE_MONITOR_EXEC = "MONITOR_EXEC";
55 String VARIABLE_MONITOR_EXEC_ARGS = "MONITOR_EXEC_ARGS";
56
57 /***
58 * Returns the unique id of this channel, for example "1099015093.165".
59 * <p>
60 * The unique id of an AsteriskChannel is immutable for the whole lifecycle
61 * of the channel.
62 *
63 * @return the unique id of this channel.
64 */
65 String getId();
66
67 /***
68 * Returns the name of this channel, for example "SIP/1310-20da".
69 * <p>
70 * In contrast to the unique id the name of an AsteriskChannel can change
71 * while the call is processed.
72 *
73 * @return the name of this channel.
74 */
75 String getName();
76
77 /***
78 * Returns the caller id of this channel.
79 *
80 * @return the caller id of this channel.
81 */
82 CallerId getCallerId();
83
84 /***
85 * Returns the state of this channel.
86 *
87 * @return the state of this channel.
88 */
89 ChannelState getState();
90
91 /***
92 * Checks if this channel was at least once in the given state.
93 * <p>
94 * For example you can use this method the check if this channel had been
95 * answered:
96 *
97 * <pre>
98 * boolean answered = channel.wasInState(ChannelState.UP);
99 * </pre>
100 *
101 * @param state the state to look for.
102 * @return <code>true</code> if this channel was at least once in the
103 * given state; <code>false</code> otherwise.
104 * @since 0.3
105 */
106 boolean wasInState(ChannelState state);
107
108 /***
109 * Checks if this channel was busy.
110 *
111 * @return <code>true</code> if this channel was busy; <code>false</code>
112 * otherwise.
113 * @since 0.3
114 */
115 boolean wasBusy();
116
117 /***
118 * Returns the account code used to bill this channel.
119 *
120 * @return the account code used to bill this channel.
121 */
122 String getAccount();
123
124 /***
125 * Returns the last visited dialplan entry.
126 *
127 * @return the last visited dialplan entry.
128 * @since 0.2
129 */
130 Extension getCurrentExtension();
131
132 /***
133 * Returns the first visited dialplan entry.
134 *
135 * @return the first visited dialplan entry.
136 * @since 0.2
137 */
138 Extension getFirstExtension();
139
140 /***
141 * Returns a list of all visited dialplan entries.
142 *
143 * @return a list of all visited dialplan entries.
144 * @since 0.3
145 */
146 List<ExtensionHistoryEntry> getExtensionHistory();
147
148 /***
149 * Returns the date this channel has been created.
150 * <p>
151 * This property is immutable.
152 *
153 * @return the date this channel has been created.
154 */
155 Date getDateOfCreation();
156
157 /***
158 * Returns the date this channel has left the Asterisk server for example by
159 * a hangup.
160 *
161 * @return the date this channel has left the Asterisk server or
162 * <code>null</code> if this channel is still active.
163 * @since 0.3
164 */
165 Date getDateOfRemoval();
166
167 /***
168 * Returns the reason for hangup.
169 *
170 * @return the reason for hangup or <code>null</code> if the channel has
171 * not yet been hung up or no hangup cause is available for this
172 * type of channel.
173 * @since 0.3
174 */
175 HangupCause getHangupCause();
176
177 /***
178 * Returns a textual representation of the reason for hangup.
179 *
180 * @return the textual representation of the reason for hangup or
181 * <code>null</code> if the channel has not yet been hung up or no
182 * hangup cause is available for this type of channel. If no hangup
183 * cause is available an empty String may be returned, too.
184 * @since 0.3
185 */
186 String getHangupCauseText();
187
188 /***
189 * Returns the call detail record for this channel.
190 *
191 * @return the call detail record for this channel or <code>null</code> if
192 * none has (yet) been received.
193 */
194 CallDetailRecord getCallDetailRecord();
195
196 /***
197 * Returns the channel that has been dialed by this channel most recently,
198 * this is the destination channel that was created because this channel
199 * dialed it.
200 *
201 * @return the channel that has been dialed by this channel or
202 * <code>null</code> if none has been dialed.
203 */
204 AsteriskChannel getDialedChannel();
205
206 /***
207 * Returns a list of all channels that have been dialed by this channel.
208 *
209 * @return a list of all channels that have been dialed by this channel.
210 */
211 List<DialedChannelHistoryEntry> getDialedChannelHistory();
212
213 /***
214 * Returns the channel that was dialing this channel, this is the source
215 * channel that created this channel by dialing it.
216 *
217 * @return the channel that was dialing this channel or <code>null</code>
218 * if none was dialing.
219 */
220 AsteriskChannel getDialingChannel();
221
222 /***
223 * Returns the channel this channel is currently bridged with, if any.
224 *
225 * @return the channel this channel is bridged with, or <code>null</code>
226 * if this channel is currently not bridged to another channel.
227 */
228 AsteriskChannel getLinkedChannel();
229
230 /***
231 * Returns a list of all channels this channel was briged with.
232 *
233 * @return a list of all channels this channel was briged with.
234 */
235 List<LinkedChannelHistoryEntry> getLinkedChannelHistory();
236
237 /***
238 * Indicates if this channel was linked to another channel at least once.
239 *
240 * @return <code>true</code> if this channel was linked to another channel
241 * at least once, <code>false</code> otherwise.
242 * @since 0.2
243 */
244 boolean wasLinked();
245
246 /***
247 * Returns the MeetMeUser associated with this channel if this channel is
248 * currently taking part in a MeetMe conference.
249 *
250 * @return the MeetMeUser associated with this channel or <code>null</code>
251 * if this channel is currently not taking part in a MeetMe
252 * conference.
253 */
254 MeetMeUser getMeetMeUser();
255
256 /***
257 * Hangs up this channel.
258 *
259 * @throws ManagerCommunicationException if the hangup action cannot be sent
260 * to Asterisk.
261 * @throws NoSuchChannelException if this channel had already been hung up
262 * before the hangup was sent.
263 * @since 0.3
264 */
265 void hangup() throws ManagerCommunicationException, NoSuchChannelException;
266
267 /***
268 * Hangs up this channel using a given cause code. The cause code is mainly
269 * used for Zap PRI channels where it makes Asterisk send a PRI DISCONNECT
270 * message with the set CAUSE element to the switch.
271 *
272 * @param cause the cause code to send.
273 * @throws ManagerCommunicationException if the hangup action cannot be sent
274 * to Asterisk.
275 * @throws NoSuchChannelException if this channel had already been hung up
276 * before the hangup was sent.
277 * @since 0.3
278 */
279 void hangup(HangupCause cause) throws ManagerCommunicationException, NoSuchChannelException;
280
281 /***
282 * Sets the absolute maximum amount of time permitted for a call on a given
283 * channel, it hangs up the channel after this time.
284 * <p>
285 * Time is counted from when you call setAbsoluteTimeout, not from the
286 * beginning of the call.
287 *
288 * @param seconds maximum duration of the call in seconds, 0 for unlimited
289 * call length.
290 * @throws ManagerCommunicationException if the absolute timeout action
291 * cannot be sent to Asterisk.
292 * @throws NoSuchChannelException if this channel had already been hung up
293 * before the absolute timeout was set.
294 * @since 0.3
295 */
296
297
298 void setAbsoluteTimeout(int seconds) throws ManagerCommunicationException, NoSuchChannelException;
299
300 /***
301 * Redirects this channel to a new extension.
302 * <p>
303 * If this channel is linked to another channel, the linked channel is hung
304 * up.
305 *
306 * @param context the destination context.
307 * @param exten the destination extension.
308 * @param priority the destination priority.
309 * @throws ManagerCommunicationException if the redirect action cannot be
310 * sent to Asterisk.
311 * @throws NoSuchChannelException if this channel had been hung up before
312 * the redirect was sent.
313 * @since 0.3
314 */
315 void redirect(String context, String exten, int priority) throws ManagerCommunicationException, NoSuchChannelException;
316
317 /***
318 * Redirects this channel and the channel this channel is linked to to a new
319 * extension.
320 * <p>
321 * If this channel is not linked to another channel only this channel is
322 * redirected.
323 *
324 * @param context the destination context.
325 * @param exten the destination extension.
326 * @param priority the destination priority.
327 * @throws ManagerCommunicationException if the redirect action cannot be
328 * sent to Asterisk.
329 * @throws NoSuchChannelException if this channel had been hung up before
330 * the redirect was sent.
331 * @since 0.3
332 */
333 void redirectBothLegs(String context, String exten, int priority) throws ManagerCommunicationException,
334 NoSuchChannelException;
335
336 /***
337 * Returns the value of the given channel variable.
338 * <p>
339 * Currently Asterisk does not support the retrieval of built-in variables
340 * like EXTEN or CALLERIDNUM but only custom variables set via Asterisk's
341 * Set command or via {@link #setVariable(String, String)}.
342 *
343 * @param variable the name of the channel variable to return.
344 * @return the value of the channel variable or <code>null</code> if it is
345 * not set.
346 * @throws ManagerCommunicationException if the get variable action cannot
347 * be sent to Asterisk.
348 * @throws NoSuchChannelException if this channel had been hung up before
349 * the variable was requested.
350 * @since 0.3
351 */
352 String getVariable(String variable) throws ManagerCommunicationException, NoSuchChannelException;
353
354 /***
355 * Sets the value of the given channel variable.
356 *
357 * @param variable the name of the channel variable to set.
358 * @param value the value of the channel variable to set.
359 * @throws ManagerCommunicationException if the set variable action cannot
360 * be sent to Asterisk.
361 * @throws NoSuchChannelException if this channel had been hung up before
362 * the variable was set.
363 * @since 0.3
364 */
365 void setVariable(String variable, String value) throws ManagerCommunicationException, NoSuchChannelException;
366
367 /***
368 * Plays the given DTMF digit on this channel.
369 * <p>
370 * Available since Asterisk 1.2.8
371 *
372 * @param digit the DTMF digit to play.
373 * @throws ManagerCommunicationException if the play DTMF action cannot be
374 * sent to Asterisk.
375 * @throws NoSuchChannelException if this channel had been hung up before
376 * the DTMF digit was set.
377 * @throws IllegalArgumentException if the digit is <code>null</code>.
378 * @since 0.3
379 */
380 void playDtmf(String digit) throws ManagerCommunicationException, NoSuchChannelException, IllegalArgumentException;
381
382 /***
383 * Starts monitoring (recording) this channel.
384 * <p>
385 * The format of the files is "wav", they are not mixed.
386 * <p>
387 * The files are called <i>filename</i>-in.wav and <i>filename</i>-out.wav.
388 *
389 * @param filename the basename of the files created in the monitor spool
390 * directory. If <code>null</code> the channel name (with
391 * slashed replaced by dashes) is used.
392 * @throws ManagerCommunicationException if the monitor action cannot be
393 * sent to Asterisk.
394 * @throws NoSuchChannelException if this channel had been hung up before
395 * starting monitoring.
396 * @see #stopMonitoring()
397 * @see #pauseMonitoring()
398 * @since 0.3
399 */
400 void startMonitoring(String filename) throws ManagerCommunicationException, NoSuchChannelException;
401
402 /***
403 * Starts monitoring (recording) this channel using the given audio format.
404 * <p>
405 * The files are not mixed.
406 * <p>
407 * The files are called <i>filename</i>-in.<i>format</i> and <i>filename</i>-out.<i>format</i>.
408 *
409 * @param filename the basename of the files created in the monitor spool
410 * directory. If <code>null</code> the channel name (with
411 * slashed replaced by dashes) is used.
412 * @param format the audio recording format. If <code>null</code> wav is
413 * used.
414 * @throws ManagerCommunicationException if the monitor action cannot be
415 * sent to Asterisk.
416 * @throws NoSuchChannelException if this channel had been hung up before
417 * starting monitoring.
418 * @see #stopMonitoring()
419 * @see #pauseMonitoring()
420 * @since 0.3
421 */
422 void startMonitoring(String filename, String format) throws ManagerCommunicationException, NoSuchChannelException;
423
424 /***
425 * Starts monitoring (recording) this channel using the given audio format
426 * and optionally mixing input and output data after recording is finished.
427 * <p>
428 * Mixing is done by soxmix by default (which has to be installed on your
429 * Asterisk server). You can use your own script by setting the variable
430 * <code>MONITOR_EXEC</code> to your custom script before starting
431 * monitoring the channel. Your script is then called with 3 arguments, the
432 * two leg files and a target mixed file name which is the same as the leg
433 * file names without the in/out designator, i.e. <i>filename</i>.<i>format</i>.<br>
434 * The two leg files are only removed by Asterisk if
435 * <code>MONITOR_EXEC</code> is not set. If you use a custom script and
436 * want to remove them, just let your script do this.<br>
437 * To pass additional arguments to your script you can set the variable
438 * <code>MONITOR_EXEC_ARGS</code> to a list of arguments (separated by
439 * spaces).
440 * <p>
441 * Example:
442 *
443 * <pre>
444 * AsteriskChannel c;
445 *
446 * [...]
447 * c.setVariable(AsteriskChannel.VARIABLE_MONITOR_EXEC, "/usr/local/bin/2wav2mp3");
448 * c.startMonitoring("my-recording", "wav", true);
449 * </pre>
450 *
451 * Side note: <tt>2wav2mp3</tt> is a nice script by Dietmar Zlabinger to mix the two
452 * legs to a stero mp3 file, for details see
453 * <a href="http://www.voip-info.org/wiki/view/Monitor+stereo-example">voip-info.org</a>.
454 *
455 * @param filename the basename of the file(s) created in the monitor spool
456 * directory. If <code>null</code> the channel name (with
457 * slashed replaced by dashes) is used.
458 * @param format the audio recording format. If <code>null</code> wav is
459 * used.
460 * @param mix <code>true</code> to mix input and output data together
461 * after recording is finished, <code>false</code> to not mix
462 * them.
463 * @throws ManagerCommunicationException if the monitor action cannot be
464 * sent to Asterisk.
465 * @throws NoSuchChannelException if this channel had been hung up before
466 * starting monitoring.
467 * @see #VARIABLE_MONITOR_EXEC
468 * @see #VARIABLE_MONITOR_EXEC_ARGS
469 * @see #stopMonitoring()
470 * @see #pauseMonitoring()
471 * @since 0.3
472 */
473 void startMonitoring(String filename, String format, boolean mix) throws ManagerCommunicationException,
474 NoSuchChannelException;
475
476 /***
477 * Changes the filename of a previously started monitoring.
478 * <p>
479 * If the channel exists but is not currently monitored your request is
480 * ignored and a warning message is written to Asterisk's CLI.
481 * <p>
482 * Use with care, this doesn't always seem to work.
483 *
484 * @param filename the basename of the file(s) created in the monitor spool
485 * directory.
486 * @throws ManagerCommunicationException if the change monitor action cannot
487 * be sent to Asterisk.
488 * @throws NoSuchChannelException if this channel had been hung up before
489 * changing monitoring.
490 * @throws IllegalArgumentException if filename is <code>null</code>.
491 * @see #stopMonitoring()
492 * @see #pauseMonitoring()
493 * @since 0.3
494 */
495 void changeMonitoring(String filename) throws ManagerCommunicationException, NoSuchChannelException,
496 IllegalArgumentException;
497
498 /***
499 * Stops monitoring this channel.
500 * <p>
501 * If the channel exists but is not currently monitored your request is
502 * ignored.
503 *
504 * @throws ManagerCommunicationException if the stop monitor action cannot
505 * be sent to Asterisk.
506 * @throws NoSuchChannelException if this channel had been hung up before
507 * stopping monitoring.
508 * @see #startMonitoring(String)
509 * @see #startMonitoring(String, String)
510 * @see #startMonitoring(String, String, boolean)
511 * @since 0.3
512 */
513 void stopMonitoring() throws ManagerCommunicationException, NoSuchChannelException;
514
515 /***
516 * Temporarily stops monitoring this channel.
517 * <p>
518 * If the channel exists but is not currently monitored your request is
519 * ignored.
520 * <p>
521 * This method is available since Asterisk 1.4.
522 *
523 * @throws ManagerCommunicationException if the pause monitor action cannot
524 * be sent to Asterisk.
525 * @throws NoSuchChannelException if this channel had been hung up before
526 * temporarily stopping monitoring.
527 * @see #unpauseMonitoring()
528 * @since 0.3
529 */
530 void pauseMonitoring() throws ManagerCommunicationException, NoSuchChannelException;
531
532 /***
533 * Re-enables monitoring this channel after calling
534 * {@link #pauseMonitoring()}.
535 * <p>
536 * If the channel exists but monitoring has not been paused your request is
537 * ignored.
538 * <p>
539 * This method is available since Asterisk 1.4.
540 *
541 * @throws ManagerCommunicationException if the unpasue monitor action
542 * cannot be sent to Asterisk.
543 * @throws NoSuchChannelException if this channel had been hung up before
544 * re-enabling monitoring.
545 * @see #pauseMonitoring()
546 * @since 0.3
547 */
548 void unpauseMonitoring() throws ManagerCommunicationException, NoSuchChannelException;
549 }