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

Vedi anche

CM_NOTIFY_ACTION

CM_NOTIFY_FILTER

CM_Unregister_Notification

RegisterDeviceNotification

Registrazione per la notifica dell'arrivo dell'interfaccia dispositivo e la rimozione del dispositivo

Uso di interfacce dispositivo