javax.telephony.media
Interface SignalDetector

All Superinterfaces:

MediaConstants, Resource, ResourceConstants, SignalConstants, SignalDetectorConstants

All Known Implementing Classes:

BasicMediaService

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 activated or deactivated. A pattern matcher is activated when its pattern Symbol is used in any of the following ways:

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

Note: the pattern stays activated while the condition(s) that activated it remain in effect, then it is deactivated.

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

The events that are controlled by p_EnabledEvents and the respective SignalDetectorListener methods are:

Event	Method
ev_SignalDetected	onSignalDetected
ev_Pattern[i]	onPatternMatched
ev_Overflow	onOverflow

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 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. All pattern matchers are reset.

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 a follows:

1. rtcc_SignalDetected triggers any applicable RTCs.
2. if p_EnabledEvents contains ev_SignalDetected, then SignalDetectorListener.onSignalDetected(event) is invoked
3. if p_Buffering is true, then the signal is added to the signal buffer.
4. if the signal buffer overflows then overflow processing is done.
5. if pattern matchers are activated, then pattern matching is done: the newly detected signal is passed to each activated pattern matcher.
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 onOverflow(event) 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 activated after a signal has been discarded, that discarded signal is not used to initialize the pattern matchers.

Pattern matching

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

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

When a pattern matcher is activated by one of the contitions above, it is initialized by scanning the current signal buffer contents. This may generate one or more pattern matching events.

• Each signal in the signal buffer is passed in turn to the [newly activated] pattern matcher(s).

Note: This procedure is called scanning the buffer. Then intent of scanning is that the new pattern matchers match patterns as if the matcher had been activated before the signals entered the buffer. This step is to handle any typeahead that may have come before before the pattern(s) were activated. A pattern matcher scans the buffer only when it is newly activated. The application should use p_Filter and flushBuffer carefully to get the desired effects.

When a signal is passed to a pattern matcher, this procedure is followed:

1. If the signal contributes to a match for this pattern matcher, then the patterm matching state machine is advanced to record that.
2. If the signal does not contribute to a match for this pattern matcher, then the pattern matching state machine resets to record that.
3. If the signal brings the pattern matcher for pattern[i] to its matched state, then then do 4-8:
4. If this pattern is activated as an RTC trigger, then 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 and all pattern matchers are reset to their initial (no input) state and this signal is not considered by subsequent pattern matchers.
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.

Note: The intent of step 6 is to ensure that a sequence of signals that is filtered does not contribute to a match in subsequent Patterns. "subsequent" means patterns with index greater than [i].

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:

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.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_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_FlushBuffer, rtca_Stop, rtcc_FlushBuffer, rtcc_Pattern, rtcc_RetrieveSignals, rtcc_SignalDetected, v_Class, v_Detecting, v_Idle

Fields inherited from interface javax.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_DTMFStar, v_Unknown

Method Summary

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

Method Detail

retrieveSignals

public SignalDetectorEvent retrieveSignals(int numSignals,
                                           Symbol[] patterns,
                                           RTC[] rtc,
                                           java.util.Dictionary optargs)
                                    throws MediaResourceException

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 onPatternMatched 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 requested operation fails.

flushBuffer

public SignalDetectorEvent flushBuffer()
                                throws MediaResourceException

Remove all signals from the signal buffer.

This prevents buffer overflow, and synchronizes the pattern matchers.

The signals flushed may be accessed using Event.getSignalBuffer() or Event.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});
but flushBuffer() also resets all the pattern matchers.

Note: flushBuffer is also available using rtca_FlushBuffer.

Returns:

a SignalDetectorEvent containing any signals flushed.

Throws:

MediaResourceException - if requested operation fails.