javax.telephony.media
Interface Recorder

All Superinterfaces:

CoderConstants, MediaConstants, RecorderConstants, Resource, ResourceConstants

All Known Implementing Classes:

BasicMediaService

public interface Recorder

extends Resource, RecorderConstants

Defines a method for recording a media stream into a data file. A Recorder transcodes the media stream data from the telephony network, and stores the result in a Media Data Object (MDO).

A variety a coder types are defined, depending on the particular Recorder.

Run Time Controls can be used to stop recording.

A Recorder may optionally support additional processing features. These features define parameters and runtime controls that affect operation of an ongoing play operation. The presence of these features is indicated by a true value for the following attributes:

Attribute:	indicates the ability to:
a_Beep	play a beep before recording. parameters p_StartBeep, p_BeepLength, p_BeepFrequency are supported
a_FixedBeep	do limited beep. parameter p_StartBeep is supported
a_CoderTypes	use the listed coders. see CoderConstants for defined coder types
a_Pause	pause and resume while recording. RTC actions rtca_Pause and rtca_Resume are supported

States:

The recorder is either Idle, Active, or Paused.

record() fails unless the state is Idle. and then the state becomes Active or Paused. The state of the Recorder after play() starts is determined by the Boolean value of the parameter p_StartPaused. The state transitions to Active if p_StartPaused is false. The state transitions to Paused if p_StartPaused is true.

When recording stops, the state becomes Idle. Recording stops for a variety of reasons.

rtca_Pause has no effect unless state is Recording, and then the state becomes Paused, and ev_Paused is sent to onPaused().

rtca_Resume has no effect unless state is Paused, and then the state becomes Recording, and ev_Resumed is sent to onResumed().

Note: The format of the String that identifies an MDO is not defined by this release of specification. [although it will be compatible with that used in the ContainerService]. The vendor-specific implementation of the MediaService (for example, the vendor of the server or resource) shall define the supported String formats.

For example, an implementation may support URLs or File pathnames; in which case an application could use Strings of the form: "file://node/dir/name" or "dir/dir/name"

If the MDO identifier is a file pathname, it is interpreted in the logical filename-space of the server. Applications and their prompts need to be installed with correct pathnames.

Since:

JTAPI-1.3

Fields inherited from interface javax.telephony.media.ResourceConstants

e_Disconnected, FOREVER, q_Disconnected, q_RTC, rtcc_Disconnected, rtcc_TriggerRTC, v_Forever

Fields inherited from interface javax.telephony.media.MediaConstants

e_OK, q_Duration, q_Standard, q_Stop

Fields inherited from interface javax.telephony.media.RecorderConstants

a_Beep, a_CoderTypes, a_FixedBeep, a_Pause, e_Coder, ev_Pause, ev_Record, ev_Resume, ev_Stop, p_Append, p_BeepFrequency, p_BeepLength, p_Coder, p_CoderTypes, p_EnabledEvents, p_MaxDuration, p_MinDuration, p_SilenceTerminationOn, p_SilenceTerminationThreshold, p_SilenceTruncationOn, p_SilenceTruncationThreshold, p_StartBeep, p_StartPaused, q_Silence, rtca_Pause, rtca_Resume, rtca_Stop, rtcc_RecordComplete, v_Class

Fields inherited from interface javax.telephony.media.CoderConstants

v_24kADPCM, v_32kADPCM, v_44kADPCM, v_48k8BitLinear, v_48kALawPCM, v_48kMuLawPCM, v_64k8BitLinear, v_64kALawPCM, v_64kMuLawPCM, v_88k8BitLinear, v_88kALawPCM, v_88kMuLawPCM, v_ADPCM_24k, v_ADPCM_32k, v_ADPCM_44k, v_ADSI, v_ALawPCM_48k, v_ALawPCM_64k, v_ALawPCM_88k, v_ASCII, v_Linear8Bit_48k, v_Linear8Bit_64k, v_Linear8Bit_88k, v_MuLawPCM_48k, v_MuLawPCM_64k, v_MuLawPCM_88k, v_TDD

Method Summary

RecorderEvent	pauseRecorder() Pause the current record.
RecorderEvent	record(java.lang.String streamID, RTC[] rtc, java.util.Dictionary optargs) Record data from the Terminal into the named Media Data Object (MDO).
RecorderEvent	resumeRecorder() Resume the current record.
RecorderEvent	stopRecorder() Stop the current record.

Method Detail

record

public RecorderEvent record(java.lang.String streamID,
                            RTC[] rtc,
                            java.util.Dictionary optargs)
                     throws MediaResourceException

Record data from the Terminal into the named Media Data Object (MDO). Encode and store data from the telephony network. record() encodes the media stream from the bound Terminal, and stores the result in the Media Stream Container identified by the given streamID.

If the MDO does not exist, it is created and associated with the coder type specified by parameter p_Coder. If the MDO does exist, the recording is made using the coder type associated with that DSD. If the Recorder does not support the indicated Coder, record() throws a MediaResourceException, indicating e_Coder.

This method returns when the recording stops because of timeout or an RTC action. (Pause/Resume does not cause this method to return.) The condition that caused recording to stop is available from the completion event using getQualifier.

The optargs argument specifies values for Recorder parameters for the duration of this record operation. For example, p_Coder or p_BeepStart can be overridden for a single method invocation.

Exceptions are thrown if pre- or post- conditions are not satisfied
Pre-conditions:

1. Recorder is configured into this MediaService
2. The SDR exists or can be created
3. The SDR is not locked (that is, is not in use)
4. Recorder is Idle
5. Recorder has the required/requested coder

Post-conditions: Record completes normally due to one of:

1. Duration time reached
2. a silence exceeding p_SilenceThreshold detected
3. stop() method invoked
4. rtca_Stop triggered

Parameters:

streamID - the String name of the MDO where data is to be stored.

rtc - an Array of RTC (Run-Time-Control) objects

optargs - a Dictionary of optional arguments

Returns:

a RecorderEvent with additional information.

Throws:

MediaResourceException - if requested operation fails.

DisconnectedException - if Terminal is disconnected.

pauseRecorder

public RecorderEvent pauseRecorder()
                            throws MediaResourceException

Pause the current record.

This is functionally equivalent to rtca_Pause, except that it generates a Completion Event instead of a non-transactional Event.

Returns:

a RecorderEvent object

Throws:

MediaResourceException -

resumeRecorder

public RecorderEvent resumeRecorder()
                             throws MediaResourceException

Resume the current record.

This is functionally equivalent to rtca_Resume, except that it generates a Completion Event instead of a non-transactional Event.

Returns:

a RecorderEvent object

Throws:

MediaResourceException -

stopRecorder

public RecorderEvent stopRecorder()
                           throws MediaResourceException

Stop the current record.

This is functionally equivalent to rtca_Stop, except that it generates a Completion Event instead of a non-transactional Event.

Returns:

a RecorderEvent object

Throws:

MediaResourceException -