Share via

3.1.4.16 ChangePermissions (Opnum 19)

  • Article

The ChangePermissions method changes permissions on an open handle.

 HRESULT ChangePermissions(
   [in] METADATA_HANDLE hMDHandle,
   [in] DWORD dwMDTimeOut,
   [in] DWORD dwMDAccessRequested
 );

hMDHandle: An unsigned 32-bit integer value containing the handle to change the permissions for, as returned by the OpenKey method.

dwMDTimeOut: An integer value specifying the time, in milliseconds, for the method to wait on a successful permission change operation.

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.

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.

0x80070006

ERROR_INVALID_HANDLE

The handle is invalid.

0x80070057

E_INVALIDARG

One or more arguments are invalid.

0x80070094

ERROR_PATH_BUSY

The path specified cannot be used at this time.

The opnum field value for this method is 19.

When processing this call, the server MUST do the following:

  • Check the handle parameter. This handle is valid if it is a handle returned from a previous OpenKey call. If the handle is invalid, return ERROR_INVALID_HANDLE.

  • Determine if it is possible to provide the requested access type for the specified node.

  • If the caller requests write access to the handle and the node falls into part of the metabase for which there are other open read handles, the server will wait for the time period specified by dwMDTimeOut for the other read handles to close. If, after this time period expires, there are still open read handles, return ERROR_PATH_BUSY.

  • If access could be provided, the server updates the state of the handle.<14>