fonction CM_Register_Notification (cfgmgr32.h)

Article
02/28/2024

La fonction CM_Register_Notification inscrit une routine de rappel d’application à appeler lorsqu’un événement PnP du type spécifié se produit.

Utilisez RegisterDeviceNotification au lieu de CM_Register_Notification si votre code cible Windows 7 ou les versions antérieures de Windows. Les appelants en mode noyau doivent utiliser IoRegisterPlugPlayNotification à la place.

Syntaxe

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

Paramètres

[in] pFilter

Pointeur vers une structure CM_NOTIFY_FILTER .

[in, optional] pContext

Pointeur vers une mémoire tampon allouée par l’appelant contenant le contexte à passer à la routine de rappel dans pCallback.

[in] pCallback

Pointeur vers la routine à appeler lorsque l’événement PnP spécifié se produit. Consultez la section Remarques pour le prototype de la fonction de rappel.

Le paramètre Action de la routine de rappel sera une valeur de l’énumération CM_NOTIFY_ACTION .

Lors de la réception d’une notification, la façon dont le rappel examine la notification dépend du membre FilterType du paramètre EventData de la routine de rappel :

CM_NOTIFY_FILTER_TYPE_DEVICEINTERFACE

Le rappel doit examiner EventData-u.DeviceInterface>.

CM_NOTIFY_FILTER_TYPE_DEVICEHANDLE

Le rappel doit examiner EventData-u.DeviceHandle>.

CM_NOTIFY_FILTER_TYPE_DEVICEINSTANCE

Le rappel doit examiner EventData-u.DeviceInstance>.

[out] pNotifyContext

Pointeur pour recevoir le handle HCMNOTIFICATION qui correspond à l’appel d’inscription.

Valeur retournée

Si l’opération réussit, la fonction retourne CR_SUCCESS. Sinon, il retourne l’un des codes d’erreur CR_ préfixés définis dans Cfgmgr32.h.

Remarques

Veillez à gérer Plug-and-Play événements d’appareil aussi rapidement que possible. Si votre gestionnaire d’événements effectue une opération susceptible de bloquer l’exécution (par exemple, les E/S), il est préférable de démarrer un autre thread pour effectuer l’opération de manière asynchrone.

La fonction CM_Register_Notification ne fournit pas de notification des interfaces d’appareil existantes. Pour récupérer des interfaces existantes, appelez d’abord CM_Register_Notification, puis appelez CM_Get_Device_Interface_List. Si l’interface est activée après que votre pilote a appelé CM_Register_Notification, mais avant que votre pilote n’appelle CM_Get_Device_Interface_List, le pilote reçoit une notification pour l’arrivée de l’interface et l’interface apparaît également dans la liste des instances d’interface de périphérique retournées par CM_Get_Device_Interface_List.

Les handles HCMNOTIFICATION retournés par CM_Register_Notification doivent être fermés en appelant la fonction CM_Unregister_Notification lorsqu’ils ne sont plus nécessaires.

Une routine de rappel utilise le prototype de fonction suivant :

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
    );

Si vous répondez à une notification de CM_NOTIFY_ACTION_DEVICEQUERYREMOVE , le rappel PCM_NOTIFY_CALLBACK doit retourner ERROR_SUCCESS ou ERROR_CANCELLED, le cas échéant. Sinon, le rappel doit retourner ERROR_SUCCESS. Le rappel ne doit pas retourner d’autres valeurs. Pour obtenir une description des autres actions, reportez-vous à la documentation CM_NOTIFY_ACTION . Consultez également CM_NOTIFY_EVENT_DATA pour plus d’informations sur la structure que ce rappel reçoit dans le paramètre EventData .

Exemples

Pour obtenir un exemple, consultez Inscription pour notification de l’arrivée de l’interface d’appareil et de la suppression d’appareil.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Microsoft Windows 8 et versions ultérieures de Windows.
Plateforme cible	Universal
En-tête	cfgmgr32.h (inclure Cfgmgr32.h)
Bibliothèque	Cfgmgr32.lib ; OneCoreUAP.lib sur Windows 10
DLL	CfgMgr32.dll