Fonction DuplicateHandle (handleapi.h)

Dupliquer un handle d’objet.

Syntaxe

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

Paramètres

[in] hSourceProcessHandle

Handle vers le processus avec le handle à dupliquer.

Le handle doit disposer du droit d’accès PROCESS_DUP_HANDLE. Pour plus d’informations, consultez Processus de sécurité et de droits d’accès.

[in] hSourceHandle

Handle à dupliquer. Il s’agit d’un handle d’objet ouvert valide dans le contexte du processus source. Pour obtenir la liste des objets dont les handles peuvent être dupliqués, consultez la section Remarques suivante.

Si hSourceHandle est un pseudo-handle retourné par GetCurrentProcess ou GetCurrentThread, hSourceProcessHandle doit être un handle pour le processus appelant DuplicateHandle.

[in] hTargetProcessHandle

Handle du processus qui doit recevoir le handle dupliqué. Le handle doit disposer du droit d’accès PROCESS_DUP_HANDLE.

Ce paramètre est facultatif et peut être spécifié comme NULL si l’indicateur de DUPLICATE_CLOSE_SOURCE est défini dans Options.

[out] lpTargetHandle

Pointeur vers une variable qui reçoit le handle en double. Cette valeur de handle est valide dans le contexte du processus cible.

Si hSourceHandle est un pseudo-handle retourné par GetCurrentProcess ou GetCurrentThread, DuplicateHandle le convertit en handle réel en processus ou thread, respectivement.

Si lpTargetHandle a la valeur NULL, la fonction dupliquera le handle, mais ne retourne pas la valeur de handle dupliquée à l’appelant. Ce comportement existe uniquement pour la compatibilité descendante avec les versions précédentes de cette fonction. Vous ne devez pas utiliser cette fonctionnalité, car vous perdrez les ressources système jusqu’à ce que le processus cible se termine.

Ce paramètre est ignoré si hTargetProcessHandle a la valeur NULL.

[in] dwDesiredAccess

Accès demandé pour le nouveau handle. Pour connaître les indicateurs qui peuvent être spécifiés pour chaque type d’objet, consultez la section Remarques suivante.

Ce paramètre est ignoré si le paramètre dwOptions spécifie l’indicateur DUPLICATE_SAME_ACCESS. Sinon, les indicateurs qui peuvent être spécifiés dépendent du type d’objet dont le handle doit être dupliqué.

Ce paramètre est ignoré si hTargetProcessHandle a la valeur NULL.

[in] bInheritHandle

Variable qui indique si le handle est hériter. Si la valeur est TRUE, le handle dupliqué peut être hérité par de nouveaux processus créés par le processus cible. Si la valeur est FALSE, le nouveau handle ne peut pas être hérité.

Ce paramètre est ignoré si hTargetProcessHandle a la valeur NULL.

[in] dwOptions

Actions facultatives. Ce paramètre peut être égal à zéro ou n’importe quelle combinaison des valeurs suivantes.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Remarques

Le handle dupliqué fait référence au même objet que le handle d’origine. Par conséquent, toutes les modifications apportées à l’objet sont reflétées par les deux handles. Par exemple, si vous dupliquez un handle de fichier, la position de fichier actuelle est toujours la même pour les deux handles. Pour que les handles de fichiers aient des positions de fichier différentes, utilisez la fonction CreateFile pour créer des handles de fichier qui partagent l’accès au même fichier.

DuplicateHandle peut être appelé par le processus source ou le processus cible (ou un processus qui est à la fois la source et le processus cible). Par exemple, un processus peut utiliser DuplicateHandle pour créer un doublon non modifiable d’un handle hériter ou un handle avec un accès différent de celui du handle d’origine.

Le processus source utilise la fonction GetCurrentProcess pour obtenir un handle à lui-même. Ce handle est un pseudo-handle, mais DuplicateHandle le convertit en handle de processus réel. Pour obtenir le handle de processus cible, il peut être nécessaire d’utiliser une forme de communication interprocesseur (par exemple, un canal nommé ou une mémoire partagée) pour communiquer l’identificateur de processus au processus source. Le processus source peut utiliser cet identificateur dans la fonction OpenProcess pour obtenir un handle au processus cible.

Si le processus qui appelle DuplicateHandle n’est pas également le processus cible, le processus source doit utiliser la communication interprocess pour transmettre la valeur du handle dupliqué au processus cible.

DuplicateHandle peut être utilisé pour dupliquer un handle entre un processus 32 bits et un processus 64 bits. Le handle résultant est correctement dimensionné pour fonctionner dans le processus cible. Pour plus d’informations, consultez l’interopérabilité des processus.

DuplicateHandle peut dupliquer des handles aux types d’objets suivants.

Vous ne devez pas utiliser DuplicateHandle pour dupliquer les handles aux objets suivants :

• Ports d’achèvement des E/S. Aucune erreur n’est retournée, mais le handle dupliqué ne peut pas être utilisé.
• Prises. Aucune erreur n’est retournée, mais le handle dupliqué peut ne pas être reconnu par Winsock au niveau du processus cible. En outre, l’utilisation de DuplicateHandle interfère avec le comptage de référence interne sur l’objet sous-jacent. Pour dupliquer un handle de socket, utilisez la fonction WSADuplicateSocket .
• Pseudo-handles autres que ceux retournés par les fonctions GetCurrentProcess ou GetCurrentThread .

• sécurité du bureau et droits d’accès
• Droits de sécurité et d’accès aux fichiers
• File-Mapping droits de sécurité et d’accès
• Sécurité des objets de travail et droits d’accès
• processus de sécurité et de droits d’accès
• sécurité des clés de Registre et droits d’accès
• Sécurité des objets de synchronisation et droits d’accès
• droits d’accès et de sécurité des threads
• Window-Station droits de sécurité et d’accès

Normalement, le processus cible ferme un handle dupliqué lorsque ce processus est terminé à l’aide du handle. Pour fermer un handle dupliqué à partir du processus source, appelez DuplicateHandle avec les paramètres suivants :

• Définissez hSourceProcessHandle sur le processus cible à partir de l’appel DuplicateHandle qui a créé le handle.
• Définissez hSourceHandle sur le handle dupliqué pour fermer.
• Définissez hTargetProcessHandle sur NULL.
• Définissez dwOptions sur DUPLICATE_CLOSE_SOURCE.

Exemples

L’exemple suivant crée un mutex, duplique un handle au mutex et le transmet à un autre thread. La duplication du handle garantit que le nombre de références est augmenté afin que l’objet mutex ne soit pas détruit tant que les deux threads n’ont pas fermé le 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;
}

Spécifications

Voir aussi

closeHandle

Gérer l’héritage

handle et fonctions d’objet