console input or output| BOOL DuplicateHandle(hSourceProcess, hSource, hTargetProcess, lphTarget, fdwAccess, fInherit, fdwOptions) | |||||
| HANDLE hSourceProcess; | /* handle for process to duplicate from | */ | |||
| HANDLE hSource; | /* handle to duplicate | */ | |||
| HANDLE hTargetProcess; | /* handle for process to duplicate to | */ | |||
| LPHANDLE lphTarget; | /* address of duplicate handle | */ | |||
| DWORD fdwAccess; | /* desired access for duplicate handle | */ | |||
| BOOL fInherit; | /* handle is inherited by child process? | */ | |||
| DWORD fdwOptions; | /* optional actions | */ | |||
The DuplicateHandle duplicates and object handle.
hSourceProcess
Specifies an open handle to the process that contains the handle to be duplicated. The handle must have been created with PROCESS_DUP_HANDLE access to the process.
hSource
Specifies an open handle to any object that is valid in the context of the source process.
hTargetProcess
Specifies an open handle to the process that is to receive the duplicated handle. The handle must have been created with PROCESS_DUP_HANDLE access to the process.
lphTarget
Points to a variable which receives the duplicated handle. This handle value will be valid in the context of the target process.
fdwAccess
Specifies the access requested for the new handle. This parameter is ignored if the DUPLICATE_SAME_ACCESS option is specified.
fInherit
If TRUE, the target handle will be inherited by new processes created by the target process. If FALSE, the new handle will not be inherited.
fdwOptions
Specifies optional actions. This parameter can be one of the following values:
| Value | Meaning |
| DUPLICATE_CLOSE_SOURCE | Close the source handle. This occurs regardless of any error status returned. |
| DUPLICATE_SAME_ACCESS | The fdwAccess parameter is ignored. The duplicate handle has the same access as the source handle. |
The return value is TRUE if the function was successful, or FALSE if an error occurred. Use the GetLastError function to obtain extended error information.
This function is used by one process to create a handle that can be used by another process. Once the handle has been duplicated, the creating process must use interprocess communication to pass the duplicate handle to the target process. The target process can then operate on the object with this handle value.
The following objects can be duplicated with the DuplicateHandle function:
console input or output
event
file (including file mapping objects)
mutex
pipe (both named and anonymous)
process
semaphore
thread
Several of these objects can be used with special access flags, in addition to the STANDARD_RIGHTS_REQUIRED. The following access flags are valid for file mapping objects:
| Value | Meaning |
| FILE_MAP_WRITE | Write map access to the file mapping object is desired. This allows a writable view of the file to be mapped. Note that if the file mapping access flags do not include PAGE_READWRITE, this access type does not allow writing the mapped file. |
| FILE_MAP_READ | Read map access to the file mapping object is desired. This allows a readable view of the file to be mapped. |
| FILE_MAP_ALL_ACCESS | Specifies all possible access flags for the file mapping object. |
The following access flags are valid for mutex objects:
| Value | Meaning |
| SYNCHRONIZE | Synchronization (wait or release) access. |
| MUTEX_ALL_ACCESS | All possible types of access. |
The following access flags are valid for semaphore objects:
| Value | Meaning |
| SEMAPHORE_MODIFY_STATE | Modify state (release) access. |
| SYNCHRONIZE | Synchronization (wait) access. |
| SEMAPHORE_ALL_ACCESS | All possible types of access. |
The following access flags are valid for thread objects:
| Value | Meaning |
| THREAD_QUERY_INFORMATION | This access is required to read certain information from the thread object. |
| THREAD_SET_INFORMATION | This access is required to set certain information in the thread object. |
| SYNCHRONIZE | Synchronization (wait) access. |
| THREAD_GET_CONTEXT | This access is required to read the context of a thread using GetThreadContext. |
| THREAD_SET_CONTEXT | This access is required to write the context of a thread using SetThreadContext. |
| THREAD_SUSPEND_RESUME | This access is required to suspend or resume a thread using SuspendThread or ResumeThread. |
| THREAD_ALL_ACCESS | This set of access flags specifies all of the possible access flags for a thread object. This includes CREATE_SUSPENDED; the thread will be created suspended. |