DuplicateHandle

Description

Duplicates an object handle.

Syntax

BOOL WINAPI DuplicateHandle(
  _In_  HANDLE   hSourceProcessHandle,
  _In_  HANDLE   hSourceHandle,
  _In_  HANDLE   hTargetProcessHandle,
  _Out_ LPHANDLE lpTargetHandle,
  _In_  DWORD    dwDesiredAccess,
  _In_  BOOL     bInheritHandle,
  _In_  DWORD    dwOptions
);

Parameters

hSourceProcessHandle [in]

A handle to the process with the handle to be duplicated.

The handle must have the PROCESS_DUP_HANDLE access right.

hSourceHandle [in]

The handle to be duplicated. This is an open object handle that is valid in the context of the source process.

hTargetProcessHandle [in]

A handle to the process that is to receive the duplicated handle. The handle must have the PROCESS_DUP_HANDLE access right.

lpTargetHandle [out]

A pointer to a variable that receives the duplicate handle. This handle value is valid in the context of the target process.

If hSourceHandle is a pseudo handle returned by GetCurrentProcess or GetCurrentThread, DuplicateHandle converts it to a real handle to a process or thread, respectively.

If lpTargetHandle is NULL, the function duplicates the handle, but does not return the duplicate handle value to the caller. This behavior exists only for backward compatibility with previous versions of this function. You should not use this feature, as you will lose system resources until the target process terminates.

dwDesiredAccess [in]

The access requested for the new handle.

This parameter is ignored if the dwOptions parameter specifies the DUPLICATE_SAME_ACCESS flag. Otherwise, the flags that can be specified depend on the type of object whose handle is to be duplicated.

bInheritHandle [in]

A variable that indicates whether the handle is inheritable. If TRUE, the duplicate handle can be inherited by new processes created by the target process. If FALSE, the new handle cannot be inherited.

dwOptions [in]

Optional actions. This parameter can be zero, or any combination of the following values.

Value	Meaning
DUPLICATE_CLOSE_SOURCE 0x00000001	Closes the source handle. This occurs regardless of any error status returned.
DUPLICATE_SAME_ACCESS 0x00000002	Ignores the dwDesiredAccess parameter. The duplicate handle has the same access as the source handle.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.