IMSAdminBase::OpenKey

IIS 6.0

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
);

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.

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.

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.

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.

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);
Show: