</head> <body> <h1>ComObjActive() 和相关函数 <span class="ver">[AHK_L 53+]</span></h1> <h2 id="toc">目录</h2> <ul> <li><a href="#ComObjActive">ComObjActive()</a>: 检索注册的 COM 对象.</li> <li><a href="#ComObject">ComObject()</a>: 包装一个要作为参数或返回值传递的值和类型.</li> <li><a href="#ComObjParameter">ComObjParameter()</a>: 包装要作为参数传递的值和类型.</li> <li><a href="#ComObjMissing">ComObjMissing()</a>: 创建一个传递给 COM 方法的 "缺参数" 对象.</li> <li><a href="#ComObjEnwrapUnwrap">ComObjEnwrap() / ComObjUnwrap()</a>: 包装/拆包 COM 对象.</li> <li><a href="#Remarks">备注</a></li> <li><a href="#Related">相关</a></li> <li><a href="#Examples">示例</a></li> </ul> <h2 id="ComObjActive">ComObjActive()</h2> <p>检索已使用 OLE(对象连接与嵌入) 注册的运行对象.</p> <pre class="Syntax">ComObject := <span class="func">ComObjActive</span>(CLSID)</pre> <h3 id="ComObjActive_Parameters">参数</h3> <dl> <dt>CLSID</dt> <dd><p>要检索的 COM 对象的 CLSID 或可读 Prog ID.</p></dd> </dl> <h3 id="ComObjActive_Return_Value">返回值</h3> <p>该函数返回一个新的 COM 包装对象, 其<a href="ComObjType.htm#vt">变量类型</a>为 VT_DISPATCH(9).</p> <h2 id="ComObject">ComObject()</h2> <p>创建一个表示要作为参数或返回值传递的类型化值的对象.</p> <pre class="Syntax">ParamObj := <span class="func">ComObject</span>(VarType, Value <span class="optional">, Flags</span>)</pre> <h3 id="ComObject_Parameters">参数</h3> <dl> <dt>VarType</dt> <dd><p>表示值类型的整数. 类型列表见 <a href="ComObjType.htm#vt">ComObjType()</a>.</p></dd> <dt>Value</dt> <dd><p>要包装的值. 当前仅支持整数值和指针值.</p></dd> <dt>Flags</dt> <dd><p>影响此函数和包装器对象行为的标志, 请参阅下表.</p></dd> </dl> <h3 id="ComObject_Return_Value">返回值</h3> <p>此函数返回一个包装对象, 其中包含<a href="ComObjType.htm#vt">变量类型</a>和值或指针.</p> <h3 id="Flags">Flags</h3> <table class="info"> <tr> <th class="center">Flag</th> <th>作用</th> </tr> <tr> <td class="center">0</td> <td> <p>默认行为. <a href="https://learn.microsoft.com/windows/win32/api/unknwn/nf-unknwn-iunknown-addref">AddRef(增加引用)</a> 自动调用 IUnknown 和 IDispatch 的指针, 所以调用者应该适当使用 <a href="ObjAddRef.htm">ObjRelease()</a> 释放指针的副本.</p> <p>未来版本中可能改变此默认行为, 因此建议当包装接口指针时总是设置 <em>标志</em> 为 <code>1</code>, 需要时再调用 <a href="ObjAddRef.htm">ObjAddRef()</a>.</p> </td> </tr> <tr> <td class="center">1</td> <td>取得 IUnknown, IDispatch 或 SAFEARRAY(安全数组) 指针的所有权. 不调用 AddRef. 如果包装器对象包含 SAFEARRAY(VT_BYREF 除外), 那么当包装器对象被释放时会自动调用 <a href="https://learn.microsoft.com/windows/win32/api/oleauto/nf-oleauto-safearraydestroy">SafeArrayDestroy</a>.</td> </tr> </table> <h3 id="ByRef">ByRef <span class="ver">[v1.1.17+]</span></h3> <p>如果包装器对象的 <a href="ComObjType.htm"><em>变量类型</em></a> 包含 VT_BYREF(0x4000) 标签, 可用空的方括号对 <code>[]</code> 来读写引用的值.</p> <p>当创建一个引用, <em>值</em> 须为变量的内存地址, 或足够存储指定类型的值的缓存. 例如, 下面的代码可以用来创建一个 VBScript 函数可以写入的变量:</p> <pre>VarSetCapacity(var, 24, 0) vref := ComObject(0x400C, &amp;var) <em>; 0x400C 是 VT_BYREF 与 VT_VARIANT 组合而得.</em> vref[] := "in value" sc.Run("Example", vref) <em>; sc 应像<a href="#ByRefEx">下面例子</a>一样进行初始化.</em> MsgBox % vref[]</pre> <p>请注意, 尽管在通过 <code>vref[]</code> 或 COM 方法分配新值时, 任何先前的值都会被释放, 但最终的值不会被自动释放. 释放该值需要知道它是哪种类型. 因为如果是 VT_VARIANT, 它可以通过使用 <a href="DllCall.htm">DllCall</a> 调用 <a href="https://learn.microsoft.com/windows/win32/api/oleauto/nf-oleauto-variantclear">VariantClear</a>, 或使用一个更简单的方法来释放: 赋值一个整数, 如 <code>vref[] := 0</code>.</p> <h2 id="ComObjParameter">ComObjParameter()</h2> <p class="warning"><strong>过时的:</strong> 不推荐在新脚本中使用此函数. 使用 <a href="#ComObject">ComObject()</a> 代替.</p> <p>创建一个对象, 该对象表示要作为参数传递的类型化值.</p> <pre class="Syntax">ParamObj := <span class="func">ComObjParameter</span>(VarType, Value <span class="optional">, Flags</span>)</pre> <p>有关详情, 请参阅上文的 <a href="#ComObject">ComObject()</a>.</p> <h2 id="ComObjMissing">ComObjMissing()</h2> <p class="warning"><span class="ver">[v1.1.12+]</span> <strong>过时的:</strong> 不推荐在新脚本中使用此函数. 而是, 简单的书写两个连续的逗号, 如 <code>Obj.Method(1,,3)</code>.</p> <p>在调用 COM(组件对象模型) 对象的方法时创建一个可用于替代可选参数默认值的对象.</p> <pre class="Syntax">ParamObj := <span class="func">ComObjMissing</span>()</pre> <h3 id="ComObjMissing_Return_Value">返回值</h3> <p>该函数返回一个<a href="ComObjType.htm#vt">变量类型</a>为 VT_ERROR(0xA) 的包装对象.</p> <div id="ComObjEnwrap"><div id="ComObjUnwrap"><h2 id="ComObjEnwrapUnwrap">ComObjEnwrap() / ComObjUnwrap()</h2></div></div> <p class="warning"><strong>过时的:</strong> 不推荐在新脚本中使用这些函数. 请参阅下文的<a href="#ComObjEnwrap_Remarks">备注</a>.</p> <p id="enwrap">装包或拆包位于可用对象的原始 <a href="https://learn.microsoft.com/windows/win32/winauto/idispatch-interface">IDispatch</a> 指针, 并自动调用 AddRef(增加引用).</p> <pre class="Syntax"> ComObject := <span class="func">ComObjEnwrap</span>(DispPtr) DispPtr := <span class="func">ComObjUnwrap</span>(ComObject) </pre> <h3 id="ComObjEnwrap_Parameters">参数</h3> <dl> <dt>ComObject</dt> <dd><p>可以使用<a href="../Objects.htm#Usage_Objects">对象语法</a>的 COM 对象.</p></dd> <dt>DispPtr</dt> <dd><p>原始的 IDispatch 指针.</p></dd> </dl> <h3 id="ComObjEnwrap_Return_Value">返回值</h3> <p>ComObjEnwrap 返回一个可用<a href="../Objects.htm#Usage_Objects">对象语法</a>的 COM 对象. ComObjUnwrap 返回一个原始的 IDispatch 指针.</p> <h3 id="ComObjEnwrap_Remarks">备注</h3> <p>要编写更多面向未来的代码, 请改用以下代码:</p> <pre>ComObject := ComObject(9, DispPtr, 1), ObjAddRef(DispPtr) DispPtr := <a href="ComObjValue.htm">ComObjValue</a>(ComObject), ObjAddRef(DispPtr)</pre> <p>相关示例, 请参阅 <a href="ComObjConnect.htm#Examples">ComObjConnect()</a>.</p> <h2 id="Remarks">备注</h2> <p>当前版本中, 任何以 "ComObj" 开头的函数调用, 如果不匹配目录列表中的其他 COM 函数, 则实际调用 ComObjActive 函数. 如, <code>ComObjEnwrap(DispPtr)</code> 及 <code>ComObjActive(DispPtr)</code> 均等效于 <code>ComObject(DispPtr)</code>(隐式地, <em>变量类型</em> 为 9). 此行为可能于后续版本不再可用, 故建议仅使用本页所展示的 <code>ComObject()</code> 及 <code>ComObjActive()</code>.</p> <p>如果 ComObjActive 不能检索活动的对象, 则可能会抛出异常, 退出脚本或返回空字符串, 具体取决于当前的 <a href="ComObjError.htm">ComObjError()</a> 设置和<a href="ComObjError.htm#factors">其他因素</a>.</p> <p>当使用此函数包装或检索 IDispatch 或 IUnknown 接口指针时, 默认的行为会增加 COM 对象的引用计数. 因此, 当不使用时, 须<a href="ObjAddRef.htm">手动释放</a>接口指针. 当用于封装的对象被释放时, 它所包含的引用被自动释放.</p> <p><b>已知限制:</b> 每次包装 COM 对象时, 都会创建新的包装器对象. 如 <code>if (obj1 == obj2)</code>, <code>array[obj1] := value</code> 这样的比较和赋值运算, 会把两个包装器对象视为独立的, 即使它们包含相同的 COM 对象.</p> <h2 id="Related">相关</h2> <p><a href="ComObjCreate.htm">ComObjCreate()</a>, <a href="ComObjGet.htm">ComObjGet()</a>, <a href="ComObjConnect.htm">ComObjConnect()</a>, <a href="ComObjError.htm">ComObjError()</a>, <a href="ComObjFlags.htm">ComObjFlags()</a>, <a href="ObjAddRef.htm">ObjAddRef() / ObjRelease()</a>, <a href="ComObjQuery.htm">ComObjQuery()</a>, <a href="https://learn.microsoft.com/windows/win32/api/oleauto/nf-oleauto-getactiveobject">GetActiveObject (Microsoft Docs)</a></p> <h2 id="Examples">示例</h2> <div class="ex" id="ByRefEx"> <p><a class="ex_number" href="#ByRefEx"></a> 传递 VARIANT ByRef 给 COM 函数.</p> <pre> <em>; 条件 - ScriptControl 需 32 位版本的 AutoHotkey.</em> code = ( Sub Example(Var) MsgBox Var Var = "out value!" End Sub ) sc := <a href="ComObjCreate.htm">ComObjCreate</a>("ScriptControl"), sc.Language := "VBScript", sc.AddCode(code) <em>; 示例: 传递 VARIANT ByRef 至 COM 函数.</em> var := ComVar() var[] := "in value" <em>; 使用 [] 来赋值.</em> sc.Run("Example", var.ref) <em>; 传递 VT_BYREF ComObject (.ref).</em> MsgBox % var[] <em>; 使用 [] 来检索值.</em> <em>; 同样的事情, 但更直接:</em> VarSetCapacity(variant_buf, 24, 0) <em>; 使 VARIANT 的缓冲足够大.</em> var := ComObject(0x400C, &amp;variant_buf) <em>; 引用 VARIANT.</em> var[] := "in value" sc.Run("Example", var) <em> ; 传递 VT_BYREF ComObject 本身, 没有 [] 或 .ref.</em> MsgBox % var[] <em>; 如果 VARIANT 包含一个字符串或对象, 必须显式地释放它 ; 通过调用 VariantClear 或赋值一个纯数字值来释放:</em> var[] := 0 <em>; ComVar: 创建可用于按引用(ByRef) 传值的对象. ; ComVar[] 返回值. ; ComVar[] := Val 设置值. ; ComVar.ref 返回用于 COM 函数的按引用传值的对象.</em> ComVar(Type := 0xC) { static base := { __Get: Func("ComVarGet"), __Set: Func("ComVarSet") , __Delete: Func("ComVarDel") } <em>; 有关 base, 请参阅自定义对象. ; 基于 base 创建一个新的对象.</em> cv := {base: base} <em>; 为 VARIANT 分配内存, 以保存我们的值. ; 即使 Type != VT_VARIANT 也会使用 VARIANT, 以便 VariantClear 可以被 __delete 使用.</em> cv.SetCapacity("buf", 24), ptr := cv.GetAddress("buf") NumPut(0, NumPut(0, ptr+0, "int64"), "int64") if (Type != 0xC) { <em>; 不是 VT_VARIANT.</em> NumPut(Type, ptr+0, "ushort") <em>; 为 __delete 设置变量类型.</em> ptr += 8 <em>; 实际值的指针.</em> } <em>; 创建一个对象, 可以用来传递变量 ByRef.</em> cv.ref := ComObject(0x4000|Type, ptr) return cv } ComVarGet(cv, p*) { <em>; 当脚本访问未知字段时调用.</em> if p.MaxIndex() = "" <em>; 没有名称/参数, 如, cv[]</em> return cv.ref[] } ComVarSet(cv, v, p*) { <em>; 当脚本设置未知字段时调用.</em> if p.MaxIndex() = "" <em>; 没有名称/参数, 如, cv[]:=v</em> return cv.ref[] := v } ComVarDel(cv) { <em>; 当对象被释放时调用. ; 根据类型的不同, 如果设置了, 可能需要释放这个值.</em> DllCall("oleaut32\VariantClear", "ptr", cv.GetAddress("buf")) } </pre> </div> </body> </html>