ISpRecoContext::SetAdaptationData
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 sends string data to the SR engine to update the current language model.
Syntax
HRESULT SetAdaptationData(
const WCHAR* pAdaptationData,
const ULONG cch
);
Parameters
- pAdaptationData
[in] Pointer to data to use in the update.
- cch
[in] Number of characters in the data specified by pAdaptationData.
Return Value
The following table shows the possible return values.
| Value | Description |
|---|---|
S_OK |
Function completed successfully. |
E_INVALIDARG |
pAdaptationData is invalid or cch equals zero. |
E_OUTOFMEMORY |
Exceeded available memory. |
SPERR_SR_ENGINE_EXCEPTION |
An exception was thrown by the SR engine during ISpSREngine::SetAdaptationData. |
FAILED(hr) |
Appropriate error message. |
Remarks
An application that wants to improve recognition accuracy for dictating uncommon words, or uncommon word groupings, can train the SR engine for the new words, or word groupings, by creating or obtaining typical text and send the results to the engine using SetAdaptationData.
For example, a word processing application can give users the ability to train its users on previously created text documents. Similarly, an email or collaboration application could train the SR engine on previously sent email or collaborated documents. After training, the SR engine could improve performance within specific domains of information, and improve the application's and SAPI's personalization experience.
The SAPI middleware component (and Microsoft) do not store this information - instead it is passed directly to the SR engine using ISpSREngine::SetAdaptationData. Note also that the SR engine (vendor) decides what to do with the string data, including how the data is persisted and for how long. Some SR engines may require a nontrivial amount of time to process the string data, so the application may want to break up the data in smaller chunks to send individually.
Applications that use SetAdaptationData should break the data into small (1K or less) blocks, call SetAdaptationData, and then wait for an SPEI_ADAPTATION event before sending the next small block of data. This method should not be used with large buffers, because calling SetAdaptationData with buffers larger than 32K can cause unpredictable results.
When the SR engine is ready to receive more string data to adapt its language model, it can fire the SPEI_ADAPTATION event to the application.
Example
The following code snippet illustrates the use of this method.
HRESULT hr = S_OK;
// get the "training" data, and break it into manageable chunks
//[for example, an array of strings]
// ...
// set interest in the adaptation event
hr = cpRecoContext->SetInterest(SPFEI(SPEI_ADAPTATION),
SPFEI(SPEI_ADAPTATION));
// Check hr
// adapt to each chunk of data
for (int i = 0; i < iCountOfDataChunk; i ++)
{
// send each chunk of data the engine
hr = cpRecoContext->SetAdaptationData(ppwszAdaptationData[i],
wcslen(ppwszAdaptationData[i]));
// Check hr
// wait for the engine to ask for more data
hr = cpRecoContext->WaitForNotifyEvent(PROCESSING_WAIT_TIME);
// Check hr
}
// SR Engine has adaptated its language model to data
Requirements
| Header | sapi.h, sapi.idl |
| Library | sapilib.lib |
| Windows Embedded CE | Windows CE .NET 4.1 and later |