org.asteriskjava.live

Interface AsteriskServer

All Known Implementing Classes:

AsteriskServerImpl, DefaultAsteriskServer, SecureAsteriskServer

public interface AsteriskServer

The AsteriskServer is built on top of the ManagerConnection and is an attempt to simplify interaction with Asterisk by abstracting the interface.
You will certainly have less freedom using AsteriskServer but it will make life easier for easy things (like originating a call or getting a list of open channels).
AsteriskServer is still in an early state of development. So, when using AsteriskServer be aware that it might change in the future.

Version:

$Id$

Author:

srt

Method Summary

Modifier and Type	Method and Description
void	addAsteriskServerListener(AsteriskServerListener listener) Adds a listener to this AsteriskServer. If this server is not yet connected it will be implicitly connected.
void	addChainListener(ManagerEventListener chainListener) The chainListener allows a listener to receive manager events after they have been processed by the AsteriskServer.
List<String>	executeCliCommand(String command) Executes a command line interface (CLI) command.
void	forceQueuesMonitor(boolean force) every time we get an event of a queue we reload the information about it from the Asterisk Server
Collection<AsteriskAgent>	getAgents() Return the agents, registered at Asterisk server.
AsteriskChannel	getChannelById(String id) Returns a channel by its unique id.
AsteriskChannel	getChannelByName(String name) Returns a channel by its name.
Collection<AsteriskChannel>	getChannels() Returns the active channels of the Asterisk server.
ConfigFile	getConfig(String filename) Reads the given Asterisk configuration file.
String	getGlobalVariable(String variable) Returns the value of the given global variable.
ManagerConnection	getManagerConnection() Returns the underlying ManagerConnection.
MeetMeRoom	getMeetMeRoom(String roomNumber) Returns the MeetMe room with the given number, if the room does not yet exist a new MeetMeRoom object is created.
Collection<MeetMeRoom>	getMeetMeRooms() Returns the acitve MeetMe rooms on the Asterisk server.
AsteriskQueue	getQueueByName(String queueName) get Asterisk Queue by name
Collection<AsteriskQueue>	getQueues() Returns the queues served by the Asterisk server.
List<AsteriskQueue>	getQueuesUpdatedAfter(Date date) List of Queues Objects updated after certain date
String	getVersion() Returns the exact version string of this Asterisk server.
int[]	getVersion(String file) <<<<<<< HEAD Returns the CVS revision of a given source file of this Asterisk server.
Collection<Voicemailbox>	getVoicemailboxes() Returns a collection of all voicemailboxes configured for this Asterisk server with the number of new and old messages they contain.
void	initialize() Opens the connection to this server.
boolean	isAsteriskServerListening(AsteriskServerListener listener) Checks whether the listener is already registered with this Asterisk server
boolean	isModuleLoaded(String module) Checks whether a module is currently loaded.
boolean	isQueuesMonitorForced() Check if the Queue Information is forced
void	loadModule(String module) Loads a module or subsystem
AsteriskChannel	originate(OriginateAction originateAction) Generates an outgoing channel.
void	originateAsync(OriginateAction originateAction, OriginateCallback cb) Asynchronously generates an outgoing channel.
AsteriskChannel	originateToApplication(String channel, String application, String data, long timeout) Generates an outgoing channel to an application.
AsteriskChannel	originateToApplication(String channel, String application, String data, long timeout, CallerId callerId, Map<String,String> variables) Generates an outgoing channel to an application and sets an optional map of channel variables.
void	originateToApplicationAsync(String channel, String application, String data, long timeout, CallerId callerId, Map<String,String> variables, OriginateCallback callback) Asynchronously generates an outgoing channel to an application and sets an optional map of channel variables.
void	originateToApplicationAsync(String channel, String application, String data, long timeout, OriginateCallback callback) Asynchronously generates an outgoing channel to an application.
AsteriskChannel	originateToExtension(String channel, String context, String exten, int priority, long timeout) Generates an outgoing channel to a dialplan entry (extension, context, priority).
AsteriskChannel	originateToExtension(String channel, String context, String exten, int priority, long timeout, CallerId callerId, Map<String,String> variables) Generates an outgoing channel to a dialplan entry (extension, context, priority) and sets an optional map of channel variables.
void	originateToExtensionAsync(String channel, String context, String exten, int priority, long timeout, CallerId callerId, Map<String,String> variables, OriginateCallback callback) Asynchronously generates an outgoing channel to a dialplan entry (extension, context, priority) and sets an optional map of channel variables.
void	originateToExtensionAsync(String channel, String context, String exten, int priority, long timeout, OriginateCallback callback) Asynchronously generates an outgoing channel to a dialplan entry (extension, context, priority).
void	reloadAllModules() Reloads all currently loaded modules.
void	reloadModule(String module) Reloads a module or subsystem.
void	removeAsteriskServerListener(AsteriskServerListener listener) Removes a listener from this Asterisk server.
void	removeChainListener(ManagerEventListener chainListener) remove the chain listener.
void	setGlobalVariable(String variable, String value) Sets the value of the given global variable.
void	shutdown() Closes the connection to this server.
void	unloadModule(String module) Unloads a module or subsystem.

Method Detail

getManagerConnection

ManagerConnection getManagerConnection()

Returns the underlying ManagerConnection.

Unlike the methods operating on the manager connection this method does not implicitly initialize the connection. Thus you can use this method to add custom ManagerEventListeners before the connection to the Asterisk server is established. If you want to ensure that the connection is established call initialize().

Returns:

the underlying ManagerConnection.

originate

AsteriskChannel originate(OriginateAction originateAction)
                   throws ManagerCommunicationException,
                          NoSuchChannelException

Generates an outgoing channel.

Parameters:

originateAction - the action that contains parameters for the originate

Returns:

the generated channel

Throws:

NoSuchChannelException - if the channel is not available on the Asterisk server, for example because you used "SIP/1310" and 1310 is not a valid SIP user, the SIP channel module hasn't been loaded or the SIP or IAX peer is not registered currently.

ManagerCommunicationException - if the originate action cannot be sent to Asterisk

originateAsync

void originateAsync(OriginateAction originateAction,
                    OriginateCallback cb)
             throws ManagerCommunicationException

Asynchronously generates an outgoing channel.

Parameters:

originateAction - the action that contains parameters for the originate

cb - callback to inform about the result

Throws:

ManagerCommunicationException - if the originate action cannot be sent to Asterisk

originateToExtension

AsteriskChannel originateToExtension(String channel,
                                     String context,
                                     String exten,
                                     int priority,
                                     long timeout)
                              throws ManagerCommunicationException,
                                     NoSuchChannelException

Generates an outgoing channel to a dialplan entry (extension, context, priority).

Parameters:

channel - channel name to call, for example "SIP/1310".

context - context to connect to

exten - extension to connect to

priority - priority to connect to

timeout - how long to wait for the channel to be answered before its considered to have failed (in ms)

Returns:

the generated channel

Throws:

NoSuchChannelException - if the channel is not available on the Asterisk server, for example because you used "SIP/1310" and 1310 is not a valid SIP user, the SIP channel module hasn't been loaded or the SIP or IAX peer is not registered currently.

ManagerCommunicationException - if the originate action cannot be sent to Asterisk

originateToExtension

AsteriskChannel originateToExtension(String channel,
                                     String context,
                                     String exten,
                                     int priority,
                                     long timeout,
                                     CallerId callerId,
                                     Map<String,String> variables)
                              throws ManagerCommunicationException,
                                     NoSuchChannelException

Generates an outgoing channel to a dialplan entry (extension, context, priority) and sets an optional map of channel variables.

Parameters:

channel - channel name to call, for example "SIP/1310".

context - context to connect to

exten - extension to connect to

priority - priority to connect to

timeout - how long to wait for the channel to be answered before its considered to have failed (in ms)

callerId - callerId to use for the outgoing channel, may be null.

variables - channel variables to set, may be null.

Returns:

the generated channel

Throws:

NoSuchChannelException - if the channel is not available on the Asterisk server, for example because you used "SIP/1310" and 1310 is not a valid SIP user, the SIP channel module hasn't been loaded or the SIP or IAX peer is not registered currently.

ManagerCommunicationException - if the originate action cannot be sent to Asterisk

originateToApplication

AsteriskChannel originateToApplication(String channel,
                                       String application,
                                       String data,
                                       long timeout)
                                throws ManagerCommunicationException,
                                       NoSuchChannelException

Generates an outgoing channel to an application.

Parameters:

channel - channel name to call, for example "SIP/1310".

application - application to connect to, for example "MeetMe"

data - data to pass to the application, for example "1000|d", may be null.

timeout - how long to wait for the channel to be answered before its considered to have failed (in ms)

Returns:

the generated channel

Throws:

NoSuchChannelException - if the channel is not available on the Asterisk server, for example because you used "SIP/1310" and 1310 is not a valid SIP user, the SIP channel module hasn't been loaded or the SIP or IAX peer is not registered currently.

ManagerCommunicationException - if the originate action cannot be sent to Asterisk

originateToApplication

AsteriskChannel originateToApplication(String channel,
                                       String application,
                                       String data,
                                       long timeout,
                                       CallerId callerId,
                                       Map<String,String> variables)
                                throws ManagerCommunicationException,
                                       NoSuchChannelException

Generates an outgoing channel to an application and sets an optional map of channel variables.

Parameters:

channel - channel name to call, for example "SIP/1310".

application - application to connect to, for example "MeetMe"

data - data to pass to the application, for example "1000|d", may be null.

timeout - how long to wait for the channel to be answered before its considered to have failed (in ms)

callerId - callerId to use for the outgoing channel, may be null.

variables - channel variables to set, may be null.

Returns:

the generated channel

Throws:

NoSuchChannelException - if the channel is not available on the Asterisk server, for example because you used "SIP/1310" and 1310 is not a valid SIP user, the SIP channel module hasn't been loaded or the SIP or IAX peer is not registered currently.

ManagerCommunicationException - if the originate action cannot be sent to Asterisk

originateToExtensionAsync

void originateToExtensionAsync(String channel,
                               String context,
                               String exten,
                               int priority,
                               long timeout,
                               OriginateCallback callback)
                        throws ManagerCommunicationException

Asynchronously generates an outgoing channel to a dialplan entry (extension, context, priority).

Parameters:

channel - channel name to call, for example "SIP/1310".

context - context to connect to

exten - extension to connect to

priority - priority to connect to

timeout - how long to wait for the channel to be answered before its considered to have failed (in ms)

callback - callback to inform about the result

Throws:

ManagerCommunicationException - if the originate action cannot be sent to Asterisk

originateToExtensionAsync

void originateToExtensionAsync(String channel,
                               String context,
                               String exten,
                               int priority,
                               long timeout,
                               CallerId callerId,
                               Map<String,String> variables,
                               OriginateCallback callback)
                        throws ManagerCommunicationException

Asynchronously generates an outgoing channel to a dialplan entry (extension, context, priority) and sets an optional map of channel variables.

Parameters:

channel - channel name to call, for example "SIP/1310".

context - context to connect to

exten - extension to connect to

priority - priority to connect to

timeout - how long to wait for the channel to be answered before its considered to have failed (in ms)

callerId - callerId to use for the outgoing channel, may be null.

variables - channel variables to set, may be null.

callback - callback to inform about the result

Throws:

ManagerCommunicationException - if the originate action cannot be sent to Asterisk

originateToApplicationAsync

void originateToApplicationAsync(String channel,
                                 String application,
                                 String data,
                                 long timeout,
                                 OriginateCallback callback)
                          throws ManagerCommunicationException

Asynchronously generates an outgoing channel to an application.

Parameters:

channel - channel name to call, for example "SIP/1310".

application - application to connect to, for example "MeetMe"

data - data to pass to the application, for example "1000|d", may be null.

timeout - how long to wait for the channel to be answered before its considered to have failed (in ms)

callback - callback to inform about the result

Throws:

ManagerCommunicationException - if the originate action cannot be sent to Asterisk

originateToApplicationAsync

void originateToApplicationAsync(String channel,
                                 String application,
                                 String data,
                                 long timeout,
                                 CallerId callerId,
                                 Map<String,String> variables,
                                 OriginateCallback callback)
                          throws ManagerCommunicationException

Asynchronously generates an outgoing channel to an application and sets an optional map of channel variables.

Parameters:

channel - channel name to call, for example "SIP/1310".

application - application to connect to, for example "MeetMe"

data - data to pass to the application, for example "1000|d", may be null.

timeout - how long to wait for the channel to be answered before its considered to have failed (in ms)

callerId - callerId to use for the outgoing channel, may be null.

variables - channel variables to set, may be null.

callback - callback to inform about the result

Throws:

ManagerCommunicationException - if the originate action cannot be sent to Asterisk

getChannels

Collection<AsteriskChannel> getChannels()
                                 throws ManagerCommunicationException

Returns the active channels of the Asterisk server.

Returns:

a Collection of active channels.

Throws:

ManagerCommunicationException - if there is a problem communication with Asterisk

getChannelByName

AsteriskChannel getChannelByName(String name)
                          throws ManagerCommunicationException

Returns a channel by its name.

Parameters:

name - name of the channel to return

Returns:

the channel with the given name or null if there is no such channel.

Throws:

ManagerCommunicationException - if there is a problem communication with Asterisk

getChannelById

AsteriskChannel getChannelById(String id)
                        throws ManagerCommunicationException

Returns a channel by its unique id.

Parameters:

id - the unique id of the channel to return

Returns:

the channel with the given unique id or null if there is no such channel.

Throws:

ManagerCommunicationException - if there is a problem communication with Asterisk

getMeetMeRooms

Collection<MeetMeRoom> getMeetMeRooms()
                               throws ManagerCommunicationException

Returns the acitve MeetMe rooms on the Asterisk server.

Returns:

a Collection of MeetMeRooms

Throws:

ManagerCommunicationException - if there is a problem communication with Asterisk

getMeetMeRoom

MeetMeRoom getMeetMeRoom(String roomNumber)
                  throws ManagerCommunicationException

Returns the MeetMe room with the given number, if the room does not yet exist a new MeetMeRoom object is created.

Parameters:

roomNumber - the number of the room to return

Returns:

the MeetMe room with the given number.

Throws:

ManagerCommunicationException - if there is a problem communication with Asterisk

getQueues

Collection<AsteriskQueue> getQueues()
                             throws ManagerCommunicationException

Returns the queues served by the Asterisk server.

Returns:

a Collection of queues.

Throws:

ManagerCommunicationException - if there is a problem communication with Asterisk

getAgents

Collection<AsteriskAgent> getAgents()
                             throws ManagerCommunicationException

Return the agents, registered at Asterisk server. (Consider remarks for AsteriskAgent)

Returns:

a Collection of agents

Throws:

ManagerCommunicationException - if there is a problem communication with Asterisk

getVersion

String getVersion()
           throws ManagerCommunicationException

Returns the exact version string of this Asterisk server.
This typically looks like "Asterisk 1.2.9.1-BRIstuffed-0.3.0-PRE-1q built by root @ pbx0 on a i686 running Linux on 2006-06-20 20:21:30 UTC".

Returns:

the version of this Asterisk server

Throws:

ManagerCommunicationException - if the version cannot be retrieved from Asterisk

Since:

0.2

getVersion

int[] getVersion(String file)
          throws ManagerCommunicationException

<<<<<<< HEAD Returns the CVS revision of a given source file of this Asterisk server.
======= Returns the CVS revision of a given source file of this Asterisk server.
>>>>>>> refs/heads/release-1.1 For example getVersion("app_meetme.c") may return {1, 102} for CVS revision "1.102".
Note that this feature is not available with Asterisk 1.0.x.
You can use this feature if you need to write applications that behave different depending on specific modules being available in a specific version or not.

Parameters:

file - the file for which to get the version like "app_meetme.c"

Returns:

the CVS revision of the file, or null if that file is not part of the Asterisk instance you are connected to (maybe due to a module that provides it has not been loaded) or if you are connected to an Astersion 1.0.x

Throws:

ManagerCommunicationException - if the version cannot be retrieved from Asterisk

Since:

0.2

getGlobalVariable

String getGlobalVariable(String variable)
                  throws ManagerCommunicationException

Returns the value of the given global variable.

Parameters:

variable - the name of the global variable to return.

Returns:

the value of the global variable or null if it is not set.

Throws:

ManagerCommunicationException - if the get variable action cannot be sent to Asterisk.

Since:

0.3

setGlobalVariable

void setGlobalVariable(String variable,
                       String value)
                throws ManagerCommunicationException

Sets the value of the given global variable.

Parameters:

variable - the name of the global variable to set.

value - the value of the global variable to set.

Throws:

ManagerCommunicationException - if the set variable action cannot be sent to Asterisk.

Since:

0.3

getVoicemailboxes

Collection<Voicemailbox> getVoicemailboxes()
                                    throws ManagerCommunicationException

Returns a collection of all voicemailboxes configured for this Asterisk server with the number of new and old messages they contain.

Returns:

a collection of all voicemailboxes configured for this Asterisk server

Throws:

ManagerCommunicationException - if the voicemailboxes can't be retrieved.

Since:

0.3

executeCliCommand

List<String> executeCliCommand(String command)
                        throws ManagerCommunicationException

Executes a command line interface (CLI) command.

Parameters:

command - the command to execute, for example "sip show peers".

Returns:

a List containing strings representing the lines returned by the CLI command.

Throws:

ManagerCommunicationException - if the command can't be executed.

Since:

0.3

See Also:

CommandAction

isModuleLoaded

boolean isModuleLoaded(String module)
                throws ManagerCommunicationException

Checks whether a module is currently loaded.

Available since Asterisk 1.6

Parameters:

module - name of the module to load (with out without the ".so" extension).

Returns:

true if the module is currently loaded, false otherwise.

Throws:

ManagerCommunicationException - if the module can't be checked.

loadModule

void loadModule(String module)
         throws ManagerCommunicationException

Loads a module or subsystem

Available since Asterisk 1.6

Parameters:

module - name of the module to load (including ".so" extension) or subsystem name.

Throws:

ManagerCommunicationException - if the module cannot be loaded.

Since:

1.0.0

unloadModule

void unloadModule(String module)
           throws ManagerCommunicationException

Unloads a module or subsystem.

Available since Asterisk 1.6

Parameters:

module - name of the module to unload (including ".so" extension) or subsystem name.

Throws:

ManagerCommunicationException - if the module cannot be unloaded.

Since:

1.0.0

reloadModule

void reloadModule(String module)
           throws ManagerCommunicationException

Reloads a module or subsystem.

Available since Asterisk 1.6

Parameters:

module - name of the module to reload (including ".so" extension) or subsystem name.

Throws:

ManagerCommunicationException - if the module cannot be reloaded.

Since:

1.0.0

reloadAllModules

void reloadAllModules()
               throws ManagerCommunicationException

Reloads all currently loaded modules.

Available since Asterisk 1.6

Throws:

ManagerCommunicationException - if the modules cannot be reloaded.

Since:

1.0.0

getConfig

ConfigFile getConfig(String filename)
              throws ManagerCommunicationException

Reads the given Asterisk configuration file.

Parameters:

filename - the filename, for example "voicemail.conf".

Returns:

the configuration file.

Throws:

ManagerCommunicationException - if the command can't be executed.

addAsteriskServerListener

void addAsteriskServerListener(AsteriskServerListener listener)
                        throws ManagerCommunicationException

Adds a listener to this AsteriskServer.
If this server is not yet connected it will be implicitly connected.

Parameters:

listener - the listener to add.

Throws:

ManagerCommunicationException - if the server is not yet connected and the connection or initialization fails.

removeAsteriskServerListener

void removeAsteriskServerListener(AsteriskServerListener listener)

Removes a listener from this Asterisk server.

Parameters:

listener - the listener to remove.

isAsteriskServerListening

boolean isAsteriskServerListening(AsteriskServerListener listener)

Checks whether the listener is already registered with this Asterisk server

Parameters:

listener - the listener to check

Returns:

true, if the listener is already registered.

addChainListener

void addChainListener(ManagerEventListener chainListener)

The chainListener allows a listener to receive manager events after they have been processed by the AsteriskServer. If the AsteriskServer is handling messages using the asyncEventHandling then these messages will also be async. You would use the chainListener if you are processing raw events and using the AJ live ChannelManager. If you don't use the chain listener then you can't be certain that a channel name passed in a raw event will match the channel name held by the live Channel Manager. By chaining events you can be certain that events such as channel Rename events have been processed by the live ChannelManager before you receive an event and as such the names will always match. Whilst name matching is not always critical (as you should be matching by the channels unique id) the channel name does also contain state information (Zombie, Masq) in these cases it can be critical that you have the same name otherwise your state information will be out of date.

removeChainListener

void removeChainListener(ManagerEventListener chainListener)

remove the chain listener.

Parameters:

chainListener -

shutdown

void shutdown()

Closes the connection to this server.

initialize

void initialize()
         throws ManagerCommunicationException

Opens the connection to this server.

Throws:

ManagerCommunicationException - if login fails

getQueueByName

AsteriskQueue getQueueByName(String queueName)

get Asterisk Queue by name

Parameters:

queueName - Name of the queue to retrieve

Returns:

getQueuesUpdatedAfter

List<AsteriskQueue> getQueuesUpdatedAfter(Date date)

List of Queues Objects updated after certain date

Parameters:

date -

Returns:

forceQueuesMonitor

void forceQueuesMonitor(boolean force)

every time we get an event of a queue we reload the information about it from the Asterisk Server

isQueuesMonitorForced

boolean isQueuesMonitorForced()

Check if the Queue Information is forced

Returns: