NAME
irInitRecog, irInitRecog2, irInitAllRecog,
irStartRecog, irStartRecog2,
irStopRecog, irStopRecog2, irStopAllRecog,
irCheckRecog, irCheckRecog2, irCheckAnyRecogOn, irCheckAllRecogOff,
initialize, start, stop, check state of speech recognizer
for channel
SYNOPSIS
#include <irapi.h>
int irInitRecog (channel_id cid);
int irInitRecog2 (channel_id cid, int recog_type);
int irInitAllRecog (channel_id cid);
int irStartRecog (channel_id cid, int tag);
int irStartRecog2 (channel_id cid, int tag, int recog_type,
int recog_grammar);
int irStopRecog (channel_id cid);
int irStopRecog2 (channel_id cid, int recog_type);
int irStopAllRecog (channel_id cid);
int irCheckRecog (channel_id cid);
int irCheckRecog2 (channel_id cid, int recog_type);
int irCheckAnyRecogOn (channel_id cid);
int irCheckAllRecogOff (channel_id cid);
DESCRIPTION
The irInitRecog function initializes speech recognizer
parameters for cid. Parameter IRP_RECOG_TYPE, set and
accessed via irSetParam and irGetParam, determine the recog-
nizer parameters to initialize. For the Dial Pulse recog-
nizer, adaptive learning parameters are reset when the
recognizer is initialized.
The irInitRecog2 function is identical to irInitRecog except
the argument recog_type determines the recognizer to ini-
tialize instead of the parameter IRP_RECOG_TYPE.
The irInitAllRecog function initializes recognizer parame-
ters for all recognizer types currently configured for the
channel.
The irStartRecog function starts speech recognition for cid.
Parameters IRP_RECOG_TYPE and IRP_RECOG_GRAMMAR, set and
accessed via irSetParam and irGetParam, determine the type
of recognition and the specific grammar for the recognition
type. See IrPARAMETERS(4IRAPI). The IRP_RECOG_TYPE parame-
ter may be set to IRD_WHOLE_WORD, IRD_FLEX_WORD, or
IRD_DIALPULSE. The IRP_RECOG_GRAMMAR parameter depends on
the recognition type. Valid values are defined in the file
/att/include/sr_grammar.h
Parameters IRP_RECOG_PRETIME and IRP_RECOG_INTERTIME, set
and accessed via irSetParam and irGetParam, determine the
number of milliseconds to wait for initial and intermediate
timeout respectively.
tag is returned to the application through the subsequent
IRE_GRANT or IRE_DENY events, on delayed resource alloca-
tion, or through the IRE_INPUT_DONE and IRE_RECOGNIZING
events associated with the recognition.
Note that speech recognition uses the IRE_INPUT_DONE event
rather than the IRE_INPUT event since speech recognizers do
not provide continuous input as touch-tone recognizers do.
Once the speech recognizer provides input, it is finished
and must be restarted for subsequent recognitions.
Note that Dial Pulse Recognizer uses the IRE_RECOGNIZING
event as well as the IRE_INPUT_DONE event. The
IRE_RECOGNIZING event indicates that the Dial Pulse Recog-
nizer has seen valid dial pulse input but it has not com-
pleted recognition. This event can be used in the following
way, suppose multiple recognizers are run simultaneously,
e.g., Dial Pulse and speech recognition. When the applica-
tion receives the IRE_RECOGNIZING event the application can
turn off non-Dial Pulse recognition and let Dial Pulse
Recognition continue. The speech recognizers do not return
the IRE_RECOGNIZING event. Alternatively, suppose both Dial
Pulse recognition and a speech recognition are running. If
either recognizer returns a timeout then that recognizer may
be stopped and the remaining recognizers should be allowed
to continue running since they may be receiving valid input.
The irStartRecog2 function is identical to irStartRecog
except the arguments recog_type and recog_grammar determine
the type of recognition and the specific grammar for the
recognition type.
The irStopRecog function stops speech recognition for cid.
Parameter IRP_RECOG_TYPE, set and accessed via irSetParam
and irGetParam, determine the recognizer to stop. A recog-
nizer started with irStartRecog2 cannot be stopped with
irStopRecog unless the IRP_RECOG_TYPE parameter is set to
match the recog_type parameter passed in to irStartRecog2.
The irStopRecog2 function is identical to irStopRecog except
the argument recog_type determines the type of recognizer to
stop.
The irStopAllRecog function stops all speech recognizers for
cid. All started recognizers are stopped.
EVENT
If resources are not available when irStartRecog is called
an IRE_INPUT_DONE event is generated with the 3rd event modifier
set to IRER_RESOURCEBUSY.
When recognition completes, an IRE_INPUT_DONE event is gen-
erated. See irRecogTimer(3IRAPI). The recognizer is
automatically turned off after receiving the IRE_INPUT_DONE
event.
No event results from the call to irStopRecog or
irCheckRecog.
RETURN VALUE
For irStartRecog, the following return codes are possible:
IRR_OK if the request is successful
IRR_FAIL if an error occurs
For irStopRecog, the following return codes are possible:
IRR_OK if the request to stop speech recognition is success-
ful
IRR_FAIL if an error occurs
For irCheckRecog, the following return codes are possible:
IRR_ON if recognition is on for the recognizer type given by
parameter IRP_RECOG_TYPE.
IRR_OFF if recognition is off for the recognizer type given
by parameter IRP_RECOG_TYPE.
The irCheckRecog2 function is identical to irCheckRecog
except the argument recog_type is used instead of the param-
eter IRP_RECOG_TYPE.
The irCheckAnyRecogOn function returns IRD_TRUE if any
recognizer is turned on, IRD_FALSE otherwise.
The irCheckAllRecogOff function returns IRD_TRUE if all
recognizers are turned off, IRD_FALSE otherwise.
For irInitRecog IRR_OK is returned on success and IRR_FAIL
is returned on error.
ERROR
irError is set as follows if an error occurs:
IRER_INVALID if the cid is invalid
IRER_RTU_BUSY if the required Feature License's are all in
use and IRP_RESOURCE_RETURNMODE is set to IRD_IMMEDIATE
IRER_NO_RTU if no Feature License has been purchased for
this function
IRER_RESOURCEBUSY if there are no resources available
IRER_SYSERROR if a system or driver call failure occurs
(check irSysError for additional information)
IRER_BADSTATE if the cid is not in the IRS_IDLE,
IRS_PLAY_QUEUED or IRS_SAY_QUEUED library state
IRER_INVALID if an operation on an unstarted recognizer is
attempted.
IRER_REDUNDANT if starting an already started recognizer.
SEE ALSO
irEcho(3IRAPI), irRecogTimer(3IRAPI), irDynGram(3IRAPI),
IrPARAMETERS(4IRAPI), IrDEFINES(4IRAPI), IrEVENTS(4IRAPI)
VERSION
This is version 11/7/02 of this man page.