hp.telephony.media
Interface SignalDetector

All Superinterfaces:

Resource, ResourceConstants, SignalConstants, SignalDetectorConstants

All Known Implementing Classes:

AsyncMediaGroup

public interface SignalDetector

extends Resource, SignalDetectorConstants

Interface for detecting signals from the telephony network. The SignalDetector can:

• detect single DTMF signals
• optionally emit an event for each signal detected
• collect a sequence of signals into a buffer
• match or detect patterns in the signal buffer
• optionally emit an event for each pattern matched
• remove signals from the signal buffer when a pattern is matched
• remove all signals from the signal buffer
• emit RTC triggers for signal and pattern detection

The details of the processing a signal are explained in the Operation section.

Components of a SignalDetector

Conceptually, a SignalDetector has these components:

• a signal detector, that detects DTMF or other signals.
• a signal buffer, that holds some detected signals for later processing or analysis.
• a collection of pattern matchers, that identify particular sequences of signals, and generate RTC triggers and events.

SignalDetector states

IDLE<==>DETECTING.

In the DETECTING state, the SignalDetector listens for and identifies any of the defined DTMF and FAX signals. The SignalDetector state is controlled by the parameter p_Mode. By default, the value of p_Mode equals v_Detecting, and the SignalDetector is in the DETECTING state.

In addition to the basic detection of signals controlled by p_Mode, the pattern matchers (each individually) are either enabled or disabled. A pattern matcher is enabled when it is used (for any of):

• to terminate retrieveSignals,
• trigger any RTCs
• filter the signal buffer, or
• generate a SignalDetectorEvent for SignalDetectorListeners
.

Parameters

Many operations of the SignalDetector are controlled by setting various parameters, using setParameters(). The relevant parameter Symbols are named SignalDetector.p_Something. The Symbols used to name parameters and other SignalDetector constants are defined in the SignalDetectorConstants interface.

Pattern matchers

The value of the read-only parameter p_PatternCount indicates the number of pattern matchers available, and the number of patterns that can be defined. The default value is 32. If the signal detector is not capable of pattern matching, then the value is zero. An application can request a minimum number of pattern matchers using the attribute a_PatternCount, which default is also 32.

The format of the Strings that define a Pattern are described below.

Note: Each of the 32 pattern matchers has an assigned Symbol. That symbol identifies the pattern as an event, as a parameter, as a qualifier or as a RTC trigger. Pattern Symbols may be designated by any of their names; the Pattern Symbol arrays

• Symbol[] ev_Pattern
• Symbol[] p_Pattern
• Symbol[] q_Pattern
• Symbol[] rtcc_Pattern

are identical.

Event delivery

Event delivery is controlled by the parameter p_EnabledEvents, the value of which is a array of event Symbols identifying the events that are sent from the SignalDetector to the ResourceEventListener.

The events that are controlled by p_EnabledEvents and onSignalDetectorEvent() method is called with :

Event

ev_SignalDetected

ev_Pattern[i]

ev_Overflow

Note: p_EnabledEvents controls the delivery of events to Listeners. The detection of signals, buffering, and pattern matching for RTC is independent of event delivery; detection is controlled by p_Mode and is (generally) always enabled.

RTC triggers

The SignalDetector supports RTC triggers for:

• rtcc_FlushBuffer
• rtcc_SignalDetected
• rtcc_RetrieveSignals
• rtcc_Pattern[i] (the pattern Symbols)

The SignalDetector triggers an RTC action (for example, to affect a play() or record()), only if the pattern is defined before requesting the RTC (that is, before doing the play() or record()). The SignalDetector does not properly "arm" an rtcc_Pattern[i] unless the p_Pattern[i] definition is already set.

Signal buffer

When individual signals are detected (and the value of p_Buffering is true), the signals are stored in the signal buffer. Signals are kept in the signal buffer until they are removed by one of

• retrieveSignals(),
• flushBuffer(),
• pattern filtering, or
• signal buffer overflow.

retrieveSignals: retrieveSignals(numSignals, ...) waits for any of the various terminating conditions and then removes and returns up to numSignals signals from the signal buffer.

flushBuffer: flushBuffer() succeeds immediately and removes all signals from the buffer.

Retrieving or flushing signals means those signals are no longer used for matching patterns.

Filtering: If a pattern is matched and that pattern Symbol appears in the value of p_Filter, then the signals that matched the pattern are removed from the signal buffer. Pattern matching is explained below.

Overflow: The length of the signal buffer is available as the value of the read-only parameter p_BufferSize, and is at least 35 (long enough to hold any international telephone number). Applications can request support for a longer buffer using the attribute a_BufferSize.

If p_BufferSize signals are in the signal buffer then the next signal causes overflow. Overflow processing is explained below.

Note: When a signal is removed from the signal buffer, it is delivered to the application in the associated event. A signal appears in at most one such event. In addition to being in a buffer removal event, a signal may appear in at most one pattern matched event.

Operation

When the signal detector detects a signal, the processing is as follows:

1. if p_Buffering is true, then the signal is added to the signal buffer.
2. rtcc_SignalDetected triggers any applicable RTCs.
3. if p_EnabledEvents contains ev_SignalDetected, then SignalDetectorListener.onSignalDetected(event) is invoked
4. if the signal buffer overflows then overflow processing is done.
5. if pattern matchers are enabled, then pattern matching is done.
6. retrieveSignals may be terminated by a pattern match.
7. the NumSignals signal counter is incremented and retrieveSignals may be terminated with q_NumSignals.

Overflow processing

If the signal buffer contains p_BufferSize signals, then the next signal causes overflow.

When overflow occurs, some signal must be discarded. The Boolean value of parameter p_DiscardOldest indicates whether the oldest signal should be removed from the signal buffer and discarded, or whether the current, new signal should be discarded. Signals that are discarded are included in the ev_Overflow event, but are not included in the signal buffer returned by retrieveSignals().

When the signal buffer overflows, the processing is as follows:

1. if the value of p_DiscardOldest is true, then the oldest signal is discarded.
2. if the value of p_DiscardOldest is false, then the current signal is discarded.
3. if the value of p_EnabledEvents contains the symbol ev_Overflow, then onSignalDetectorEvent() is invoked and the event contains the discarded signal.

Note: even if the current signal is discarded from the signal buffer, it is still used for pattern matching. However, if pattern matching is enabled after a signal has been discarded, it is not used to initialize the pattern matchers.

Pattern matching

A pattern matcher is enabled when its pattern Symbol is used in any of these ways:

• as an RTC trigger in an active resource method,
• in p_EnabledEvents, or
• as a terminating condition in retrieveSignals() (that is, it appears in the patterns argument).

When pattern matchers becomes enabled, the processing is as follows:

1. Each signal in the signal buffer is passed in turn to the [newly enabled or re-enabled] pattern matcher(s).
2. After the signal buffer has been processed, any newly detected signals are passed in turn to [all] the pattern matcher(s).
3. When pattern[i] is matched, then do 4-8:
4. RTC trigger rtcc_pattern[i] is generated
5. If the value of p_EnabledEvents contains ev_Pattern[i] then onPatternMatched(event) is invoked on all SignalDetectorListeners, and the event contains the signals that matched the pattern.
6. If the value of p_Filter contains p_Pattern[i] then the matching signals are removed from the signal buffer.
7. If the value of the patterns argument to retrieveSignals contains p_Pattern[i] then retrieveSignals terminates with qualifier q_Pattern[i] and returns the current contents of the signal buffer.
8. All pattern matchers are reset to their intial, no input state, and continue processing the signals that are passed in.

Then intent of step 1 is that the new matchers match any patterns as if they had been enabled before the signals entered the buffer. The application should use filters and flushBuffer carefully to get the desired effects.

The intent of step 8 is to ensure that one sequence of signals does not complete a match in two Patterns. If two patterns are enabled that would match the same input, the lower numbered pattern matcher succeeds and the other is reset.

Format of Strings that define a Pattern

Pattern definitions are Strings of the form:
{ [{count}] signal | [{count}] [signals] }*

{ count } specifies an optional repeat count. If not specifed count is 1, otherwise it is some decimal number.
signal names a (DTMF) signal to be detected, one of: 0,1,2,3,4,5,6,7,8,9,*,#,A,B,C,D,CNG,CED,?.
[ signals ] is a space separated list of signal names, that specifies a set of equivalent or alternative signals to be detected. For example: [0 1 2 3] matches any one of the given four signals.
signal == `?` matches any single signal.

The pattern matches a sequence of count occurences of a specified signal, or count occurences of any of the named signals.

The Pattern parameters can be set with setParameters or in the optargs argument of retrieveSignals. Each pattern String is set as the value of one of the pattern parameter symbols (p_Pattern[i]).

Example: define some patterns

 dict.put(p_Pattern[1], "[1 2 3 4]");  // valid menu choices
 dict.put(p_Pattern[2], "[5 6 8 9]");  // invalid menu choices
 dict.put(p_Pattern[3], "0");          // route to live operator
 dict.put(p_Pattern[4], "{2} #");      // ## hangup
 dict.put(p_Pattern[5], "{12} [0 1 2 3 4 5 6 7 8 9]"); // Accnt number 
 setParameters(dict);

Example: enable patterns for event callbacks:

 Symbol[] patternSetOne = {p_Pattern[1], p_Pattern[2], p_Pattern[3]};
 dict.put(SignalDetector.p_EnabledEvents, patternSetOne);
 setParameters(dict);

Example: enable patterns and wait for a match:

 Symbol[] patternSetTwo = {p_Pattern[3], p_Pattern[4]};
 sigDetEvent = retrieveSignals(-1, patternSetTwo, null, null);

For an extensive example, see AnswerPhone.java

Since:

OCMP 2.0

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.SignalDetectorConstants

a_Buffering, a_BufferSize, a_DiscardOldest, a_PatternCount, ev_FlushBuffer, ev_Overflow, ev_Pattern, ev_RetrieveSignals, ev_SignalDetected, p_Buffering, p_BufferSize, p_DiscardOldest, p_DtmfDetectorMode, p_Duration, p_EnabledEvents, p_Filter, p_InitialTimeout, p_InterSigTimeout, p_Mode, p_Pattern, p_PatternCount, q_Duration, q_InitialTimeout, q_InterSigTimeout, q_NumSignals, q_Pattern, rtca_DetectFaxCallingTone, rtca_EvalBuffer, rtca_FlushBuffer, rtca_IgnoreFaxCallingTone, rtca_PassSignalsThru, rtca_Stop, rtca_TruncateSignals, rtcc_FlushBuffer, rtcc_Pattern, rtcc_RetrieveSignals, rtcc_SignalDetected, v_Detecting, v_Idle

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

Method Summary

void	flushBuffer() Remove all signals from the signal buffer.
void	retrieveSignals(int numSignals, Symbol[] patterns, RTC[] rtc, Dictionary optargs) Retrieve some signals from the signal buffer.

Method Detail

retrieveSignals

public void retrieveSignals(int numSignals,
                            Symbol[] patterns,
                            RTC[] rtc,
                            Dictionary optargs)
                     throws MediaResourceException,
                            AccessControlException

Retrieve some signals from the signal buffer. This method returns when numSignals 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.

Parameters:

numSignals - 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.

Returns:

a SignalDetectorEvent, suitable for for getSignalBuffer().

Throws:

MediaResourceException - if this request fails; usually because of a badly formed request, or implementation cannot process the request.

AccessControlException

See Also:

ResourceEventListener.onSignalDetectorEvent(SignalDetectorEvent)

flushBuffer

public void flushBuffer()
                 throws MediaResourceException,
                        AccessControlException

Remove all signals from the signal buffer.

This 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.

Returns:

a SignalDetectorEvent containing any signals flushed.

Throws:

MediaResourceException - if this request fails.

AccessControlException

See Also:

ResourceEventListener.onSignalDetectorEvent(SignalDetectorEvent)