ch.ecma.csta.binding
Class PlayMessage

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

All Implemented Interfaces:

java.io.Serializable

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

Plays a voice message on a particular Connection. The service may also specify termination conditions, which if encountered, causes message playback to stop. Refer to ECMA-269, Figure 6-21, "Voice Unit Operational Model" in section 6.2.1 for the operational model. The monitoring event sequence for both call-type and event-type monitoring is the PlayEvent.

The supported encoding algorithm types for these messages are:

• Pulse Code Modulation (PCM) 8 bit and 16 bit
• G.711 A-law and Mu-law
• G.729 and G.729A

The application can choose to play a single Wave file:

• Once - Achieve this by setting the playCount in extensions parameter to one or by not setting any termination conditions.
• Until a digit is detected - Achieve this by setting the termination parameter's DTMFDigitDetected to true in the PlayMessage request.
• For a duration - Achieve this by setting the duration parameter in the PlayMessage request.
• Multiple times - Achieve this by setting these two parameters in extensions parameter's PlayMessagePrivateData:
  • playCount - the number of times to play the file.
  • playInterval - the interval between consecutive plays.

Multiple termination conditions can be specified. The playing will continue until one of the specified termination conditions occurs or until it is explicitly stopped with a Stop request (stops both the player and the recorder) or an Extended Voice Unit Services StopPlaying request.

Alternatively, the application can choose to play multiple Wave files. This is achieved by listing the filenames in the extensions paramter of the request. This parameter contains the class PlayMessagePrivateData where the fileList is set. If fileList is set, then all files are sequentially played once and all termination conditions are ignored.

All of the above options may cause the play to continue across calls on the device. If you wish to play only until the call ends, then monitor the call appearance lamps to determine when the call ends and explicitly stop playing with the Stop request or the Extended Voice Unit Services StopPlayingrequest.

To indicate what message(s) to play, the application can specify only one of following parameters:

• messageToBePlayed - to specify a non-zero numeric filename
• extensions.playMessage - to specify an alphanumeric filename
• extensions.fileList - to specify a list of filenames

If more than one is specified, then only one is used and the precedence is messageToBePlayed, then extensions.fileList.

The PlayMessage request has these parameters:

PlayMessage Request Parameters
messageToBePlayed	Mandatory	Specifies the numeric filename of the message to be played. Do not include the ".wav" suffix for a numeric filename; it will be automatically appended. Neither a full directory path nor a subpath can be included with the filename. To specify an alphanumeric filename, a relative path with the filename, or a list of files, set messageToBePlayed to "0" and specify the alphanumeric filename in extensions playMessage.
overConnection	Mandatory	Specifies the device on which the message is to be played (only the deviceID field of the connectionID is used).
duration	Optional	Specifies the length of time to play the message in milliseconds. If set to zero, then the play service will immediately terminate and a StopEvent will be generated. If the duration is shorter than the length of the message, then the message will be played until duration is met. If the message length is less than the duration parameter, then the message will be played only once.
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 with an Avaya-specified PlayMessagePrivateData object. The optional parameters include: playMessage - Optional playCount - Optional playInterval - Optional fileList - Optional Use CSTACommonArguments.setSinglePrivateData (PlayMessagePrivateData). See example code below.

CSTA Functional Requirements have been implemented as follows:

1. The Play Message service plays a designated message until one of the following occurs:
   • a Voice Unit Services Stop request or an Extended Voice Unit Services StopPlaying request is made.
   • a Voice Unit Services Suspend request or an Extended Voice Unit Services SuspendPlaying request is made.
   • the end of the message is reached
   • a specified termination condition is detected
   • the duration is reached
   • the message has been played the specified number of times
2. If the duration is set to zero, then the play service will immediately terminate and a StopEvent will be generated.
3. This service provides media codec conversion if the file being played is in a different codec than the codec used on the call. Conversions between G.711 A-Law, G.711 Mu-Law, 8 bit and 16 bit Pulse-code modulation (PCM) with a sampling rate of 8 Kilo Hertz are supported.
4. Only one message can be played on a device at a time.
5. If a message on a given device is playing or suspended, a second Play request for the same message is rejected.

The PlayMessageResponse indicates that the request has been accepted, the request appears valid, and the request is being processed. There is no valuable information in this response.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 PlayMessage request. If you do it after PlayMessage 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 PlayMessage request include:

• PlayEvent
• StopEvent

Negative Acknowledgements:

• operation:invalidConnectionID - Sent if unable to find the Media Session associated with the DeviceID of this request.
• operation:invalidFile - Sent if Audio File format is not supported or if File (messageID) specified is not found.
• operation:invalidMsgID - Sent if the specified messageID is invalid or if the File (messageID) is not found.
• operation:invalidParameterValue - Sent if an invalid parameter is passed.
• operation:messageIDRequired - Sent if messageID is null.
• stateIncompatibility:notAbleToPlay - Sent if an IOError occurs with the Player or Recorder of this Service or if any other error occurs with the Player or Recorder of this Service.
• systemResourceAvailability:generic - Sent if a severe system error like un-availability of a system wide resource.
• stateIncompatibility:invalidObjectState - Sent if the player is in an invalid state.
• unspecified - Sent if an implementation-specific error occurs.

Version:

$Revision$ $Date$

See Also:

Serialized Form

Constructor Summary

PlayMessage()

Method Summary

boolean	equals(java.lang.Object obj) Note: hashCode() has not been overriden
java.lang.Long	getDuration() Returns the value of field 'duration'.
CSTACommonArguments	getExtensions() Returns the value of field 'extensions'.
java.lang.String	getMessageToBePlayed() Returns the value of field 'messageToBePlayed'.
ConnectionID	getOverConnection() Returns the value of field 'overConnection'.
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	setDuration(java.lang.Long duration) Sets the value of field 'duration'.
void	setExtensions(CSTACommonArguments extensions) Sets the value of field 'extensions'.
void	setMessageToBePlayed(java.lang.String messageToBePlayed) Sets the value of field 'messageToBePlayed'.
void	setOverConnection(ConnectionID overConnection) Sets the value of field 'overConnection'.
void	setTermination(TerminatingConditions termination) Sets the value of field 'termination'.
static PlayMessage	unmarshalPlayMessage(java.io.Reader reader) Method unmarshalPlayMessage
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

PlayMessage

public PlayMessage()

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

getDuration

public java.lang.Long getDuration()

Returns the value of field 'duration'. The field 'duration' has the following description: Specifies the length of time to play the message in milliseconds. If set to zero, then the play service will immediately terminate and a StopEvent will be generated. If the duration is shorter than the length of the message, then the message will be played until duration is met. If the message length is less than the duration parameter, then the message will be played only once. Optional

Returns:

Long

getExtensions

public CSTACommonArguments getExtensions()

Returns the value of field 'extensions'.

Returns:

CSTACommonArguments

getMessageToBePlayed

public java.lang.String getMessageToBePlayed()

Returns the value of field 'messageToBePlayed'. The field 'messageToBePlayed' has the following description: Specifies the numeric filename of the message to be played. Do not include the ".wav" suffix for a numeric filename; it will be automatically appended. Neither a full directory path nor a subpath can be included with the filename. To specify an alphanumeric filename, a relative path with the filename, or a list of files, set messageToBePlayed to "0" and specify the alphanumeric filename in extensions playMessage. Mandatory.

Returns:

String

getOverConnection

public ConnectionID getOverConnection()

Returns the value of field 'overConnection'. The field 'overConnection' has the following description: Specifies the connection on which the message is to be played. Only the deviceID field of the connectionID is used. Mandatory.

Returns:

ConnectionID

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 conditions that cause the playback to terminate.

This may include one or more of the following actions:

• duration exceeded (this value can only be provided if the duration parameter is provided)
• DTMF digit (external to the message being played) detected
• end of message detected
• speech (external to the message being played) detected.

Optional.

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

setDuration

public void setDuration(java.lang.Long duration)

Sets the value of field 'duration'. The field 'duration' has the following description: Specifies the length of time to play the message in milliseconds. If set to zero, then the play service will immediately terminate and a StopEvent will be generated. If the duration is shorter than the length of the message, then the message will be played until duration is met. If the message length is less than the duration parameter, then the message will be played only once. Optional

Parameters:

duration - the value of field 'duration'.

setExtensions

public void setExtensions(CSTACommonArguments extensions)

Sets the value of field 'extensions'.

Parameters:

extensions - the value of field 'extensions'.

setMessageToBePlayed

public void setMessageToBePlayed(java.lang.String messageToBePlayed)

Sets the value of field 'messageToBePlayed'. The field 'messageToBePlayed' has the following description: Specifies the numeric filename of the message to be played. Do not include the ".wav" suffix for a numeric filename; it will be automatically appended. Neither a full directory path nor a subpath can be included with the filename. To specify an alphanumeric filename, a relative path with the filename, or a list of files, set messageToBePlayed to "0" and specify the alphanumeric filename in extensions playMessage. Mandatory.

Parameters:

messageToBePlayed - the value of field 'messageToBePlayed'.

setOverConnection

public void setOverConnection(ConnectionID overConnection)

Sets the value of field 'overConnection'. The field 'overConnection' has the following description: Specifies the connection on which the message is to be played. Only the deviceID field of the connectionID is used. Mandatory.

Parameters:

overConnection - the value of field 'overConnection'.

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 conditions that cause the playback to terminate.

This may include one or more of the following actions:

• duration exceeded (this value can only be provided if the duration parameter is provided)
• DTMF digit (external to the message being played) detected
• end of message detected
• speech (external to the message being played) detected.

Optional.

Parameters:

termination - the value of field 'termination'.

unmarshalPlayMessage

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

Method unmarshalPlayMessage

Parameters:

reader -

Returns:

PlayMessage

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