SplEnumUserDict

This function enumerates the words in internal and external user dictionaries, allowing an application to manipulate or display dictionary contents.

At a Glance

Header file:	Splapi.h
Windows CE versions:	2.10 and later

Syntax

int SplEnumUserDict( HSPL hspl, int nID, DWORD nIndex, SPLBUFFER * psb );

Parameters

hspl

Handle to the spelling session. An application initiates a spelling session by calling the SplInit function, which then generates this handle.

nID

Identifier of the user dictionary.

nIndex

Index of the word at which enumeration begins.

psb

Pointer to the SPLBUFFER structure.

Return Values

1 indicates success. 0 indicates failure.

Remarks

The main dictionary cannot be enumerated.

By enumerating user dictionaries, an application can present a dictionary’s contents to a user, who can then select words to be removed by means of the SplRemUserDict function, or specify words to be added by means of the SplAddUserDict function. The SplClrUserDictionary function clears the contents of a dictionary.

The SplEnumUserDict function places null-terminated words from the specified dictionary into the output buffer pointed to by the pwszOut member of the SPLBUFFER structure. The aspl member is an array of pointers to each word in the output buffer.

Because the output buffer contains a maximum of eight words, an application needs to continue calling SplEnumUserDict to enumerate dictionaries that are larger than eight words. To indicate that there are more words in the dictionary, SplEnumUserDict sets the dwErr member of SPLBUFFER to SPL_MORE_INFO_THAN_BUFFER_CAN_HOLD. In this case, use the nIndex parameter as a placeholder to a mark where in the dictionary to begin enumeration on the next call. When all the entries in a dictionary are enumerated, dwErr is set to SPL_OK, and the cspl member indicates how many words are in the output buffer.

When the entries of an enumerated dictionary consist of paired words, such as in the SPL_CHANGE_ALWAYS_LEX internal user dictionary, an entry has a separate aspl member in SPLBUFFER for each word in the pair.