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 |
); |
Windows NT: The handle must have PROCESS_DUP_HANDLE
access. For more information, see Process
Objects.
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. |
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.
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 GetCurrentProcess 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 OpenProcess 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 CreateFile function when CONIN$ is specified, or by the GetStdHandle 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 CreateEvent or OpenEvent function. |
File or communications device |
The handle is returned by the CreateFile function. |
File mapping |
The handle is returned by the CreateFileMapping function. |
Mutex |
The handle is returned by the CreateMutex or OpenMutex function. |
Pipe |
A named pipe handle is returned by the CreateNamedPipe or CreateFile function. An anonymous pipe handle is returned by the CreatePipe function. |
Process |
The handle is returned by the CreateProcess, GetCurrentProcess, or OpenProcess function. |
Registry key |
Windows NT: The handle is returned by the RegCreateKey, RegCreateKeyEx, RegOpenKey, or RegOpenKeyEx function. Note that registry key handles returned by the RegConnectRegistry function cannot be used in a call to DuplicateHandle. Windows 95: You cannot use DuplicateHandle to duplicate registry key handles. |
Semaphore |
The handle is returned by the CreateSemaphore or OpenSemaphore function. |
Thread |
The handle is returned by the CreateProcess, CreateThread, CreateRemoteThread, or GetCurrentThread function |
Timer |
The handle is returned by the CreateWaitableTimer or OpenWaitableTimer 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 CreateFileMapping 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 functions to acquire ownership of the mutex, or in the ReleaseMutex 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 ReleaseSemaphore function to modify the semaphore’s count. |
SYNCHRONIZE |
Windows NT only: Enables use of the semaphore handle in any of the wait functions 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 SetEvent and ResetEvent functions to modify the event’s state. |
SYNCHRONIZE |
Windows NT only: Enables use of the event handle in any of the wait functions 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 CreateRemoteThread 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 GetExitCodeProcess and GetPriorityClass functions to read information from the process object. |
PROCESS_SET_INFORMATION |
Enables using the process handle in the SetPriorityClass function to set the process’s priority class. |
PROCESS_TERMINATE |
Enables using the process handle in the TerminateProcess function to terminate the process. |
PROCESS_VM_OPERATION |
Enables using the process handle in the VirtualProtectEx and WriteProcessMemory functions to modify the virtual memory of the process. |
PROCESS_VM_READ |
Enables using the process handle in the ReadProcessMemory function to read from the virtual memory of the process. |
PROCESS_VM_WRITE |
Enables using the process handle in the WriteProcessMemory function to write to the virtual memory of the process. |
SYNCHRONIZE |
Windows NT only: Enables using the process handle in any of the wait functions 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 functions 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 GetThreadContext function to read the thread’s context. |
THREAD_IMPERSONATE |
Used internally. |
THREAD_QUERY_INFORMATION |
Enables using the thread handle in the GetExitCodeThread, GetThreadPriority, and GetThreadSelectorEntry functions to read information from the thread object. |
THREAD_SET_CONTEXT |
Enables using the thread handle in the SetThreadContext function to set the thread’s context. |
THREAD_SET_INFORMATION |
Enables using the thread handle in the SetThreadPriority function to set the thread’s priority. |
THREAD_SET_THREAD_TOKEN |
Used internally. |
THREAD_SUSPEND_RESUME |
Enables using the thread handle in the SuspendThread or ResumeThread functions to suspend or resume a thread. |
THREAD_TERMINATE |
Enables using the thread handle in the TerminateThread function to terminate the thread. |
CloseHandle, CreateEvent, CreateFile, CreateFileMapping, CreateMutex, CreateNamedPipe, CreatePipe, CreateProcess, CreateRemoteThread, CreateSemaphore, CreateThread, CreateWaitableTimer, GetCurrentProcess, GetExitCodeProcess, GetExitCodeThread, GetPriorityClass, GetStdHandle, GetThreadContext, GetThreadPriority, GetThreadSelectorEntry, OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, OpenWaitableTimer, ReadProcessMemory, RegConnectRegistry, RegCreateKey, RegCreateKeyEx, RegOpenKey, RegOpenKeyEx, ReleaseMutex, ReleaseSemaphore, ResetEvent, ResumeThread, SetEvent, SetPriorityClass, SetThreadContext, SetThreadPriority, SuspendThread, TerminateProcess, TerminateThread, VirtualProtectEx, WriteProcessMemory
file: /Techref/os/win/api/win32/func/src/f18_10.htm, 27KB, , updated: 2000/4/7 11:19, local time: 2024/12/7 19:14,
18.97.9.168:LOG IN
|
©2024 These pages are served without commercial sponsorship. (No popup ads, etc...).Bandwidth abuse increases hosting cost forcing sponsorship or shutdown. This server aggressively defends against automated copying for any reason including offline viewing, duplication, etc... Please respect this requirement and DO NOT RIP THIS SITE. Questions? <A HREF="http://www.piclist.com/techref/os/win/api/win32/func/src/f18_10.htm"> DuplicateHandle</A> |
Did you find what you needed? |
PICList 2024 contributors:
o List host: MIT, Site host massmind.org, Top posters @none found - Page Editors: James Newton, David Cary, and YOU! * Roman Black of Black Robotics donates from sales of Linistep stepper controller kits. * Ashley Roll of Digital Nemesis donates from sales of RCL-1 RS232 to TTL converters. * Monthly Subscribers: Gregg Rew. on-going support is MOST appreciated! * Contributors: Richard Seriani, Sr. |
Welcome to www.piclist.com! |
.