DuplicateHandle XJPK0M

The DuplicateHandle function duplicates an object handle.

BOOL DuplicateHandle(

HANDLE hSourceProcessHandle,	// handle to process with handle to duplicate
HANDLE hSourceHandle,	// handle to duplicate
HANDLE hTargetProcessHandle,	// handle to process to duplicate to
LPHANDLE lpTargetHandle,	// pointer to duplicate handle
DWORD dwDesiredAccess,	// access for duplicate handle
BOOL bInheritHandle,	// handle inheritance flag
DWORD dwOptions	// optional actions
);

Parameters

hSourceProcessHandle

Identifies the process containing the handle to duplicate. The handle must have PROCESS_DUP_HANDLEPDITN2 access. For more information, see Process ObjectsPDITN2.

hSourceHandle

Identifies the handle to duplicate. This is an open object handle that is valid in the context of the source process. For a list of objects whose handles can be duplicated, see the following Remarks section.

hTargetProcessHandle

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

lpTargetHandle

Points to a variable receiving the value of the duplicate handle. This handle value is valid in the context of the target process. If lpTargetHandle is NULL, the function duplicates the handle, but does not return the duplicate handle value to the caller.

dwDesiredAccess

Specifies 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 being duplicated. For the flags that can be specified for each object type, see the following Remarks section. Note that the new handle can have more access than the original handle.

bInheritHandle

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

Specifies optional actions. This parameter can be zero, or any combination of the following flags:

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

Return Values

If the function succeeds, the return value is nonzero.

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

Remarks

DuplicateHandle can be called by either the source process or the target process. It can also be invoked where the source and target process are the same. For example, a process can use DuplicateHandle to create a noninheritable duplicate of an inheritable handle, or a handle with different access than the original handle.

The duplicating process uses the GetCurrentProcessJIU.65 function to get a handle of itself. To get the other process handle, it may be necessary to use some form of interprocess communication (for example, named pipe or shared memory) to communicate the process identifier to the duplicating process. This identifier is then used in the OpenProcess9MLGUT function to open a handle.

If the process that calls DuplicateHandle is not the target process, the duplicating process must use interprocess communication to pass the value of the duplicate handle to the target process.

The duplicate handle is the same object handle as the source handle. This means that the state of the object is the same for both handles. For example, the current file mark for a file handle is always the same for both handles.

DuplicateHandle can duplicate handles to the following types of objects:

Object	Description
Console input	The handle is returned by the CreateFileXN35YD function when CONIN$ is specified, or by the GetStdHandle1B8L_FR function when STD_INPUT_HANDLE is specified. Console handles can be duplicated for use only in the same process.
Console screen buffer	The handle is returned by the CreateFile function when CONOUT$ is specified, or by the GetStdHandle function when STD_OUTPUT_HANDLE is specified. Console handles can be duplicated for use only in the same process.
Event	The handle is returned by the CreateEventJ_ZBJV or OpenEventQTG5JZ function.
File or communications device	The handle is returned by the CreateFileXN35YD function.
File mapping	The handle is returned by the CreateFileMapping3LCK_3 function.
Mutex	The handle is returned by the CreateMutexJEYQAZ or OpenMutex4S0DUN function.
Pipe	A named pipe handle is returned by the CreateNamedPipe21DZYT or CreateFileXN35YD function. An anonymous pipe handle is returned by the CreatePipeXN_62D function.
Process	The handle is returned by the CreateProcess5FBJ_XX, GetCurrentProcessJIU.65, or OpenProcess9MLGUT function.
Registry key	The handle is returned by the RegCreateKeyIOABQX, RegCreateKeyEx.5U9K7, RegOpenKeyWG.8D, or RegOpenKeyExRZ_3FO function. Note that registry key handles returned by the RegConnectRegistry5.7D_UJ function cannot be used in a call to DuplicateHandle.
Semaphore	The handle is returned by the CreateSemaphore41RE8TU or OpenSemaphoreB3N75Z function.
Thread	The handle is returned by the CreateProcess5FBJ_XX, CreateThread70TS0Y, CreateRemoteThread19IU6KT, or GetCurrentThread12SSWFX function

In addition to STANDARD_RIGHTS_REQUIRED, the following access flags can be specified in the dwDesiredAccess parameter for the different object types. Note that the new handle can have more access than the original handle. However, in some cases DuplicateHandle cannot create a duplicate handle with more access permission than the original handle. For example, a file handle created with GENERIC_READ access cannot be duplicated so that it has both GENERIC_READ and GENERIC_WRITE access.

Any combination of the following access flags is valid for handles to communications devices, console input, console screen buffers, files, and pipes:

Access	Description
GENERIC_READ	Enables read access.
GENERIC_WRITE	Enables write access.

Any combination of the following access flags is valid for file-mapping objects:

Access	Description
FILE_MAP_ALL_ACCESS	Specifies all possible access flags for the file-mapping object.
FILE_MAP_READ	Enables mapping the object into memory that permits read access.
FILE_MAP_WRITE	Enables mapping the object into memory that permits write access. For write access, PAGE_READWRITE protection must have been specified when the file-mapping object was created by the CreateFileMapping3LCK_3 function.

Any combination of the following access flags is valid for mutex objects:

Access	Description
MUTEX_ALL_ACCESS	Specifies all possible access flags for the mutex object.
SYNCHRONIZE	Windows NT only: Enables use of the mutex handle in any of the wait functionsY2TC_3 to acquire ownership of the mutex, or in the ReleaseMutex82B0XA function to release ownership.

Any combination of the following access flags is valid for semaphore objects:

Access	Description
SEMAPHORE_ALL_ACCESS	Specifies all possible access flags for the semaphore object.
SEMAPHORE_MODIFY_STATE	Enables use of the semaphore handle in the ReleaseSemaphoreJ17UY. function to modify the semaphore s count.
SYNCHRONIZE	Windows NT only: Enables use of the semaphore handle in any of the wait functionsY2TC_3 to wait for the semaphore s state to be signaled.

Any combination of the following access flags is valid for event objects:

Access	Description
EVENT_ALL_ACCESS	Specifies all possible access flags for the event object.
EVENT_MODIFY_STATE	Enables use of the event handle in the SetEventAT02D. and ResetEvent1.IH1GV functions to modify the event s state.
SYNCHRONIZE	Windows NT only: Enables use of the event handle in any of the wait functionsY2TC_3 to wait for the event s state to be signaled.

Any combination of the following access flags is valid for handles to registry keys:

Value	Meaning
KEY_ALL_ACCESS	Specifies all possible flags for the registry key.
KEY_CREATE_LINK	Enables using the handle to create a link to a registry-key object.
KEY_CREATE_SUB_KEY	Enables using the handle to create a subkey of a registry-key object.
KEY_ENUMERATE_SUB_KEYS	Enables using the handle to enumerate the subkeys of a registry-key object.
KEY_EXECUTE	Equivalent to KEY_READ.
KEY_NOTIFY	Enables using the handle to request change notifications for a registry key or for subkeys of a registry key.
KEY_QUERY_VALUE	Enables using the handle to query a value of a registry-key object.
KEY_READ	Combines the STANDARD_RIGHTS_READ, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_NOTIFY values.
KEY_SET_VALUE	Enables using the handle to create or set a value of a registry-key object.
KEY_WRITE	Combines the STANDARD_RIGHTS_WRITE, KEY_SET_VALUE, and KEY_CREATE_SUB_KEY values.

Any combination of the following access flags is valid for process objects:

Access	Description
PROCESS_ALL_ACCESS	Specifies all possible access flags for the process object.
PROCESS_CREATE_PROCESS	Used internally.
PROCESS_CREATE_THREAD	Enables using the process handle in the CreateRemoteThread19IU6KT function to create a thread in the process.
PROCESS_DUP_HANDLE	Enables using the process handle as either the source or target process in the DuplicateHandle function to duplicate a handle.
PROCESS_QUERY_INFORMATION	Enables using the process handle in the GetExitCodeProcess2MM.I. and GetPriorityClassF6UWF_ functions to read information from the process object.
PROCESS_SET_INFORMATION	Enables using the process handle in the SetPriorityClass1HDPHK3 function to set the process s priority class.
PROCESS_TERMINATE	Enables using the process handle in the TerminateProcess.D3M14 function to terminate the process.
PROCESS_VM_OPERATION	Enables using the process handle in the VirtualProtectExSFLVDY and WriteProcessMemory_4C4HP functions to modify the virtual memory of the process.
PROCESS_VM_READ	Enables using the process handle in the ReadProcessMemory2RLM_KF function to read from the virtual memory of the process.
PROCESS_VM_WRITE	Enables using the process handle in the WriteProcessMemory_4C4HP function to write to the virtual memory of the process.
SYNCHRONIZE	Windows NT only: Enables using the process handle in any of the wait functionsY2TC_3 to wait for the process to terminate.

Any combination of the following access flags is valid for thread objects:

Access	Description
SYNCHRONIZE	Windows NT only: Enables using the thread handle in any of the wait functionsY2TC_3 to wait for the thread to terminate.
THREAD_ALL_ACCESS	Specifies all possible access flags for the thread object.
THREAD_DIRECT_IMPERSONATION	Used internally.
THREAD_GET_CONTEXT	Enables using the thread handle in the GetThreadContextH1G8JB function to read the thread s context.
THREAD_IMPERSONATE	Used internally.
THREAD_QUERY_INFORMATION	Enables using the thread handle in the GetExitCodeThread3YYT_HX, GetThreadPriority0B6AW9, and GetThreadSelectorEntry1LJ7T0P functions to read information from the thread object.
THREAD_SET_CONTEXT	Enables using the thread handle in the SetThreadContext0WTUKC function to set the thread s context.
THREAD_SET_INFORMATION	Enables using the thread handle in the SetThreadPriorityO2A9RL function to set the thread s priority.
THREAD_SET_THREAD_TOKEN	Used internally.
THREAD_SUSPEND_RESUME	Enables using the thread handle in the SuspendThread0PF8EH or ResumeThread5KEZ_MI functions to suspend or resume a thread.
THREAD_TERMINATE	Enables using the thread handle in the TerminateThread0TMWD4 function to terminate the thread.