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 [2024-01-16 16:36] – Fix up some wording geekguides:com:start [2025-03-26 12:36] (current) – [IDispatch Objects] Demote header level geek
Line 72: Line 72:
  
 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. 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>
  
 ---- ----