Interface java.telephony.media.MediaTerminalConnection
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface java.telephony.media.MediaTerminalConnection

public interface MediaTerminalConnection
extends Object
extends TerminalConnection
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.

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 java.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.

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 java.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.


Variable Index

 o AVAILABLE
Media is currently available on this terminal connection
 o PLAYING
There is currently playing on this terminal connection
 o RECORDING
There is currently recording on this terminal connection
 o UNAVAILABLE
Media is currently not available on this terminal connection

Method Index

 o generateDtmf(String)
 o getMediaAvailability()
Returns the current media availability state, either AVAILABLE or UNAVAILABLE.
 o getMediaState()
Returns the current state of the terminal connection as a bit mask of PLAYING and RECORDING.
 o setDtmfDetection(boolean)
 o startPlaying()
Start the playing.
 o startRecording()
Start the recording.
 o stopPlaying()
Stop the playing.
 o stopRecording()
Stop the recording.
 o useDefaultMicrophone()
Instructs the terminal connection to use the default microphone for playing to the telephone line.
 o useDefaultSpeaker()
Instructs the terminal connection to use the default speaker for recording from the telephone line.
 o usePlayURL(URL)
Instructs the terminal connection to use a file for playing to the telephone line.
 o useRecordURL(URL)
Instructs the terminal connection to use a file for recording from the telephone line.

Variables

 o AVAILABLE
  public final static int AVAILABLE
Media is currently available on this terminal connection
 o UNAVAILABLE
  public final static int UNAVAILABLE
Media is currently not available on this terminal connection
 o PLAYING
  public final static int PLAYING
There is currently playing on this terminal connection
 o RECORDING
  public final static int RECORDING
There is currently recording on this terminal connection

Methods

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

Returns:
The current availability of the media channel.
Throws: PlatformException
A platform-specific exception occurred.
 o getMediaState
  public abstract int getMediaState() throws PlatformException
Returns the current state of the terminal connection as a bit mask of PLAYING and RECORDING.

Returns:
The current state of playing or recording.
Throws: PlatformException
A platform-specific exception occurred.
 o useDefaultSpeaker
  public abstract void useDefaultSpeaker() throws PrivilegeViolationException, ResourceUnavailableException, PlatformException
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.
Throws: ResourceUnavailableException
Indicates that the speaker is not currently available for use.
Throws: PlatformException
A platform-specific exception occurred.
 o useRecordURL
  public abstract void useRecordURL(URL url) throws PrivilegeViolationException, ResourceUnavailableException, PlatformException
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.
Throws: ResourceUnavailableException
Indicates the URL given is not available, either because the URL was invalid or a network problem occurred.
Throws: PlatformException
A platform-specific exception occurred.
 o useDefaultMicrophone
  public abstract void useDefaultMicrophone() throws PrivilegeViolationException, ResourceUnavailableException, PlatformException
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.
Throws: ResourceUnavailableException
Indicates that the microphone is not currently available for use.
Throws: PlatformException
A platform-specific exception occurred.
 o usePlayURL
  public abstract void usePlayURL(URL url) throws PrivilegeViolationException, ResourceUnavailableException, PlatformException
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.
Throws: ResourceUnavailableException
Indicates the URL given is not available, either because the URL was invalid or a network problem occurred.
Throws: PlatformException
A platform-specific exception occurred.
 o startPlaying
  public abstract void startPlaying() throws MethodNotSupportedException, ResourceUnavailableException, InvalidStateException, PlatformException
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.
Throws: ResourceUnavailableException
Indicates playing is not able to be started because some resource is unavailable.
Throws: InvalidStateException
Indicates the TerminalConnection is not in the media channel available state.
Throws: PlatformException
A platform-specific exception occurred.
 o stopPlaying
  public abstract void stopPlaying() throws PlatformException
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.

Throws: PlatformException
A platform-specific exception occurred.
 o startRecording
  public abstract void startRecording() throws MethodNotSupportedException, ResourceUnavailableException, InvalidStateException, PlatformException
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.
Throws: ResourceUnavailableException
Indicates recording is not able to be started because some resource is unavailable.
Throws: InvalidStateException
Indicates the TerminalConnection is not in the media channel available state.
Throws: PlatformException
A platform-specific exception occurred.
 o stopRecording
  public abstract void stopRecording() throws PlatformException
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.

Throws: PlatformException
A platform-specific exception occurred.
 o setDtmfDetection
  public abstract void setDtmfDetection(boolean enable) throws MethodNotSupportedException, ResourceUnavailableException, InvalidStateException, PlatformException
 o generateDtmf
  public abstract void generateDtmf(String digits) throws MethodNotSupportedException, ResourceUnavailableException, InvalidStateException, PlatformException

All Packages  Class Hierarchy  This Package  Previous  Next  Index