ComObjActive() [AHK_L 53+]

Retrieves a running object that has been registered with OLE.

ComObject := ComObjActive(CLSID)

Creates an object representing a typed value to be passed as a parameter or return value.

ParamObj := ComObject(VarType, Value , Flags)

DEPRECATED:

The usages shown below are deprecated and may be altered or unavailable in a future release.

Creates an object which may be used in place of an optional parameter's default value when calling a method of a COM object. [v1.1.12+]: This function is obsolete. Instead, simply write two consecutive commas, as in Obj.Method(1,,3)

ParamObj := ComObjMissing()

Wraps or unwraps a raw IDispatch pointer in a usable object and automatically calls AddRef.

ComObject := ComObjEnwrap(DispPtr)
DispPtr := ComObjUnwrap(ComObject)

To write more future-proof code, use the following instead:

ComObject := ComObject(9, DispPtr, 1), ObjAddRef(DispPtr)
DispPtr := ComObjValue(ComObject), ObjAddRef(DispPtr)

Parameters

CLSID

CLSID or human-readable Prog ID of the COM object to retrieve.

ComObject

COM object usable with object syntax.

VarType

An integer indicating the type of value. See ComObjType() for a list of types.

Value

The value to wrap. Currently only integer and pointer values are supported.

Flags

Flags affecting the behaviour of this function and the wrapper object; see below.

DispPtr

Raw IDispatch pointer.

Flags

ByRef [v1.1.17+]

If a wrapper object's VarType includes the VT_BYREF (0x4000) flag, empty brackets [] can be used to read or write the referenced value.

When creating a reference, Value must be the memory address of a variable or buffer with sufficient capacity to store a value of the given type. For example, the following can be used to create a variable which a VBScript function can write into:

VarSetCapacity(var, 24, 0)
vref := ComObject(0x400C, &var)  ; 0x400C is a combination of VT_BYREF and VT_VARIANT.

vref[] := "in value"
sc.Run("Example", vref)  ; sc should be initialized as in the example below.
MsgBox % vref[]

General Remarks

In current versions, any function-call beginning with "ComObj" that does not match one of the other COM functions actually calls ComObjActive. For example, ComObjEnwrap(DispPtr) and ComObjActive(DispPtr) are both equivalent to ComObject(DispPtr) (VarType 9 is implied). However, this behaviour will be unavailable in a future release, so it is best to use only ComObject() and ComObjActive() as shown on this page.

If ComObjActive cannot retrieve an active object, it may throw an exception, exit the script or return an empty string, depending on the current ComObjError setting and other factors.

When this function is used to wrap or retrieve an IDispatch or IUnknown interface pointer, the default behaviour is to increment the COM object's reference count. Therefore, the interface pointer must be manually released when it is no longer needed. When the wrapper object is freed, the reference it contains is automatically released.

Known limitation: Each time a COM object is wrapped, a new wrapper object is created. Comparisons and assignments such as obj1 == obj2 and array[obj1] := value treat the two wrapper objects as unique, even though they contain the same COM object.

Related

ComObjCreate, ComObjGet, ComObjConnect, ComObjError, ComObjFlags, ObjAddRef/ObjRelease, ComObjQuery, GetActiveObject (MSDN)

Examples

ComObjUnwrap: See ComObjConnect.

; Preamble - ScriptControl requires a 32-bit version of AutoHotkey.
code =
(
Sub Example(Var)
    MsgBox Var
    Var = "out value!"
End Sub
)
sc := ComObjCreate("ScriptControl"), sc.Language := "VBScript", sc.AddCode(code)


; Example: Pass a VARIANT ByRef to a COM function.
var := ComVar()
var[] := "in value"
sc.Run("Example", var.ref)
MsgBox % var[]


; ComVar: Creates an object which can be used to pass a value ByRef.
;   ComVar[] retrieves the value.
;   ComVar[] := Val sets the value.
;   ComVar.ref retrieves a ByRef object for passing to a COM function.
ComVar(Type=0xC)
{
    static base := { __Get: "ComVarGet", __Set: "ComVarSet", __Delete: "ComVarDel" }
    ; Create an array of 1 VARIANT.  This method allows built-in code to take
    ; care of all conversions between VARIANT and AutoHotkey internal types.
    arr := ComObjArray(Type, 1)
    ; Lock the array and retrieve a pointer to the VARIANT.
    DllCall("oleaut32\SafeArrayAccessData", "ptr", ComObjValue(arr), "ptr*", arr_data)
    ; Store the array and an object which can be used to pass the VARIANT ByRef.
    return { ref: ComObject(0x4000|Type, arr_data), _: arr, base: base }
}

ComVarGet(cv, p*) { ; Called when script accesses an unknown field.
    if p.MaxIndex() = "" ; No name/parameters, i.e. cv[]
        return cv._[0]
}

ComVarSet(cv, v, p*) { ; Called when script sets an unknown field.
    if p.MaxIndex() = "" ; No name/parameters, i.e. cv[]:=v
        return cv._[0] := v
}

ComVarDel(cv) { ; Called when the object is being freed.
    ; This must be done to allow the internal array to be freed.
    DllCall("oleaut32\SafeArrayUnaccessData", "ptr", ComObjValue(cv._))
}