DisplayUI and the Extra Data parameters

Hardcore SAPI programmers know that you can show the various SR engine user experiences (user training, microphone training, and so forth) using ISpRecognizer::DisplayUI.  (Even harder-core SAPI developers know that the real function is ISpObjectToken::DisplayUI, and that ISpRecognizer::DisplayUI simply forwards to the token of the loaded engine, but I digress…)

Most of the examples for DisplayUI just show the simple case where all the extra data parameters are NULL or 0, and don’t really explain what all those parameters are for.  Mostly that’s because these parameters are vendor specific (i.e., different SR engines may have different behavior); the following behaviors are specifically for the Microsoft Desktop SR engine.  Also, the valid values for the parameters depend on the pszTypeOfUI parameter.

For the Microsoft Desktop SR engine, the pUnkObject parameter should always be NULL.  There are no (interesting) valid non-null values for this parameter.

pvExtraData and cbExtraData can be non-NULL if pszTypeOfUI is either SPDUI_UserTraining or SPDUI_AddRemoveWord. 

When pszTypeOfUI is SPDUI_AddRemoveWord, then pvExtraData should be a standard null-terminated string containing the word to add to the lexicon.

When pszTypeOfUI is SPDUI_UserTraining, then pvExtraData should be a double-null-terminated string containing a set of training sentences.

Typically there should be 20-30 sentences to get good results.