<div class="content" name="OpenKey" uuid="a54be1d0-009a-493d-a53e-e2f7fbe87293"><p>The OpenKey method opens a node for read access, write
access, or both. The returned handle can be used by several of the other
methods in the <a href="d1031bb7-b690-455e-ab66-5e6cd757ab9b" data-linktype="relative-path">IMSAdminBaseW</a>
interface.</p><dl>
<dd>
<div><pre> HRESULT OpenKey(
   [in] METADATA_HANDLE hMDHandle,
   [unique, in, string] LPCWSTR pszMDPath,
   [in] DWORD dwMDAccessRequested,
   [in] DWORD dwMDTimeOut,
   [out] METADATA_HANDLE* phMDNewHandle
 );
</pre></div>
</dd></dl><p><b>hMDHandle: </b>An unsigned 32-bit integer value
containing a handle to a node in the <a href="1243ba70-74ca-44f9-be0b-dfd6697010b4#gt_086b13f2-2715-4000-a16c-6acc3d59cc19" data-linktype="relative-path">metabase</a> with read
permissions as returned by the OpenKey method or the metabase master root
handle (0x00000000).</p><p><b>pszMDPath: </b>A pointer to a Unicode string that
contains the path of the node to be opened, relative to the <i>hMDHandle</i>
parameter.</p><p><b>dwMDAccessRequested: </b>A set of bit flags
specifying the requested permissions for the handle. This parameter MUST be set
to at least one of the following values.</p><dl>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Value</p>
   </th>
   <th>
   <p>Meaning</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>METADATA_PERMISSION_READ 0x00000001</td>
  <td>Open the node for reading.</td>
 </tr><tr>
  <td>METADATA_PERMISSION_WRITE 0x00000002</td>
  <td>Open the node for writing.</td>
 </tr></tbody></table>
</dd></dl><p><b>dwMDTimeOut: </b>An unsigned 32-bit integer value
specifying the time, in milliseconds, for the method to wait on a successful
open operation.</p><p><b>phMDNewHandle: </b>A pointer to the newly opened
metadata handle (see <a href="../ms-dtyp/262627d8-3418-4627-9218-4ffe110850b2" data-linktype="relative-path">DWORD</a>).</p><p><b>Return Values: </b>A signed 32-bit value that
indicates return status. If the method returns a negative value, it failed. If
the 12-bit facility code (bits 16–27) is set to 0x007, the value contains a
Win32 error code in the lower 16 bits. Zero or positive values indicate
success, with the lower 16 bits in positive nonzero values containing warnings
or flags defined in the method implementation. For more information about Win32
error codes and <a href="../ms-dtyp/a9046ed2-bfb2-4d56-a719-2824afce59ac" data-linktype="relative-path">HRESULT</a>
values, see <a href="../ms-erref/1bc92ddf-b79e-413c-bbaa-99a5281a6c90" data-linktype="relative-path">[MS-ERREF]</a>.</p><dl>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Return value/code</p>
   </th>
   <th>
   <p>Description</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>0x00000000 S_OK</td>
  <td>The call was successful.</td>
 </tr><tr>
  <td>0x80070003 ERROR_PATH_NOT_FOUND</td>
  <td>The system cannot find the path specified.</td>
 </tr><tr>
  <td>0x80070006 ERROR_INVALID_HANDLE</td>
  <td>The handle is invalid.</td>
 </tr><tr>
  <td>0x80070094 ERROR_PATH_BUSY</td>
  <td>The path specified cannot be used at this time.</td>
 </tr><tr>
  <td>0x80070057 E_INVALIDARG</td>
  <td>One or more arguments are invalid.</td>
 </tr></tbody></table>
</dd></dl><p>The <b>opnum</b> field value for this method is 17. </p><p>When processing this call, the <a href="1243ba70-74ca-44f9-be0b-dfd6697010b4#gt_434b0234-e970-4e8c-bdfa-e16a30d96703" data-linktype="relative-path">server</a> MUST do the
following:</p><ul><li><p><span><span> 
</span></span>Check the handle parameter. This handle is valid if it is either
the master root handle or a handle returned from a previous OpenKey call. If
the handle is invalid, return ERROR_INVALID_HANDLE error.</p>
</li><li><p><span><span> 
</span></span>Check that the relative path points to a valid node; otherwise,
return ERROR_PATH_NOT_FOUND.</p>
</li><li><p><span><span> 
</span></span>Determine if it is possible to provide the required access type
for the destination node with the path combined from the parent handle path and
the relative path.</p>
</li><li><p><span><span> 
</span></span>If the destination node represents the root of the metabase and
the requested access is for write, the server returns an error.</p>
</li><li><p><span><span> 
</span></span>If the destination node falls into part of the metabase that is
locked as described in <a href="cc341011-6012-4be9-9787-e5cf58869dc7" data-linktype="relative-path">3.1.1</a>,
the server SHOULD attempt to provide access during the time-out, which is
passed as a parameter. If, after this time-out, the node is still locked, the
server SHOULD return ERROR_PATH_BUSY.<a id="Appendix_A_Target_3"></a><a aria-label="Product behavior note 3" href="88fd1df0-e63e-41ca-9bf3-bedcab57cd86#Appendix_A_3" data-linktype="relative-path">&lt;3&gt;</a></p>
</li><li><p><span><span> 
</span></span>If access could be provided, the server calculates the handle of
the destination node, increases its lock count, and saves its state.</p>
</li></ul><p>Return the following information to the client:</p><ul><li><p><span><span> 
</span></span>The handle of the opened node.</p>
</li></ul></div>