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:

• HRECOGNIZER
• HRECOCONTEXT
• HRECOALT
• HRECOWORDLIST

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);