javax.telephony.media
Interface MediaTerminalConnection

All Superinterfaces:
TerminalConnection
All Known Subinterfaces:
ITsapiTerminalConnection, LucentTerminalConnection, LucentV5TerminalConnection, LucentV5TerminalConnectionEx
All Known Implementing Classes:
com.avaya.jtapi.tsapi.LucentTerminalConnectionImpl, LucentV5TerminalConnectionExImpl, com.avaya.jtapi.tsapi.LucentV5TerminalConnectionImpl, com.avaya.jtapi.tsapi.TsapiTerminalConnection

public interface MediaTerminalConnection
extends TerminalConnection

Introduction

The MediaTerminalConnection interface extends the TerminalConnection interface to add media capabilities. Media streams are associated with the TerminalConnection object in the call model. Therefore, different Terminals which are part of the same call at the same Address may have their own media streams. Additionality, Terminals which are part of more than one call have separate media streams for each of its calls.

The media interface consists of a base media API which supports all of the various types of media-based telephony applications. A simplier, voice-based API exist for applications which desire only the most simply voice-based media features. The base media API is still under development. This specification only represent the voice API.

The voice API supports the following applications: routing voice data to/from the telephone line to/from a workstation's speaker of microphone; routing voice data to/from the telephone line to/from audio files; starting and stoping of playing and recording; and DTMF tone detection.

In this specification, "playing" is defined as sending information to the telephone line. For example, an application would "play" an audio file to the telephone line for the opposite parties to hear. The term "recording" is defines as receiving information from the telephone line. For example, an application may "record" data from the telephone line into a file on disk.

Playing

For playing, applications may either route data from a URL with the usePlayURL() method or from the workstatation's default microphone using the useDefaultMicrophone() method. Note that if there is more than one microphone on the workstation, then the default microphone may be set using the javax.telephony.phone package. Applications begin playing using the startPlaying() method and stop playing using the stopPlaying() method. If an application issues a startPlaying() after a stopPlaying(), the implementation attempts to read from the media where it last left off, if possible. If the application wishes to "rewind" the media to the beginning, it should re-issue the usePlayURL() method.

Recording

For recording, applications may either route data to a URL with the useRecordURL() method or to the workstation's default speaker using the useDefaultSpeaker() method. Note that if there is more than one speaker on the workstation, then the default speaker may be set using the javax.telephony.phone package. Applications begin recording using the startRecording() method and stop recording using the stopRecording() method. If an application issues a startRecording() after a stopRecording(), the implementation attempts to write to the media where it last left off, if possible. If the application wishes to "overwrite" the media from the beginning, it should re-issue the useRecordURL() method.


Field Summary
static int AVAILABLE
          Media is currently available on this terminal connection
static int NOACTIVITY
          There is currently no activity on this TerminalConnection.
static int PLAYING
          There is currently playing on this terminal connection
static int RECORDING
          There is currently recording on this terminal connection
static int UNAVAILABLE
          Media is currently not available on this terminal connection
 
Fields inherited from interface javax.telephony.TerminalConnection
ACTIVE, DROPPED, IDLE, PASSIVE, RINGING, UNKNOWN
 
Method Summary
 void generateDtmf(java.lang.String digits)
           
 int getMediaAvailability()
          Returns the current media availability state, either AVAILABLE or UNAVAILABLE.
 int getMediaState()
          Returns the current state of the terminal connection as a bit mask of PLAYING and RECORDING.
 void setDtmfDetection(boolean enable)
           
 void startPlaying()
          Start the playing.
 void startRecording()
          Start the recording.
 void stopPlaying()
          Stop the playing.
 void stopRecording()
          Stop the recording.
 void useDefaultMicrophone()
          Instructs the terminal connection to use the default microphone for playing to the telephone line.
 void useDefaultSpeaker()
          Instructs the terminal connection to use the default speaker for recording from the telephone line.
 void usePlayURL(java.net.URL url)
          Instructs the terminal connection to use a file for playing to the telephone line.
 void useRecordURL(java.net.URL url)
          Instructs the terminal connection to use a file for recording from the telephone line.
 
Methods inherited from interface javax.telephony.TerminalConnection
answer, getCapabilities, getConnection, getState, getTerminal, getTerminalConnectionCapabilities
 

Field Detail

AVAILABLE

public static final int AVAILABLE
Media is currently available on this terminal connection

See Also:
Constant Field Values

UNAVAILABLE

public static final int UNAVAILABLE
Media is currently not available on this terminal connection

See Also:
Constant Field Values

PLAYING

public static final int PLAYING
There is currently playing on this terminal connection

See Also:
Constant Field Values

RECORDING

public static final int RECORDING
There is currently recording on this terminal connection

See Also:
Constant Field Values

NOACTIVITY

public static final int NOACTIVITY
There is currently no activity on this TerminalConnection.

See Also:
Constant Field Values
Method Detail

getMediaAvailability

public int getMediaAvailability()
Returns the current media availability state, either AVAILABLE or UNAVAILABLE.

Returns:
The current availability of the media channel.

getMediaState

public int getMediaState()
Returns the current state of the terminal connection as a bit mask of PLAYING and RECORDING. If there is not activity, then this method returns MediaTerminalConnection.NOACTIVITY.

Returns:
The current state of playing or recording.

useDefaultSpeaker

public void useDefaultSpeaker()
                       throws PrivilegeViolationException,
                              ResourceUnavailableException,
                              MethodNotSupportedException
Instructs the terminal connection to use the default speaker for recording from the telephone line.

Throws:
PrivilegeViolationException - Indicates the application is not permitted to direct voice media to the default speaker.
ResourceUnavailableException - Indicates that the speaker is not currently available for use.
MethodNotSupportedException - This method is not supported by the implementation.

useRecordURL

public void useRecordURL(java.net.URL url)
                  throws PrivilegeViolationException,
                         ResourceUnavailableException,
                         MethodNotSupportedException
Instructs the terminal connection to use a file for recording from the telephone line.

Parameters:
url - The URL-destination for the voice data for recording.
Throws:
PrivilegeViolationException - Indicates the application is not permitted to use the give URL for recording.
ResourceUnavailableException - Indicates the URL given is not available, either because the URL was invalid or a network problem occurred.
MethodNotSupportedException - This method is not supported by the implementation.

useDefaultMicrophone

public void useDefaultMicrophone()
                          throws PrivilegeViolationException,
                                 ResourceUnavailableException,
                                 MethodNotSupportedException
Instructs the terminal connection to use the default microphone for playing to the telephone line.

Throws:
PrivilegeViolationException - Indicates the application is not permitted to direct voice media from the default microphone.
ResourceUnavailableException - Indicates that the microphone is not currently available for use.
MethodNotSupportedException - This method is not supported by the implementation.

usePlayURL

public void usePlayURL(java.net.URL url)
                throws PrivilegeViolationException,
                       ResourceUnavailableException,
                       MethodNotSupportedException
Instructs the terminal connection to use a file for playing to the telephone line.

Parameters:
url - The URL-source of the voice data to play. valid or available source of voice data.
Throws:
PrivilegeViolationException - Indicates the application is not permitted to use the give URL for playing.
ResourceUnavailableException - Indicates the URL given is not available, either because the URL was invalid or a network problem occurred.
MethodNotSupportedException - This method is not supported by the implementation.

startPlaying

public void startPlaying()
                  throws MethodNotSupportedException,
                         ResourceUnavailableException,
                         InvalidStateException
Start the playing. This method returns once playing has begun, that is, when getMediaState() & PLAYING == PLAYING.

Throws:
MethodNotSupportedException - The implementation does not support playing to the telephone line.
ResourceUnavailableException - Indicates playing is not able to be started because some resource is unavailable.
InvalidStateException - Indicates the TerminalConnection is not in the media channel available state.

stopPlaying

public void stopPlaying()
Stop the playing. This method returns once the playing has stopped, that is, when getMediaState() & PLAYING == 0. If playing is not currently taking place, this method has no effect.


startRecording

public void startRecording()
                    throws MethodNotSupportedException,
                           ResourceUnavailableException,
                           InvalidStateException
Start the recording. This method returns once the recording has started, that is, when getMediaState() & RECORDING == RECORDING.

Throws:
MethodNotSupportedException - The implementation does not support recording from the telephone line.
ResourceUnavailableException - Indicates recording is not able to be started because some resource is unavailable.
InvalidStateException - Indicates the TerminalConnection is not in the media channel available state.

stopRecording

public void stopRecording()
Stop the recording. This method returns once the recording has stopped, that is, when getMediaState() & RECORDING == 0. If recording is not currently taking place, this method has no effect.


setDtmfDetection

public void setDtmfDetection(boolean enable)
                      throws MethodNotSupportedException,
                             ResourceUnavailableException,
                             InvalidStateException
Throws:
MethodNotSupportedException
ResourceUnavailableException
InvalidStateException

generateDtmf

public void generateDtmf(java.lang.String digits)
                  throws MethodNotSupportedException,
                         ResourceUnavailableException,
                         InvalidStateException
Throws:
MethodNotSupportedException
ResourceUnavailableException
InvalidStateException


Copyright © 2005 Avaya All Rights Reserved.