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 IMSAdminBaseW interface.

 HRESULT OpenKey(
   [in] METADATA_HANDLE hMDHandle,
   [unique, in, string] LPCWSTR pszMDPath,
   [in] DWORD dwMDAccessRequested,
   [in] DWORD dwMDTimeOut,
   [out] METADATA_HANDLE* phMDNewHandle
 );

hMDHandle: An unsigned 32-bit integer value containing a handle to a node in the metabase with read permissions as returned by the OpenKey method or the metabase master root handle (0x00000000).

pszMDPath: A pointer to a Unicode string that contains the path of the node to be opened, relative to the hMDHandle parameter.

dwMDAccessRequested: 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.

Value	Meaning
METADATA_PERMISSION_READ 0x00000001	Open the node for reading.
METADATA_PERMISSION_WRITE 0x00000002	Open the node for writing.

Value

Meaning

METADATA_PERMISSION_READ

0x00000001

Open the node for reading.

METADATA_PERMISSION_WRITE

0x00000002

Open the node for writing.

dwMDTimeOut: An unsigned 32-bit integer value specifying the time, in milliseconds, for the method to wait on a successful open operation.

phMDNewHandle: A pointer to the newly opened metadata handle (see DWORD).

Return Values: 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 HRESULT values, see [MS-ERREF].

Return value/code	Description
0x00000000 S_OK	The call was successful.
0x80070003 ERROR_PATH_NOT_FOUND	The system cannot find the path specified.
0x80070006 ERROR_INVALID_HANDLE	The handle is invalid.
0x80070094 ERROR_PATH_BUSY	The path specified cannot be used at this time.
0x80070057 E_INVALIDARG	One or more arguments are invalid.

The opnum field value for this method is 17.

When processing this call, the server MUST do the following:

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.
Check that the relative path points to a valid node; otherwise, return ERROR_PATH_NOT_FOUND.
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.
If the destination node represents the root of the metabase and the requested access is for write, the server returns an error.
If the destination node falls into part of the metabase that is locked as described in 3.1.1, 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.<3>
If access could be provided, the server calculates the handle of the destination node, increases its lock count, and saves its state.

Return the following information to the client:

The handle of the opened node.