ISpSREngineSite::GetStateInfo (SAPI 5.4)

  • Article

Microsoft Speech API 5.4

ISpSREngineSite::GetStateInfo

ISpSREngineSite::GetStateInfo retrieves information on the transitions from a CFG state.

  
    HRESULT GetStateInfo(
   SPSTATEHANDLE   hState,
SPSTATEINFO    *pStateInfo
);

Parameters

  • hState
    [in] Handle to the current state.
  • pStateInfo
    [out] The state information.

Return values

Value
S_OK
E_POINTER
E_OUTOFMEMORY
SPERR_INVALID_HANDLE
FAILED (hr)

Remarks

This method is called so that the SR engine can discern the full contents of the rule. GetStateInfo can be called immediately upon receiving a ISpSREngine::RuleNotify call about a rule, or later during recognition. This method supplies information about all the subsequent states from any given state.

The engine passes this method a state handle (starting with the hInitialState of the rule), and a pointer to an SPSTATEINFO structure with all its fields initially zeroed. This structure is filled out with information on all of the transitions out of that state in the pTransitions array. SAPI uses CoTaskMemAlloc to allocate this array. The engine can call this method again on each of the states following the current state, and so on, in order to get information about all of the states in the rule. Loop-back transitions are possible in a rule and the engine may need to confirm that it has not visited the state before.

When the engine calls GetStateInfo subsequent times, it can call it with the cAllocatedEntries and pTransitions fields unchanged from the last call. If possible, SAPI will then re-use the memory from the transition array rather that re-allocating it. Alternatively, the engine can use CoTaskMemFree to free the pTransitions memory, set these fields to NULL and SAPI will re-allocate the memory every time.

Each transition represents a link from one state to another state. Each transition is represented by an SPTRANSITIONENTRY structure. This structure contains an ID field that uniquely identifies the transition, an hNextState handle that indicates the state the transition is connected to, and a Type field that indicates the type of transition.

There are three common types of transition, which all engines should support:

  • Word transitions (SPTRANSWORD). These represent single words that the recognizer will recognize before advancing to the next state. The handle to the word and the engine's word pointer are supplied inside the SPTRANSITIONENTRY structure. To produce recognition results, the engine needs to keep track of the transition IDs of word transitions as they are used in the ParseFromTransitions method.
  • Rule transitions (SPTRANSRULE). These represent transitions into sub-rules. This transition is only passed when a path through the sub-rule has been recognized. The rule handle, engine's rule pointer and initial state of the sub-rule are supplied. Rules can be recursive (not left recursive).
  • Epsilon transitions (SPTRANSEPSILON). These are NULL transitions that can be traversed without recognizing anything.

A state that has a transition to a null state handle indicates the end of a rule. There can also be 'void' states, which block and indicate that there is no recognition path from this state. A void state has zero transitions out of it.

There are also a number of special transitions, which may not be supported by all engines.

See the SR Engine Guide document for more information on CFG grammars.