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,
} 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 and call-progress tones as well as ASR vocabulary words, and Only on Prosody version 1: pulse dialled digits.
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). If the band 2 set of frequencies is empty in the active tone set then param1 should be ignored).
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 = band-1-input-frequency-index + 256 * band-2-input-frequency-index
and param1 will contain the duration in milliseconds of the detected tone (granularity of 32 mS).
If the type returned is kSMRecognisedCPTone, then in order for the same call-progress tone to be recognised as the next recognised call-progress tone sm_listen_for() must be re-invoked. For example, if you are listening for both ringing and busy, and a ringing signal is being received, then ringing will be reported. It cannot then be reported again, even if the incoming ringing signal keeps repeating, though if it changes to a busy signal, that will be reported.
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.
In order to poll all input channels, an application should call
sm_get_recognised()
with
channel
set to kSMNullChannelId. On return, if any input
channel has a recognition result to report,
channel
will be set to an identifier indicating one such channel and the
other parameters will be set as above to report the result for
that channel. If no item was recognised
on any allocated channel running speech processing firmware,
channel
will remain set to kSMNullChannelId and the call
will return ERR_SM_NO_SUCH_CHANNEL.
Application
writers should bear in mind the fact that if this call is
invoked when no speech processing firmware hosted channels are
allocated at the time of the call,
sm_get_recognised()
will return an error code ERR_SM_NO_SUCH_CHANNEL.
kSMNullChannelId, the only channels which can
be indicated as being ready are those which have been
registered for 'any channel' recognition operation using
sm_channel_set_event()
See Prosody TiNG: any channel operation
for how to do this.
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.