javax.telephony.media
Interface MediaTerminalConnection

All Superinterfaces:

TerminalConnection

Deprecated. As of JTAPI 1.3, replaced by MediaService

public interface MediaTerminalConnection

extends TerminalConnection

Old MediaTerminalConnection class. Replaced in JTAPI-1.3 by the MediaService interface, which delegates resource management and media stream state control from the telephony application to the provider implementation. This makes applications simpler and allows multiple applications to easily share access to the provider's plaform; because the provider software controls access, and applications don't build competing frameworks for each platform.

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 Deprecated. Media is currently available on this terminal connection.
static int	NOACTIVITY Deprecated. There is currently no activity on this TerminalConnection.
static int	PLAYING Deprecated. There is currently playing on this terminal connection.
static int	RECORDING Deprecated. There is currently recording on this terminal connection.
static int	UNAVAILABLE Deprecated. 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) Deprecated. Generates one or more DTMF tones.
int	getMediaAvailability() Deprecated. Returns the current media availability state, either AVAILABLE or UNAVAILABLE.
int	getMediaState() Deprecated. Returns the current state of the terminal connection as a bit mask of PLAYING and RECORDING.
void	setDtmfDetection(boolean enable) Deprecated. Sets the DTMF tone detection either on or off.
void	startPlaying() Deprecated. Start the playing.
void	startRecording() Deprecated. Start the recording.
void	stopPlaying() Deprecated. Stop the playing.
void	stopRecording() Deprecated. Stop the recording.
void	useDefaultMicrophone() Deprecated. Instructs the terminal connection to use the default microphone for playing to the telephone line.
void	useDefaultSpeaker() Deprecated. Instructs the terminal connection to use the default speaker for recording from the telephone line.
void	usePlayURL(java.net.URL url) Deprecated. Instructs the terminal connection to use a file for playing to the telephone line.
void	useRecordURL(java.net.URL url) Deprecated. 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

Deprecated.

Media is currently available on this terminal connection.

UNAVAILABLE

public static final int UNAVAILABLE

Deprecated.

Media is currently not available on this terminal connection.

PLAYING

public static final int PLAYING

Deprecated.

There is currently playing on this terminal connection.

RECORDING

public static final int RECORDING

Deprecated.

There is currently recording on this terminal connection.

NOACTIVITY

public static final int NOACTIVITY

Deprecated.

There is currently no activity on this TerminalConnection.

Method Detail

getMediaAvailability

public int getMediaAvailability()

Deprecated.

Returns the current media availability state, either AVAILABLE or UNAVAILABLE.

Returns:

The current availability of the media channel.

getMediaState

public int getMediaState()

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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()

Deprecated.

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

Deprecated.

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()

Deprecated.

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

Deprecated.

Sets the DTMF tone detection either on or off. If the boolean flag argument is true, then DTMF detection is turned on, otherwise, it is turned off.

Parameters:

enable - If true, turns DTMF-tone detection on, if false, turns DTMF-tone detection off.

Throws:

MethodNotSupportedException - The implementation does not support the detection of DTMF-tones.

ResourceUnavailableException - Indicates DTMF-detection cannot be started because some resource is unavailable.

InvalidStateException - Indicates the TerminalConnection is not in the media channel available state.

generateDtmf

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

Deprecated.

Generates one or more DTMF tones. The string parameters must consist of one or more of the following characters: the numbers zero through nine (0 - 9), the letters A through D, asterisk (*), or pound(#). Any other characters in the string parameter are ignored.

Parameters:

digits - The string of DTMF-tone digits to generate on the telephone line.

Throws:

MethodNotSupportedException - The implementation does not support generating DTMF tones.

ResourceUnavailableException - Indicates the generating of DTMF tones cannot be done because some resource is unavailable.

InvalidStateException - Indicates the TerminalConnection is not in the media channel available state.