ComObjActive() [AHK_L 53+]

检索已注册到 OLE 的正在运行的对象.

用户COM对象 := ComObjActive(CLSID)

创建表示作为参数或返回值传递的类型化值的对象.

参数对象 := ComObj(变量类型, 值 [, 标志])

不建议：

不推荐以下使用方法，后续版本中可能被替换或不再支持。

创建在调用 COM 对象的方法时可以用来代替可选参数默认值的对象. 自v1.1.12废弃：使用两个连续的逗号替换，如Obj.Method(1,,3)

参数对象 := ComObjMissing()

装包或拆包位于可用对象的原始IDispatch指针，并自动调用AddRef（增加引用）。

用户COM对象 := ComObjEnwrap(DispPtr)	;装包
DispPtr := ComObjUnwrap(用户COM对象)	;拆包

使用以下方式，使代码更可靠：

用户COM对象 := ComObject(9, DispPtr, 1), ObjAddRef(DispPtr)
DispPtr := ComObjValue(用户COM对象), ObjAddRef(DispPtr)

参数

CLSID: 要检索的 COM 对象的 CLSID 或可读 Prog ID.
用户COM对象: 可以使用对象语法的 COM 对象.
变量类型: 表示值类型的整数。类型列表见ComObjType()。
值: 要包装的值. 当前仅支持整数值和指针值.
标志: 影响此函数和包装器对象行为的标志，请参阅后面。
DispPtr: 原始的 IDispatch 指针.

标志

默认行为. 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，需要时再调用ObjAddRef()。

1 取得 IUnknown, IDispatch 或 SAFEARRAY（安全数组）指针的所有权. 不调用 AddRef. 如果包装器对象包含 SAFEARRAY (VT_BYREF 除外), 那么当包装器对象被释放时会自动调用 SafeArrayDestroy.

ByRef [v1.1.17+]

如果包装器对象的变量类型包含VT_BYREF (0x4000) 标签, 可用空的方括号对 []来读写引用的值.

当创建一个引用, 值须为变量的内存地址，或，足够存储指定类型的值的缓存。例如, 下面的代码可以用来创建一个VBScript函数可以写入的变量:

VarSetCapacity(var, 24, 0)
vref := ComObject(0x400C, &var)  ; 0x400C是VT_BYREF与VT_VARIANT组合而得.

vref[] := "in value"
sc.Run("Example", vref)  ; sc应像下面例子一样进行初始化.
MsgBox % vref[]

一般说明

当前版本中，除COM相关函数，任何以"ComObj"函数名开头的函数调用实际调用ComObjActive函数。如，ComObjEnwrap(DispPtr)及ComObjActive(DispPtr)均等效于ComObject(DispPtr)（隐式地，变量类型为9）。此行为可能于后续版本改变，故，建议仅使用本页所展示的ComObject()及ComObjActive()。

当使用此函数包装或检索 IDispatch 或 IUnknown 接口指针时, 默认的行为会增加 COM 对象的引用计数. 因此，当不使用时，须手动释放接口指针。. 当用于封装的对象被释放时，他所包含的引用被自动释放。

已知限制: 每次包装 COM 对象时, 都会创建新的包装器对象. 如 obj1 == obj2 、array[obj1] := value的比较和赋值运算, 会把两个包装器对象视为独立的, 即使它们包含相同的 COM 对象.

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

示例

ComObjUnwrap（COM对象拆包）: 参见ComObjConnect.

; 条件 - ScriptControl 需32位版本的AutoHotkey.
code =
(
Sub Example(Var)
    MsgBox Var
    Var = "输出了值!"
End Sub
)
sc := ComObjCreate("ScriptControl"), sc.Language := "VBScript", sc.AddCode(code)


; 示例: 传递VARIANT ByRef至COM函数.
var := ComVar()
var[] := "in value"
sc.Run("Example", var.ref)
MsgBox % var[]


; ComVar: 创建可用于按引用（ByRef）传值的对象。
;   ComVar[] 返回值。
;   ComVar[] := Val 设置值。
;   ComVar.ref 返回用于COM函数的按引用传值的对象。
ComVar(Type=0xC)
{
    static base := { __Get: "ComVarGet", __Set: "ComVarSet", __Delete: "ComVarDel" }
    ; 创建含 1 个 VARIANT 类型变量的数组.  此方法可以让内部代码处理
    ; 在 VARIANT 和 AutoHotkey 内部类型之间的所有转换.
    arr := ComObjArray(Type, 1)
    ;锁定数组并检索到 VARIANT 的指针.
    DllCall("oleaut32\SafeArrayAccessData", "ptr", ComObjValue(arr), "ptr*", arr_data)
    ;保存数组及可用于按引用传递VARIANT值的对象.
    return { ref: ComObject(0x4000|Type, arr_data), _: arr, base: base }
}

ComVarGet(cv, p*) { ; 当脚本访问未知字段时调用.
    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() = "" ; 没有名称/参数，如，cv[]:=v
        return cv._[0] := v
}

ComVarDel(cv) { ; 当对象被释放时调用.
    ; 必须进行这样的处理才能释放内部数组.
    DllCall("oleaut32\SafeArrayUnaccessData", "ptr", ComObjValue(cv._))
}