PageRenderTime 59ms CodeModel.GetById 27ms RepoModel.GetById 1ms app.codeStats 0ms

/docs/commands/ComObjActive.htm

https://github.com/Lexikos/AutoHotkey_L-Docs
HTML | 176 lines | 144 code | 32 blank | 0 comment | 0 complexity | 54459a69cd6f3e35a64bf4ae0157cbca MD5 | raw file
    

  1. <!DOCTYPE HTML>
    2. 

  2. <html lang="en">
    3. 

  3. <head>
    4. 

  4. <title>ComObjActive() - Syntax &amp; Usage | AutoHotkey</title>
    5. 

  5. <meta name="description" content="The ComObjActive function retrieves a running object that has been registered with OLE." />
    6. 

  6. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    7. 

  7. <meta http-equiv="X-UA-Compatible" content="IE=edge">
    8. 

  8. <link href="../static/theme.css" rel="stylesheet" type="text/css" />
    9. 

  9. <script src="../static/content.js" type="text/javascript"></script>
    10. 

  10. </head>
    11. 

  11. <body>
    12. 

  12. 

  13. <h1>ComObjActive() <span class="ver">[AHK_L 53+]</span></h1>
    14. 

  14. 

  15. <p>Retrieves a running object that has been registered with OLE.</p>
    16. 

  16. <pre class="Syntax">ComObject := <span class="func">ComObjActive</span>(CLSID)</pre>
    17. 

  17. 

  18. <p id="param">Creates an object representing a typed value to be passed as a parameter or return value.</p>
    19. 

  19. <pre class="Syntax">ParamObj := <span class="func">ComObject</span>(VarType, Value <span class="optional">, Flags</span>)</pre>
    20. 

  20. <hr>
    21. 

  21. <p class="warning"><strong>Deprecated:</strong> The usages shown below are deprecated and may be altered or unavailable in a future release.</p>
    22. 

  22. <p id="missing">Creates an object which may be used in place of an optional parameter's default value when calling a method of a COM object. <span class="ver">[v1.1.12+]</span>: This function is obsolete. Instead, simply write two consecutive commas, as in <code>Obj.Method(1,,3)</code></p>
    23. 

  23. <pre class="Syntax">ParamObj := <span class="func">ComObjMissing</span>()</pre>
    24. 

  24. 

  25. <p id="enwrap">Wraps or unwraps a raw <a href="http://msdn.microsoft.com/en-us/library/dd318520.aspx">IDispatch</a> pointer in a usable object and automatically calls AddRef.</p>
    26. 

  26. <pre class="Syntax">
    27. 

  27. ComObject := <span class="func">ComObjEnwrap</span>(DispPtr)
    28. 

  28. DispPtr := <span class="func">ComObjUnwrap</span>(ComObject)
    29. 

  29. </pre>
    30. 

  30. <p>To write more future-proof code, use the following instead:</p>
    31. 

  31. <pre>ComObject := ComObject(9, DispPtr, 1), ObjAddRef(DispPtr)
    32. 

  32. DispPtr := <a href="ComObjValue.htm">ComObjValue</a>(ComObject), ObjAddRef(DispPtr)</pre>
    33. 

  33. <hr>
    34. 

  34. 

  35. <h2 id="Parameters">Parameters</h2>
    36. 

  36. <dl>
    37. 

  37. 

  38.   <dt>CLSID</dt>
    39. 

  39.   <dd><p>CLSID or human-readable Prog ID of the COM object to retrieve.</p></dd>
    40. 

  40. 

  41.   <dt>ComObject</dt>
    42. 

  42.   <dd><p>COM object usable with <a href="../Objects.htm#Usage_Objects">object syntax</a>.</p></dd>
    43. 

  43. 

  44.   <dt>VarType</dt>
    45. 

  45.   <dd><p>An integer indicating the type of value. See <a href="ComObjType.htm#vt">ComObjType()</a> for a list of types.</p></dd>
    46. 

  46. 

  47.   <dt>Value</dt>
    48. 

  48.   <dd><p>The value to wrap. Currently only integer and pointer values are supported.</p></dd>
    49. 

  49. 

  50.   <dt>Flags</dt>
    51. 

  51.   <dd><p>Flags affecting the behaviour of this function and the wrapper object; see below.</p></dd>
    52. 

  52. 

  53.   <dt>DispPtr</dt>
    54. 

  54.   <dd><p>Raw IDispatch pointer.</p></dd>
    55. 

  55. 

  56. </dl>
    57. 

  57. 

  58. <h2 id="Flags">Flags</h2>
    59. 

  59. <table class="info">
    60. 

  60.   <tr>
    61. 

  61.     <th class="center">Flag</th>
    62. 

  62.     <th>Effect</th>
    63. 

  63.   </tr>
    64. 

  64.   <tr>
    65. 

  65.     <td class="center">0</td>
    66. 

  66.     <td>
    67. 

  67.       <p>Default behaviour. <a href="http://msdn.microsoft.com/en-us/library/ms691379.aspx">AddRef</a> is called automatically for IUnknown and IDispatch pointers, so the caller should use <a href="ObjAddRef.htm">ObjRelease()</a> to release their copy of the pointer if appropriate.</p>
    68. 

  68.       <p>As the default behaviour may be changing in a future release, it is recommended to always set <em>Flags</em> to <code>1</code> when wrapping an interface pointer, and call <a href="ObjAddRef.htm">ObjAddRef()</a> if needed.</p>
    69. 

  69.     </td>
    70. 

  70.   </tr>
    71. 

  71.   <tr>
    72. 

  72.     <td class="center">1</td>
    73. 

  73.     <td>Take ownership of an IUnknown, IDispatch or SAFEARRAY pointer. AddRef is not called. If the wrapper object contains a SAFEARRAY (excluding VT_BYREF), <a href="https://msdn.microsoft.com/en-us/library/ms221702(v=vs.85).aspx">SafeArrayDestroy</a> is called automatically when the wrapper object is freed.</td>
    74. 

  74.   </tr>
    75. 

  75. </table>
    76. 

  76. 

  77. <h2 id="ByRef">ByRef <span class="ver">[v1.1.17+]</span></h2>
    78. 

  78. <p>If a wrapper object's <a href="ComObjType.htm"><em>VarType</em></a> includes the VT_BYREF (0x4000) flag, empty brackets <code>[]</code> can be used to read or write the referenced value.</p>
    79. 

  79. <p>When creating a reference, <em>Value</em> must be the memory address of a variable or buffer with sufficient capacity to store a value of the given type. For example, the following can be used to create a variable which a VBScript function can write into:</p>
    80. 

  80. <pre>VarSetCapacity(var, 24, 0)
    81. 

  81. vref := ComObject(0x400C, &amp;var)  <em>; 0x400C is a combination of VT_BYREF and VT_VARIANT.</em>
    82. 

  82. 

  83. vref[] := "in value"
    84. 

  84. sc.Run("Example", vref)  <em>; sc should be initialized as in the <a href="#ByRefEx">example below</a>.</em>
    85. 

  85. MsgBox % vref[]</pre>
    86. 

  86. <p>Note that although any previous value is freed when a new value is assigned by <code>vref[]</code> or the COM method, the final value is not freed automatically. Freeing the value requires knowing which type it is. Because it is VT_VARIANT in this case, it can be freed by calling <a href="https://docs.microsoft.com/en-us/windows/win32/api/oleauto/nf-oleauto-variantclear">VariantClear</a> with <a href="DllCall.htm">DllCall</a> or by using a simpler method: assign an integer, such as <code>vref[] := 0</code>.</p>
    87. 

  87. 

  88. <h2 id="Remarks">General Remarks</h2>
    89. 

  89. <p>In current versions, any function-call beginning with "ComObj" that does not match one of the other COM functions actually calls ComObjActive. For example, <code>ComObjEnwrap(DispPtr)</code> and <code>ComObjActive(DispPtr)</code> are both equivalent to <code>ComObject(DispPtr)</code> (<em>VarType</em> 9 is implied). However, this behaviour will be unavailable in a future release, so it is best to use only <code>ComObject()</code> and <code>ComObjActive()</code> as shown on this page.</p>
    90. 

  90. <p>If ComObjActive cannot retrieve an active object, it may throw an exception, exit the script or return an empty string, depending on the current <a href="ComObjError.htm">ComObjError()</a> setting and <a href="ComObjError.htm#factors">other factors</a>.</p>
    91. 

  91. <p>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. Therefore, the interface pointer must be <a href="ObjAddRef.htm">manually released</a> when it is no longer needed. When the wrapper object is freed, the reference it contains is automatically released.</p>
    92. 

  92. <p><b>Known limitation:</b> Each time a COM object is wrapped, a new wrapper object is created. Comparisons and assignments such as <code>if (obj1 == obj2)</code> and <code>array[obj1] := value</code> treat the two wrapper objects as unique, even though they contain the same COM object.</p>
    93. 

  93. 

  94. <h2 id="Related">Related</h2>
    95. 

  95. <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="http://msdn.microsoft.com/en-us/library/ms221467.aspx">GetActiveObject (MSDN)</a></p>
    96. 

  96. 

  97. <h2 id="Examples">Examples</h2>
    98. 

  98. <p>ComObjUnwrap: See <a href="ComObjConnect.htm#Examples">ComObjConnect()</a>.</p>
    99. 

  99. <div class="ex" id="ByRefEx">
    100. 

  100. <p><a class="ex_number" href="#ByRefEx"></a> Passes a VARIANT ByRef to a COM function.</p>
    101. 

  101. <pre>
    102. 

  102. <em>; Preamble - ScriptControl requires a 32-bit version of AutoHotkey.</em>
    103. 

  103. code =
    104. 

  104. (
    105. 

  105. Sub Example(Var)
    106. 

  106.     MsgBox Var
    107. 

  107.     Var = "out value!"
    108. 

  108. End Sub
    109. 

  109. )
    110. 

  110. sc := <a href="ComObjCreate.htm">ComObjCreate</a>("ScriptControl"), sc.Language := "VBScript", sc.AddCode(code)
    111. 

  111. 

  112. 

  113. <em>; Example: Pass a VARIANT ByRef to a COM function.</em>
    114. 

  114. var := ComVar()
    115. 

  115. var[] := "in value"  <em>; Use [] to assign a value.</em>
    116. 

  116. sc.Run("Example", var.ref)  <em>; Pass the VT_BYREF ComObject (.ref).</em>
    117. 

  117. MsgBox % var[]  <em>; Use [] to retrieve a value.</em>
    118. 

  118. 

  119. <em>; The same thing again, but more direct:</em>
    120. 

  120. VarSetCapacity(variant_buf, 24, 0)  <em>; Make a buffer big enough for a VARIANT.</em>
    121. 

  121. var := ComObject(0x400C, &amp;variant_buf)  <em>; Make a reference to a VARIANT.</em>
    122. 

  122. var[] := "in value"
    123. 

  123. sc.Run("Example", var)  <em>; Pass the VT_BYREF ComObject itself, no [] or .ref.</em>
    124. 

  124. MsgBox % var[]
    125. 

  125. <em>; If a VARIANT contains a string or object, it must be explicitly freed
    126. 

  126. ; by calling VariantClear or assigning a pure numeric value:</em>
    127. 

  127. var[] := 0
    128. 

  128. 

  129. 

  130. <em>; ComVar: Creates an object which can be used to pass a value ByRef.
    131. 

  131. ;   ComVar[] retrieves the value.
    132. 

  132. ;   ComVar[] := Val sets the value.
    133. 

  133. ;   ComVar.ref retrieves a ByRef object for passing to a COM function.</em>
    134. 

  134. ComVar(Type := 0xC)
    135. 

  135. {
    136. 

  136.     static base := { __Get: Func("ComVarGet"), __Set: Func("ComVarSet")
    137. 

  137.         , __Delete: Func("ComVarDel") } <em>; For base, see Custom Objects.
    138. 

  138.     
    139. 

  139.     ; Create a new object based on base.</em>
    140. 

  140.     cv := {base: base}
    141. 

  141.     
    142. 

  142.     <em>; Allocate memory for a VARIANT to hold our value. VARIANT is used even
    143. 

  143.     ; when Type != VT_VARIANT so that VariantClear can be used by __delete.</em>
    144. 

  144.     cv.SetCapacity("buf", 24), ptr := cv.GetAddress("buf")
    145. 

  145.     NumPut(0, NumPut(0, ptr+0, "int64"), "int64")
    146. 

  146.     
    147. 

  147.     if (Type != 0xC) { <em>; Not VT_VARIANT.</em>
    148. 

  148.         NumPut(Type, ptr+0, "ushort") <em>; Set the variant type for __delete.</em>
    149. 

  149.         ptr += 8 <em>; Point to the actual value.</em>
    150. 

  150.     }
    151. 

  151.     
    152. 

  152.     <em>; Create an object which can be used to pass the variable ByRef.</em>
    153. 

  153.     cv.ref := ComObject(0x4000|Type, ptr)
    154. 

  154.     
    155. 

  155.     return cv
    156. 

  156. }
    157. 

  157. 

  158. ComVarGet(cv, p*) { <em>; Called when script accesses an unknown field.</em>
    159. 

  159.     if p.MaxIndex() = "" <em>; No name/parameters, i.e. cv[]</em>
    160. 

  160.         return cv.ref[]
    161. 

  161. }
    162. 

  162. 

  163. ComVarSet(cv, v, p*) { <em>; Called when script sets an unknown field.</em>
    164. 

  164.     if p.MaxIndex() = "" <em>; No name/parameters, i.e. cv[]:=v</em>
    165. 

  165.         return cv.ref[] := v
    166. 

  166. }
    167. 

  167. 

  168. ComVarDel(cv) { <em>; Called when the object is being freed.
    169. 

  169.     ; Depending on type, this may be needed to free the value, if set.</em>
    170. 

  170.     DllCall("oleaut32\VariantClear", "ptr", cv.GetAddress("buf"))
    171. 

  171. }
    172. 

  172. </pre>
    173. 

  173. </div>
    174. 

  174. 

  175. </body>
    176. 

  176. </html>
    177. 

  177.