Required Recognition APIs
Required Recognition APIs |
Description of API functions that are required when implementing your own recognizer.
The following list shows the C-style API functions. These functions are logically grouped under four recognizer handles:
You must include Recapis.h (installed by default in C:\Program Files\Microsoft Tablet PC Platform SDK\Include). Except where noted, your dynamic-link library (DLL) must export all of the API functions, even if you choose to have some of them return E_NOTIMPL.
The following declarations and comments are included in the Recapis.h file.
////////////////////////
// HRECOGNIZER
////////////////////////
HRESULT WINAPI CreateRecognizer(CLSID *pCLSID, HRECOGNIZER *phrec);
HRESULT WINAPI DestroyRecognizer(HRECOGNIZER hrec);
HRESULT WINAPI GetRecoAttributes(HRECOGNIZER hrec, RECO_ATTRS *pRecoAttrs);
HRESULT WINAPI CreateContext(HRECOGNIZER hrec, HRECOCONTEXT *phrc);
HRESULT WINAPI DestroyContext(HRECOCONTEXT hrc);
HRESULT WINAPI GetResultPropertyList(HRECOGNIZER hrec, ULONG *pPropertyCount, GUID *pPropertyGuid);
HRESULT WINAPI GetPreferredPacketDescription(HRECOGNIZER hrec, PACKET_DESCRIPTION *pPacketDescription);
//The GetUnicodeRanges function is optional for application recognizers.
HRESULT WINAPI GetUnicodeRanges(HRECOGNIZER hrec, ULONG *pcRanges, CHARACTER_RANGE *pcr);
////////////////////////
// HRECOCONTEXT
////////////////////////
HRESULT WINAPI AddStroke(HRECOCONTEXT hrc, const PACKET_DESCRIPTION *pPacketDesc, ULONG cbPacket, const BYTE *pPacket, const XFORM *pXForm);
//The IsStringSupported function is optional for application recognizers.
HRESULT WINAPI IsStringSupported(HRECOCONTEXT hrc, ULONG wcString, const WCHAR *pwcString)
HRESULT WINAPI GetBestResultString(HRECOCONTEXT hrc, ULONG *pcSize, WCHAR *pwcBestResult);
HRESULT WINAPI GetBestAlternate(HRECOCONTEXT hrc, HRECOALT *pHrcAlt);
HRESULT WINAPI DestroyAlternate(HRECOALT hrcalt);
HRESULT WINAPI SetGuide(HRECOCONTEXT hrc, const RECO_GUIDE *pGuide, ULONG iIndex);
HRESULT WINAPI GetGuide(HRECOCONTEXT hrc, RECO_GUIDE *pGuide, ULONG *piIndex);
HRESULT WINAPI AdviseInkChange(HRECOCONTEXT hrc, BOOL bNewStroke);
HRESULT WINAPI SetCACMode(HRECOCONTEXT hrc, int iMode);
HRESULT WINAPI EndInkInput(HRECOCONTEXT hrc);
HRESULT WINAPI CloneContext(HRECOCONTEXT hrc, HRECOCONTEXT *pCloneHrc);
HRESULT WINAPI ResetContext(HRECOCONTEXT hrc);
HRESULT WINAPI GetAlternateList(HRECOCONTEXT hrc, RECO_RANGE *pRecoRange, ULONG *pcAlt, HRECOALT *phrcalt, ALT_BREAKS iBreak);
HRESULT WINAPI Process(HRECOCONTEXT hrc, BOOL *pbPartialProcessing);
// The SetFactoid function is optional for application recognizers.
HRESULT WINAPI SetFactoid(HRECOCONTEXT hrc, ULONG cwcFactoid, const WCHAR *pwcFactoid);
// The SetFlags function is optional for application recognizers.
HRESULT WINAPI SetFlags(HRECOCONTEXT hrc, DWORD dwFlags);
// The GetLatticPtr function is optional for application recognizers.
HRESULT WINAPI GetLatticePtr(HRECOCONTEXT hrc, RECO_LATTICE **ppLattice);
// The SetTextContext function is optional for application recognizers.
HRESULT WINAPI SetTextContext(HRECOCONTEXT hrc, ULONG cwcBefore, const WCHAR *pwcBefore, ULONG cwcAfter, WCHAR *pwcAfter);
//The GetEnabledUnicodeRanges function is optional for application recognizers.
HRESULT WINAPI GetEnabledUnicodeRanges(HRECOCONTEXT hrc, ULONG *pcRanges, CHARACTER_RANGE *pcr);
//The SetEnabledUnicodeRanges function is optional for application recognizers.
HRESULT WINAPI SetEnabledUnicodeRanges(HRECOCONTEXT hrc, ULONG cRanges, CHARACTER_RANGE, *pcr);
//The GetContextPropertyList function is optional for application recognizers.
HRESULT WINAPI GetContextPropertyList(HRECOCONTEXT hrc, ULONG *pcProperties, GUID *pPropertyGUIDS);
//The GetContextPropertyValue function is optional for application recognizers.
HRESULT WINAPI GetContextPropertyValue(HRECOCONTEXT hrc, GUID *pGuid, ULONG *pcbSize, BYTE *pProperty);
//The SetContextPropertyValue function is optional.
HRESULT WINAPI SetContextPropertyValue(HRECOCONTEXT hrc, GUID *pGuid, ULONG cbSize, BYTE *pProperty);
//The SetWordList function is optional for application recognizers.
HRESULT WINAPI SetWordList(HRECOCONTEXT hrc, HRECOWORDLIST hwl);
////////////////////////
// HRECOALT
// HRECOALT handles are required but not by Automation/Managed APIs.
////////////////////////
HRESULT WINAPI GetString(HRECOALT hrcalt, RECO_RANGE *pRecoRange, ULONG *pcSize, WCHAR *pwcString);
HRESULT WINAPI GetStrokeRanges(HRECOALT hrcalt, RECO_RANGE *pRecoRange, ULONG *pcRanges, STROKE_RANGE *pStrokeRange);
HRESULT WINAPI GetSegmentAlternateList(HRECOALT hrcalt, RECO_RANGE *pRecoRange, ULONG *pcAlts, HRECOALT *pAlts);
HRESULT WINAPI GetMetrics(HRECOALT hrcalt, RECO_RANGE *pRecoRange, LINE_METRICS lm, LINE_SEGMENT *pls);
HRESULT WINAPI GetGuideIndex(HRECOALT hrcalt, RECO_RANGE *pRecoRange, ULONG *piIndex);
HRESULT WINAPI GetConfidenceLevel(HRECOALT hrcalt, RECO_RANGE *pRecoRange, CONFIDENCE_LEVEL *pcl);
HRESULT WINAPI GetPropertyRanges(HRECOALT hrcalt, const GUID *pPropertyGUID, ULONG *pcRanges, RECO_RANGE *pRecoRange);
HRESULT WINAPI GetRangePropertyValue(HRECOALT hrcalt, const GUID *pPropertyGUID, RECO_RANGE *pRecoRange, ULONG *cbSize, BYTE *pProperty);
////////////////////////
// HRECOWORDLIST
// These functions are optional for application recognizers.
////////////////////////
HRESULT WINAPI DestroyWordList(HRECOWORDLIST hwl);
HRESULT WINAPI MakeWordList(HRECOGNIZER hrec, WCHAR *pBuffer, HRECOWORDLIST *phwl);
HRESULT WINAPI AddWordsToWordList (HRECOWORDLIST hwl, WCHAR *pwcWords);