Condividi tramite

Funzione DuplicateHandle (handleapi.h)

Duplica un handle di oggetto.

Sintassi

BOOL DuplicateHandle(
  [in]  HANDLE   hSourceProcessHandle,
  [in]  HANDLE   hSourceHandle,
  [in]  HANDLE   hTargetProcessHandle,
  [out] LPHANDLE lpTargetHandle,
  [in]  DWORD    dwDesiredAccess,
  [in]  BOOL     bInheritHandle,
  [in]  DWORD    dwOptions
);

Parametri

[in] hSourceProcessHandle

Handle per il processo con l'handle da duplicare.

L'handle deve avere il diritto di accesso PROCESS_DUP_HANDLE. Per altre informazioni, vedere Process Security and Access Rights.

[in] hSourceHandle

Handle da duplicare. Si tratta di un handle di oggetto aperto valido nel contesto del processo di origine. Per un elenco di oggetti i cui handle possono essere duplicati, vedere la sezione Osservazioni seguente.

Se hSourceHandle è uno pseudo handle restituito da GetCurrentProcess o GetCurrentThread, hSourceProcessHandle deve essere un handle per il processo che chiama DuplicateHandle.

[in] hTargetProcessHandle

Handle per il processo che deve ricevere l'handle duplicato. L'handle deve avere il diritto di accesso PROCESS_DUP_HANDLE.

Questo parametro è facoltativo e può essere specificato come NULL se il flag DUPLICATE_CLOSE_SOURCE è impostato in Opzioni.

[out] lpTargetHandle

Puntatore a una variabile che riceve l'handle duplicato. Questo valore di handle è valido nel contesto del processo di destinazione.

Se hSourceHandle è uno pseudo handle restituito da GetCurrentProcess o GetCurrentThread, DuplicateHandle lo converte rispettivamente in un handle reale in un processo o in un thread.

Se lpTargetHandle è NULL, la funzione duplica l'handle, ma non restituisce il valore dell'handle duplicato al chiamante. Questo comportamento esiste solo per compatibilità con le versioni precedenti di questa funzione. Non è consigliabile usare questa funzionalità, perché le risorse di sistema andranno perse fino al termine del processo di destinazione.

Questo parametro viene ignorato se hTargetProcessHandle è NULL.

[in] dwDesiredAccess

Accesso richiesto per il nuovo handle. Per i flag che è possibile specificare per ogni tipo di oggetto, vedere la sezione Osservazioni seguente.

Questo parametro viene ignorato se il parametro dwOptions specifica il flag DUPLICATE_SAME_ACCESS. In caso contrario, i flag che possono essere specificati dipendono dal tipo di oggetto il cui handle deve essere duplicato.

Questo parametro viene ignorato se hTargetProcessHandle è NULL.

[in] bInheritHandle

Variabile che indica se l'handle è ereditabile. Se TRUE, l'handle duplicato può essere ereditato da nuovi processi creati dal processo di destinazione. Se FALSE, il nuovo handle non può essere ereditato.

Questo parametro viene ignorato se hTargetProcessHandle è NULL.

[in] dwOptions

Azioni facoltative. Questo parametro può essere zero o qualsiasi combinazione dei valori seguenti.

Valore Significato
DUPLICATE_CLOSE_SOURCE
0x00000001
 Chiude l'handle di origine. Ciò si verifica indipendentemente dallo stato di errore restituito.
DUPLICATE_SAME_ACCESS
0x00000002
 Ignora il parametro dwDesiredAccess . L'handle duplicato ha lo stesso accesso dell'handle di origine.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per ottenere informazioni estese sull'errore, chiamare GetLastError.

Osservazioni:

L'handle duplicato fa riferimento allo stesso oggetto dell'handle originale. Di conseguenza, tutte le modifiche apportate all'oggetto vengono riflesse tramite entrambi gli handle. Ad esempio, se si duplica un handle di file, la posizione del file corrente è sempre la stessa per entrambi gli handle. Affinché gli handle di file abbiano posizioni di file diverse, usare la funzione CreateFile per creare handle di file che condividono l'accesso allo stesso file.

DuplicateHandle può essere chiamato dal processo di origine o dal processo di destinazione (o da un processo sia di origine che di destinazione). Ad esempio, un processo può usare DuplicateHandle per creare un duplicato nonheritable di un handle ereditabile o un handle con accesso diverso rispetto all'handle originale.

Il processo di origine usa la funzione GetCurrentProcess per ottenere un handle per se stesso. Questo handle è uno pseudo handle, ma DuplicateHandle lo converte in un handle di processo reale. Per ottenere l'handle del processo di destinazione, potrebbe essere necessario usare una forma di comunicazione interprocesso (ad esempio, una named pipe o una memoria condivisa) per comunicare l'identificatore del processo al processo di origine. Il processo di origine può usare questo identificatore nella funzione OpenProcess per ottenere un handle per il processo di destinazione.

Se il processo che chiama DuplicateHandle non è anche il processo di destinazione, il processo di origine deve usare la comunicazione interprocesso per passare il valore dell'handle duplicato al processo di destinazione.

DuplicateHandle può essere usato per duplicare un handle tra un processo a 32 bit e un processo a 64 bit. L'handle risultante viene ridimensionato in modo appropriato per funzionare nel processo di destinazione. Per altre informazioni, vedere Interoperabilità dei processi.

DuplicateHandle può duplicare handle per i tipi di oggetti seguenti.

Oggetto Descrizione
Token di accesso L'handle viene restituito dalla funzione CreateRestrictedToken, DuplicateToken, DuplicateTokenEx, OpenProcessToken o OpenThreadToken .
Notifica di modifica L'handle viene restituito dalla funzione FindFirstChangeNotification .
Dispositivo di comunicazione L'handle viene restituito dalla funzione CreateFile .
Input della console L'handle viene restituito dalla funzione CreateFile quando si specifica CONIN$ o dalla funzione GetStdHandle quando viene specificato STD_INPUT_HANDLE. Gli handle della console possono essere duplicati per l'uso solo nello stesso processo.
Buffer dello schermo della console L'handle viene restituito dalla funzione CreateFile quando si specifica CONOUT$ o dalla funzione GetStdHandle quando viene specificato STD_OUTPUT_HANDLE. Gli handle della console possono essere duplicati per l'uso solo nello stesso processo.
Schermo L'handle viene restituito dalla funzione GetThreadDesktop .
Evento L'handle viene restituito dalla funzione CreateEvent o OpenEvent .
Documento L'handle viene restituito dalla funzione CreateFile .
Mapping dei file L'handle viene restituito dalla funzione CreateFileMapping .
Lavoro L'handle viene restituito dalla funzione CreateJobObject .
Mailslot L'handle viene restituito dalla funzione CreateMailslot .
Mutex L'handle viene restituito da CreateMutex o [OpenMutex](.. Funzione /synchapi/nf-synchapi-openmutexw.md).
Pipa Un handle named pipe viene restituito dalla funzione CreateNamedPipe o CreateFile . Un handle pipe anonimo viene restituito dalla funzione CreatePipe .
Processo L'handle viene restituito dalla funzione CreateProcess, GetCurrentProcess o OpenProcess .
Chiave di Registro L'handle viene restituito dalla funzione RegCreateKey, RegCreateKeyEx, RegOpenKey o RegOpenKeyEx. Si noti che gli handle di chiave del Registro di sistema restituiti dalla funzione RegConnectRegistry non possono essere usati in una chiamata a DuplicateHandle.
Semaforo L'handle viene restituito dalla funzione CreateSemaphore o OpenSemaphore .
Filo L'handle viene restituito dalla funzione CreateProcess, CreateThread, CreateRemoteThread o GetCurrentThread
Temporizzatore L'handle viene restituito dalla funzione CreateWaitableTimerW o OpenWaitableTimerW .
Transazione L'handle viene restituito dalla funzione CreateTransaction .
Stazione finestra L'handle viene restituito dalla funzione GetProcessWindowStation .
 

Non utilizzare DuplicateHandle per duplicare handle per gli oggetti seguenti:

  • Porte di completamento di I/O. Non viene restituito alcun errore, ma non è possibile usare l'handle duplicato.
  • Sockets. Non viene restituito alcun errore, ma l'handle duplicato potrebbe non essere riconosciuto da Winsock nel processo di destinazione. Inoltre, l'uso di DuplicateHandle interferisce con il conteggio dei riferimenti interni sull'oggetto sottostante. Per duplicare un handle socket, usare la funzione WSADuplicateSocket .
  • Pseudo-handle diversi da quelli restituiti dalle funzioni GetCurrentProcess o GetCurrentThread .
Il parametro dwDesiredAccess specifica i diritti di accesso del nuovo handle. Tutti gli oggetti supportano i diritti di accesso standard. Gli oggetti possono anche supportare diritti di accesso aggiuntivi a seconda del tipo di oggetto. Per altre informazioni, vedere gli argomenti seguenti: In alcuni casi, il nuovo handle può avere più diritti di accesso rispetto all'handle originale. In altri casi, tuttavia, DuplicateHandle non può creare un handle con più diritti di accesso rispetto all'originale. Ad esempio, un handle di file creato con il diritto di accesso GENERIC_READ non può essere duplicato in modo che abbia sia il GENERIC_READ che GENERIC_WRITE diritto di accesso.

In genere, il processo di destinazione chiude un handle duplicato al termine dell'utilizzo dell'handle. Per chiudere un handle duplicato dal processo di origine, chiamare DuplicateHandle con i parametri seguenti:

  • Impostare hSourceProcessHandle sul processo di destinazione dalla chiamata DuplicateHandle che ha creato l'handle.
  • Impostare hSourceHandle sull'handle duplicato da chiudere.
  • Impostare hTargetProcessHandle suNULL.
  • Impostare dwOptions su DUPLICATE_CLOSE_SOURCE.

Esempi

L'esempio seguente crea un mutex, duplica un handle per il mutex e lo passa a un altro thread. La duplicazione dell'handle garantisce che il conteggio dei riferimenti venga aumentato in modo che l'oggetto mutex non venga eliminato definitivamente finché entrambi i thread non hanno chiuso l'handle.

#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;
}

Requisiti

Requisito Valore
Client minimo supportato Windows 2000 Professional [app desktop | App UWP]
Server minimo supportato Windows 2000 Server [app desktop | App UWP]
Piattaforma di destinazione Finestre
Intestazione handleapi.h (include Windows.h)
Biblioteca kernel32.lib
DLL Kernel32.dll

Vedere anche

CloseHandle

Gestire l'ereditarietà

handle e funzioni oggetto

  • Last updated on