Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
| guides:com:start [2022-02-27 15:05] – ↷ Page moved and renamed from guides:com_object_reference to guides:com:start geek | guides:com:start [2025-03-26 12:36] (current) – [IDispatch Objects] Demote header level geek | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== COM Object Reference | + | ====== COM APIs ====== |
| - | [[ahk:com:htmlfile]] - Represents | + | > Via [[https:// |
| + | > | ||
| + | > The Microsoft Component Object Model (COM) is a platform-independent, | ||
| + | > | ||
| + | > To understand COM (and therefore all COM-based technologies), | ||
| - | [[ahk: | + | COM (the Component Object Model) is an object-oriented standard for designing objects (collections of function code called methods, and variable-like data called properties) to be accessible and usable across different programming languages. COM was designed by Microsoft and is reliant on the Windows API to function. Following the COM design, an application |
| - | [[ahk: | + | A COM component registered by a software package provides one or more globally unique identifiers (GUIDs), which are a 128-bit numbers formatted in hex like '' |
| - | [[ahk: | + | When your application retrieves an object from a COM component, that object can either connect to a new instance of the third-party code, or connect to an existing instance of the third-party code. For example, a COM Object registered by Microsoft Office could be requested to allow your application to manipulate documents in the background independently of any running Office applications. Or it could connect to a running application to allow manipulation of the document in a visible application window. |
| - | [[ahk: | + | Because of its flexibility, |
| - | [[ahk:com: | + | OLE: Under OLE, COM facilitates the embedding of objects representing documents of one type, within another type of document. For example, embedding a piece of media in a slideshow. Or embedding a spreadsheet in a text document. |
| - | [[ahk:com:shell.application]] - Access Explorer & IE Windows/ | + | ActiveX: Under ActiveX, COM facilitates the embedding of software within other software. For example, embedding a Java applet or a Flash player within a web browser. Or embedding a web browser within another desktop |
| - | [[ahk:com:shell.explorer]] - Embed an Explorer/ | + | [[https://en.wikipedia.org/ |
| - | [[ahk: | + | In short, COM was Microsoft' |
| - | [[ahk: | + | ===== Anatomy of a COM Object ===== |
| - | Windows Media Player - Play Media Files; Embed WMPlayer Control in a GUI. | + | A COM Object follows the %%C++%% [[https:// |
| - | [[ahk: | + | 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 " |
| - | [[ahk: | + | <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; | ||
| + | </ | ||
| - | [[ahk:com: | + | And an //object// with this interface would look like this: |
| + | <code c> | ||
| + | typedef struct IUnknown { | ||
| + | IUnknownVtbl* vtbl; | ||
| + | ... // any data fields go here | ||
| + | } IUnknown; | ||
| + | </ | ||
| - | **MS Office Applications** | + | So when you have a (pointer to a) COM object '' |
| + | - Retrieving the vtable: '' | ||
| + | - Retrieving the function reference at index '' | ||
| + | - Calling the function passing the object as the first parameter: '' | ||
| + | (or in AHKv2, by using ComCall which performs all those steps for you) | ||
| - | [[ahk: | + | 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: |
| - | [[ahk: | + | <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); | ||
| - | [[ahk: | + | // From IDispatch |
| + | __stdcall HRESULT(*GetTypeInfoCount)(IDispatch *This, | ||
| + | __stdcall HRESULT(*GetTypeInfo)(IDispatch * This, ...); | ||
| + | __stdcall HRESULT(*GetIDsOfNames)(IDispatch *This, ...); | ||
| + | __stdcall HRESULT(*Invoke)(IDispatch *This, ...); | ||
| + | } IDispatchVtbl; | ||
| + | </ | ||
| - | [[ahk:com:word.application]] | + | Therefore, the indexes of the IDispatch methods in the vtable start '' |
| + | ===== IDispatch Objects ===== | ||
| + | |||
| + | The IDispatch interface is Microsoft' | ||
| + | |||
| + | * (Optional) GetTypeInfoCount - Get the count of " | ||
| + | * (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 " | ||
| + | shell := ComObject(" | ||
| + | |||
| + | ; This call first invokes GetIDsOfNames to convert " | ||
| + | ; then it calls Invoke with that ID, specifying this should be a method call | ||
| + | ; with the given parameter " | ||
| + | shell.Exec(" | ||
| + | </ | ||
| + | |||
| + | <tabbox ComCall Syntax> | ||
| + | |||
| + | <code autohotkey> | ||
| + | #Requires AutoHotkey v2 | ||
| + | |||
| + | ; Retrieve a WScript.Shell IDispatch object using its human-readable ProgID. | ||
| + | ; You could also specify CLSID " | ||
| + | shell := ComObject(" | ||
| + | |||
| + | name := " | ||
| + | arg1 := " | ||
| + | |||
| + | ; Retreive the ID for method " | ||
| + | IID_NULL := Buffer(16, 0) | ||
| + | names := Buffer(A_PtrSize * 1, 0) | ||
| + | NumPut(" | ||
| + | ids := Buffer(16 * 1, 0) | ||
| + | ComCall(5, ComObjValue(shell), | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | ) | ||
| + | execId := NumGet(ids, " | ||
| + | |||
| + | ; Stage the arguments for the call | ||
| + | args := Buffer((8+A_PtrSize*2) * 1, 0) ; one argument | ||
| + | NumPut( | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | args | ||
| + | ) | ||
| + | dp := Buffer(A_PtrSize*2+8, | ||
| + | NumPut( | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | dp | ||
| + | ) | ||
| + | |||
| + | ; Call " | ||
| + | res := Buffer((8+A_PtrSize*2) * 1, 0) ; one result | ||
| + | ComCall(6, ComObjValue(shell), | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | ) | ||
| + | </ | ||
| + | |||
| + | </ | ||
| + | |||
| + | ---- | ||
| + | |||
| + | [[https:// | ||
| + | |||
| + | [[https:// | ||