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.
-
AVAILABLE
- Media is currently available on this terminal connection
-
PLAYING
- There is currently playing on this terminal connection
-
RECORDING
- There is currently recording on this terminal connection
-
UNAVAILABLE
- Media is currently not available on this terminal connection
-
generateDtmf(String)
-
-
getMediaAvailability()
- Returns the current media availability state, either AVAILABLE or
UNAVAILABLE.
-
getMediaState()
- Returns the current state of the terminal connection as a bit mask
of PLAYING and RECORDING.
-
setDtmfDetection(boolean)
-
-
startPlaying()
- Start the playing.
-
startRecording()
- Start the recording.
-
stopPlaying()
- Stop the playing.
-
stopRecording()
- Stop the recording.
-
useDefaultMicrophone()
- Instructs the terminal connection to use the default microphone for
playing to the telephone line.
-
useDefaultSpeaker()
- Instructs the terminal connection to use the default speaker for
recording from the telephone line.
-
usePlayURL(URL)
- Instructs the terminal connection to use a file for playing to
the telephone line.
-
useRecordURL(URL)
- Instructs the terminal connection to use a file for recording from
the telephone line.
AVAILABLE
public final static int AVAILABLE
- Media is currently available on this terminal connection
UNAVAILABLE
public final static int UNAVAILABLE
- Media is currently not available on this terminal connection
PLAYING
public final static int PLAYING
- There is currently playing on this terminal connection
RECORDING
public final static int RECORDING
- There is currently recording on this terminal connection
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
setDtmfDetection
public abstract void setDtmfDetection(boolean enable) throws MethodNotSupportedException, ResourceUnavailableException, InvalidStateException, PlatformException
generateDtmf
public abstract void generateDtmf(String digits) throws MethodNotSupportedException, ResourceUnavailableException, InvalidStateException, PlatformException
All Packages Class Hierarchy This Package Previous Next Index