SPWORDLIST

Other versions of this page are also available for the following:

• Windows Embedded CE 6.0 R3

8/28/2008

This structure contains word information. It is the start of a linked list of SPWORD structures, and contains the size and actual buffer of all subsequent words. The structure is used with ISpLexicon to receive words that are currently in the lexicon or that have changed since the last time an engine checked the lexicon. For its use, see ISpLexicon::GetWords and ISpLexicon::GetGenerationChange.

Syntax

typedef struct SPWORDLIST{
  ULONG ulSize;
  BYTE* pvBuffer;
  SPWORD* pFirstWord;
} SPWORDLIST;

Members

• ulSize
  Size, in bytes, of the buffer for all the words (pvBuffer).

• pvBuffer
  Pointer to the buffer for all word information or changes.

• pFirstWord
  Pointer to an SPWORD structure representing the first word in the linked list contained in the buffer specified by pvBuffer.

Remarks

The client should call the Platform SDK memory management function ZeroMemory before using this structure to initialize it, and call CoTaskMemFree to free the buffer allocated during the calls The buffer should not be freed between the calls. ISpLexicon::GetWords and ISpLexicon::GetGenerationChange reuse the buffer for efficiency and will reallocate it when necessary. For more information about ZeroMemory, see the MSDN Library.

Examples

The following example is a code fragment demonstrating the use and creation of an SPWORDLIST structure. The code initializes the structure prior to use. The retrieved structure is attached to a buffer allocated with CoTaskMemAllocate. This buffer is freed after all operations using the list. If not all words are retrieved by ISpLexicon::GetWords, the structure is not wiped and can be passed into subsequent calls to allow efficient reuse of the allocated memory block.

SPWORDLIST SPWordList;
hr = ZeroMemory(&SPWordList, sizeof(SPWordList));
// Check return value here. Handle error.
hr = S_FALSE;
while (hr == S_FALSE)
{
hr = pLex->GetWords(eLEXTYPE_USER, &dwGen, &dwCookie, &SPWordList);
// Do something with the received words.
// S_FALSE is returned if there are still words remaining to be got and 
the cookie is updated.
}
// Have finished with the list. Free the enclosed buffer.
::CoTaskMemFree(SPWordList.pvBuffer);

The following helper class will ensure the correct use of SPWORDLIST.

class CSpWordList : public SPWORDLIST
{
public:
CSpWordList()
{
ZeroMemory(static_cast<SPWORDLIST*>(this), sizeof(SPWORDLIST));
}
~CSpWordList()
{
CoTaskMemFree(pvBuffer);
}
};

Using the helper class, the previous example becomes:

CSpWordList SPWordList;
hr = S_FALSE;
while (hr == S_FALSE)
{
hr = pLex->GetWords(eLEXTYPE_USER, &dwGen, &dwCookie, &SPWordList);
// Do something with the received words.
// S_FALSE is returned if there are still words remaining to be got and the cookie is updated.
}

Requirements

Header	sapi.h, sapi.idl
Windows Embedded CE	Windows CE .NET 4.1 and later

See Also

Reference

SAPI Structures