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 := ComObjParameter(VarType, Value [, Flags])
Creates an object which may be used in place of an optional parameter's default value when calling a method of a COM object.
ParamObj := ComObjMissing()
Wraps or unwraps a raw IDispatch pointer in a usable object.
ComObject := ComObjEnwrap(DispPtr) DispPtr := ComObjUnwrap(ComObject)
| 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. |
| 0 | Default behaviour. AddRef is called automatically for IUnknown and IDispatch pointers, so the caller should use ObjRelease to release their copy of the pointer if appropriate. |
| 1 | Take ownership of an IUnknown, IDispatch or SAFEARRAY pointer. AddRef is not called. If the wrapper object contains a SAFEARRAY (excluding VT_BYREF), SafeArrayDestroy is called automatically when the wrapper object is freed. |
ComObjActive is polymorphic; that is, any function-call beginning with "ComObj" that does not match one of the other COM functions actually calls ComObjActive. For example, ComObj(9, DispPtr) and ComObjActive(DispPtr) are both equivalent to ComObjEnwrap(DispPtr). However, as this behaviour may be changed (or new functions may be implemented) in a future version, it is best to use only the forms demonstrated on this page, with the addition that "ComObject" may be used in place of ComObjEnwrap or ComObjParameter.
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. As a general rule, the script's original copy of the pointer is considered a separate reference which must be manually released by the script when it is no longer needed. When the wrapper object is freed, it also releases its reference to the COM object.
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.
ComObjCreate, ComObjGet, ComObjConnect, ComObjError, ComObjFlags, ObjAddRef/ObjRelease, GetActiveObject (MSDN)
ComObjUnwrap: See ComObjConnect.
; Example: Pass a VARIANT ByRef to a COM function.
code =
(
Sub Example(Var)
MsgBox Var
Var = "out value!"
End Sub
)
sc := ComObjCreate("ScriptControl"), sc.Language := "VBScript", sc.AddCode(code)
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: ComObjParameter(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._))
}