Duplicating handles

Handle duplication is similar to a handle transfer, but duplication is performed within a process. A handle descendant is created in the same process and from the same handle space. The rights of the handle descendant may be less than or equal to the rights of the original handle. Handle duplication can be associated with a resource transfer context object. This lets you use the notification mechanism to track the closure or revocation of all handle descendants that form the handle inheritance subtree whose root node was generated by the duplication operation. It also provides the capability to revoke these descendants.

To duplicate a handle, call the KnHandleCopy() function. To do so, the OCAP_HANDLE_COPY flag must be set in the handle permissions mask.

Information about API functions is provided in the table below.

handle_api.h functions

Function

Information about the function

KnHandleCopy()

Purpose

Duplicates a handle.

As a result of duplication, the calling process receives the handle descendant.

Parameters

  • [in] inHandle – original handle.
  • [in] newRightsMask – permissions mask of the handle descendant.
  • [in,optional] copyBadge – handle of the resource transfer context object, or INVALID_HANDLE if you do not need to associate handle duplication with this object.
  • [out] outHandle – pointer to the handle descendant.

Returned values

If successful, the function returns rcOk, otherwise it returns an error code.

Page top