ISpRecoContext::SetAdaptationData
ISpRecoContext::SetAdaptationData passes a block of text to the SR engine which can be used to adapt the active language models.
HRESULT SetAdaptationData(
LPCWSTR *pAdaptationData,
const ULONG cch
);
Parameters
- pAdaptationData
- [in] The string to adapt.
- cch
- [in] The number of characters in pAdaptationData.
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. |
| FAILED(hr) | Appropriate error message. |
Remarks
An application can improve recognition accuracy for dictating uncommon words, or uncommon word groupings, by training 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 train the engine on previously created text documents. Similarly, an e-mail or collaboration application could train the SR engine on previously sent e-mail or collaborated documents. After training, the SR engine could perform better 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. The SR engine (vendor) determines what to do with the string data, including how the data is persisted and for how long. Some SR engines may require a significant 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. Passing a large string in pAdaptationData to this method 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 ISpRecoContext::SetAdaptationData.
// Declare local identifiers:
HRESULT hr = S_OK;
CComPtr<ISpRecoContext> cpRecoContext;
USHORT iCountOfDataChunk = 0;
WCHAR *ppwszAdaptationData[5];
const USHORT PROCESSING_WAIT_TIME = 500;
// Get "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));
if (SUCCEEDED(hr))
{
// Adapting to each chunk of data--
for (int i = 0; i < iCountOfDataChunk; i ++)
{
// Send each chunk of data to the engine.
hr = cpRecoContext->SetAdaptationData(ppwszAdaptationData[i], wcslen(ppwszAdaptationData[i]));
if (SUCCEEDED(hr))
{
// Wait for the engine to ask for more data.
hr = cpRecoContext->WaitForNotifyEvent(PROCESSING_WAIT_TIME);
if (SUCCEEDED(hr))
{
}
}
}
// SR Engine has adapted its language model to data.
}