CompareObjectHandles, fonction (handleapi.h)

Compare deux handles d’objet pour déterminer s’ils font référence au même objet noyau sous-jacent.

Syntaxe

BOOL CompareObjectHandles(
  [in] HANDLE hFirstObjectHandle,
  [in] HANDLE hSecondObjectHandle
);

Paramètres

[in] hFirstObjectHandle

Premier handle d’objet à comparer.

[in] hSecondObjectHandle

Deuxième handle d’objet à comparer.

Valeur retournée

Valeur booléenne qui indique si les deux handles font référence au même objet noyau sous-jacent. TRUE si identique, sinon FALSE.

Remarques

La fonction CompareObjectHandles est utile pour déterminer si deux descripteurs de noyau font référence au même objet de noyau sans imposer l’octroi de droits d’accès spécifiques à l’un ou l’autre des handles pour effectuer la comparaison. Par exemple, si un processus souhaite déterminer si un handle de processus est un handle pour le processus actuel, un appel à CompareObjectHandles (GetCurrentProcess (), hProcess) peut être utilisé pour déterminer si hProcess fait référence au processus actuel. Notamment, cela ne nécessite pas l’utilisation de droits d’accès spécifiques à l’objet, alors que dans cet exemple, l’appel de GetProcessId pour case activée les ID de processus de deux handles de processus impose que les handles accordent un accès PROCESS_QUERY_LIMITED_INFORMATION. Toutefois, il est légal pour un handle de processus de ne pas avoir ce droit d’accès accordé en fonction de la façon dont le handle est destiné à être utilisé.

Exemples

L’exemple de code suivant crée trois handles, dont deux font référence au même objet, puis les compare pour montrer que les objets noyau sous-jacents identiques retournent TRUE, tandis que les objets non identiques retournent FALSE.

#include <windows.h>
#include <stdio.h>
#include <wchar.h>

HANDLE Event1;
HANDLE Event2;
HANDLE Event3;

	// Create a handle to a named event.
Event1 = CreateEventW (NULL, TRUE, FALSE, L"{75A520B7-2C11-4809-B43A-0D31FB1FDD19}");
if (Event1 == NULL) {	ExitProcess (0);	}

	// Create a handle to the same event.
Event2 = CreateEventW (NULL, TRUE, FALSE, L"{75A520B7-2C11-4809-B43A-0D31FB1FDD19}");
if (Event2 == NULL) {	ExitProcess (0);	}

	// Create a handle to an anonymous, unnamed event.
Event3 = CreateEventW (NULL, TRUE, FALSE, NULL);
if (Event3 == NULL) {	ExitProcess (0);	}

	// Compare two handles to the same kernel object.
if (CompareObjectHandles (Event1, Event2) != FALSE) 
	{	// This message should be printed by the program.
		wprintf (L"Event1 and Event2 refer to the same underlying event object.\n");
	}

	// Compare two handles to different kernel objects.
if (CompareObjectHandles (Event1, Event3) == FALSE) 
	{	// This message should be printed by the program.
		wprintf (L"Event1 and Event3 refer to different underlying event objects.  (Error %lu)\n", GetLastError ());		
	}

	// Compare two handles to different kernel objects, each of a different type of kernel object.
	// The comparison is legal to make, though the function will always return FALSE and indicate 
	// a last error status of ERROR_NOT_SAME_OBJECT.
if (CompareObjectHandles (Event1, GetCurrentProcess ()) == FALSE) 
	{	// This message should be printed by the program.
		wprintf (L"Event1 and the current process refer to different underlying kernel objects.  (Error %lu)\n", GetLastError ());
	}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 10 [applications de bureau | Applications UWP]
Serveur minimal pris en charge	Windows Server 2016 [applications de bureau | Applications UWP]
Plateforme cible	Windows
En-tête	handleapi.h (inclure Windows.h)
Bibliothèque	Kernelbase.lib
DLL	Kernelbase.dll

Voir aussi

Fonctions de handle et d’objet