SPWORDLIST (SAPI 5.3)

Microsoft Speech API 5.3

SPWORDLIST

SPWORDLIST receives words currently in the lexicon or that have changed since the last time an engine was checked. It is used in conjunction with ISpLexicon.

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

Members

• ulSize
  The size of the buffer for all of the words, in bytes.
• pvBuffer
  Pointer to the buffer for all word information or changes.
• pFirstWord
  Pointer to the first word in the list.

Remarks

This structure is the beginning of a linked list of SPWORD structures and contains the size and actual buffer of all subsequent word operations. It is used with ISpLexicon::GetWords and ISpLexicon::GetGenerationChange.

Call ZeroMemory before using SPWORDLIST to initialize it, and call CoTaskMemFree(spWordList.pvBuffer) to free the buffer allocated during the calls.  The pvBuffer need not (and should not) be freed between the calls.  ISpLexicon::GetWords and ISpLexicon::GetGenerationChange will reuse the buffer for efficiency and reallocate when necessary.

Examples

The following example is a code fragment demonstrating the use and creation of SPWORDLIST. The code initializes the structure prior to use. Note that the returned SPWORDLIST has a CoTaskMemAllocate buffer attached to it. This should be freed after all operations using the list. If not all words are returned from ISpLexicon::GetWords, the structure should not be wiped and can be passed into subsequent calls to efficiently reuse 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 usage of SPWORDLIST.

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

Using the helper class, the above sample 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.
}