Asterisk-Java

org.asteriskjava.live
Interface AsteriskChannel

All Superinterfaces:
LiveObject

public interface AsteriskChannel
extends LiveObject

Represents an Asterisk channel.

PropertyChangeEvents are fired for the following properties:

Author:
srt

Field Summary
static java.lang.String PROPERTY_ACCOUNT
           
static java.lang.String PROPERTY_CALL_DETAIL_RECORD
           
static java.lang.String PROPERTY_CALLER_ID
           
static java.lang.String PROPERTY_CURRENT_EXTENSION
           
static java.lang.String PROPERTY_DIALED_CHANNEL
           
static java.lang.String PROPERTY_DIALING_CHANNEL
           
static java.lang.String PROPERTY_DTMF_RECEIVED
           
static java.lang.String PROPERTY_DTMF_SENT
           
static java.lang.String PROPERTY_ID
           
static java.lang.String PROPERTY_LINKED_CHANNEL
           
static java.lang.String PROPERTY_MEET_ME_USER
           
static java.lang.String PROPERTY_NAME
           
static java.lang.String PROPERTY_PARKED_AT
           
static java.lang.String PROPERTY_QUEUE_ENTRY
           
static java.lang.String PROPERTY_STATE
           
static java.lang.String VARIABLE_MONITOR_EXEC
           
static java.lang.String VARIABLE_MONITOR_EXEC_ARGS
           
 
Method Summary
 void changeMonitoring(java.lang.String filename)
          Changes the filename of a previously started monitoring.
 java.lang.String getAccount()
          Returns the account code used to bill this channel.
 CallDetailRecord getCallDetailRecord()
          Returns the call detail record for this channel.
 CallerId getCallerId()
          Returns the caller id of this channel.
 Extension getCurrentExtension()
          Returns the last visited dialplan entry.
 java.util.Date getDateOfCreation()
          Returns the date this channel has been created.
 java.util.Date getDateOfRemoval()
          Returns the date this channel has left the Asterisk server for example by a hangup.
 AsteriskChannel getDialedChannel()
          Returns the channel that has been dialed by this channel most recently, this is the destination channel that was created because this channel dialed it.
 java.util.List<DialedChannelHistoryEntry> getDialedChannelHistory()
          Returns a list of all channels that have been dialed by this channel.
 AsteriskChannel getDialingChannel()
          Returns the channel that was dialing this channel, this is the source channel that created this channel by dialing it.
 java.lang.Character getDtmfReceived()
          Returns the last DTMF digit received on this channels.
 java.lang.Character getDtmfSent()
          Returns the last DTMF digit sent on this channels.
 java.util.List<ExtensionHistoryEntry> getExtensionHistory()
          Returns a list of all visited dialplan entries.
 Extension getFirstExtension()
          Returns the first visited dialplan entry.
 HangupCause getHangupCause()
          Returns the reason for hangup.
 java.lang.String getHangupCauseText()
          Returns a textual representation of the reason for hangup.
 java.lang.String getId()
          Returns the unique id of this channel, for example "1099015093.165".
 AsteriskChannel getLinkedChannel()
          Returns the channel this channel is currently bridged with, if any.
 java.util.List<LinkedChannelHistoryEntry> getLinkedChannelHistory()
          Returns a list of all channels this channel was briged with.
 MeetMeUser getMeetMeUser()
          Returns the MeetMeUser associated with this channel if this channel is currently taking part in a MeetMe conference.
 java.lang.String getName()
          Returns the name of this channel, for example "SIP/1310-20da".
 Extension getParkedAt()
          Return the extension to dial to pickup he channel of the parking if the channel is currently parked.
 AsteriskQueueEntry getQueueEntry()
          Returns the queue entry associated with this channel.
 ChannelState getState()
          Returns the state of this channel.
 java.lang.String getVariable(java.lang.String variable)
          Returns the value of the given channel variable.
 java.util.Map<java.lang.String,java.lang.String> getVariables()
          Returns the channel variables as received by VarSetEvents.
 void hangup()
          Hangs up this channel.
 void hangup(HangupCause cause)
          Hangs up this channel using a given cause code.
 void pauseMonitoring()
          Temporarily stops monitoring this channel.
 void playDtmf(java.lang.String digit)
          Plays the given DTMF digit on this channel.
 void redirect(java.lang.String context, java.lang.String exten, int priority)
          Redirects this channel to a new extension.
 void redirectBothLegs(java.lang.String context, java.lang.String exten, int priority)
          Redirects this channel and the channel this channel is linked to to a new extension.
 void setAbsoluteTimeout(int seconds)
          Sets the absolute maximum amount of time permitted for a call on a given channel, it hangs up the channel after this time.
 void setVariable(java.lang.String variable, java.lang.String value)
          Sets the value of the given channel variable.
 void startMonitoring(java.lang.String filename)
          Starts monitoring (recording) this channel.
 void startMonitoring(java.lang.String filename, java.lang.String format)
          Starts monitoring (recording) this channel using the given audio format.
 void startMonitoring(java.lang.String filename, java.lang.String format, boolean mix)
          Starts monitoring (recording) this channel using the given audio format and optionally mixing input and output data after recording is finished.
 void stopMonitoring()
          Stops monitoring this channel.
 void unpauseMonitoring()
          Re-enables monitoring this channel after calling pauseMonitoring().
 boolean wasBusy()
          Checks if this channel was busy.
 boolean wasInState(ChannelState state)
          Checks if this channel was at least once in the given state.
 boolean wasLinked()
          Indicates if this channel was linked to another channel at least once.
 
Methods inherited from interface org.asteriskjava.live.LiveObject
addPropertyChangeListener, addPropertyChangeListener, getServer, removePropertyChangeListener, removePropertyChangeListener
 

Field Detail

PROPERTY_ID

static final java.lang.String PROPERTY_ID
See Also:
Constant Field Values

PROPERTY_NAME

static final java.lang.String PROPERTY_NAME
See Also:
Constant Field Values

PROPERTY_CALLER_ID

static final java.lang.String PROPERTY_CALLER_ID
See Also:
Constant Field Values

PROPERTY_STATE

static final java.lang.String PROPERTY_STATE
See Also:
Constant Field Values

PROPERTY_ACCOUNT

static final java.lang.String PROPERTY_ACCOUNT
See Also:
Constant Field Values

PROPERTY_CURRENT_EXTENSION

static final java.lang.String PROPERTY_CURRENT_EXTENSION
See Also:
Constant Field Values

PROPERTY_CALL_DETAIL_RECORD

static final java.lang.String PROPERTY_CALL_DETAIL_RECORD
See Also:
Constant Field Values

PROPERTY_DIALED_CHANNEL

static final java.lang.String PROPERTY_DIALED_CHANNEL
See Also:
Constant Field Values

PROPERTY_DIALING_CHANNEL

static final java.lang.String PROPERTY_DIALING_CHANNEL
See Also:
Constant Field Values

PROPERTY_LINKED_CHANNEL

static final java.lang.String PROPERTY_LINKED_CHANNEL
See Also:
Constant Field Values

PROPERTY_MEET_ME_USER

static final java.lang.String PROPERTY_MEET_ME_USER
See Also:
Constant Field Values

PROPERTY_QUEUE_ENTRY

static final java.lang.String PROPERTY_QUEUE_ENTRY
See Also:
Constant Field Values

PROPERTY_PARKED_AT

static final java.lang.String PROPERTY_PARKED_AT
See Also:
Constant Field Values

PROPERTY_DTMF_RECEIVED

static final java.lang.String PROPERTY_DTMF_RECEIVED
See Also:
Constant Field Values

PROPERTY_DTMF_SENT

static final java.lang.String PROPERTY_DTMF_SENT
See Also:
Constant Field Values

VARIABLE_MONITOR_EXEC

static final java.lang.String VARIABLE_MONITOR_EXEC
See Also:
Constant Field Values

VARIABLE_MONITOR_EXEC_ARGS

static final java.lang.String VARIABLE_MONITOR_EXEC_ARGS
See Also:
Constant Field Values
Method Detail

getId

java.lang.String getId()
Returns the unique id of this channel, for example "1099015093.165".

Returns:
the unique id of this channel.

getName

java.lang.String getName()
Returns the name of this channel, for example "SIP/1310-20da".

Returns:
the name of this channel.

getCallerId

CallerId getCallerId()
Returns the caller id of this channel.

Returns:
the caller id of this channel.

getState

ChannelState getState()
Returns the state of this channel.

Returns:
the state of this channel.

wasInState

boolean wasInState(ChannelState state)
Checks if this channel was at least once in the given state.

For example you can use this method the check if this channel had been answered:

 boolean answered = channel.wasInState(ChannelState.UP);
 

Parameters:
state - the state to look for.
Returns:
true if this channel was at least once in the given state; false otherwise.
Since:
0.3

wasBusy

boolean wasBusy()
Checks if this channel was busy.

Returns:
true if this channel was busy; false otherwise.
Since:
0.3

getAccount

java.lang.String getAccount()
Returns the account code used to bill this channel.

Returns:
the account code used to bill this channel.

getCurrentExtension

Extension getCurrentExtension()
Returns the last visited dialplan entry.

Returns:
the last visited dialplan entry.
Since:
0.2

getFirstExtension

Extension getFirstExtension()
Returns the first visited dialplan entry.

Returns:
the first visited dialplan entry.
Since:
0.2

getExtensionHistory

java.util.List<ExtensionHistoryEntry> getExtensionHistory()
Returns a list of all visited dialplan entries.

Returns:
a list of all visited dialplan entries.
Since:
0.3

getDateOfCreation

java.util.Date getDateOfCreation()
Returns the date this channel has been created.

This property is immutable.

Returns:
the date this channel has been created.

getDateOfRemoval

java.util.Date getDateOfRemoval()
Returns the date this channel has left the Asterisk server for example by a hangup.

Returns:
the date this channel has left the Asterisk server or null if this channel is still active.
Since:
0.3

getHangupCause

HangupCause getHangupCause()
Returns the reason for hangup.

Returns:
the reason for hangup or null if the channel has not yet been hung up or no hangup cause is available for this type of channel.
Since:
0.3

getHangupCauseText

java.lang.String getHangupCauseText()
Returns a textual representation of the reason for hangup.

Returns:
the textual representation of the reason for hangup or null if the channel has not yet been hung up or no hangup cause is available for this type of channel. If no hangup cause is available an empty String may be returned, too.
Since:
0.3

getCallDetailRecord

CallDetailRecord getCallDetailRecord()
Returns the call detail record for this channel.

Returns:
the call detail record for this channel or null if none has (yet) been received.

getDialedChannel

AsteriskChannel getDialedChannel()
Returns the channel that has been dialed by this channel most recently, this is the destination channel that was created because this channel dialed it.

Returns:
the channel that has been dialed by this channel or null if none has been dialed.

getDialedChannelHistory

java.util.List<DialedChannelHistoryEntry> getDialedChannelHistory()
Returns a list of all channels that have been dialed by this channel.

Returns:
a list of all channels that have been dialed by this channel.

getDialingChannel

AsteriskChannel getDialingChannel()
Returns the channel that was dialing this channel, this is the source channel that created this channel by dialing it.

Returns:
the channel that was dialing this channel or null if none was dialing.

getLinkedChannel

AsteriskChannel getLinkedChannel()
Returns the channel this channel is currently bridged with, if any.

Returns:
the channel this channel is bridged with, or null if this channel is currently not bridged to another channel.

getLinkedChannelHistory

java.util.List<LinkedChannelHistoryEntry> getLinkedChannelHistory()
Returns a list of all channels this channel was briged with.

Returns:
a list of all channels this channel was briged with.

wasLinked

boolean wasLinked()
Indicates if this channel was linked to another channel at least once.

Returns:
true if this channel was linked to another channel at least once, false otherwise.
Since:
0.2

getMeetMeUser

MeetMeUser getMeetMeUser()
Returns the MeetMeUser associated with this channel if this channel is currently taking part in a MeetMe conference.

Returns:
the MeetMeUser associated with this channel or null if this channel is currently not taking part in a MeetMe conference.

getQueueEntry

AsteriskQueueEntry getQueueEntry()
Returns the queue entry associated with this channel.

Returns:
the queue entry associated with this channel if any, null otherwise.

getParkedAt

Extension getParkedAt()
Return the extension to dial to pickup he channel of the parking if the channel is currently parked.

Returns:
the Extension to dial, null if not currently parked.

getVariables

java.util.Map<java.lang.String,java.lang.String> getVariables()
Returns the channel variables as received by VarSetEvents.

Available since Asterisk 1.6.

Returns:
the channel variables.
Since:
1.0.0

getDtmfReceived

java.lang.Character getDtmfReceived()
Returns the last DTMF digit received on this channels.

Returns:
the last DTMF digit received on this channels or null if none has yet been received.
Since:
1.0.0

getDtmfSent

java.lang.Character getDtmfSent()
Returns the last DTMF digit sent on this channels.

Returns:
the last DTMF digit sent on this channels or null if none has yet been sent.
Since:
1.0.0

hangup

void hangup()
            throws ManagerCommunicationException,
                   NoSuchChannelException
Hangs up this channel.

Throws:
ManagerCommunicationException - if the hangup action cannot be sent to Asterisk.
NoSuchChannelException - if this channel had already been hung up before the hangup was sent.
Since:
0.3

hangup

void hangup(HangupCause cause)
            throws ManagerCommunicationException,
                   NoSuchChannelException
Hangs up this channel using a given cause code. The cause code is mainly used for Zap PRI channels where it makes Asterisk send a PRI DISCONNECT message with the set CAUSE element to the switch.

Parameters:
cause - the cause code to send.
Throws:
ManagerCommunicationException - if the hangup action cannot be sent to Asterisk.
NoSuchChannelException - if this channel had already been hung up before the hangup was sent.
Since:
0.3

setAbsoluteTimeout

void setAbsoluteTimeout(int seconds)
                        throws ManagerCommunicationException,
                               NoSuchChannelException
Sets the absolute maximum amount of time permitted for a call on a given channel, it hangs up the channel after this time.

Time is counted from when you call setAbsoluteTimeout, not from the beginning of the call.

Parameters:
seconds - maximum duration of the call in seconds, 0 for unlimited call length.
Throws:
ManagerCommunicationException - if the absolute timeout action cannot be sent to Asterisk.
NoSuchChannelException - if this channel had already been hung up before the absolute timeout was set.
Since:
0.3

redirect

void redirect(java.lang.String context,
              java.lang.String exten,
              int priority)
              throws ManagerCommunicationException,
                     NoSuchChannelException
Redirects this channel to a new extension.

If this channel is linked to another channel, the linked channel is hung up.

Parameters:
context - the destination context.
exten - the destination extension.
priority - the destination priority.
Throws:
ManagerCommunicationException - if the redirect action cannot be sent to Asterisk.
NoSuchChannelException - if this channel had been hung up before the redirect was sent.
Since:
0.3

redirectBothLegs

void redirectBothLegs(java.lang.String context,
                      java.lang.String exten,
                      int priority)
                      throws ManagerCommunicationException,
                             NoSuchChannelException
Redirects this channel and the channel this channel is linked to to a new extension.

If this channel is not linked to another channel only this channel is redirected.

Parameters:
context - the destination context.
exten - the destination extension.
priority - the destination priority.
Throws:
ManagerCommunicationException - if the redirect action cannot be sent to Asterisk.
NoSuchChannelException - if this channel had been hung up before the redirect was sent.
Since:
0.3

getVariable

java.lang.String getVariable(java.lang.String variable)
                             throws ManagerCommunicationException,
                                    NoSuchChannelException
Returns the value of the given channel variable.

Currently Asterisk does not support the retrieval of built-in variables like EXTEN or CALLERIDNUM but only custom variables set via Asterisk's Set command or via setVariable(String, String).

Parameters:
variable - the name of the channel variable to return.
Returns:
the value of the channel variable or null if it is not set.
Throws:
ManagerCommunicationException - if the get variable action cannot be sent to Asterisk.
NoSuchChannelException - if this channel had been hung up before the variable was requested.
Since:
0.3

setVariable

void setVariable(java.lang.String variable,
                 java.lang.String value)
                 throws ManagerCommunicationException,
                        NoSuchChannelException
Sets the value of the given channel variable.

Parameters:
variable - the name of the channel variable to set.
value - the value of the channel variable to set.
Throws:
ManagerCommunicationException - if the set variable action cannot be sent to Asterisk.
NoSuchChannelException - if this channel had been hung up before the variable was set.
Since:
0.3

playDtmf

void playDtmf(java.lang.String digit)
              throws ManagerCommunicationException,
                     NoSuchChannelException,
                     java.lang.IllegalArgumentException
Plays the given DTMF digit on this channel.

Available since Asterisk 1.2.8

Parameters:
digit - the DTMF digit to play.
Throws:
ManagerCommunicationException - if the play DTMF action cannot be sent to Asterisk.
NoSuchChannelException - if this channel had been hung up before the DTMF digit was set.
java.lang.IllegalArgumentException - if the digit is null.
Since:
0.3

startMonitoring

void startMonitoring(java.lang.String filename)
                     throws ManagerCommunicationException,
                            NoSuchChannelException
Starts monitoring (recording) this channel.

The format of the files is "wav", they are not mixed.

The files are called filename-in.wav and filename-out.wav.

Parameters:
filename - the basename of the files created in the monitor spool directory. If null the channel name (with slashed replaced by dashes) is used.
Throws:
ManagerCommunicationException - if the monitor action cannot be sent to Asterisk.
NoSuchChannelException - if this channel had been hung up before starting monitoring.
Since:
0.3
See Also:
stopMonitoring(), pauseMonitoring()

startMonitoring

void startMonitoring(java.lang.String filename,
                     java.lang.String format)
                     throws ManagerCommunicationException,
                            NoSuchChannelException
Starts monitoring (recording) this channel using the given audio format.

The files are not mixed.

The files are called filename-in.format and filename-out.format.

Parameters:
filename - the basename of the files created in the monitor spool directory. If null the channel name (with slashed replaced by dashes) is used.
format - the audio recording format. If null wav is used.
Throws:
ManagerCommunicationException - if the monitor action cannot be sent to Asterisk.
NoSuchChannelException - if this channel had been hung up before starting monitoring.
Since:
0.3
See Also:
stopMonitoring(), pauseMonitoring()

startMonitoring

void startMonitoring(java.lang.String filename,
                     java.lang.String format,
                     boolean mix)
                     throws ManagerCommunicationException,
                            NoSuchChannelException
Starts monitoring (recording) this channel using the given audio format and optionally mixing input and output data after recording is finished.

Mixing is done by soxmix by default (which has to be installed on your Asterisk server). You can use your own script by setting the variable MONITOR_EXEC to your custom script before starting monitoring the channel. Your script is then called with 3 arguments, the two leg files and a target mixed file name which is the same as the leg file names without the in/out designator, i.e. filename.format.
The two leg files are only removed by Asterisk if MONITOR_EXEC is not set. If you use a custom script and want to remove them, just let your script do this.
To pass additional arguments to your script you can set the variable MONITOR_EXEC_ARGS to a list of arguments (separated by spaces).

Example:

      AsteriskChannel c;
      
      [...]
      c.setVariable(AsteriskChannel.VARIABLE_MONITOR_EXEC, "/usr/local/bin/2wav2mp3");
      c.startMonitoring("my-recording", "wav", true);
 
Side note: 2wav2mp3 is a nice script by Dietmar Zlabinger to mix the two legs to a stero mp3 file, for details see voip-info.org.

Parameters:
filename - the basename of the file(s) created in the monitor spool directory. If null the channel name (with slashed replaced by dashes) is used.
format - the audio recording format. If null wav is used.
mix - true to mix input and output data together after recording is finished, false to not mix them.
Throws:
ManagerCommunicationException - if the monitor action cannot be sent to Asterisk.
NoSuchChannelException - if this channel had been hung up before starting monitoring.
Since:
0.3
See Also:
VARIABLE_MONITOR_EXEC, VARIABLE_MONITOR_EXEC_ARGS, stopMonitoring(), pauseMonitoring()

changeMonitoring

void changeMonitoring(java.lang.String filename)
                      throws ManagerCommunicationException,
                             NoSuchChannelException,
                             java.lang.IllegalArgumentException
Changes the filename of a previously started monitoring.

If the channel exists but is not currently monitored your request is ignored and a warning message is written to Asterisk's CLI.

Use with care, this doesn't always seem to work.

Parameters:
filename - the basename of the file(s) created in the monitor spool directory.
Throws:
ManagerCommunicationException - if the change monitor action cannot be sent to Asterisk.
NoSuchChannelException - if this channel had been hung up before changing monitoring.
java.lang.IllegalArgumentException - if filename is null.
Since:
0.3
See Also:
stopMonitoring(), pauseMonitoring()

stopMonitoring

void stopMonitoring()
                    throws ManagerCommunicationException,
                           NoSuchChannelException
Stops monitoring this channel.

If the channel exists but is not currently monitored your request is ignored.

Throws:
ManagerCommunicationException - if the stop monitor action cannot be sent to Asterisk.
NoSuchChannelException - if this channel had been hung up before stopping monitoring.
Since:
0.3
See Also:
startMonitoring(String), startMonitoring(String, String), startMonitoring(String, String, boolean)

pauseMonitoring

void pauseMonitoring()
                     throws ManagerCommunicationException,
                            NoSuchChannelException
Temporarily stops monitoring this channel.

If the channel exists but is not currently monitored your request is ignored.

This method is available since Asterisk 1.4.

Throws:
ManagerCommunicationException - if the pause monitor action cannot be sent to Asterisk.
NoSuchChannelException - if this channel had been hung up before temporarily stopping monitoring.
Since:
0.3
See Also:
unpauseMonitoring()

unpauseMonitoring

void unpauseMonitoring()
                       throws ManagerCommunicationException,
                              NoSuchChannelException
Re-enables monitoring this channel after calling pauseMonitoring().

If the channel exists but monitoring has not been paused your request is ignored.

This method is available since Asterisk 1.4.

Throws:
ManagerCommunicationException - if the unpasue monitor action cannot be sent to Asterisk.
NoSuchChannelException - if this channel had been hung up before re-enabling monitoring.
Since:
0.3
See Also:
pauseMonitoring()

Asterisk-Java

Copyright © 2004-2009 Stefan Reuter. All Rights Reserved.