ISpSREngineSite::GetStateInfo
Other versions of this page are also available for the following:
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/28/2008
This method gets information on the transitions from a CFG state. The SR engine calls the method to find out the full contents of the rule. This can be done immediately on receiving a ISpSREngine::RuleNotify call about a rule, or later during recognition.
The engine passes into this method a handle to a state for the rule, starting with the initial state. The engine also calls this method with a pointer to an SPSTATEINFO structure, with all its members set to zero. During processing, the method fills in the structure with information on all the transitions out of the provided state, using an array allocated by SAPI using CoTaskMemAlloc.
To get information about all the states in the rule, the engine repeats its call to GetStateInfo for each state following the current state. Since loop-back transitions are possible in a rule, the engine needs to check to see if it has visited a state before.
When the engine calls GetStateInfo after the first time, it can leave the cAllocatedEntries and pTransitions members of SPSTATEINFO unchanged from the last call. SAPI then reuses the memory from the transition array if possible, rather that reallocating it. Alternatively, the engine can use CoTaskMemFree to free the memory for the transition array, and set cAllocatedEntries and pTransitions to NULL so that SAPI will reallocate the memory for each subsequent call.
Syntax
HRESULT GetStateInfo(
SPSTATEHANDLE hState,
SPSTATEINFO* pStateInfo
);
Parameters
- hState
[in] Handle to the current CFG state.
- pStateInfo
[in, out] Pointer to an SPSTATEINFO structure. On input, all members of the structure are set to zero. On output, the structure contains the retrieved state information.
Return Value
The following table shows the possible return values.
| Value | Description |
|---|---|
S_OK |
Function completed successfully. |
E_POINTER |
Either pStateInfo or pTransitions in the SPSTATEINFO structurepoints to invalid memory. |
E_OUTOFMEMORY |
Not enough memory to complete the operation. |
SPERR_INVALID_HANDLE |
Invalid hState parameter. |
FAILED(hr) |
Appropriate error message. |
Remarks
Each transition represents a link from one state to another state. A transition is represented by an SPTRANSITIONENTRY structure. This structure contains an identifier that uniquely identifies the transition, a handle that shows the state to which the transition is connected, and a type for the transition.
There are three common types of transition that all engines should support: word transitions, rule transitions, and epsilon transitions. There are also special transitions that may not be supported by all engines. All transition types are defined by the SPTRANSITIONTYPE enumeration.
Requirements
| Header | sapiddk.h, sapiddk.idl |
| Library | sapilib.lib |
| Windows Embedded CE | Windows CE .NET 4.1 and later |