org.freeswitch.esl.client.inbound
Class Client

java.lang.Object
  org.freeswitch.esl.client.inbound.Client

public class Client
extends Object

Entry point to connect to a running FreeSWITCH Event Socket Library module, as a client.

This class provides what the FreeSWITCH documentation refers to as an 'Inbound' connection to the Event Socket module. That is, with reference to the socket listening on the FreeSWITCH server, this client occurs as an inbound connection to the server.

See http://wiki.freeswitch.org/wiki/Mod_event_socket

Author:

david varnes

Constructor Summary

Client()

Method Summary

CommandResponse	addEventFilter(String eventHeader, String valueToFilter) Add an event filter to the current set of event filters on this connection.
void	addEventListener(IEslEventListener listener)
CommandResponse	cancelEventSubscriptions() Cancel any existing event subscription.
CommandResponse	cancelLogging() Disable any logging previously enabled with setLogLevel().
boolean	canSend()
CommandResponse	close() Close the socket connection
void	connect(String host, int port, String password, int timeoutSeconds) Attempt to establish an authenticated connection to the nominated FreeSWITCH ESL server socket.
CommandResponse	deleteEventFilter(String eventHeader, String valueToFilter) Delete an event filter from the current set of event filters on this connection.
String	sendAsyncApiCommand(String command, String arg) Submit a FreeSWITCH API command to the server to be executed in background mode.
CommandResponse	sendMessage(SendMsg sendMsg) Send a SendMsg command to FreeSWITCH.
EslMessage	sendSyncApiCommand(String command, String arg) Sends a FreeSWITCH API command to the server and blocks, waiting for an immediate response from the server.
CommandResponse	setEventSubscriptions(String format, String events) Set the current event subscription for this connection to the server.
CommandResponse	setLoggingLevel(String level) Enable log output.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Client

public Client()

Method Detail

canSend

public boolean canSend()

addEventListener

public void addEventListener(IEslEventListener listener)

connect

public void connect(String host,
                    int port,
                    String password,
                    int timeoutSeconds)
             throws InboundConnectionFailure

Attempt to establish an authenticated connection to the nominated FreeSWITCH ESL server socket. This call will block, waiting for an authentication handshake to occur, or timeout after the supplied number of seconds.

Parameters:

host - can be either ip address or hostname

port - tcp port that server socket is listening on (set in event_socket_conf.xml)

password - server event socket is expecting (set in event_socket_conf.xml)

timeoutSeconds - number of seconds to wait for the server socket before aborting

Throws:

InboundConnectionFailure

sendSyncApiCommand

public EslMessage sendSyncApiCommand(String command,
                                     String arg)

Sends a FreeSWITCH API command to the server and blocks, waiting for an immediate response from the server.

The outcome of the command from the server is retured in an EslMessage object.

Parameters:

command - API command to send

arg - command arguments

Returns:

an EslMessage containing command results

sendAsyncApiCommand

public String sendAsyncApiCommand(String command,
                                  String arg)

Submit a FreeSWITCH API command to the server to be executed in background mode. A synchronous response from the server provides a UUID to identify the job execution results. When the server has completed the job execution it fires a BACKGROUND_JOB Event with the execution results.

Note that this Client must be subscribed in the normal way to BACKGOUND_JOB Events, in order to receive this event.

Parameters:

command - API command to send

arg - command arguments

Returns:

String Job-UUID that the server will tag result event with.

setEventSubscriptions

public CommandResponse setEventSubscriptions(String format,
                                             String events)

Set the current event subscription for this connection to the server. Examples of the events argument are:

   ALL
   CHANNEL_CREATE CHANNEL_DESTROY HEARTBEAT
   CUSTOM conference::maintenance
   CHANNEL_CREATE CHANNEL_DESTROY CUSTOM conference::maintenance sofia::register sofia::expire
 

Subsequent calls to this method replaces any previous subscriptions that were set.

Note: current implementation can only process 'plain' events.

Parameters:

format - can be { plain | xml }

events - { all | space separated list of events }

Returns:

a CommandResponse with the server's response.

cancelEventSubscriptions

public CommandResponse cancelEventSubscriptions()

Cancel any existing event subscription.

Returns:

a CommandResponse with the server's response.

addEventFilter

public CommandResponse addEventFilter(String eventHeader,
                                      String valueToFilter)

Add an event filter to the current set of event filters on this connection. Any of the event headers can be used as a filter.

Note that event filters follow 'filter-in' semantics. That is, when a filter is applied only the filtered values will be received. Multiple filters can be added to the current connection.

Example filters:

    eventHeader        valueToFilter
    ----------------------------------
    Event-Name         CHANNEL_EXECUTE
    Channel-State      CS_NEW
 

Parameters:

eventHeader - to filter on

valueToFilter - the value to match

Returns:

a CommandResponse with the server's response.

deleteEventFilter

public CommandResponse deleteEventFilter(String eventHeader,
                                         String valueToFilter)

Delete an event filter from the current set of event filters on this connection. See Client.addEventFilter

Parameters:

eventHeader - to remove

valueToFilter - to remove

Returns:

a CommandResponse with the server's response.

sendMessage

public CommandResponse sendMessage(SendMsg sendMsg)

Send a SendMsg command to FreeSWITCH. This client requires that the SendMsg has a call UUID parameter.

Parameters:

sendMsg - a SendMsg with call UUID

Returns:

a CommandResponse with the server's response.

setLoggingLevel

public CommandResponse setLoggingLevel(String level)

Enable log output.

Parameters:

level - using the same values as in console.conf

Returns:

a CommandResponse with the server's response.

cancelLogging

public CommandResponse cancelLogging()

Disable any logging previously enabled with setLogLevel().

Returns:

a CommandResponse with the server's response.

close

public CommandResponse close()

Close the socket connection

Returns:

a CommandResponse with the server's response.