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,
LPCWSTR pszMDPath,
DWORD dwMDAccessRequested,
DWORD dwMDTimeOut,
PMETADATA_HANDLE phMDNewHandle
);
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 by 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
Meaning
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:
Value |
Description |
|---|---|
E_INVALIDARG |
The parameter is incorrect. |
HRESULT_FROM_WIN32(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. |
HRESULT_FROM_WIN32(ERROR_PATH_NOT_FOUND) |
The specified path is not found. |
S_OK |
The method succeeded. |
Remarks
When the metabase is initialized at startup, a handle to the metabase called METADATA_MASTER_ROOT_HANDLE is automatically opened with read-only permissions. You can use the OpenKey method to get a handle to a key in the metabase by providing the key's path relative to this handle, such as /LM/W3SVC/2, the path to the key for the second Web server. You can also use a handle to any key as a reference point to its subkeys. For example, if you have opened a handle to /LM/W3SVC/2, you can then use this handle and the relative path, /ROOT/VDir1, with the OpenKey method to get a handle to the key /LM/W3SVC/2/ROOT/VDir1. For more information, see Metabase Connections in ABO.
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.
Requirements
Client: Requires Windows XP Professional, Windows 2000 Professional, or Windows NT Workstation 4.0.
Server: Requires Windows Server 2003, Windows 2000 Server, or Windows NT Server 4.0.
Product: IIS
Header: Declared in iadmw.h; include iiscnfg.h.
Example
The following line of code illustrates the correct way to call the OpenKey method.
IMSAdminBase::OpenKey(
METADATA_MASTER_ROOT_HANDLE,
wchar_t* "/LM/W3SVC/1/root",
METADATA_PERMISSION_WRITE | METADATA_PERMISSION_READ,
1000,
&hmdParentHandle);