hp.opencall.media.ccapi.AsyncMediaGroup
|
|||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||||
java.lang.Object
Adapter class which provides the asynchronous media resource interface to the native Call Control API including access to ASR/TTS servers.
Most of its methods are documented in classes and interfaces defined in
JTAPI Media (ECTF S.410) or add for additional features :
Player, Recorder, SignalDetector,
SignalGenerator, Conference, EchoCanceller,
RTPPlayer, RTPRecorder, SilencePlayer, SpeechDetector.
The access to these methods depends on the resource given in the ConfigSpec.
Due to the asynchronous nature of the API, the media resources methods
(of interfaces Player, Recorder, SignalDetector and SignalGenerator) are
non-blocking and the result is passed back to the application as an event
through a listener interface (Callback methods). For example, in the
play().
method, the result of the play is passed as a PlayerEvent event in a call to
onPlayerEvent().
On the contrary, Conference methods (#join/#unjoin) are synchronous and do not return any result with an event.
This class assumes that all methods are called on a User Thread (see
Thread Management in CCSession).
| Nested Class Summary |
| Nested classes inherited from class hp.opencall.media.ccapi.FaxLoggerIf |
FaxLoggerIf.FaxLoggerIf2 |
| Field Summary |
| Fields inherited from interface hp.telephony.media.ResourceConstants |
e_Disconnected, e_OK, FOREVER, q_Duration, q_RTC, q_Standard, q_Stop, rtcc_Disconnected, rtcc_TriggerRTC, v_Forever |
| Fields inherited from interface hp.telephony.media.CoderConstants |
p_AMR_SDPelement, p_channels, p_crc, p_G723_annexa, p_G723_bitrate, p_G729_annexb, p_interleaving, p_maxptime, p_modechangeneighbor, p_modechangeperiod, p_modeset, p_octetalign, p_ptime, p_robustsorting, v_ADPCM_16kG726, v_ADPCM_24k, v_ADPCM_32k, v_ADPCM_32kG726, v_ADPCM_32kOKI, v_ADPCM_44k, v_ALawPCM_48k, v_ALawPCM_64k, v_ALawPCM_88k, v_AMR, v_AMR_WB, v_G723_1b, v_G723_53, v_G723_63, v_G723_no_vad, v_G723_yes, v_G729_no_vad, v_G729_yes, v_G729a, v_GSM, v_Linear16Bit_64k, v_Linear8Bit_48k, v_Linear8Bit_64k, v_Linear8Bit_88k, v_MuLawPCM_48k, v_MuLawPCM_64k, v_MuLawPCM_88k |
| Fields inherited from interface hp.telephony.media.SpeechDetectorConstants |
p_BargeIn, p_FinalTimeout, p_InitialTimeout, p_InPromptSensitivityPercent, p_Sensitivity, p_Type, q_EndOfSpeechDetected, q_NoSpeechTimeout, q_SpeechDetected, rtca_PromptDone, rtcc_EndOfSpeechDetected, rtcc_NoSpeechTimeout, rtcc_SpeechDetected, v_HP, v_Nvad, v_SwiEp, v_Telisma |
| Fields inherited from interface hp.telephony.media.EchoCancellerConstants |
p_AcousticEcho, p_AlcInEnable, p_AlcInGain, p_AlcOutEnable, p_AlcOutGain, p_Bypass, p_EchoThreshold, p_MaxDelaySearch, p_Mu, p_NlpControl |
| Fields inherited from interface hp.telephony.media.RTPRecorderConstants |
p_SendSignalsUsingRFC2833 |
| Fields inherited from interface hp.telephony.media.SMSRecorderConstants |
e_TL_InternalError, ev_SMS, q_TL_Message, v_TL_DATA_CFM, v_TL_DATA_ERR, v_TL_DATA_IND, v_TL_DATA_REJ, v_TL_EST_CFM, v_TL_EST_REJ, v_TL_INFO_ABRT, v_TL_INFO_CFM, v_TL_INFO_IND, v_TL_INFO_REJ, v_TL_NOT_DLL_EST_IND, v_TL_REL_ABRT, v_TL_REL_CFM, v_TL_REL_IND |
| Fields inherited from interface hp.telephony.media.SignalGeneratorConstants |
a_SourceProvided, ev_SendSignals, p_Amplitude, p_DtmfGeneratorMode, p_InterSigGap, p_Length |
| Fields inherited from interface hp.telephony.media.SignalConstants |
p_SymbolChar, v_CED, v_CNG, v_DTMF0, v_DTMF1, v_DTMF2, v_DTMF3, v_DTMF4, v_DTMF5, v_DTMF6, v_DTMF7, v_DTMF8, v_DTMF9, v_DTMFA, v_DTMFB, v_DTMFC, v_DTMFD, v_DTMFHash, v_DtmfInBand, v_DtmfInBandOutBand, v_DtmfNone, v_DtmfOutBand, v_DTMFStar |
| Fields inherited from interface hp.telephony.media.ConferenceConstants |
p_AutoRelease, p_ListenOnly, p_TalkOnly |
| Method Summary | |
void |
addResourceEventListener(ResourceEventListener aListener)
Adds the specified resource event listener to receive events from the media group. |
void |
configure(ConfigSpec configSpec)
Configures the MediaGroup according to the given configSpec. |
void |
flushBuffer()
Remove all signals from the signal buffer. |
ConfigSpec |
getConfiguration()
Returns a ConfigSpec that describes the current configuration of the MediaGroup. |
com.hp.opencall.media.common.MGLabel |
getLabel()
|
Dictionary |
getParameters(Symbol[] params)
Gets the value of various parameters from the MediaGroup. |
Dictionary |
getUserDictionary()
Deprecated. No longer needed. |
Dictionary |
getUserValues(Symbol[] keys)
Deprecated. No longer needed. |
void |
join(ConferenceIF confIF)
Join to a given conference in both directions. |
void |
performFaxLog(String caller,
String called,
int duration,
Date timeStamp)
Default means to log fax operations. |
void |
play(String[] streamIDs,
int offset,
RTC[] rtc,
Dictionary optargs)
Play a sequence of MSCs (Media Stream Containers) identified by the streamIDs. |
void |
play(String streamID,
int offset,
RTC[] rtc,
Dictionary optargs)
Play a single MSC (Media Stream Container) named by streamID. |
void |
record(String streamID,
RTC[] rtc,
Dictionary optargs)
Record data from the Terminal into the named Media Stream Container (MSC). |
void |
retrieveSignals(int numSignals,
Symbol[] patterns,
RTC[] rtc,
Dictionary optargs)
Retrieve some signals from the signal buffer. |
void |
sendSignals(String signals,
RTC[] rtc,
Dictionary optargs)
Transmit a series of signals out the Terminal to the network. |
void |
sendSignals(Symbol[] signals,
RTC[] rtc,
Dictionary optargs)
signal generator methods |
static void |
setFaxLogger(FaxLoggerIf listener)
Provides the OC MP platform with a means to log fax operations. |
void |
setParameters(Dictionary params)
Set the value of various parameters for the MediaGroup. |
void |
setUserDictionary(Dictionary newDict)
Deprecated. No longer needed. |
void |
setUserValues(Dictionary params)
Deprecated. No longer needed. |
void |
stop()
Stops all operations currently in progress on this media group. |
String |
toString()
|
void |
triggerRTC(Symbol rtca)
Triggers a RTC action from the application. |
void |
unjoin(ConferenceIF confIF)
Unjoin the MG from a conference. |
| Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
| Method Detail |
public com.hp.opencall.media.common.MGLabel getLabel()
public void configure(ConfigSpec configSpec)
throws MediaConfigException
MediaConfigException
public ConfigSpec getConfiguration()
throws AccessControlException
AccessControlExceptionpublic void stop()
Those operations that are stopped get a completion event with:
ResourceEvent.getQualifier() == ResourceEvent.q_Stop
public void triggerRTC(Symbol rtca)
This method allows the application to synthesize the triggering of RTC
actions. The RTC Condition associated with this action is:
rtcc_TriggerRTC.
rtca - a Symbol for a recognized RTC action: rtca_Actionpublic void setUserDictionary(Dictionary newDict)
public void setParameters(Dictionary params)
For each key in the supplied Dictionary, the corresponding parameter of
the MediaGroup is set to the value of that key in the Dictionary.
For interoperability with other languages, the keys in the Dictionary
are restricted to type Symbol. The result of using keys of other
types is undefined.
If a parameter Symbol refers to a resource that is not present, or the MediaGroup or Resource has no meaning associated with a particular Symbol, the setting for that parameter is quietly ignored.
params - a Dictionary in which the keys are Symbols and the values
are assigned to the parameter with that Symbol name.public void setUserValues(Dictionary params)
The values supplied in the given dict are merged with the current UserDictionary.
params - a Dictionary whose contents is merged into the UserDictionary.
public Dictionary getUserValues(Symbol[] keys)
throws AccessControlException
If the keys argument is null then a snapshot of the entire UserDictionary is returned.
For interoperability with other languages, the keys in the Dictionary are restricted to type Symbol. The result of using keys of other types is undefined.
keys - an array of key Symbols
AccessControlException
public Dictionary getParameters(Symbol[] params)
throws AccessControlException
Each key in the returned Dictionary has the value of the corresponding parameter. If the params is null, then get all parameters. For example:
Dictionary parms; parms = getParameters(null); // on return, parms contains all parameters.
If a key refers to a Resource that is not present, or the resource has no meaning associated with a particular Symbol, the key is ignored, no error is generated, and that key does not appear in the returned Dictionary.
params - - an array of Symbols naming parameters to be retrieved.
BadThreadException - if the method is not called on the proper User
Thread.
AccessControlException
public Dictionary getUserDictionary()
throws AccessControlException
AccessControlException
public void play(String[] streamIDs,
int offset,
RTC[] rtc,
Dictionary optargs)
throws MediaResourceException,
AccessControlException
PlayerThis method cannot be used for sending TTS synthesize requests. Sequences of MSCs are not supported for this type of requests.
This method cannot either be used for SMS, nor for fax.
This method returns when the MSC list is started.
This method is non-blocking. The result is passed in a
PlayerEvent event through the ResourceEventListener Interface.
The condition that caused the play to stop is included in the
completion event. RTC actions can alter the course of the play
without the intervention of the application.
Optional arguments can alter the characteristics of the play.
Exceptions are thrown if pre- or post- conditions are not satisfied
Pre-conditions:
Post-conditions:
getQualifier():q_EndOfData: All MSCs named in this MSC list
have been played.q_Stop: play was stopped by the
stop() method
or because (p_IfBusy=v_Stop)q_RTC: play was stopped by
Player.rtca_Stop
play in interface PlayerstreamIDs - a String[] naming the MSC list to be played.offset - number of milliseconds into the MSC list at
which play is to start, offset may span several items in streamIDs.rtc - Array of RTC that effect this play.optargs - a Dictionary of optional arguments.
AccessControlException - if access to resource is refused
MediaResourceException - if requested operation fails.ResourceEventListener.onPlayerEvent(PlayerEvent)
public void play(String streamID,
int offset,
RTC[] rtc,
Dictionary optargs)
throws MediaResourceException,
AccessControlException
Playerplay() with a String[] of length one,
containing the given streamID.
This method should be used for sending TTS synthesize, Fax and SMS requests.
This method is non-blocking. The result is passed in a
PlayerEvent event through the ResourceEventListener Interface
play in interface PlayerstreamID - a String naming the MSC to be played or the TTS
Audio Service URI in form "rtsp://audioservice"
"sms-tl://"
"fax://".offset - int number milliseconds into the MSC (ignored for
TTS synthesize, fax or SMS requests) at which play is to start. Not supported for
file with encoding format: v_ADPCM_32k, v_ADPCM_32kOKI, v_ADPCM_16kG726 and v_ADPCM_32kG726.rtc - Array of RTC that effect this play.optargs - a Dictionary of optional arguments.
AccessControlException - if access to resource is refused
MediaResourceException - if requested operation failsResourceEventListener.onPlayerEvent(PlayerEvent)
public void record(String streamID,
RTC[] rtc,
Dictionary optargs)
throws MediaResourceException,
AccessControlException
Recorderrecord() encodes the media stream
from the bound Terminal, and stores the result in
the Media Stream Container identified by
the given streamID.
This method can also be used for sending ASR recognize requests as well as for SMS and, soon, faxes.
If the MSC does not exist, it is created and associated
with the coder type specified by parameter p_CoderTypesp_Coder ; value is a one element array, the coder type).
If the MSC does exist, the recording is made using
the coder type associated with that DSD, in case of a WAV file, otherwise, the coder type specified by p_CoderTypesrecord()MediaResourceExceptionError.e_Coder
This method is non-blocking. The result is passed in a
RecorderEventResourceEventListener Interface.
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_CoderTypes (instead of 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:
p_SilenceTerminationThresholdstop() method invokedRecorderConstants.rtca_Stop
record in interface RecorderstreamID - the String name of the MSC where data is to be stored
"rtsp://audioservice"
"sms-tl://"
"fax://".rtc - an Array of RTC (Run-Time-Control) objectsoptargs - a Dictionary of optional arguments among
RecorderConstants.p_FileFormat RecorderConstants.p_CoderTypes RecorderConstants.p_Append RecorderConstants.p_EnabledEvents RecorderConstants.p_MaxDuration RecorderConstants.p_MinDuration RecorderConstants.p_SilenceTerminationOn RecorderConstants.p_SilenceTerminationThreshold RecorderConstants.p_SilenceTruncationOn RecorderConstants.p_SilenceTruncationThreshold RecorderConstants.p_SignalTruncationOn RecorderConstants.p_SilenceEnergyThreshold RecorderConstants.p_StartBeep RecorderConstants.p_StartPaused MediaResourceException - if requested operation fails.
AccessControlExceptionResourceEventListener.onRecorderEvent(hp.telephony.media.RecorderEvent)
public void sendSignals(Symbol[] signals,
RTC[] rtc,
Dictionary optargs)
throws MediaResourceException,
AccessControlException
sendSignals in interface SignalGeneratorsignals - an array of Symbols that defines a signal.rtc - an array of RTC objects that controls this transactions.optargs - a Dictionary of optional arguments
MediaResourceException - if this request fails.
AccessControlExceptionResourceEventListener.onSignalGeneratorEvent(SignalGeneratorEvent)
public void sendSignals(String signals,
RTC[] rtc,
Dictionary optargs)
throws MediaResourceException,
AccessControlException
SignalGeneratorEach signal is defined by a char in the String.
sendSignals in interface SignalGeneratorsignals - an array of Symbols that defines a signal.rtc - an array of RTC objects that controls this transactions.optargs - a Dictionary of optional arguments
MediaResourceException - if this request fails.
AccessControlExceptionResourceEventListener.onSignalGeneratorEvent(SignalGeneratorEvent)
public void retrieveSignals(int numSignals,
Symbol[] patterns,
RTC[] rtc,
Dictionary optargs)
throws MediaResourceException,
AccessControlException
SignalDetectornumSignals signals are
in the signal buffer (and removes them). May return with fewer than
numSignals when some other terminating condition
occurs (rtca_Stop, a Pattern is detected, or timeout).
In that case, the method returns and removes all the signals
from the signal buffer. If (numSignals == -1), then
this method returns only when some other termination condition
occurs.
The terminating conditions are controlled by the arguments
patterns and rtc, and various
timeout parameters.
patterns is an array of Symbols, with an entry for
each Pattern to enable.
If the patterns array contains a pattern Symbol
then recognition of that pattern is treated as
a terminating condition for retrieveSignals().
If patterns is null, then pattern recognition is not
considered as a terminating condition.
retrieveSignals also terminates if any of the
p_InitialTimeout,
p_InterSigTimeout,
p_Duration
timeouts are exceeded. These times are relative to the start
of the retrieveSignals operation.
These parameters can be set with setParameters
or in the optargs argument.
To get the retrieved signals, invoke getSignalBuffer()
on the SignalDetectorEvent returned from retrieveSignals.
If retrieveSignals can not return a signal buffer,
it throws an exception,
so retrieveSignals(...).getSignalBuffer() is safe.
The Signals are accessed as elements of the Symbol[] returned by
getSignalBuffer
or char elements of the String returned by
getSignalString.
Example:
String nextDTMF = retrieveSignals(1,null,null,null).getSignalBuffer();
Note:
Due to the effects of overflow and typeahead synchronization,
the more reliable way to get the signals that matched a pattern
is from the ev_PatternMatched event in the
onSignalDetectorEvent()
method.
retrieveSignals in interface SignalDetectornumSignals - the int number of signals to be retrieved.patterns - indicates which Patterns should terminate retrieval.rtc - an Array of RTC (Run Time Control) objects.
The RTC actions may be rtca_Stop
or rtca_FlushBuffer.optargs - a Dictionary of optional arguments.
p_Pattern[i] may be set as transient parameters.
MediaResourceException - if this request fails;
usually because of a badly formed request,
or implementation cannot process the request.
AccessControlExceptionResourceEventListener.onSignalDetectorEvent(SignalDetectorEvent)
public void flushBuffer()
throws MediaResourceException,
AccessControlException
SignalDetectorThis prevents buffer overflow, and synchronizes the pattern matchers.
The signals flushed may be accessed
using SignalDetectorEvent.getSignalBuffer()
or SignalDetectorEvent.getSignalString().
If the flushed signals are not available,
then these methods return null.
This is conceptually equivalent to:
retrieveSignals((p_BufferSize), null, null, {p_Duration=0});
Note:
flushBuffer is also available using rtca_FlushBuffer.
flushBuffer in interface SignalDetectorMediaResourceException - if this request fails.
AccessControlExceptionResourceEventListener.onSignalDetectorEvent(SignalDetectorEvent)
public void performFaxLog(String caller,
String called,
int duration,
Date timeStamp)
performFaxLog in interface FaxLoggerIfpublic static void setFaxLogger(FaxLoggerIf listener)
The OC MP fax log can be set up externally on the command line, or by an Oclet, e.g..
These examples can be found at the end of the "/etc/opt/OC/ocmp/initOCMP.bsh" file (linux FSL) and in the "/opt/OC/tutorials/examples/oclets/hp/opencall/media/exampoclets/play/SimpleSend.java" tutorial.
Command line sample :
ocmpSh "source(\"/home/faxAppl/setFaxLogger\"); "Bean Shell code sample (so-called setFaxLogger file) :
defineFaxLogger( _faxlog ) {
hp.opencall.media.ccapi.AsyncMediaGroup.setFaxLogger( this );
performFaxLog(cp1,cp2,aDuration,aTimeStamp) {
String thatLog = aTimeStamp+", "+aDuration+" ms, "+cp1+" =--> "+cp2;
try{
//System.out.println(thatLog);
PrintStream logger = new PrintStream(new FileOutputStream(_faxlog,true));//append
//logger.println(thatLog);
logger.close();
} catch (java.io.FileNotFoundException e) {
e.printStackTrace();
}
}
String thatLog = _faxlog+" initialized on "+new Date();
PrintStream logger = new PrintStream(new FileOutputStream(_faxlog,true));//append
//logger.println(thatLog);
logger.close();
}
defineFaxLogger( "/tmp/bFaxLog.txt" );
This script sets up the method which will be called back each time a fax operation completes.
In this example, the name of the file is passed as a parameter.
The method calls that would make an uncontrolled file grow have been commented out.
Oclet Code sample:
final static String _faxlog = "/tmp/pFaxLog.txt" ;
FaxLoggerIf aFaxLogger = new FaxLoggerIf.FaxLoggerIf2() {
public void performFaxLog(String thatLog) {
try{
PrintStream logger = new PrintStream(new FileOutputStream(_faxlog,true));//append
logger.println(thatLog);
logger.close();
} catch (java.io.FileNotFoundException e) {
//e.printStackTrace();
}
}
public void addFaxLogEntry(String cp1,String cp2,int aDuration,String remoteId,int useCase,int pageNumber,int totalPageCount,int errorCode,Date aTimeStamp,int tac) {
String thatLog = aTimeStamp+", "+aDuration+" ms, "+cp1+", "+cp2
+", "+useCase+", "+errorCode+", "+tac
+", "+remoteId+", "+pageNumber+" / "+totalPageCount;
performFaxLog(thatLog);
}
public void performFaxLog(String cp1,String cp2,int aDuration,Date aTimeStamp) {
String thatLog = aTimeStamp+", "+aDuration+" ms, "+cp1+" =--> "+cp2;
//performFaxLog(thatLog);//will not be called because addFaxLogEntry() will be prefered.
}
};
AsyncMediaGroup.setFaxLogger(aFaxLogger);
The code above uses an extension of the FaxLoggerIf interface which allows additionnal information to be logged.
public void join(ConferenceIF confIF)
throws AccessControlException
Conference
Pre-conditions:
1. The configSpec used to build this AsyncMediaGroup is a userConferenceConfig ConfigSpec.
2. The CP looped to this MG must have been registered to this conference.
Post-conditions:
1. Media operations play & record are stopped and get a completion event with :
ResourceEvent.getQualifier() == ResourceEvent.q_Stop.
2. SignalDetection remains the only media operation possible.
3. To do other media operations (play, record..), a call to method unjoin(..) is necessary.
join in interface ConferenceAccessControlException
public void unjoin(ConferenceIF confIF)
throws AccessControlException
Conference
Pre-conditions:
1. The configSpec used to build this AsyncMediaGroup is a userConferenceConfig ConfigSpec.
2. The MG must have been previously joined to this conferenceIF.
unjoin in interface ConferenceAccessControlExceptionpublic void addResourceEventListener(