PROTOCOL_NET_PNP_EVENT funzione di callback (ndis.h)

Articolo
08/07/2023

NDIS chiama la funzione ProtocolNetPnPEvent per indicare un evento di rete Plug and Play, un evento NDIS PnP o un evento di risparmio energia a un driver di protocollo.

Nota È necessario dichiarare la funzione usando il tipo di PROTOCOL_NET_PNP_EVENT . Per altre informazioni, vedere la sezione Esempi seguenti.

Sintassi

PROTOCOL_NET_PNP_EVENT ProtocolNetPnpEvent;

NDIS_STATUS ProtocolNetPnpEvent(
  [in] NDIS_HANDLE ProtocolBindingContext,
  [in] PNET_PNP_EVENT_NOTIFICATION NetPnPEventNotification
)
{...}

Parametri

[in] ProtocolBindingContext

Handle in un'area di contesto allocata da protocollo-driver in cui questo driver gestisce le informazioni sullo stato di runtime per binding. Il driver del protocollo ha fornito questo handle quando ha chiamato la funzione NdisOpenAdapterEx . Un evento NetEventXxx indicato con un protocollo NULLBindingContext si applica a tutte le associazioni. NetEventBindList e NetEventBindsComplete sono sempre indicati con un protocollo NULLBindingContext. NetEventReconfigure può essere indicato con un protocollo ProtocolBindingContext specificato o con un protocollo NULLBindingContext.

[in] NetPnPEventNotification

Puntatore a NET_PNP_EVENT_NOTIFICATION struttura che descrive l'evento Plug and Play o l'evento power Management che indica NDIS al driver del protocollo.

Valore restituito

ProtocolNetPnPEvent può restituire uno dei seguenti elementi:

Codice restituito	Descrizione
NDIS_STATUS_SUCCESS	Il driver del protocollo ha gestito correttamente l'evento di rete indicato Plug and Play, l'evento NDIS PnP o l'evento di risparmio energia. Il significato di questo codice di stato dipende dal codice NetEvent nel buffer NET_PNP_EVENT_NOTIFICATION struttura in NetPnPEvent: NetEventSetPower Il driver del protocollo ha eseguito azioni specifiche del driver necessarie per preparare la transizione del dispositivo allo stato di alimentazione del dispositivo richiesto. NetEventQueryPower L'adattatore sottostante può passare allo stato di alimentazione del dispositivo richiesto. NetEventQueryRemoveDevice L'adattatore sottostante può essere rimosso. NetEventCancelRemoveDevice Il driver del protocollo ha eseguito tutte le azioni specifiche del driver necessarie per preparare la rimozione annullata dell'adattatore sottostante. NetEventReconfigure Il driver del protocollo ha accettato la configurazione modificata. NetEventBindList Il driver del protocollo ha il nuovo elenco di binding ed ha eseguito l'elaborazione correlata. NetEventBindsComplete Il driver del protocollo ha riconosciuto l'indicazione da NDIS che il driver del protocollo è associato a tutte le schede sottostanti disponibili. NetEventPnPCapabilities Il driver del protocollo ha riconosciuto che ha ricevuto le funzionalità di riattivazione correnti dell'adattatore sottostante associato all'associazione specificata. NetEventPause L'associazione del protocollo specificata ha immesso lo stato Di sospensione . L'associazione immetterà lo stato sospeso dopo che NDIS ha completato tutte le richieste di invio in sospeso per l'associazione. Per altre informazioni sulle operazioni di sospensione, vedere Sospensione di un'associazione. NetEventRestart L'associazione del protocollo specificata ha immesso lo stato Di riavvio . Dopo che il driver del protocollo è pronto per riprendere le operazioni di invio e ricezione per l'associazione, l'associazione entra nello stato In esecuzione . NetEventPortActivation Il driver del protocollo ha riconosciuto l'attivazione di una porta associata all'associazione specificata. Per altre informazioni sull'attivazione della porta, vedere Attivazione di una porta NDIS. NetEventPortDeactivation Il driver del protocollo ha riconosciuto l'attivazione di una porta associata all'associazione specificata.
NDIS_STATUS_PENDING	Il driver del protocollo restituirà la risposta all'evento indicato in modo asincrono con una chiamata all'oggetto Funzione NdisCompleteNetPnPEvent .
NDIS_STATUS_RESOURCES	Il driver del protocollo non è riuscito a ottenere le risorse di sistema necessarie per soddisfare l'evento Plug and Play o Power Management indicato.
NDIS_STATUS_NOT_SUPPORTED	I driver di protocollo NDIS 6.0 e versioni successive non devono restituire questo stato. NDIS 5. x protocol driver che non supporta Plug and Play può restituire questo stato in risposta a un netEventSetPower per indicare che NDIS deve annullare l'associazione dall'adattatore sottostante.
NDIS_STATUS_FAILURE	Il driver del protocollo ha avuto esito negativo sull'evento indicato per motivi diversi da quelli indicati nell'elenco precedente.

Un driver di protocollo può non riuscire gli eventi NetEventQueryRemoveDevice e NetEventPortActivation .

Se un driver di protocollo non riesce l'evento NetEventPortActivation , non deve usare alcuna porta associata nelle operazioni successive.

Un driver di protocollo deve sempre avere esito positivo sugli eventi NetEventRestart, NetEventIMReEnableDevice, NetEventCancelRemoveDevice, NetEventBindList, NetEventBindList, NetEventBindsComplete, NetEventPause, NetEventPortDeactivation e NetEventPnPCapabilities restituendo NDIS_STATUS_SUCCESS.

Commenti

La funzione ProtocolNetPnPEvent è necessaria nei driver di protocollo per supportare Plug and Play e Power Management. NDIS chiama ProtocolNetPnPEvent per notificare a un driver di protocollo che si è verificato un evento di rete Plug and Play, un evento NDIS PnP o Power Management.

The NET_PNP_EVENT_NOTIFICATION struttura passata a ProtocolNetPnPEvent descrive l'evento. ProtocolNetPnPEvent interpreta due elementi di base delle informazioni nella struttura NET_PNP_EVENT_NOTIFICATION:

Codice nel membro NetEvent che identifica il tipo di evento Plug and Play o Power Management.
Informazioni specifiche dell'evento. Ad esempio, con un evento NetEventSetPower il membro Buffer contiene lo stato di alimentazione del dispositivo a cui il dispositivo sta passando.

Il driver del protocollo deve salvare il puntatore NetPnPEvent . Questo puntatore è un parametro di input obbligatorio per la funzione NdisCompleteNetPnPEvent , che il driver del protocollo deve chiamare successivamente se ProtocolNetPnPEvent restituisce NDIS_STATUS_PENDING.

Un driver di protocollo deve sempre avere esito positivo su un evento NetEventQueryPower . Dopo aver stabilito una connessione attiva, un driver del protocollo può chiamare la funzione PoRegisterSystemState per registrare uno stato continuamente occupato. Purché la registrazione dello stato sia effettiva, il power manager non tenta di mettere il sistema in sospensione. Dopo che la connessione diventa inattiva, il driver del protocollo annulla la registrazione dello stato chiamando la funzione PoUnregisterSystemState . Un driver di protocollo non deve mai tentare di impedire al sistema di passare allo stato di sospensione eseguendo un evento NetEventQueryPower . Si noti che un evento NetEventQueryPower è sempre seguito da un evento NetEventSetPower . Un evento NetEventSetPower che specifica lo stato corrente del dispositivo sottostante annulla l'evento NetEventQueryPower .

Se un driver di protocollo non può rilasciare un dispositivo (ad esempio, perché il dispositivo è in uso) deve non riuscire un evento NetEventQueryRemoveDevice restituito NDIS_STATUS_FAILURE.

Un driver di protocollo deve sempre avere esito positivo su NetEventCancelRemoveDevice, netEventReconfigure, NetEventBindList, NetEventBindsComplete, NetEventPnPCapabilities, NetEventPause o NetEventPortDeactivation restituendo NDIS_STATUS_SUCCESS.

Quando si gestisce un oggetto NetEventReconfigure o netEventBindList, un driver di protocollo deve convalidare i dati associati all'evento. Per altre informazioni su tali dati, vedere NET_PNP_EVENT_NOTIFICATION.

NDIS chiama ProtocolNetPnPEvent in IRQL = PASSIVE_LEVEL.

Esempi

Per definire una funzione ProtocolNetPnPEvent , è prima necessario specificare una dichiarazione di funzione che identifica il tipo di funzione che si sta definendo. Windows fornisce un set di tipi di funzione per i driver. La dichiarazione di una funzione usando i tipi di funzione consente l'analisi del codice per i driver, il verifica driver statico (SDV) e altri strumenti di verifica trovano errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire una funzione ProtocolNetPnPEvent denominata "MyNetPnPEvent", usare il tipo di PROTOCOL_NET_PNP_EVENT come illustrato in questo esempio di codice:

PROTOCOL_NET_PNP_EVENT MyNetPnPEvent;

Implementare quindi la funzione come indicato di seguito:

_Use_decl_annotations_
NDIS_STATUS
 MyNetPnPEvent(
    NDIS_HANDLE  ProtocolBindingContext,
    PNET_PNP_EVENT_NOTIFICATION  NetPnPEvent
    )
  {...}

Il tipo di funzione PROTOCOL_NET_PNP_EVENT è definito nel file di intestazione Ndis.h. Per identificare in modo più accurato gli errori durante l'esecuzione degli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione Use_decl_annotations alla definizione della funzione. L'annotazione Use_decl_annotations garantisce che vengano usate le annotazioni applicate al tipo di funzione PROTOCOL_NET_PNP_EVENT nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo per i driver NDIS.

Per informazioni su Use_decl_annotations, vedere Annotazione del comportamento della funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Supportato in NDIS 6.0 e versioni successive.
Piattaforma di destinazione	Windows
Intestazione	ndis.h (includere Ndis.h)
IRQL	PASSIVE_LEVEL