guides:com:start

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
guides:com:start [2023-07-25 16:16] – Add article content geekguides:com:start [2025-03-26 12:36] (current) – [IDispatch Objects] Demote header level geek
Line 22: Line 22:
  
 In short, COM was Microsoft's primary solution for communication between software packages in the years before leaning into before their .NET Common Language Runtime. A lot of the Windows API and third-party software still supports COM interfaces, and utilizing those interfaces will allow you to do amazing things. AutoHotkey, especially AutoHotkey v2, has a variety of tools for interacting with those interfaces, if only you take the time to learn how to use them. In short, COM was Microsoft's primary solution for communication between software packages in the years before leaning into before their .NET Common Language Runtime. A lot of the Windows API and third-party software still supports COM interfaces, and utilizing those interfaces will allow you to do amazing things. AutoHotkey, especially AutoHotkey v2, has a variety of tools for interacting with those interfaces, if only you take the time to learn how to use them.
 +
 +===== Anatomy of a COM Object =====
 +
 +A COM Object follows the %%C++%% [[https://en.wikipedia.org/wiki/Application_binary_interface|ABI]] for objects. COM objects are composed of structured data, and what is known as a virtual method table (vtable).
 +
 +The virtual method table is an array of pointers to %%__stdcall%% functions. They are arranged in the order they are declared in headers. Each method is implemented by a regular function where the first parameter is "This", a pointer to the structured data of the object. All COM objects derive from the IUnknown interface, so a basic IUnknown-compatible COM object's vtable would look like this:
 +
 +<code c>
 +// Interface Identifier (IID) {00000000-0000-0000-C000-000000000046}
 +typedef struct IUnknownVtbl {
 + __stdcall HRESULT(*QueryInterface)(IUnknown *This, ...); // From IUnknown
 + __stdcall ULONG(*AddRef)(IUnknown *This, ...); // From IUnknown
 + __stdcall ULONG(*Release)(IUnknown *This, ...); // From IUnknown
 +} IUnknownVtbl;
 +</code>
 +
 +And an //object// with this interface would look like this:
 +
 +<code c>
 +typedef struct IUnknown {
 + IUnknownVtbl* vtbl;
 + ... // any data fields go here
 +} IUnknown;
 +</code>
 +
 +So when you have a (pointer to a) COM object ''pObject'' of type IUnknown, you could call its method "QueryInterface" by:
 +  - Retrieving the vtable: ''pObjectVtbl := NumGet(pObject, 0, "Ptr")''
 +  - Retrieving the function reference at index ''0'': ''pObjectQueryInterface := NumGet(pObjectVtbl, 0 * A_PtrSize, "Ptr")''
 +  - Calling the function passing the object as the first parameter: ''DllCall(pObjectQueryInterface, "Ptr", pObject, ...)''
 +(or in AHKv2, by using ComCall which performs all those steps for you)
 +
 +IUnknown is the most basic of COM Object interfaces, but to perform useful work it is typically necessary to work with objects that //extend// IUnknown, such as IDispatch. With an interface that extends another, the vtable will start with the functions from the original interface and then continue into the new extended functions. For IDispatch, this means its vtable would look like this:
 +
 +<code c>
 +// Interface Identifier (IID) {00020400-0000-0000-C000-000000000046}
 +typedef struct IDispatchVtbl {
 + // From IUnknown
 + __stdcall HRESULT(*QueryInterface)(IDispatch *This, ...);
 + __stdcall ULONG(*AddRef)(IDispatch *This);
 + __stdcall ULONG(*Release)(IDispatch *This);
 +
 + // From IDispatch
 + __stdcall HRESULT(*GetTypeInfoCount)(IDispatch *This, ...);
 + __stdcall HRESULT(*GetTypeInfo)(IDispatch * This, ...);
 + __stdcall HRESULT(*GetIDsOfNames)(IDispatch *This, ...);
 + __stdcall HRESULT(*Invoke)(IDispatch *This, ...);
 +} IDispatchVtbl;
 +</code>
 +
 +Therefore, the indexes of the IDispatch methods in the vtable start ''3'' not ''0''. This is very important to keep in mind when looking for indexes from headers posted online. For example, it is often helpful to perform Google searches such as ''IDispatchVtbl filetype:h'' to find header files [[https://github.com/tpn/winsdk-10/blob/master/Include/10.0.16299.0/um/OAIdl.h#L2242|like this one]]. Instead of showing that it begins with the IUnknown functions, it just has the text ''BEGIN_INTERFACE'' which, while it's likely easier to write and manage, it is not very useful to us the readers.
 +
 +===== IDispatch Objects =====
 +
 +The IDispatch interface is Microsoft's "automation" interface, designed to allow easy integration with automation languages like Visual Basic and VBScript. Rather than following a strict structure, objects implementing the IDispatch interface only implement four additional methods on top of IUnknown's reference counter methods:
 +
 +  * (Optional) GetTypeInfoCount - Get the count of "TypeInfo" entries
 +  * (Optional) GetTypeInfo - Get a list of TypeInfo entries that describe object properties
 +  * GetIDsOfNames - Turns text names into property IDs at run-time
 +  * Invoke - Accesses a property by ID, either retrieving, setting, or calling the property as a method
 +
 +From these four methods, IDispatch allows rigidly structured languages like C++ to create or access free-form objects where the properties may not all be known at compile time. AutoHotkey itself uses IDispatch as the basis for all its objects, and handles accessing IDispatch properties transparently with regular object syntax.
 +
 +<tabbox Native Syntax>
 +
 +<code autohotkey>
 +#Requires AutoHotkey v2
 +
 +; Retrieve a WScript.Shell IDispatch object using its human-readable ProgID.
 +; You could also specify CLSID "{72C24DD5-D70A-438B-8A42-98424B88AFB8}" instead.
 +shell := ComObject("WScript.Shell")
 +
 +; This call first invokes GetIDsOfNames to convert "Exec" into a property ID,
 +; then it calls Invoke with that ID, specifying this should be a method call
 +; with the given parameter "calc.exe".
 +shell.Exec("calc.exe")
 +</code>
 +
 +<tabbox ComCall Syntax>
 +
 +<code autohotkey>
 +#Requires AutoHotkey v2
 +
 +; Retrieve a WScript.Shell IDispatch object using its human-readable ProgID.
 +; You could also specify CLSID "{72C24DD5-D70A-438B-8A42-98424B88AFB8}" instead.
 +shell := ComObject("WScript.Shell")
 +
 +name := "Exec"
 +arg1 := "calc.exe"
 +
 +; Retreive the ID for method "Exec"
 +IID_NULL := Buffer(16, 0)
 +names := Buffer(A_PtrSize * 1, 0)
 +NumPut("Ptr", StrPtr(name), names)
 +ids := Buffer(16 * 1, 0)
 +ComCall(5, ComObjValue(shell), ; shell.GetIDsOfNames
 + "Ptr", IID_NULL, ; REFIID   riid
 + "Ptr", names,    ; LPOLESTR *rgszNames
 + "UInt", 1,       ; UINT     cNames
 + "Ptr", 0,        ; LCID     lcid
 + "Ptr", ids,      ; DISPID   *rgDispId
 + "Int" ; HRESULT
 +)
 +execId := NumGet(ids, "Int")
 +
 +; Stage the arguments for the call
 +args := Buffer((8+A_PtrSize*2) * 1, 0) ; one argument
 +NumPut(
 + "Short", 8,          ; VARTYPE vt = VT_BSTR
 + "Short", 0,          ; WORD wReserved1
 + "Short", 0,          ; WORD wReserved2
 + "Short", 0,          ; WORD wReserved3
 + "Ptr", StrPtr(arg1), ; BSTR bstrVal = arg1
 + args
 +)
 +dp := Buffer(A_PtrSize*2+8, 0)
 +NumPut(
 + "Ptr", args.Ptr, ; VARIANTARG *rgvarg
 + "Ptr", 0,        ; DISPID     *rgdispidNamedArgs
 + "UInt", 1,       ; UINT       cArgs
 + "UInt", 0,       ; UINT       cNamedArgs
 + dp
 +)
 +
 +; Call "Exec" with those arguments
 +res := Buffer((8+A_PtrSize*2) * 1, 0) ; one result
 +ComCall(6, ComObjValue(shell), ; shell.Invoke
 + "Int", execId,   ; DISPID     dispIdMember - The member to invoke
 + "Ptr", IID_NULL, ; REFIID     riid
 + "Ptr", 0,        ; LCID       lcid
 + "Int", 1,        ; WORD       wFlags = DISPATCH_METHOD
 + "Ptr", dp,       ; DISPPARAMS *pDispParams
 + "Ptr", res,      ; VARIANT    *pVarResult
 + "Ptr", 0,        ; EXCEPINFO  *pExcepInfo
 + "Ptr", 0,        ; UINT       *puArgErr
 + "Int" ; HRESULT
 +)
 +</code>
 +
 +</tabbox>
  
 ---- ----