int sm_get_recognised(struct sm_recognised_parms *recogp)
typedef struct sm_recognised_parms {
tSMChannelId channel; /* inout */
enum kSMRecognition {
kSMRecognisedNothing,
kSMRecognisedTrainingDigit,
kSMRecognisedDigit,
kSMRecognisedTone,
kSMRecognisedCPTone,
kSMRecognisedGruntStart,
kSMRecognisedGruntEnd,
kSMRecognisedASRResult,
kSMRecognisedASRUncertain,
kSMRecognisedASRRejected,
kSMRecognisedASRTimeout,
kSMRecognisedCatSig,
kSMRecognisedOverrun,
kSMRecognisedANS,
kSMRecognisedBeep,
kSMRecognisedOnHook,
} type; /* out */
tSM_INT param0; /* out */
tSM_INT param1; /* out */
} SM_RECOGNISED_PARMS;
This call, typically invoked in response to a recognition event being signalled, allows an application to determine what item, if any, was detected. This includes simple tones, call-progress tones and grunts.
In order to poll a specific input channel, the application should set channel to specify the input channel concerned. On successful completion, the type parameter will have been set to indicate the status of detections on that channel.
If the type returned is kSMRecognisedTone, then param0 and param1 may be used to determine the two component frequencies that together made up the recognised simple tone. Normally param0 will be the zero based index into the set of band 1 frequencies of the active tone set, and param1 will be the zero based index into the set of band 2 frequencies of the active tone set (e.g. if there are 4 frequencies in band 1 for the active tone set, param0 may have any value between 0 and 3, note it does not reflect the actual id for the input frequency, just its offset in the enumerated band 1 set of input frequencies).
When the band 2 set of frequencies is empty in the active tone set then param1 will be the zero based index into the set of band 1 frequencies of the active tone set, and param0 will be zero.
However if a tone detection mode of type
kSMToneLen... was specified in
sm_listen_for()
then
param0
will contain identifiers for the two component
frequencies packed into a single integer as follows:
param0 = normal-param0 + 256 * normal-param1
and param1 will contain the duration in milliseconds of the detected tone (granularity of 32 mS).
If the type returned is kSMRecognisedCPTone, then no part of the call-progress tone being reported can be recognised as part of a later call-progress tone, but any signal after the call-progress tone will be analysed and may trigger recognition of another call-progress tone. For example, if a ringing signal is being received, and this matches a cadence in the call-progress table, then each complete cadence of ringing received will be reported as a separate call-progress tone.
This function can also be used for 'any channel' operation. This mode of operation is a legacy feature and is not recommended for new applications. See Prosody TiNG: any channel operation for more details.
This function may report that nothing has been detected even if a wait done on an event associated with this channel has woken up. This is because sm_get_recognised() has decided that, although something happened, it was not one of the events which is 'interesting'. This is typically noticed when tone detection has been enabled, which will wake the event periodically (between about once per second to once per minute) to keep the library informed of the channel status. These extra wakeups only cause a tone to be reported if the current status is that a continuous tone is being received and this matches a tone with unlimited duration.
kSMPulseDigits or
kSMDTMFDigits) unless a tone detection mode
of type kSMToneLen... was specified in
which case it will contain the duration in milliseconds
of the detected DTMF digit.
0 if call completed successfully, otherwise a standard error such as:
This function is part of the Prosody speech processing API.