ComObjActive() 和相关函数

该函数返回一个新的 COM 包装对象, 其变量类型为 VT_DISPATCH(9).

ComObject()

参数

返回值

Flags

Flag	作用
0	默认行为. AddRef(增加引用) 自动调用 IUnknown 和 IDispatch 的指针, 所以调用者应该适当使用 ObjRelease() 释放指针的副本. 未来版本中可能改变此默认行为, 因此建议当包装接口指针时总是设置标志为 `1`, 需要时再调用 ObjAddRef().
1	取得 IUnknown, IDispatch 或 SAFEARRAY(安全数组) 指针的所有权. 不调用 AddRef. 如果包装器对象包含 SAFEARRAY(VT_BYREF 除外), 那么当包装器对象被释放时会自动调用 SafeArrayDestroy.

ByRef [v1.1.17+]

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

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

请注意, 尽管在通过 vref[] 或 COM 方法分配新值时, 任何先前的值都会被释放, 但最终的值不会被自动释放. 释放该值需要知道它是哪种类型. 因为如果是 VT_VARIANT, 它可以通过使用 DllCall 调用 VariantClear, 或使用一个更简单的方法来释放: 赋值一个整数, 如 vref[] := 0.

ComObjParameter()

过时的: 不推荐在新脚本中使用此函数. 使用 ComObject() 代替.

ComObjMissing()

[v1.1.12+] 过时的: 不推荐在新脚本中使用此函数. 而是, 简单的书写两个连续的逗号, 如 Obj.Method(1,,3).

在调用 COM(组件对象模型) 对象的方法时创建一个可用于替代可选参数默认值的对象.

返回值

过时的: 不推荐在新脚本中使用这些函数. 请参阅下文的备注.

装包或拆包位于可用对象的原始 IDispatch 指针, 并自动调用 AddRef(增加引用).

参数

返回值

ComObjEnwrap 返回一个可用对象语法的 COM 对象. ComObjUnwrap 返回一个原始的 IDispatch 指针.

备注

当前版本中, 任何以 "ComObj" 开头的函数调用, 如果不匹配目录列表中的其他 COM 函数, 则实际调用 ComObjActive 函数. 如, ComObjEnwrap(DispPtr) 及 ComObjActive(DispPtr) 均等效于 ComObject(DispPtr)(隐式地, 变量类型 为 9). 此行为可能于后续版本不再可用, 故建议仅使用本页所展示的 ComObject() 及 ComObjActive().

如果 ComObjActive 不能检索活动的对象, 则可能会抛出异常, 退出脚本或返回空字符串, 具体取决于当前的 ComObjError() 设置和其他因素.

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

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

相关

示例

传递 VARIANT ByRef 给 COM 函数.

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

; 示例: 传递 VARIANT ByRef 至 COM 函数.
var := ComVar()
var[] := "in value"  ; 使用 [] 来赋值.
sc.Run("Example", var.ref)  ; 传递 VT_BYREF ComObject (.ref).
MsgBox % var[]  ; 使用 [] 来检索值.

; 同样的事情, 但更直接:
VarSetCapacity(variant_buf, 24, 0)  ; 使 VARIANT 的缓冲足够大.
var := ComObject(0x400C, &variant_buf)  ; 引用 VARIANT.
var[] := "in value"
sc.Run("Example", var)  ; 传递 VT_BYREF ComObject 本身, 没有 [] 或 .ref.
MsgBox % var[]
; 如果 VARIANT 包含一个字符串或对象, 必须显式地释放它
; 通过调用 VariantClear 或赋值一个纯数字值来释放:
var[] := 0

; ComVar: 创建可用于按引用(ByRef) 传值的对象.
;   ComVar[] 返回值.
;   ComVar[] := Val 设置值.
;   ComVar.ref 返回用于 COM 函数的按引用传值的对象.
ComVar(Type := 0xC)
{
    static base := { __Get: Func("ComVarGet"), __Set: Func("ComVarSet")
        , __Delete: Func("ComVarDel") } ; 有关 base, 请参阅自定义对象.
    ; 基于 base 创建一个新的对象.
    cv := {base: base}

    ; 为 VARIANT 分配内存, 以保存我们的值.
    ; 即使 Type != VT_VARIANT 也会使用 VARIANT, 以便 VariantClear 可以被 __delete 使用.
    cv.SetCapacity("buf", 24), ptr := cv.GetAddress("buf")
    NumPut(0, NumPut(0, ptr+0, "int64"), "int64")

    if (Type != 0xC) { ; 不是 VT_VARIANT.
        NumPut(Type, ptr+0, "ushort") ; 为 __delete 设置变量类型.
        ptr += 8 ; 实际值的指针.
    }

    ; 创建一个对象, 可以用来传递变量 ByRef.
    cv.ref := ComObject(0x4000|Type, ptr)

    return cv
}

ComVarGet(cv, p*) { ; 当脚本访问未知字段时调用.
    if p.MaxIndex() = "" ; 没有名称/参数, 如, cv[]
        return cv.ref[]
}

ComVarSet(cv, v, p*) { ; 当脚本设置未知字段时调用.
    if p.MaxIndex() = "" ; 没有名称/参数, 如, cv[]:=v
        return cv.ref[] := v
}

ComVarDel(cv) { ; 当对象被释放时调用.
    ; 根据类型的不同, 如果设置了, 可能需要释放这个值.
    DllCall("oleaut32\VariantClear", "ptr", cv.GetAddress("buf"))
}

ComObjActive() 和相关函数 [AHK_L 53+]

目录

ComObjActive()

参数

返回值

ComObject()

参数

返回值

Flags

ByRef [v1.1.17+]

ComObjParameter()

ComObjMissing()

返回值

ComObjEnwrap() / ComObjUnwrap()

参数

返回值

备注

备注

示例