funzione CM_Register_Notification (cfgmgr32.h)
La funzione CM_Register_Notification registra una routine di callback dell'applicazione da chiamare quando si verifica un evento PnP del tipo specificato.
Usare RegisterDeviceNotification anziché CM_Register_Notification se il codice è destinato a Windows 7 o versioni precedenti di Windows. I chiamanti in modalità kernel devono usare invece IoRegisterPlugPlayNotification .
Sintassi
CMAPI CONFIGRET CM_Register_Notification(
[in] PCM_NOTIFY_FILTER pFilter,
[in, optional] PVOID pContext,
[in] PCM_NOTIFY_CALLBACK pCallback,
[out] PHCMNOTIFICATION pNotifyContext
);
Parametri
[in] pFilter
Puntatore a una struttura CM_NOTIFY_FILTER .
[in, optional] pContext
Puntatore a un buffer allocato del chiamante contenente il contesto da passare alla routine di callback in pCallback.
[in] pCallback
Puntatore alla routine da chiamare quando si verifica l'evento PnP specificato. Vedere la sezione Osservazioni per il prototipo della funzione di callback.
Il parametro Action della routine di callback sarà un valore dell'enumerazione CM_NOTIFY_ACTION .
Al momento della ricezione di una notifica, il callback esamina la notifica dipenderà dal membro FilterType del parametro EventData della routine di callback:
CM_NOTIFY_FILTER_TYPE_DEVICEINTERFACE
Il callback deve esaminare EventData-u.DeviceInterface>.
CM_NOTIFY_FILTER_TYPE_DEVICEHANDLE
Il callback deve esaminare EventData-u.DeviceHandle>.
CM_NOTIFY_FILTER_TYPE_DEVICEINSTANCE
Il callback deve esaminare EventData-u.DeviceInstance>.
[out] pNotifyContext
Puntatore per ricevere l'handle HCMNOTIFICATION che corrisponde alla chiamata di registrazione.
Valore restituito
Se l'operazione ha esito positivo, la funzione restituisce CR_SUCCESS. In caso contrario, restituisce uno dei codici di errore con prefisso CR_ definiti in Cfgmgr32.h.
Commenti
Assicurarsi di gestire Plug and Play eventi del dispositivo il più rapidamente possibile. Se il gestore eventi esegue qualsiasi operazione che può bloccare l'esecuzione (ad esempio I/O), è consigliabile avviare un altro thread per eseguire l'operazione in modo asincrono.
La funzione CM_Register_Notification non fornisce la notifica delle interfacce del dispositivo esistenti. Per recuperare le interfacce esistenti, chiamare prima CM_Register_Notification e quindi chiamare CM_Get_Device_Interface_List. Se l'interfaccia è abilitata dopo che il driver chiama CM_Register_Notification, ma prima che il driver chiami CM_Get_Device_Interface_List, il driver riceve una notifica per l'arrivo dell'interfaccia e l'interfaccia viene visualizzata anche nell'elenco delle istanze dell'interfaccia del dispositivo restituite da CM_Get_Device_Interface_List.
Gli handle HCMNOTIFICATION restituiti da CM_Register_Notification devono essere chiusi chiamando la funzione CM_Unregister_Notification quando non sono più necessari.
Una routine di callback usa il prototipo di funzione seguente:
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
);
Se risponde a una notifica di CM_NOTIFY_ACTION_DEVICEQUERYREMOVE , il callback PCM_NOTIFY_CALLBACK deve restituire ERROR_SUCCESS o ERROR_CANCELLED, in base alle esigenze. In caso contrario, il callback deve restituire ERROR_SUCCESS. Il callback non deve restituire altri valori. Per una descrizione di altre azioni, vedere la documentazione di CM_NOTIFY_ACTION . Vedere anche CM_NOTIFY_EVENT_DATA per informazioni sulla struttura ricevuta dal callback nel parametro EventData .
Esempio
Per un esempio, vedere Registrazione per la notifica dell'arrivo dell'interfaccia dispositivo e rimozione del dispositivo.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Disponibile in Microsoft Windows 8 e versioni successive di Windows. |
| Piattaforma di destinazione | Universale |
| Intestazione | cfgmgr32.h (include Cfgmgr32.h) |
| Libreria | Cfgmgr32.lib; OneCoreUAP.lib in Windows 10 |
| DLL | CfgMgr32.dll |