IMSAdminBase::OpenKey

The IMSAdminBase::OpenKey method opens a key for read access, write access or both. The returned handle can be used by several of the other methods.

The first time you call this method, you must pass in the METADATA_MASTER_ROOT_HANDLE.

HRESULT OpenKey(
  METADATA_HANDLE hMDHandle,      //metabase handle
  LPCWSTR pszMDPath,              //path to the key, relative to hMDHandle
  DWORD dwMDAccessRequested,      //specifies read and/or write permissions
  DWORD dwMDTimeOut,              //the time, in milliseconds, before the 
                                  // method times out
  PMETADATA_HANDLE phMDNewHandle  //receives the handle to the opened key
);

Parameters

hMDHandle

Specifies a handle to the metabase. This can either be METADATA_MASTER_ROOT_HANDLE or a handle returned by a previous call to IMSAdminBase::OpenKey.

pszMDPath

Points to a string that contains the path of the key to be opened, relative to hMDHandle. For example, if the handle references the /LM key, you could specify the Web services subkey using the path /W3SVC.

dwMDAccessRequested

Specifies the requested permissions for the handle. This parameter must be set to at least one of the following values:

Value	Description
METADATA_PERMISSION_READ	Open the key for reading.
METADATA_PERMISSION_WRITE	Open the key for writing.

dwMDTimeOut

Specifies the time, in milliseconds, for the method to wait for the open operation to succeed.

phMDNewHandle

Points to a handle to receive the opened handle.

Return Values

Returns an HRESULT that contains one of the following values:

ERROR_INVALID_PARAMETER	The parameter is incorrect.
ERROR_PATH_BUSY	The path specified cannot be used at this time because a handle to the key, or one of its ancestors or descendents, is already open.
ERROR_PATH_NOT_FOUND	The specified path is not found.
ERROR_SUCCESS	The method succeeded.

Remarks

Opening a key with read permissions guarantees that the view of the data will not change while the key is open. Opening a key with write permissions guarantees that no other processes will read or write any data until the handle is closed. This applies to the open key and all of its ancestor and descendent keys. Because opening a key locks a portion of the metabase, it is recommended that you open the key, perform any reads or writes, and immediately close the key when done.

If you try to open a key with read access, the method will wait until all open write access handles to the key and to all ancestor and descendent keys are closed. If you try to open a key with write access, the method will wait until all open handles (either read or write) to the key and to all ancestor and descendent keys are closed.

The METADATA_MASTER_ROOT_HANDLE remains open at all times, and does not block other handles of either access type from being opened.