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 write permissions.
DWORD dwMDTimeOut, //the time, in milliseconds, before the method times out.
PMETADATA_HANDLE phMDNewHandle //receives the handle to the opened key.
);
Value | Description |
METADATA_PERMISSION_READ | Open the key for reading. |
METADATA_PERMISSION_WRITE | Open the key for writing. |
Returns an HRESULT that contains one of the following values:
Value | Description |
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 parents or children, is already open. |
ERROR_PATH_NOT_FOUND | The specified path is not found. |
ERROR_SUCCESS | The method succeeded. |
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 parent keys and subkeys. 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 parent keys and subkeys 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 parent keys and subkeys 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.