CM_Register_Notification-Funktion (cfgmgr32.h)

Artikel
03/01/2024

Die funktion CM_Register_Notification registriert eine Anwendungsrückrufroutine, die aufgerufen werden soll, wenn ein PnP-Ereignis des angegebenen Typs auftritt.

Verwenden Sie RegisterDeviceNotification anstelle von CM_Register_Notification , wenn Ihr Code auf Windows 7 oder frühere Versionen von Windows abzielt. Aufrufer im Kernelmodus sollten stattdessen IoRegisterPlugPlayNotification verwenden.

Syntax

CMAPI CONFIGRET CM_Register_Notification(
  [in]           PCM_NOTIFY_FILTER   pFilter,
  [in, optional] PVOID               pContext,
  [in]           PCM_NOTIFY_CALLBACK pCallback,
  [out]          PHCMNOTIFICATION    pNotifyContext
);

Parameter

[in] pFilter

Zeiger auf eine CM_NOTIFY_FILTER-Struktur .

[in, optional] pContext

Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der den Kontext enthält, der an die Rückrufroutine in pCallback übergeben werden soll.

[in] pCallback

Zeiger auf die Routine, die aufgerufen werden soll, wenn das angegebene PnP-Ereignis auftritt. Den Prototyp der Rückruffunktion finden Sie im Abschnitt Hinweise .

Der Action-Parameter der Rückrufroutine ist ein Wert aus der CM_NOTIFY_ACTION-Enumeration .

Wenn eine Benachrichtigung empfangen wird, hängt die Art und Weisen, wie der Rückruf die Benachrichtigung untersucht, vom FilterType-Element des EventData-Parameters der Rückrufroutine ab:

CM_NOTIFY_FILTER_TYPE_DEVICEINTERFACE

Der Rückruf sollte EventData-u.DeviceInterface> untersuchen.

CM_NOTIFY_FILTER_TYPE_DEVICEHANDLE

Der Rückruf sollte EventData-u.DeviceHandle> untersuchen.

CM_NOTIFY_FILTER_TYPE_DEVICEINSTANCE

Der Rückruf sollte EventData-u.DeviceInstance> untersuchen.

[out] pNotifyContext

Zeiger zum Empfangen des HCMNOTIFICATION-Handles, das dem Registrierungsaufruf entspricht.

Rückgabewert

Wenn der Vorgang erfolgreich ist, gibt die Funktion CR_SUCCESS zurück. Andernfalls wird einer der in Cfgmgr32.h definierten Fehlercodes mit CR_ Präfix zurückgegeben.

Hinweise

Achten Sie darauf, Plug & Play Geräteereignisse so schnell wie möglich zu behandeln. Wenn Ihr Ereignishandler einen Vorgang ausführt, der die Ausführung möglicherweise blockiert (z. B. E/A), empfiehlt es sich, einen anderen Thread zu starten, um den Vorgang asynchron auszuführen.

Die funktion CM_Register_Notification stellt keine Benachrichtigung über vorhandene Geräteschnittstellen bereit. Um vorhandene Schnittstellen abzurufen, rufen Sie zuerst CM_Register_Notification und dann CM_Get_Device_Interface_List auf. Wenn die Schnittstelle aktiviert ist, nachdem Ihr Treiber CM_Register_Notification aufgerufen hat, aber bevor der Treiber CM_Get_Device_Interface_List aufruft, erhält der Treiber eine Benachrichtigung über die Ankunft der Schnittstelle, und die Schnittstelle wird auch in der Liste der Geräteschnittstelleninstanzen angezeigt, die von CM_Get_Device_Interface_List zurückgegeben werden.

HCMNOTIFICATION-Handles, die von CM_Register_Notification zurückgegeben werden, müssen durch Aufrufen der funktion CM_Unregister_Notification geschlossen werden, wenn sie nicht mehr benötigt werden.

Eine Rückrufroutine verwendet den folgenden Funktionsprototyp:

typedef __callback DWORD (CALLBACK *PCM_NOTIFY_CALLBACK)(
    _In_ HCMNOTIFICATION       hNotify,
    _In_opt_ PVOID             Context,
    _In_ CM_NOTIFY_ACTION      Action,
    _In_reads_bytes_(EventDataSize) PCM_NOTIFY_EVENT_DATA EventData,
    _In_ DWORD                 EventDataSize
    );

Wenn Sie auf eine CM_NOTIFY_ACTION_DEVICEQUERYREMOVE-Benachrichtigung reagieren, sollte der PCM_NOTIFY_CALLBACK Rückruf entweder ERROR_SUCCESS oder ERROR_CANCELLED zurückgeben. Andernfalls sollte der Rückruf ERROR_SUCCESS zurückgeben. Der Rückruf sollte keine anderen Werte zurückgeben. Eine Beschreibung anderer Aktionen finden Sie in der Dokumentation zu CM_NOTIFY_ACTION . Informationen zur Struktur, die dieser Rückruf im EventData-Parameter empfängt, finden Sie auch unter CM_NOTIFY_EVENT_DATA.

Beispiele

Ein Beispiel finden Sie unter Registrieren für die Benachrichtigung über die Ankunft der Geräteschnittstelle und Geräteentfernung.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Microsoft Windows 8 und höheren Versionen von Windows.
Zielplattform	Universell
Header	cfgmgr32.h (include Cfgmgr32.h)
Bibliothek	Cfgmgr32.lib; OneCoreUAP.lib auf Windows 10
DLL	CfgMgr32.dll