MS Spell Checking API

[mLipok]

I saw here on the forum few different ways of checking spell:
Spell Checker (by iCode)
OpenOffice/LibreOffice Spell Checker (by GMK) 
v0.1.1 Scite4AutoIt SpellChecker using LibreOffice

even few topics about spell checking with Word.
Custom Spell Checker

But I start wondering how Notepad in Windows 11 finds out that some words are written incorrectly.

Then I ask ChatGPT about and he point me to Spell Checking API.

https://learn.microsoft.com/en-us/windows/win32/intl/about-the-spell-checker-api

So here is my question: Has anyone worked in AutoIt with MS Windows Spell Checking API ?



EDIT:
https://github.com/microsoft/Windows-classic-samples/blob/main/Samples/SpellCheckerClient/cpp/SampleSpellingClient.cpp

Edited April 19 by mLipok

[mLipok]

btw.
It is little funny (as I did many COM stuff in AutoIt) but ....

I'm not familiar with ObjCreateInterface() and for this reason at first I also asked ChatGPT for example:
 

expandcollapse popup

#include <MsgBoxConstants.au3>

; === COM interface GUIDs (global constants) ===
Global Const $CLSID_SpellCheckerFactory = "{7AB36653-1796-484B-BDFA-E74F1DB7C1DC}"
Global Const $IID_ISpellCheckerFactory = "{8E018A9D-2415-4677-BF08-794EA61F94BB}"
Global Const $IID_ISpellChecker = "{B6FD0B71-E2BC-4653-8D05-F197E0D3B83B}"

; === Interface definitions (global tags) ===
Global Const $TAG_ISpellCheckerFactory = _
        "CreateSpellChecker hresult(wstr;ptr*);" & _ ; Create spell checker for language
        "get_SupportedLanguages hresult(ptr*);"  ; Get supported languages

Global Const $TAG_ISpellChecker = _
        "Check hresult(wstr;ptr*);" & _ ; Check text for spelling errors
        "Suggest hresult(wstr;ptr*);" ; Get suggestions

; === Example entry point ===
_EXAMPLE()

Func _EXAMPLE()
    ; Create SpellCheckerFactory COM object
    Local $oFactory = ObjCreateInterface( _
            $CLSID_SpellCheckerFactory, _
            $IID_ISpellCheckerFactory, _
            $TAG_ISpellCheckerFactory)

    If @error Then
        MsgBox($MB_ICONERROR, "Error", "Failed to create SpellCheckerFactory")
        Return
    EndIf

    ; Create spell checker for Polish language
    Local $pSpellChecker = 0
    $oFactory.CreateSpellChecker("pl-PL", $pSpellChecker)

    If $pSpellChecker = 0 Then
        MsgBox($MB_ICONERROR, "Error", "Failed to create SpellChecker for pl-PL")
        Return
    EndIf

    ; Bind ISpellChecker interface
    Local $oSpell = ObjCreateInterface($pSpellChecker, $IID_ISpellChecker, $TAG_ISpellChecker)

    If @error Then
        MsgBox($MB_ICONERROR, "Error", "Failed to bind ISpellChecker interface")
        Return
    EndIf

    ; Word to test
    Local $sWord = "ksionszka"

    ; Perform spell check
    Local $pErrors = 0
    $oSpell.Check($sWord, $pErrors)

    ; NOTE: This is simplified logic!
    ; Proper implementation should enumerate IEnumSpellingError
    If $pErrors = 0 Then
        MsgBox($MB_ICONINFORMATION, "Result", "Word is correct: " & $sWord)
    Else
        MsgBox($MB_ICONWARNING, "Result", "Word is INCORRECT: " & $sWord)
    EndIf
EndFunc   ;==>_EXAMPLE

of course not works well.

[Nine]

If you can provide spellcheck.h file (not link), I will look at it.

[mLipok]

https://learn.microsoft.com/en-us/windows/win32/api/spellcheck/
https://github.com/gcc-mirror/gcc/blob/master/gcc/spellcheck.h
https://gist.github.com/mnovakovic/583648d14835de86bd45608c1c507826
https://github.com/microsoft/Windows-classic-samples/blob/main/Samples/SpellCheckerClient/cpp/commands.h

?

 

 

Edited April 20 by mLipok

[ioa747]

spellcheck.h

Windows Kits\10\Include\10.0.26100.0\um

Edit:
it has to do with
'Methods/properties of the description tag string must be in correct Vtable order'

👉  related

Edited April 20 by ioa747

[Nine]

24 minutes ago, ioa747 said:

Methods/properties of the description tag string must be in correct Vtable order

Exactly.  It is not the greatest idea of MS to list the methods in alphabetical order instead of the real order.

[mLipok]

2 hours ago, Nine said:

spellcheck.h file (not link),

I was in hope that my links were good.
Finally I found this file on my disc as I had this file:
c:\Program Files (x86)\Windows Kits\10\Include\10.0.26100.0\um\spellcheck.h

but @ioa747 was faster than me.

[Nine]

That seems to work correctly (at least in french)  :

expandcollapse popup

; From Nine

Opt("MustDeclareVars", True)

#include <Constants.au3>

Global Const $CLSID_SpellCheckerFactory = "{7AB36653-1796-484B-BDFA-E74F1DB7C1DC}"
Global Const $IID_ISpellCheckerFactory = "{8E018A9D-2415-4677-BF08-794EA61F94BB}"
Global Const $tag_ISpellCheckerFactory = _
    "get_SupportedLanguages hresult(ptr*);" & _
    "IsSupported hresult(wstr;bool*);" & _
    "CreateSpellChecker hresult(wstr;ptr*);"

Global Const $IID_ISpellChecker = "{B6FD0B71-E2BC-4653-8D05-F197E412770B}"
Global Const $tag_ISpellChecker = _
    "get_LanguageTag hresult(wstr*);" & _
    "Check hresult(wstr;ptr*);" & _
    "Suggest hresult(wstr;ptr*);" & _
    "Add hresult(wstr);" & _
    "Ignore hresult(wstr);"

Global Const $IID_IEnumSpellingError = "{803E3BD4-2828-4410-8290-418D1D73C762}"
Global Const $tag_IEnumSpellingError = _
    "Next hresult(ptr*);"

Example()

Func Example()
  Local $oFactory = ObjCreateInterface($CLSID_SpellCheckerFactory, $IID_ISpellCheckerFactory, $tag_ISpellCheckerFactory)
  If Not IsObj($oFactory) Then Exit ConsoleWrite("Err : oFactory" & @CRLF)
  Local $pSpellChecker
  $oFactory.CreateSpellChecker("fr-FR", $pSpellChecker)
  Local $oSpell = ObjCreateInterface($pSpellChecker, $IID_ISpellChecker, $tag_ISpellChecker)
  If Not IsObj($oSpell) Then Exit ConsoleWrite("Err : oSpell" & @CRLF)

  Local $aWord = ["Test", "Entêté", "Pasd'allure"]
  Local $pErrors, $oErrors, $iHresult
  For $sWord In $aWord
    $oSpell.Check($sWord, $pErrors)
    $oErrors = ObjCreateInterface($pErrors, $IID_IEnumSpellingError, $tag_IEnumSpellingError)
    If Not IsObj($oErrors) Then Exit ConsoleWrite("oErrors" & @CRLF)
    $iHresult = $oErrors.Next($pErrors)
    MsgBox($MB_OK, $iHresult ? "Correct" : "Error", $sWord)
  Next
EndFunc   ;==>Example

I didn't list all methods of ISpellChecker.  But I am tempted to explore this interface as it looks quite robust and promising.

Edited April 20 by Nine

[mLipok]

Small refactoring:

expandcollapse popup

; From Nine

Opt("MustDeclareVars", True)

#include <Constants.au3>

Global Const $CLSID_SpellCheckerFactory = "{7AB36653-1796-484B-BDFA-E74F1DB7C1DC}"
Global Const $IID_ISpellCheckerFactory = "{8E018A9D-2415-4677-BF08-794EA61F94BB}"
Global Const $tag_ISpellCheckerFactory = _
        "get_SupportedLanguages hresult(ptr*);" & _
        "IsSupported hresult(wstr;bool*);" & _
        "CreateSpellChecker hresult(wstr;ptr*);"

Global Const $IID_ISpellChecker = "{B6FD0B71-E2BC-4653-8D05-F197E412770B}"
Global Const $tag_ISpellChecker = _
        "get_LanguageTag hresult(wstr*);" & _
        "Check hresult(wstr;ptr*);" & _
        "Suggest hresult(wstr;ptr*);" & _
        "Add hresult(wstr);" & _
        "Ignore hresult(wstr);"

Global Const $IID_IEnumSpellingError = "{803E3BD4-2828-4410-8290-418D1D73C762}"
Global Const $tag_IEnumSpellingError = _
        "Next hresult(ptr*);"

Example()

Func Example()
    ; initialize Spell Checking API
    Local $oSpell = _MSSpellCheckingAPI_CreateSpell("en-EN") ; English SetUp
;~  Local $oSpell = _MSSpellCheckingAPI_CreateSpell("fr-FR") ; French SetUp
;~  Local $oSpell = _MSSpellCheckingAPI_CreateSpell("pl-PL") ; Polish SetUp
    If @error Then Return SetError(@error, @extended, '')

    ; some words to check
    Local $aWord = ["Spell Checking", "Speell", "Checcking"] ; English words
;~  Local $aWord = ["Test", "Entêté", "Pasd'allure"] ; French words
;~  Local $aWord = ["Sprawdzanie pisowni", "sprawdanie", "pissowni"] ; Polish words

    Local $bHresult = False
    For $sWord In $aWord
        $bHresult = _MSSpellCheckingAPI_Check($oSpell, $sWord)
        MsgBox((($bHresult) ? ($MB_OK) : ($MB_ICONWARNING)), ($bHresult ? "Correct" : "Error"), $sWord)
    Next
EndFunc   ;==>Example

Func _MSSpellCheckingAPI_CreateSpell($tag_language = "en-EN")
    Local $oFactory = ObjCreateInterface($CLSID_SpellCheckerFactory, $IID_ISpellCheckerFactory, $tag_ISpellCheckerFactory)
    If Not IsObj($oFactory) Then
        If Not @Compiled Then ConsoleWrite("! Err : oFactory" & @CRLF)
        Return SetError(1)
    EndIf

    Local $pSpellChecker
    $oFactory.CreateSpellChecker($tag_language, $pSpellChecker)
    Local $oSpell = ObjCreateInterface($pSpellChecker, $IID_ISpellChecker, $tag_ISpellChecker)
    If Not IsObj($oSpell) Then
        If Not @Compiled Then ConsoleWrite("! Err : oSpell" & @CRLF)
        Return SetError(2)
    EndIf

    Return $oSpell

EndFunc   ;==>_MSSpellCheckingAPI_CreateSpell

Func _MSSpellCheckingAPI_Check(ByRef $oSpell, $sWord)
    Local $pErrors, $oErrors, $iHresult
    $oSpell.Check($sWord, $pErrors)
    $oErrors = ObjCreateInterface($pErrors, $IID_IEnumSpellingError, $tag_IEnumSpellingError)
    If Not IsObj($oErrors) Then
        If Not @Compiled Then ConsoleWrite("! Err : oErrors" & @CRLF)
        Return SetError(3, 0, False)
    EndIf
    $iHresult = $oErrors.Next($pErrors)
    Return $iHresult ? True : False
EndFunc   ;==>_MSSpellCheckingAPI_Check

 

Edited April 20 by mLipok

[bladem2003]

expandcollapse popup

#include <WindowsConstants.au3>
#include <GUIConstantsEx.au3>
#include <Array.au3>
Opt("MustDeclareVars", True)

#include <Constants.au3>

; ============================================================
; UDF: SpellCheck.au3 (Windows Spell Checking API)
; ============================================================

Global Const $CLSID_SpellCheckerFactory = "{7AB36653-1796-484B-BDFA-E74F1DB7C1DC}"
Global Const $IID_ISpellCheckerFactory = "{8E018A9D-2415-4677-BF08-794EA61F94BB}"
Global Const $tag_ISpellCheckerFactory = _
    "get_SupportedLanguages hresult(ptr*);" & _
    "IsSupported hresult(wstr;bool*);" & _
    "CreateSpellChecker hresult(wstr;ptr*);"

Global Const $IID_ISpellChecker = "{B6FD0B71-E2BC-4653-8D05-F197E412770B}"
Global Const $tag_ISpellChecker = _
    "get_LanguageTag hresult(wstr*);" & _
    "Check hresult(wstr;ptr*);" & _
    "Suggest hresult(wstr;ptr*);" & _
    "Add hresult(wstr);" & _
    "Ignore hresult(wstr);"

Global Const $IID_IEnumSpellingError = "{803E3BD4-2828-4410-8290-418D1D73C762}"
Global Const $tag_IEnumSpellingError = "Next hresult(ptr*);"

Global Const $IID_IEnumString = "{00000101-0000-0000-C000-000000000046}"
Global Const $tag_IEnumString = "Next hresult(ulong;ptr;ulong*);"

; Module-level variables to cache the object
Global $__g_oSpellFactory = Null
Global $__g_oSpellChecker = Null
Global $__g_sSpellLang = ""

; ------------------------------------------------------------
; _SpellCheck_Init($sLang = "en-US")
; ------------------------------------------------------------
Func _SpellCheck_Init($sLang = "en-US")
    If $__g_sSpellLang = $sLang And IsObj($__g_oSpellChecker) Then Return True

    If Not IsObj($__g_oSpellFactory) Then
        $__g_oSpellFactory = ObjCreateInterface($CLSID_SpellCheckerFactory, $IID_ISpellCheckerFactory, $tag_ISpellCheckerFactory)
        If Not IsObj($__g_oSpellFactory) Then Return SetError(1, 0, False)
    EndIf

    Local $bSupported = False
    $__g_oSpellFactory.IsSupported($sLang, $bSupported)
    If Not $bSupported Then Return SetError(2, 0, False)

    Local $pSpellChecker
    Local $iRet = $__g_oSpellFactory.CreateSpellChecker($sLang, $pSpellChecker)
    If $iRet <> 0 Or Not $pSpellChecker Then Return SetError(3, $iRet, False)

    $__g_oSpellChecker = ObjCreateInterface($pSpellChecker, $IID_ISpellChecker, $tag_ISpellChecker)
    If Not IsObj($__g_oSpellChecker) Then Return SetError(4, 0, False)

    $__g_sSpellLang = $sLang
    Return True
EndFunc   ;==>_SpellCheck_Init

; ------------------------------------------------------------
; _SpellCheck_IsCorrect($sWord, $sLang = "en-US")
; ------------------------------------------------------------
Func _SpellCheck_IsCorrect($sWord, $sLang = "en-US")
    If Not _SpellCheck_Init($sLang) Then Return SetError(@error, 0, False)

    Local $pErrors
    $__g_oSpellChecker.Check($sWord, $pErrors)
    Local $oErrors = ObjCreateInterface($pErrors, $IID_IEnumSpellingError, $tag_IEnumSpellingError)
    If Not IsObj($oErrors) Then Return SetError(5, 0, False)

    Local $pErrItem
    Local $iHresult = $oErrors.Next($pErrItem)

    Return ($iHresult = 1) ; S_FALSE (1) = no errors found = word is correct
EndFunc   ;==>_SpellCheck_IsCorrect

; ------------------------------------------------------------
; _SpellCheck_GetSuggestions($sWord, $sLang = "en-US")
; ------------------------------------------------------------
Func _SpellCheck_GetSuggestions($sWord, $sLang = "en-US")
    If Not _SpellCheck_Init($sLang) Then Return SetError(@error, 0, False)

    Local $bCorrect = _SpellCheck_IsCorrect($sWord, $sLang)
    If @error Then Return SetError(@error, 0, False)

    If $bCorrect Then
        Local $aResult[2] = [1, $sWord]
        Return $aResult
    EndIf

    Local $pSuggestions
    $__g_oSpellChecker.Suggest($sWord, $pSuggestions)
    Local $oSuggestions = ObjCreateInterface($pSuggestions, $IID_IEnumString, $tag_IEnumString)
    If Not IsObj($oSuggestions) Then Return SetError(6, 0, False)

    Local $aResult[1] = [0]
    Local $iFetched

    Local $tPtr = DllStructCreate("ptr")
    Local $pPtr = DllStructGetPtr($tPtr)

    While True
        $iFetched = 0
        DllStructSetData($tPtr, 1, 0)

        $oSuggestions.Next(1, $pPtr, $iFetched)

        If $iFetched = 0 Then ExitLoop

        Local $pStr = DllStructGetData($tPtr, 1)
        If $pStr <> 0 Then
            Local $sSug = DllStructGetData(DllStructCreate("wchar[1024]", $pStr), 1)
            _ArrayAdd($aResult, $sSug)
            $aResult[0] += 1

            DllCall("ole32.dll", "none", "CoTaskMemFree", "ptr", $pStr)
        EndIf
    WEnd

    Return $aResult
EndFunc   ;==>_SpellCheck_GetSuggestions

; ============================================================
; Example Execution (English Language Setup)
; ============================================================

Example()

Func Example()
    ; English test words (Correct vs. Typos)
    Local $aWords = ["Beautiful", "Tomorow", "Language", "Recieve"]
    Local $sLang = "en-US" ; Using US English

    For $sWord In $aWords
        Local $aSuggestions = _SpellCheck_GetSuggestions($sWord, $sLang)

        If @error Then
            MsgBox($MB_OK, "Error", "Initialization/Check failed (Code " & @error & ")")
            ContinueLoop
        EndIf

        If $aSuggestions[0] = 1 And $aSuggestions[1] = $sWord Then
            MsgBox($MB_OK, "Correct Spelling", '"' & $sWord & '" is spelled correctly!')
        Else
            Local $sMsg = "Word: " & $sWord & @CRLF & "Suggestions:" & @CRLF
            If $aSuggestions[0] = 0 Then
                $sMsg &= "(no suggestions found)"
            Else
                For $i = 1 To $aSuggestions[0]
                    $sMsg &= " - " & $aSuggestions[$i] & @CRLF
                Next
            EndIf
            MsgBox($MB_OK, "Misspelled Word", $sMsg)
        EndIf
    Next
EndFunc   ;==>Example

 

[mLipok]

My latest version: MSSpellCheckingAPI.au3

I'll compare it to yours.

 

  

[mLipok]

Todays mod to my version:

MSSpellCheckingAPI.au3

Edited 16 hours ago by mLipok

[mLipok]

Long comparison generated by artificial intelligence:

Spoiler

Comparative analysis in English

I directly compared the contents of the two attachments:

File	Role in the comparison	Number of lines
MSSpellCheckingAPI.au3AU3	Your current version	169
MSSpellCheckingAPI_2.au3AU3	bladem2003’s version	163

The line numbers below refer to these files. Implementation findings come from their source code; I additionally checked the relevant COM contracts and AutoIt behavior against the documentation.

This is a static analysis. I did not run the scripts on Windows, perform memory tests, or benchmark them. I did not modify the files.

1. Overall conclusion

I would retain your version as the foundation and add suggestion retrieval using an improved implementation of bladem2003’s approach.

Your version separates spelling results from technical failures more effectively and allows the application to manage independent spell-checker objects. bladem2003’s version adds useful functionality—suggestions—but simplifies error handling and omits releasing a returned ISpellingError interface.

Area	Your version	bladem2003’s version
Core UDF interface	_CreateSpell() returns an object; _Check() accepts it	Functions use shared global state
Spell checking	_MSSpellCheckingAPI_Check()	_SpellCheck_IsCorrect()
Suggestion retrieval	COM method declared, but no ready-to-use wrapper	_SpellCheck_GetSuggestions()
Caching	Static pl-PL checker in _CheckWord()	Global factory and checker for the last language
HRESULT checking	Results of the spell-checking operations used are checked	Several important results are ignored
Returned spelling-error interface	Attempts to wrap the pointer in an AutoIt object and releases the object	Raw pointer remains unreleased
Example execution	Conditional	Unconditional
#include-once	Present	Missing

Source locations: your version, lines 1–39 and 72–169; bladem2003’s version, lines 33–134.

2. COM declarations: the shared core is identical

Both files contain the same identifier values and method descriptions for ISpellCheckerFactory, ISpellChecker, and IEnumSpellingError. Their differences are formatting differences, not differences in those declarations’ contents.

Your version additionally declares ISpellingError; bladem2003’s version declares IEnumString.

I checked the identifiers and declared method order for the Spell Checking interfaces against Microsoft’s spellcheck.h. I found no discrepancies in the identifiers or method order used for checking text. This does not constitute a runtime test of AutoIt’s complete marshalling behavior. GitHub

There is no need to replace your UDF’s shared declarations with bladem2003’s declarations. Suggestion retrieval primarily requires adding support for IEnumString.

3. Error handling: a significant advantage of your version

Initialization and language support

Your _MSSpellCheckingAPI_CreateSpell() separates the status of the IsSupported() call from the information indicating whether the language is supported:

Local $iHRESULT = $oFactory.IsSupported($sLanguageTag, $bSupported)
If $iHRESULT <> $MSSPELLCHECKINGAPI_S_OK Then
    ...
    Return SetError(2, $iHRESULT, 0)
EndIf

If Not $bSupported Then
    ...
    Return SetError(3, 0, 0)
EndIf

This appears in lines 80–91 of your file.

In bladem2003’s version, lines 52–54 discard the HRESULT:

Local $bSupported = False
$__g_oSpellFactory.IsSupported($sLang, $bSupported)
If Not $bSupported Then Return SetError(2, 0, False)

An IsSupported() failure and a successful “language not supported” response can therefore produce the same UDF error. These are different situations: the documentation distinguishes the call status from the value returned through BOOL*. Microsoft Learn

However, both versions check the result of CreateSpellChecker() and the returned pointer—your version in lines 94–99, and bladem2003’s in 56–58. It would therefore be incorrect to claim that bladem2003’s version completely ignores initialization errors.

Checking text

Your _MSSpellCheckingAPI_Check() checks the Check() result, the presence of an enumerator, and successful creation of an AutoIt object—lines 114–131.

In bladem2003’s version:

Local $pErrors
$__g_oSpellChecker.Check($sWord, $pErrors)
Local $oErrors = ObjCreateInterface($pErrors, $IID_IEnumSpellingError, $tag_IEnumSpellingError)
If Not IsObj($oErrors) Then Return SetError(5, 0, False)

Lines 73–76 discard the status of Check(). Consequently, the actual failure reason may be replaced by a generic enumerator-creation error.

An important distinction: for correctly spelled text, Check() returns an empty enumerator, not a null pointer. Your $pEnumSpellingError = 0 check therefore does not reject the valid “no spelling errors” result. Microsoft Learn

The result of enumerating spelling errors

Your version, lines 138–155, distinguishes:

Result of IEnumSpellingError.Next()	Your UDF’s behavior
S_OK	An error was found; returns False after handling the interface
S_FALSE	No error was found; returns True
Another result	Returns False, with @error = 7 and @extended = HRESULT

The interpretation of S_OK and S_FALSE matches the enumerator’s documentation. Microsoft Learn

In bladem2003’s version, line 81:

Return ($iHresult = 1)

Every result other than S_FALSE becomes False, without a separate SetError() for an unexpected status. An API failure can be presented to the application as an ordinary spelling mistake. AutoIt requires explicitly setting @error for a user-defined function to report failure through it. AutoIt

Propagating error details

bladem2003 uses:

Return SetError(@error, 0, False)

in lines 71, 88, and 91. This discards the previous @extended, including a HRESULT stored there by _SpellCheck_Init().

Your _MSSpellCheckingAPI_CheckWord(), lines 164 and 168, preserves both macros. This behavior should be retained during further development.

4. COM management: an unreleased ISpellingError in bladem2003’s version

bladem2003’s version, lines 78–81:

Local $pErrItem
Local $iHresult = $oErrors.Next($pErrItem)

Return ($iHresult = 1)

After an item is returned, $pErrItem receives no further handling. It is neither wrapped in an AutoIt object nor released through Release().

This is a concrete omission of a COM reference release. Releasing a reference returned through an output parameter is the caller’s responsibility; discarding a variable containing a raw pointer does not fulfill that responsibility. Microsoft Learn

The issue occurs on the path where the enumerator returns a spelling error. It also affects _SpellCheck_GetSuggestions(), because that function calls _SpellCheck_IsCorrect().

Your version, lines 140–146, instead contains:

Local $oSpellingError = ObjCreateInterface($pSpellingError, $IID_ISpellingError, $tag_ISpellingError)
If Not IsObj($oSpellingError) Then
    ...
EndIf
$oSpellingError = 0

There is an explicit path for wrapping the interface and releasing the object. AutoIt documents releasing object references when another value is assigned and when a local object variable reaches the end of its lifetime. AutoIt

Qualification: I have not measured the reference-counting balance inside ObjCreateInterface(), particularly when wrapping fails. Both versions need their “the API returned a pointer, but the AutoIt object was not created” paths reviewed. I would not add an extra Release() without establishing who owns the reference at that point.

Keeping a global factory and checker in bladem2003’s version is intentional caching, not evidence of a leak. That is different from abandoning $pErrItem on successive calls.

5. Suggestions: useful functionality that needs refinement

What is implemented sensibly

Lines 87–128 of bladem2003’s version provide a complete wrapper: calling Suggest(), enumerating strings, and building an array with a count in [0].

The use of a memory slot for the returned pointer is also appropriate:

Global Const $tag_IEnumString = "Next hresult(ulong;ptr;ulong*);"

together with:

Local $tPtr = DllStructCreate("ptr")
Local $pPtr = DllStructGetPtr($tPtr)

$oSuggestions.Next(1, $pPtr, $iFetched)

The second parameter’s ptr type is not an error here. $pPtr already addresses the output pointer slot, matching the native LPOLESTR *rgelt parameter. Microsoft Learn

I would not change ptr to ptr* without changing the calling code accordingly.

Ignored status codes

Lines 99 and 113 ignore the results of:

$__g_oSpellChecker.Suggest($sWord, $pSuggestions)
$oSuggestions.Next(1, $pPtr, $iFetched)

The loop terminates solely on:

If $iFetched = 0 Then ExitLoop

An enumeration failure may therefore be mistaken for successful completion of a partial list. The status must also be checked: when requesting one item, S_OK means it was retrieved; S_FALSE means enumeration has ended. Microsoft Learn

Suggest() and correctly spelled text

Lines 90–96 first call _SpellCheck_IsCorrect() and return the following for correctly spelled text:

Local $aResult[2] = [1, $sWord]

This format is not inherently wrong. Suggest() documents S_FALSE as correctly spelled text, with an enumerator containing that text as its only entry. Microsoft Learn

Consequently, the preliminary check is unnecessary solely to obtain this result. A new suggestion wrapper can call Suggest() directly, provided it accepts both S_OK and S_FALSE.

This does not mean the separate text-checking function should be removed. Checking text and retrieving suggestions still serve different purposes.

Reading through wchar[1024]

Line 119:

Local $sSug = DllStructGetData(DllStructCreate("wchar[1024]", $pStr), 1)

The code imposes a fixed size without determining the string length. With a supplied pointer, DllStructCreate() describes existing memory rather than allocating a new buffer. This is an arbitrary limit and size assumption—not evidence of a confirmed buffer overflow. AutoIt

A better starting point would be _WinAPI_GetString($pStr) from WinAPIMisc.au3, which reads null-terminated strings, with @error checking. AutoIt

The string memory still requires freeing afterward. bladem2003 does this with CoTaskMemFree() in line 123. Changing the reader must preserve this caller-side cleanup obligation. Microsoft Learn

_ArrayAdd() can split a single suggestion

Lines 120–121:

_ArrayAdd($aResult, $sSug)
$aResult[0] += 1

By default, _ArrayAdd() splits strings containing |. A single suggestion could therefore produce multiple elements while the count increases by only one. This is a scenario implied by the code, not an observed result from a particular dictionary. AutoIt

I would use $ARRAYFILL_FORCE_SINGLEITEM or assign directly into the array. Structure creation and element insertion should also be checked before the function considers the operation successful.

6. bladem2003’s example incorrectly infers correctness from string comparison

Line 149:

If $aSuggestions[0] = 1 And $aSuggestions[1] = $sWord Then

The = operator compares strings without case sensitivity. If the only suggestion differs from the input solely in capitalization, the example may classify the original spelling as correct. The minimal change is ==, but a better design would report correctness separately rather than reconstruct it from the suggestions. AutoIt

There is no basis, however, for claiming that this condition necessarily reads a nonexistent [1] element when the list is empty. AutoIt short-circuits And: when the first condition is false, the second is not evaluated. AutoIt

7. Caching and multiple languages

In your version, the application receives an object from _MSSpellCheckingAPI_CreateSpell() and can retain several independent checkers. _MSSpellCheckingAPI_Check() does not create a factory on every check.

Additionally, _MSSpellCheckingAPI_CheckWord(), lines 158–169, statically retains a pl-PL checker and retries initialization after an earlier failure.

In bladem2003’s version, lines 36–65, one factory and one checker are retained. Consecutive calls for the same language reuse the cache. However, this sequence:

pl-PL → en-US → pl-PL

recreates the checker at each language change. This is a last-language cache, not a collection of checkers for multiple languages.

Furthermore, _SpellCheck_GetSuggestions() calls _SpellCheck_Init() directly and again through _SpellCheck_IsCorrect(). The second call normally returns immediately. This does not mean the checker is created twice, but it is an unnecessary layer.

There is no basis for a blanket claim that either version is faster. The code reveals differences in where and how often operations are called; their practical significance requires measurements using the intended workload.

8. Suitability for inclusion as a library

bladem2003’s version unconditionally calls:

Example()

in line 134. Including the file therefore executes its example. It also lacks #include-once, and the generic Example() name can collide with an application function.

Line 7:

Opt("MustDeclareVars", True)

changes a script runtime option, not merely a module-local setting. It is useful for testing, but a library should not impose it implicitly. AutoIt

Your version has #include-once, the _MSSpellCheckingAPI_Example() name, and conditional example execution in lines 37–39. The condition also means that the example does not run after compilation or when the script is renamed to something outside the regular expression’s accepted pattern.

In bladem2003’s version, I see no direct use requiring WindowsConstants.au3 or GUIConstantsEx.au3; Array.au3 is used by _ArrayAdd().

The files should not be treated as independently includable modules that can simply be included together unchanged: they declare the same global interface constants. Different function names do not make them fully independent.

9. What I would also improve in your version

COM wrapping failure paths. Lines 101–105, 127–131, and 140–145 require checking pointer ownership when ObjCreateInterface() fails to create an object. I do not consider that question resolved by source inspection alone.

Object-creation diagnostics. Returning a custom error with @extended = 0 at these locations limits access to the original failure information. The ObjCreateInterface() error should be captured immediately after the call; its documentation confirms that failures are reported through @error. AutoIt

Contract documentation. Function headers should describe parameters, error codes, and the distinction between False meaning a spelling mistake was found and False accompanied by a nonzero @error. The fixed pl-PL language in _CheckWord() should also be explicitly documented.

Object validation. Line 111 checks that the argument is an object, but it does not establish that it is the required ISpellChecker. At minimum, the current API should clearly require an object returned by _MSSpellCheckingAPI_CreateSpell().

Functional scope. Declaring ISpellingError does not mean the UDF currently returns error positions, lengths, or corrective actions. The interface is presently used to handle the reference; _Check() still returns only a Boolean result.

Stopping enumeration at the first spelling error is appropriate for that contract. Retrieving all errors is unnecessary to answer “does this text contain a spelling error?”

10. Recommended development direction

I would retain the existing _MSSpellCheckingAPI_CreateSpell(), _MSSpellCheckingAPI_Check(), and _MSSpellCheckingAPI_CheckWord() functions.

I would name the new function consistently with your UDF:

_MSSpellCheckingAPI_GetSuggestions(ByRef $oSpell, $sWord)

It should use the supplied checker, handle both S_OK and S_FALSE from Suggest(), check enumeration status, read strings without the fixed 1024 size, and free memory on failure paths as well. Each suggestion should occupy exactly one array element.

After implementation, the most important tests would cover correctly spelled text, misspellings with and without suggestions, empty input, unsupported languages, alternating languages, a capitalization-only suggestion, and repeated checks of misspelled text to examine resource handling. These are proposed tests, not results of tests already performed.

In summary: bladem2003’s version is a useful functional extension, but not a better replacement for your UDF. The strongest approach is to integrate improved suggestion handling into your architecture while preserving the separation between spelling results and API failures.

 

[mLipok]

new version MSSpellCheckingAPI.au3

AI long description:

Spoiler

2026/09/07 01:30

MSSpellCheckingAPI.au3AU3

The updated file is based on your original UDF, with suggestion retrieval integrated into its existing object-based architecture. Your original attachments remain unchanged.

1. Added suggestion retrieval

The new public function is:

_MSSpellCheckingAPI_GetSuggestions(ByRef $oSpell, $sWord)

It uses an existing checker returned by _MSSpellCheckingAPI_CreateSpell(). It does not create a global checker, change the selected language, or perform a preliminary _Check() call.

On success, it returns a counted array:

$aSuggestions[0] ; Number of suggestions
$aSuggestions[1] ; First suggestion
$aSuggestions[2] ; Second suggestion

An empty suggestion list is returned as a one-element array containing 0, with @error = 0. A technical failure returns False with a nonzero @error; a partially retrieved list is not returned as a success.

The function also preserves the original Suggest() status in @extended:

Result	@error	@extended
Suggestion request succeeded	0	$MSSPELLCHECKINGAPI_S_OK
API reports correctly spelled input	0	$MSSPELLCHECKINGAPI_S_FALSE
Technical failure	Nonzero	Diagnostic information documented in the function header

Microsoft documents S_FALSE from Suggest() as correctly spelled input, with the input itself returned as the sole suggestion. This status is accepted rather than treated as an error. Capture @error and @extended immediately after the call. Microsoft Learn

2. Added explicit enumeration checks

The suggestion loop checks the HRESULT, fetched count, and returned string pointer together.

When requesting one element, it accepts S_OK with one non-null string, or S_FALSE with no element. Unexpected statuses and inconsistent output combinations produce distinct errors instead of silently ending enumeration. The two meanings of S_FALSE remain separate: from Suggest() it indicates correct spelling; from IEnumString.Next() it indicates the end of enumeration. Microsoft Learn

3. Improved string handling and cleanup

The implementation reads null-terminated Unicode strings through:

_WinAPI_GetString($pString, True)

This avoids importing bladem2003’s fixed wchar[1024] buffer assumption. WinAPIMisc.au3 was added for this function, and string-reading errors are checked. AutoIt

Returned strings are passed to CoTaskMemFree() after reading, including recoverable paths where enumeration or reading fails. This follows the Spell Checking API’s requirement to free returned IEnumString strings with the COM task allocator. Microsoft Learn

The new internal helper is:

__MSSpellCheckingAPI_CoTaskMemFree(ByRef $pMemory)

It clears the pointer after a successful call and reports a DllCall failure. It does not interpret a nonexistent API return value: CoTaskMemFree() returns void. If another error occurred before cleanup, that original diagnostic is preserved. Microsoft Learn

Suggestions are inserted through direct array assignment, not _ArrayAdd(). Each returned string therefore occupies exactly one element, including strings containing | or line breaks. The array grows geometrically and is resized to the exact count before returning.

4. Strengthened the existing functions without changing their signatures

The existing _MSSpellCheckingAPI_CreateSpell(), _MSSpellCheckingAPI_Check(), and _MSSpellCheckingAPI_CheckWord() signatures remain unchanged.

Object-creation errors are now captured immediately after ObjCreateInterface() and exposed through @extended, rather than always being replaced with zero. ObjCreateInterface() reports its failures through @error. AutoIt

I also added an explicit null-pointer check when IEnumSpellingError.Next() reports an item and made successful return paths explicitly clear @error and @extended.

Your existing distinction remains intact: False with @error = 0 means a spelling error was found; False with a nonzero @error means checking failed. The cached pl-PL checker and initialization retry behavior in _CheckWord() are preserved.

5. Updated the example and documentation

The existing example now displays suggestions for text that _Check() identifies as incorrect. It does not infer correctness by comparing the input with a suggestion.

All six functions have English headers documenting parameters, return values, and errors. The headers also clarify that checker arguments must come from _MSSpellCheckingAPI_CreateSpell(); merely passing an arbitrary COM object is unsupported.

The new function names follow the UDF’s prefix: _MSSpellCheckingAPI_ for the public function and __MSSpellCheckingAPI_ for the internal helper. No existing function was renamed.

The file retains #include-once and conditional example execution. It is saved as UTF-8 with BOM and Windows CRLF line endings.

Validation and remaining limitation

Custom structural checks passed for block structure, declarations, function signatures, and preserved interface identifiers. Additionally, 23 mocked control-flow cases passed against a Python translation of the new suggestion function, covering empty results, status handling, long Unicode strings, array growth, partial-result failures, and diagnostic preservation during cleanup.

These are not native AutoIt or Windows COM tests. I did not run Au3Check, exercise installed Windows dictionaries, or measure COM reference counts.

One proposed investigation remains unresolved: ownership of a returned interface pointer when ObjCreateInterface() fails to wrap it. I preserved the existing ownership policy and explicitly marked those paths in the code rather than adding an unverified Release() that could introduce a double release. Consequently, this update does not claim to have resolved or verified cleanup on failed-wrapper paths.

 

[mLipok]

23 hours ago, bladem2003 said:

expandcollapse popup

#include <WindowsConstants.au3>
#include <GUIConstantsEx.au3>
#include <Array.au3>
Opt("MustDeclareVars", True)

#include <Constants.au3>

; ============================================================
; UDF: SpellCheck.au3 (Windows Spell Checking API)
; ============================================================

Global Const $CLSID_SpellCheckerFactory = "{7AB36653-1796-484B-BDFA-E74F1DB7C1DC}"
Global Const $IID_ISpellCheckerFactory = "{8E018A9D-2415-4677-BF08-794EA61F94BB}"
Global Const $tag_ISpellCheckerFactory = _
    "get_SupportedLanguages hresult(ptr*);" & _
    "IsSupported hresult(wstr;bool*);" & _
    "CreateSpellChecker hresult(wstr;ptr*);"

Global Const $IID_ISpellChecker = "{B6FD0B71-E2BC-4653-8D05-F197E412770B}"
Global Const $tag_ISpellChecker = _
    "get_LanguageTag hresult(wstr*);" & _
    "Check hresult(wstr;ptr*);" & _
    "Suggest hresult(wstr;ptr*);" & _
    "Add hresult(wstr);" & _
    "Ignore hresult(wstr);"

Global Const $IID_IEnumSpellingError = "{803E3BD4-2828-4410-8290-418D1D73C762}"
Global Const $tag_IEnumSpellingError = "Next hresult(ptr*);"

Global Const $IID_IEnumString = "{00000101-0000-0000-C000-000000000046}"
Global Const $tag_IEnumString = "Next hresult(ulong;ptr;ulong*);"

; Module-level variables to cache the object
Global $__g_oSpellFactory = Null
Global $__g_oSpellChecker = Null
Global $__g_sSpellLang = ""

; ------------------------------------------------------------
; _SpellCheck_Init($sLang = "en-US")
; ------------------------------------------------------------
Func _SpellCheck_Init($sLang = "en-US")
    If $__g_sSpellLang = $sLang And IsObj($__g_oSpellChecker) Then Return True

    If Not IsObj($__g_oSpellFactory) Then
        $__g_oSpellFactory = ObjCreateInterface($CLSID_SpellCheckerFactory, $IID_ISpellCheckerFactory, $tag_ISpellCheckerFactory)
        If Not IsObj($__g_oSpellFactory) Then Return SetError(1, 0, False)
    EndIf

    Local $bSupported = False
    $__g_oSpellFactory.IsSupported($sLang, $bSupported)
    If Not $bSupported Then Return SetError(2, 0, False)

    Local $pSpellChecker
    Local $iRet = $__g_oSpellFactory.CreateSpellChecker($sLang, $pSpellChecker)
    If $iRet <> 0 Or Not $pSpellChecker Then Return SetError(3, $iRet, False)

    $__g_oSpellChecker = ObjCreateInterface($pSpellChecker, $IID_ISpellChecker, $tag_ISpellChecker)
    If Not IsObj($__g_oSpellChecker) Then Return SetError(4, 0, False)

    $__g_sSpellLang = $sLang
    Return True
EndFunc   ;==>_SpellCheck_Init

; ------------------------------------------------------------
; _SpellCheck_IsCorrect($sWord, $sLang = "en-US")
; ------------------------------------------------------------
Func _SpellCheck_IsCorrect($sWord, $sLang = "en-US")
    If Not _SpellCheck_Init($sLang) Then Return SetError(@error, 0, False)

    Local $pErrors
    $__g_oSpellChecker.Check($sWord, $pErrors)
    Local $oErrors = ObjCreateInterface($pErrors, $IID_IEnumSpellingError, $tag_IEnumSpellingError)
    If Not IsObj($oErrors) Then Return SetError(5, 0, False)

    Local $pErrItem
    Local $iHresult = $oErrors.Next($pErrItem)

    Return ($iHresult = 1) ; S_FALSE (1) = no errors found = word is correct
EndFunc   ;==>_SpellCheck_IsCorrect

; ------------------------------------------------------------
; _SpellCheck_GetSuggestions($sWord, $sLang = "en-US")
; ------------------------------------------------------------
Func _SpellCheck_GetSuggestions($sWord, $sLang = "en-US")
    If Not _SpellCheck_Init($sLang) Then Return SetError(@error, 0, False)

    Local $bCorrect = _SpellCheck_IsCorrect($sWord, $sLang)
    If @error Then Return SetError(@error, 0, False)

    If $bCorrect Then
        Local $aResult[2] = [1, $sWord]
        Return $aResult
    EndIf

    Local $pSuggestions
    $__g_oSpellChecker.Suggest($sWord, $pSuggestions)
    Local $oSuggestions = ObjCreateInterface($pSuggestions, $IID_IEnumString, $tag_IEnumString)
    If Not IsObj($oSuggestions) Then Return SetError(6, 0, False)

    Local $aResult[1] = [0]
    Local $iFetched

    Local $tPtr = DllStructCreate("ptr")
    Local $pPtr = DllStructGetPtr($tPtr)

    While True
        $iFetched = 0
        DllStructSetData($tPtr, 1, 0)

        $oSuggestions.Next(1, $pPtr, $iFetched)

        If $iFetched = 0 Then ExitLoop

        Local $pStr = DllStructGetData($tPtr, 1)
        If $pStr <> 0 Then
            Local $sSug = DllStructGetData(DllStructCreate("wchar[1024]", $pStr), 1)
            _ArrayAdd($aResult, $sSug)
            $aResult[0] += 1

            DllCall("ole32.dll", "none", "CoTaskMemFree", "ptr", $pStr)
        EndIf
    WEnd

    Return $aResult
EndFunc   ;==>_SpellCheck_GetSuggestions

; ============================================================
; Example Execution (English Language Setup)
; ============================================================

Example()

Func Example()
    ; English test words (Correct vs. Typos)
    Local $aWords = ["Beautiful", "Tomorow", "Language", "Recieve"]
    Local $sLang = "en-US" ; Using US English

    For $sWord In $aWords
        Local $aSuggestions = _SpellCheck_GetSuggestions($sWord, $sLang)

        If @error Then
            MsgBox($MB_OK, "Error", "Initialization/Check failed (Code " & @error & ")")
            ContinueLoop
        EndIf

        If $aSuggestions[0] = 1 And $aSuggestions[1] = $sWord Then
            MsgBox($MB_OK, "Correct Spelling", '"' & $sWord & '" is spelled correctly!')
        Else
            Local $sMsg = "Word: " & $sWord & @CRLF & "Suggestions:" & @CRLF
            If $aSuggestions[0] = 0 Then
                $sMsg &= "(no suggestions found)"
            Else
                For $i = 1 To $aSuggestions[0]
                    $sMsg &= " - " & $aSuggestions[$i] & @CRLF
                Next
            EndIf
            MsgBox($MB_OK, "Misspelled Word", $sMsg)
        EndIf
    Next
EndFunc   ;==>Example

 

@bladem2003 thanks for pointing me in this direction