ch.ecma.csta.binding
Class RecordMessage

java.lang.Object
  ch.ecma.csta.CastorObject
      ch.ecma.csta.binding.RecordMessage

All Implemented Interfaces:

java.io.Serializable

public class RecordMessage
extends ch.ecma.csta.CastorObject
implements java.io.Serializable

Starts recording media stream coming into a specified device. The application can specify a file name to hold the recorded message or the file name can default to timestampextension.wav, where timestamp is the local start time of the recording and extension is the phone number of the device.

Timestamp is formatted as yyyyMMddhhmmss, where

yyyy	is year
MM	is month
dd	is day
hh	is hour
mm	is minutes
ss	is seconds

Since recording applies to a device and not a call, recording will continue even after a call on that device has ended. Recording on the device has to be stopped by the application or termination criteria can be specified. An application can choose to record:

• A specified duration - Achieve this by setting the maxDuration parameter.
• Until a DTMF digit is detected - Achieve this by setting the termination parameter's DTMFDigitDetected to true.
• A single call - Achieve this by monitoring lamp events to determine when the call has finished and then stopping the recording with the stop method or an ExtendedVoiceUnitServices.stopRecording method.

Once the recording on the device has stopped, a StopEvent is sent and the recorded file is ready for the application.

The RecordMessage request has these parameters:

RecordMessage Request Parameters
callToBeRecorded	Mandatory	Specifies the device whose incoming media stream is to be recorded (only the deviceID field of the connectionID is used).
samplingRate	Not supported
encodingAlgorithm	Not supported	Set the encoding algorithm in the extensions' PrivateData instead. See extensions parameter.
maxDuration	Optional	Specifies the maximum duration of the recording in milliseconds.
termination	Optional	The DTMF digit detection termination condition is supported. If this is set, the recording will continue until a DTMF digit is detected on the device.
extensions	Optional	Optional parameters can be set in this parameter's CSTACommonArguments private data area. The parameters that can be set are: encoding - Optional filename - Optional

The RecordMessagePrivateData class contains these parameters:

RecordMessagePrivateData Parameters
encoding	Optional	Specifies the desired encoding format of the resulting Wave file. If the incoming media is in a different format than what is specified, then the media will be converted to the specified format. Conversions that are supported include: from any G.711 type to any PCM or G.711 encoding type from any PCM type to any G.711 or PCM type The encoding format of the recorded message can be set to one of the following strings: "PCM_8_K_16_BITS_WAV" - PCM 16 bit with sampling rate of 8 KHz "PCM_8_K_8_BITS_WAV" - PCM 8 bit with sampling rate of 8 KHz "ULAW_WAV" - G.711 Mu-Law "ALAW_WAV" - G.711 A-Law If the Wave file's encoding format is not specified, no conversion is performed and the Wave file will be in whatever format the incoming media is in.
filename	Optional	Specifies an alphanumeric recording file name.

Negative Acknowledgements:

• operation:invalidParameterValue - Sent if an invalid parameter is passed.
• operation:invalidConnectionID - Sent if unable to find the Media Session associated with the DeviceID of this request.
• operation:invalidFile - Sent if File (messageID) Specified is not found or if a Security Exception occurred for the specified File (messageID).
• operation:generic - Sent if an IOError occurred or if a channel is already closed.
• systemResourceAvailability:generic - Sent if a severe system error like un-availability of a system wide resource.
• stateIncompatibility:invalidObjectState - Sent if the recorder is in an invalid state.
• unspecified - Sent if an implementation-specific error occurs.

The RecordMessageResponse indicates that request has been accepted, the request appears valid, and the request is being processed. The RecordMessageResponse returns the name of the file where the message is being recorded. RecordMessageResponse has these parameters:

RecordMessageResponse Parameters
resultingMessage	Always Provided	If the application chose to default the filename to timestamp extension .wav, then this field specifies the resulting Wave file name (with timestamp and extension ) without the ".wav" suffix. The file is placed on the connector server. A ".wav" needs to be appended to a numeric filename to get the complete filename as stored on the disk. If the application instead specified its own filename in the request's RecordMessagePrivateData, then this field is "0" and the file name is returned in the response's extension in RecordMessageResponsePrivateData.
extensions	Always Provided	Additional data is returned in this parameter's CSTACommonArguments private data area. The data that is returned is: filename - Always provided timestamp - Always provided

The response's extension has these private data parameters:

RecordMessageResponsePrivateData Parameters
filename	Always Provided	The alphanumeric recording filename.
timestamp	Always Provided	The start time of the recording. Time is measured in the number of milliseconds between the current time on the connector server and midnight, January 1, 1970 coordinated univeral time (UTC).

If there is a problem with the request, an exception is sent.

To avoid potential timing problems, you should request monitoring of the events generated by this request prior to sending the RecordMessage request. If you do it after RecordMessage request is sent, your application may or may not receive the appropriate event (the event may occur before).

The events that may be caused by a RecordMessage request include:

• RecordEvent
• StopEvent
• SuspendRecordEvent

CSTA's Functional Requirements have been implemented as follows:

• G.711 A-Law, G.711 Mu-Law, G.729 and G.729A encoding algorithms and, 8 bit and 16 bit Pulse-code modulation (PCM) with a sampling rate of 8 Kilo Hertz are supported.

Version:

$Revision$ $Date$

See Also:

Serialized Form

Constructor Summary

RecordMessage()

Method Summary

boolean	equals(java.lang.Object obj) Note: hashCode() has not been overriden
ConnectionID	getCallToBeRecorded() Returns the value of field 'callToBeRecorded'.
EncodingAlgorithm	getEncodingAlgorithm() Returns the value of field 'encodingAlgorithm'.
CSTACommonArguments	getExtensions() Returns the value of field 'extensions'.
java.lang.Long	getMaxDuration() Returns the value of field 'maxDuration'.
java.lang.String	getResource() Returns the value of field 'resource'.
java.lang.Long	getSamplingRate() Returns the value of field 'samplingRate'.
TerminatingConditions	getTermination() Returns the value of field 'termination'.
boolean	isValid() Method isValid
void	marshal(org.xml.sax.ContentHandler handler) Method marshal
void	marshal(java.io.Writer out) Method marshal
void	setCallToBeRecorded(ConnectionID callToBeRecorded) Sets the value of field 'callToBeRecorded'.
void	setEncodingAlgorithm(EncodingAlgorithm encodingAlgorithm) Sets the value of field 'encodingAlgorithm'.
void	setExtensions(CSTACommonArguments extensions) Sets the value of field 'extensions'.
void	setMaxDuration(java.lang.Long maxDuration) Sets the value of field 'maxDuration'.
void	setResource(java.lang.String resource) Sets the value of field 'resource'.
void	setSamplingRate(java.lang.Long samplingRate) Sets the value of field 'samplingRate'.
void	setTermination(TerminatingConditions termination) Sets the value of field 'termination'.
static RecordMessage	unmarshalRecordMessage(java.io.Reader reader) Method unmarshalRecordMessage
void	validate() Method validate

Methods inherited from class ch.ecma.csta.CastorObject

getOldSessionID, hashCode, setOldSessionID, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

RecordMessage

public RecordMessage()

Method Detail

equals

public boolean equals(java.lang.Object obj)

Note: hashCode() has not been overriden

Overrides:

equals in class ch.ecma.csta.CastorObject

Parameters:

obj -

Returns:

boolean

getCallToBeRecorded

public ConnectionID getCallToBeRecorded()

Returns the value of field 'callToBeRecorded'. The field 'callToBeRecorded' has the following description: Specifies the device whose incoming media stream is to be recorded (only the deviceID field of the connectionID is used).Mandatory.

Returns:

ConnectionID

getEncodingAlgorithm

public EncodingAlgorithm getEncodingAlgorithm()

Returns the value of field 'encodingAlgorithm'. The field 'encodingAlgorithm' has the following description: Not supported. Set the encoding algorithm in the extensions' PrivateData instead. See extensions parameter.

Returns:

EncodingAlgorithm

getExtensions

public CSTACommonArguments getExtensions()

Returns the value of field 'extensions'.

Returns:

CSTACommonArguments

getMaxDuration

public java.lang.Long getMaxDuration()

Returns the value of field 'maxDuration'. The field 'maxDuration' has the following description: Specifies the maximum message time to record (in milliseconds). Optional.

Returns:

Long

getResource

public java.lang.String getResource()

Returns the value of field 'resource'.

Returns:

String

getSamplingRate

public java.lang.Long getSamplingRate()

Returns the value of field 'samplingRate'. The field 'samplingRate' has the following description: Not supported. Specifies the sampling rate to be used for recording. Optional.

Returns:

Long

getTermination

public TerminatingConditions getTermination()

Returns the value of field 'termination'. The field 'termination' has the following description: The DTMF digit detection termination condition is supported. If this is set, the recording will continue until a DTMF digit is detected on the device.

Specifies the list of actions that causes the recording to terminate. Optional.

This may include one or more of the following actions:

• duration exceeded
• DTMF digit detected
• end of data detected
• speech detected

Returns:

TerminatingConditions

isValid

public boolean isValid()

Method isValid

Returns:

boolean

marshal

public void marshal(java.io.Writer out)
             throws org.exolab.castor.xml.MarshalException,
                    org.exolab.castor.xml.ValidationException

Method marshal

Parameters:

out -

Throws:

org.exolab.castor.xml.MarshalException

org.exolab.castor.xml.ValidationException

marshal

public void marshal(org.xml.sax.ContentHandler handler)
             throws java.io.IOException,
                    org.exolab.castor.xml.MarshalException,
                    org.exolab.castor.xml.ValidationException

Method marshal

Parameters:

handler -

Throws:

java.io.IOException

org.exolab.castor.xml.MarshalException

org.exolab.castor.xml.ValidationException

setCallToBeRecorded

public void setCallToBeRecorded(ConnectionID callToBeRecorded)

Sets the value of field 'callToBeRecorded'. The field 'callToBeRecorded' has the following description: Specifies the device whose incoming media stream is to be recorded (only the deviceID field of the connectionID is used).Mandatory.

Parameters:

callToBeRecorded - the value of field 'callToBeRecorded'

setEncodingAlgorithm

public void setEncodingAlgorithm(EncodingAlgorithm encodingAlgorithm)

Sets the value of field 'encodingAlgorithm'. The field 'encodingAlgorithm' has the following description: Not supported. Set the encoding algorithm in the extensions' PrivateData instead. See extensions parameter.

Parameters:

encodingAlgorithm - the value of field 'encodingAlgorithm'.

setExtensions

public void setExtensions(CSTACommonArguments extensions)

Sets the value of field 'extensions'.

Parameters:

extensions - the value of field 'extensions'.

setMaxDuration

public void setMaxDuration(java.lang.Long maxDuration)

Sets the value of field 'maxDuration'. The field 'maxDuration' has the following description: Specifies the maximum message time to record (in milliseconds). Optional.

Parameters:

maxDuration - the value of field 'maxDuration'.

setResource

public void setResource(java.lang.String resource)

Sets the value of field 'resource'.

Parameters:

resource - the value of field 'resource'.

setSamplingRate

public void setSamplingRate(java.lang.Long samplingRate)

Sets the value of field 'samplingRate'. The field 'samplingRate' has the following description: Not supported. Specifies the sampling rate to be used for recording. Optional.

Parameters:

samplingRate - the value of field 'samplingRate'.

setTermination

public void setTermination(TerminatingConditions termination)

Sets the value of field 'termination'. The field 'termination' has the following description: The DTMF digit detection termination condition is supported. If this is set, the recording will continue until a DTMF digit is detected on the device.

Specifies the list of actions that causes the recording to terminate. Optional.

This may include one or more of the following actions:

• duration exceeded
• DTMF digit detected
• end of data detected
• speech detected

Parameters:

termination - the value of field 'termination'.

unmarshalRecordMessage

public static RecordMessage unmarshalRecordMessage(java.io.Reader reader)
                                            throws org.exolab.castor.xml.MarshalException,
                                                   org.exolab.castor.xml.ValidationException

Method unmarshalRecordMessage

Parameters:

reader -

Returns:

RecordMessage

Throws:

org.exolab.castor.xml.MarshalException

org.exolab.castor.xml.ValidationException

validate

public void validate()
              throws org.exolab.castor.xml.ValidationException

Method validate

Throws:

org.exolab.castor.xml.ValidationException