3.1.4.2 OpenKey (Opnum 17)

  • Article

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.

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.