DuplicateHandle

Description

Duplicates an object handle.

C++ Syntax

PowerBASIC Syntax

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. For a list of objects whose handles can be duplicated, see the following Remarks section.

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. For the flags that can be specified for each object type, see the following Remarks section.

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.

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.

Remarks

The duplicate handle refers to the same object as the original handle. Therefore, any changes to the object are reflected through both handles. For example, if you duplicate a file handle, the current file position is always the same for both handles. For file handles to have different file positions, use the CreateFile function to create file handles that share access to the same file.

DuplicateHandle can be called by either the source process or the target process (or a process that is both the source and target process). 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 source process uses the GetCurrentProcess function to get a handle to itself. This handle is a pseudo handle, but DuplicateHandle converts it to a real process handle. To get the target process handle, it may be necessary to use some form of interprocess communication (for example, a named pipe or shared memory) to communicate the process identifier to the source process. The source process can use this identifier in the OpenProcess function to obtain a handle to the target process.

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

DuplicateHandle can be used to duplicate a handle between a 32-bit process and a 64-bit process. The resulting handle is appropriately sized to work in the target process.

DuplicateHandle can duplicate handles to the following types of objects.

You should not use DuplicateHandle to duplicate handles to the following objects:

The dwDesiredAccess parameter specifies the new handle's access rights. All objects support the standard access rights. Objects may also support additional access rights depending on the object type.

In some cases, the new handle can have more access rights than the original handle. However, in other cases, DuplicateHandle cannot create a handle with more access rights than the original. For example, a file handle created with the GENERIC_READ access right cannot be duplicated so that it has both the GENERIC_READ and GENERIC_WRITE access right.

Normally the target process closes a duplicated handle when that process is finished using the handle. To close a duplicated handle from the source process, call DuplicateHandle with the following parameters:

Example

The following example creates a mutex, duplicates a handle to the mutex, and passes it to another thread. Duplicating the handle ensures that the reference count is increased so that the mutex object will not be destroyed until both threads have closed the handle.

C++ code

#include <windows.h>

DWORD CALLBACK ThreadProc(PVOID pvParam);

int main()

{

  HANDLE hMutex = CreateMutex(NULL, FALSE, NULL);

  HANDLE hMutexDup, hThread;

  DWORD dwThreadId;

  DuplicateHandle(GetCurrentProcess(),

                  hMutex,

                  GetCurrentProcess(),

                  &hMutexDup,

                  0,

                  FALSE,

                  DUPLICATE_SAME_ACCESS);

  hThread = CreateThread(NULL, 0, ThreadProc,

      (LPVOID) hMutexDup, 0, &dwThreadId);

  // Perform work here, closing the handle when finished with the

  // mutex. If the reference count is zero, the object is destroyed.

  CloseHandle(hMutex);

  // Wait for the worker thread to terminate and clean up.

  WaitForSingleObject(hThread, INFINITE);

  CloseHandle(hThread);

  return 0;

}

DWORD CALLBACK ThreadProc(PVOID pvParam)

{

  HANDLE hMutex = (HANDLE)pvParam;

  // Perform work here, closing the handle when finished with the

  // mutex. If the reference count is zero, the object is destroyed.

  CloseHandle(hMutex);

  return 0;

}

PowerBASIC code

#COMPILE EXE

#DIM ALL

#INCLUDE "windows.inc"

FUNCTION ThreadProc (BYVAL hMutexDup AS DWORD) AS DWORD

 ' // Perform work here, closing the handle when finished with the

 ' // mutex. If the reference count is zero, the object is destroyed.

 CloseHandle(hMutexDup)

END FUNCTION

FUNCTION PBMAIN () AS LONG

 LOCAL hMutex AS DWORD

 LOCAL hMutexDup AS DWORD

 LOCAL hThread AS DWORD

 LOCAL dwThreadId AS DWORD

 hMutex = CreateMutex(BYVAL %NULL, %FALSE, BYVAL %NULL)

 DuplicateHandle(GetCurrentProcess(), hMutex, GetCurrentProcess(), _

                 hMutexDup, 0, %FALSE, %DUPLICATE_SAME_ACCESS)

 hThread = CreateThread(BYVAL %NULL, 0, CODEPTR(ThreadProc), _

           hMutexDup, 0, dwThreadId)

 ' // Perform work here, closing the handle when finished with the

 ' // mutex. If the reference count is zero, the object is destroyed.

 CloseHandle(hMutex)

 ' // Wait for the worker thread to terminate and clean up.

 WaitForSingleObject(hThread, %INFINITE)

 CloseHandle(hThread)

END FUNCTION