SimpleCapi
Class SimpleCapi

java.lang.Object
  |
  +--SimpleCapi.SimpleCapi

public class SimpleCapi

extends java.lang.Object

Constructor Summary

SimpleCapi(java.lang.String server, int port)
Establishes a connection to the main Caiviar IVR Server.

Method Summary

void	acceptCalls() signal to the server that incoming calls should trigger an event.
boolean	answer(CapiEvent event) answer an incoming call.
void	beep(java.lang.String notes) generate one or more DTMFs.
int	call_nonblock(java.lang.String msisdn) call the specified msisdn, return immediately.
int	call(java.lang.String msisdn, int timeout) call the specified msisdn.
void	close() close the connection to the capiserver.
void	connect(SimpleCapi capi1, SimpleCapi capi2) merge the audio datas of two connections (or connections-to-be).
void	del(java.lang.String filename) remove a file from the server.
boolean	fax(java.lang.String msisdn, java.lang.String filename) send a fax through the line.
void	finalize()
boolean	forward(java.lang.String msisdn) forward an incoming call / a connection
void	get(java.lang.String filename, java.lang.String destname) get a file from the server.
void	hangup() hangup on a connection.
boolean	hold() put existing call on hold.
void	ignore(CapiEvent event) ignore an incoming call.
CapiEvent	listen(int timeout) wait for something to happen.
int	play(java.lang.String filename) send a sound file into a line.
void	put(java.lang.String filename, java.lang.String destname) put a file on the server, for subsequent play() or fax() calls.
int	record(java.lang.String filename, int seconds) record the other end's voice into buf.
void	reject(CapiEvent event) reject an incoming call.
boolean	retrieve() retrieve call on hold.
void	setMSISDN(java.lang.String msisdn) sets another host msisdn than the one specified in the defaults.
int	speak(java.lang.String text) use tts functionality to speak a text.
void	stop(int jobid) stop a running job.
boolean	supplemental(java.lang.String command) do a supplemental service command, for example "3conf".

Methods inherited from class java.lang.Object

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

Constructor Detail

SimpleCapi

public SimpleCapi(java.lang.String server,
                  int port)
           throws java.io.IOException,
                  NoLineFreeException

Establishes a connection to the main Caiviar IVR Server. The Caiviar IVR Server is an application running on some remote (or local) system which has ISDN hardware build into it. This server will then act according to the commands which are send with the function calls of this class.

Parameters:

server - The Adress of the IVR Server

port - The port on the IVR Server (usually 7347)

Method Detail

setMSISDN

public void setMSISDN(java.lang.String msisdn)
               throws java.io.IOException,
                      CommandFailedException

sets another host msisdn than the one specified in the defaults. Use this before calling any other functions.

Parameters:

msisdn - the msisdn to use

java.io.IOException

CommandFailedException

acceptCalls

public void acceptCalls()
                 throws java.io.IOException,
                        CommandFailedException

signal to the server that incoming calls should trigger an event. If this is called, incoming connections will trigger a CAPI_EVENT_INCOMING event. Note that to reset this, you'll have to terminate the connection to the server and reconnect.

java.io.IOException

CommandFailedException

call

public int call(java.lang.String msisdn,
                int timeout)
         throws java.io.IOException,
                CommandFailedException

call the specified msisdn.

Parameters:

msisdn - the msisdn to call

timeout - the number of seconds to wait for an answer

Returns:

0 if somebody answered in time, REASON otherwise

java.io.IOException

CommandFailedException

call_nonblock

public int call_nonblock(java.lang.String msisdn)
                  throws java.io.IOException,
                         CommandFailedException

call the specified msisdn, return immediately. It returns a job id which can be used to wait for the call to succeed (CAPI_EVENT_DONE) or fail (CAPI_EVENT_HANGUP)

Parameters:

msisdn - the misdn to call

Returns:

a job id for the calling task

java.io.IOException

CommandFailedException

put

public void put(java.lang.String filename,
                java.lang.String destname)
         throws java.io.IOException,
                CommandFailedException

put a file on the server, for subsequent play() or fax() calls.

Parameters:

filename - The filename of the file to send

destname - How the file should be named on the server. Must not contain the characters '/' or '\\'.

java.io.IOException

CommandFailedException

get

public void get(java.lang.String filename,
                java.lang.String destname)
         throws java.io.IOException,
                CommandFailedException

get a file from the server. (E.g. one that record() has created)

Parameters:

filename - The filename of the file to receive. Must not contain the characters '/' or '\\'.

destname - The destination file.

java.io.IOException

CommandFailedException

del

public void del(java.lang.String filename)
         throws java.io.IOException,
                CommandFailedException

remove a file from the server.

Parameters:

filename - The filename of the file to remove. Like in put(), the filename must not contain the characters '/' and '\\'.

java.io.IOException

CommandFailedException

beep

public void beep(java.lang.String notes)
          throws java.io.IOException,
                 CommandFailedException

generate one or more DTMFs.

Parameters:

notes - A String of DTMFs to generate. Allowed characters are '0'-'9','*','#'.

java.io.IOException

CommandFailedException

hold

public boolean hold()
             throws java.io.IOException,
                    CommandFailedException

put existing call on hold.

Returns:

true on success, false on failure (e.g. if the caller hung up already)

java.io.IOException

CommandFailedException

retrieve

public boolean retrieve()
                 throws java.io.IOException,
                        CommandFailedException

retrieve call on hold.

Returns:

true on success, false on failure (e.g. if the caller hung up already)

java.io.IOException

CommandFailedException

supplemental

public boolean supplemental(java.lang.String command)
                     throws java.io.IOException,
                            CommandFailedException

do a supplemental service command, for example "3conf".

Parameters:

command - the command to send, e.g. "3conf".

Returns:

true on success, false on failure.

java.io.IOException

CommandFailedException

play

public int play(java.lang.String filename)
         throws java.io.IOException,
                CommandFailedException

send a sound file into a line. This call does not block, but rather returns a job id which can be used for waiting for the end of the sound file.

Parameters:

filename - the filename of the soundfile

Returns:

a job id. An event with this job id will be generated when the end of the audio data is reached.

java.io.IOException

CommandFailedException

speak

public int speak(java.lang.String text)
          throws java.io.IOException,
                 CommandFailedException

use tts functionality to speak a text. This call does not block, but rather returns a job id which can be used for waiting for the end of the speaking process.

Parameters:

text - the text to speech

Returns:

a job id. An event with this job id will be generated when the end of the audio data is reached.

java.io.IOException

CommandFailedException

record

public int record(java.lang.String filename,
                  int seconds)
           throws java.io.IOException,
                  CommandFailedException

record the other end's voice into buf. This call does not block, but rather returns a job id which can be used for waiting for the end of an recording. Notice that other events (especially DIALTONE and HANGUP) will still be sent.

Parameters:

filename - the filename to store the recorded file in. this file will be put on the server, not the local directory!

seconds - how many seconds to record. The recording will be shorter if the other end hangs up.

Returns:

a job id, which can be used to wait for the end of the recording

java.io.IOException

CommandFailedException

fax

public boolean fax(java.lang.String msisdn,
                   java.lang.String filename)
            throws java.io.IOException,
                   CommandFailedException

send a fax through the line. This call blocks until the fax has been transmitted. You should have transferred the file to fax on the server with put() before calling this function. The fax file can either be SFF, Postscript or HTML. Depending on your capiserver, Postscript or HTML may not be supported.

Parameters:

msisdn - the msisdn of the fax machine

filename - the filename of the fax file (on the server)

Returns:

true on success, false on failure

java.io.IOException

CommandFailedException

stop

public void stop(int jobid)
          throws java.io.IOException,
                 CommandFailedException

stop a running job. Most likely you will want to stop jobs which play soundfiles (for barge-in functionality)

Parameters:

jobid - the job to stop

java.io.IOException

CommandFailedException

listen

public CapiEvent listen(int timeout)
                 throws java.io.IOException,
                        CommandFailedException

wait for something to happen. This might be a hangup by the other end, a job that finished, an incoming call etc.

Parameters:

timeout - the time to listen. If nothing happened while we were waiting, return a TIMEOUT event. If timeout=0, wait forever.

java.io.IOException

CommandFailedException

answer

public boolean answer(CapiEvent event)
               throws java.io.IOException,
                      CommandFailedException

answer an incoming call.

Parameters:

event - the INCOMING event to answer

Returns:

true on success, false on failure (e.g. if the caller hung up or another thread has answered the Call already)

java.io.IOException

CommandFailedException

reject

public void reject(CapiEvent event)
            throws java.io.IOException,
                   CommandFailedException

reject an incoming call.

Parameters:

event - the INCOMING event to hang up on

java.io.IOException

CommandFailedException

ignore

public void ignore(CapiEvent event)
            throws java.io.IOException,
                   CommandFailedException

ignore an incoming call. This is different from reject in that the call keeps ringing, so that other devices may answer it.

Parameters:

event - the INCOMING event to ignore

java.io.IOException

CommandFailedException

forward

public boolean forward(java.lang.String msisdn)
                throws java.io.IOException,
                       CommandFailedException

forward an incoming call / a connection

Parameters:

msisdn - the new msisdn

Returns:

true on success, false on failure (e.g. if the caller hung up already)

java.io.IOException

CommandFailedException

hangup

public void hangup()
            throws java.io.IOException,
                   CommandFailedException

hangup on a connection. This call blocks until the connection is correctly terminated.

java.io.IOException

CommandFailedException

connect

public void connect(SimpleCapi capi1,
                    SimpleCapi capi2)
             throws java.io.IOException,
                    CommandFailedException

merge the audio datas of two connections (or connections-to-be).

Parameters:

capi1 - SimpleCapi object corresponding to the first connection

capi2 - SimpleCapi object corresponding to the second connection

java.io.IOException

CommandFailedException

close

public void close()

close the connection to the capiserver. Also called by the class's finalize method.

finalize

public void finalize()

Overrides:

finalize in class java.lang.Object