ComObjActive()

AutoHotkey

ComObjActive() [AHK_L 53+]

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

ComObject := ComObjActive(CLSID)

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

ParamObj := ComObjParameter(VarType, Value [, Flags])

创建在调用 COM 对象的方法时可以用来代替可选参数默认值的对象.

ParamObj := ComObjMissing()

高级

包装或解开可用对象中的原始 IDispatch 指针.

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

参数

CLSID

要检索的 COM 对象的 CLSID 或可读 Prog ID.

ComObject

可以使用 对象语法 的 COM 对象.

VarType

表示值类型的整数. 请参阅 ComObjType() 了解类型列表.

要包装的值. 当前仅支持整数值和指针值.

Flags

影响此函数和包装器对象行为的标志,请参阅后面。

DispPtr

原始的 IDispatch 指针.

Flags

 0  默认行为. 为 IUnknown 和 IDispatch 指针自动调用 AddRef, 所以调用者应该在适当时使用 ObjRelease 释放这些指针副本.
 1  取得 IUnknown, IDispatch 或 SAFEARRAY 指针的所有权. 不调用 AddRef. 如果包装器对象包含 SAFEARRAY (VT_BYREF 除外), 那么当包装器对象被释放时会自动调用 SafeArrayDestroy.

一般说明

ComObjActive 是 多态的; 即任何名称以 "ComObj" 开始且不匹配其他某个 COM 函数的函数调用实际在调用 ComObjActive. 例如, ComObj(9, DispPtr)ComObjActive(DispPtr) 都等同于 ComObjEnwrap(DispPtr). 然而, 在未来的版本中此特性可能发生变化 (或实现了新的函数), 所以最好仅显示此页面中演示的形式, 此外 "ComObject" 可以用来代替 ComObjEnwrap 或 ComObjParameter.

当使用此函数包装或检索 IDispatch 或 IUnknown 接口指针时, 默认的行为会增加 COM 对象的引用数. 一般而言, 脚本中指针的原始副本被视为独立的引用, 当不再需要时必须在脚本中对其进行 手动释放. 释放包装器对象时, 也会同时释放其到 COM 对象的引用.

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

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

示例

ComObjUnwrap: 请参阅 ComObjConnect.

; 示例: 传递 VARIANT ByRef 到 COM 函数.

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: 创建用来传递 ByRef 值的对象.
;   ComVar[] 检索值.
;   ComVar[] := Val 设置值.
;   ComVar.ref 检索 ByRef 对象用于传递到 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 ByRef 的数组和对象.
    return { ref: ComObjParameter(0x4000|Type, arr_data), _: arr, base: base }
}
ComVarGet(cv, p*) { ; 当脚本访问未知字段时调用.
    if p.MaxIndex() = "" ; 没有名称/参数, 即 cv[]
        return cv._[0]
}
ComVarSet(cv, v, p*) { ; 当脚本设置未知字段时调用.
    if p.MaxIndex() = "" ; 没有名称/参数, 即 cv[]:=v
        return cv._[0] := v
}
ComVarDel(cv) { ; 当对象被释放时调用.
    ; 必须进行这样的处理以释放内部数组.
    DllCall("oleaut32\SafeArrayUnaccessData", "ptr", ComObjValue(cv._))
}