PROTOCOL_UNBIND_ADAPTER_EX funzione di callback (ndis.h)

Articolo
03/05/2024

NDIS chiama la funzione ProtocolUnbindAdapterEx di un driver di protocollo per richiedere al driver di annullare l'associazione da un adattatore miniport sottostante.

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

Sintassi

PROTOCOL_UNBIND_ADAPTER_EX ProtocolUnbindAdapterEx;

NDIS_STATUS ProtocolUnbindAdapterEx(
  [in] NDIS_HANDLE UnbindContext,
  [in] NDIS_HANDLE ProtocolBindingContext
)
{...}

Parametri

[in] UnbindContext

Handle che identifica l'area del contesto NDIS per questa operazione di annullamento dell'associazione.

[in] ProtocolBindingContext

Handle per un'area di contesto allocata dal driver del protocollo. Il driver di protocollo gestisce le informazioni sul contesto per associazione in questa area di contesto. Il driver ha fornito questo handle a NDIS quando il driver ha chiamato la funzione NdisOpenAdapterEx .

Valore restituito

ProtocolUnbindAdapterEx restituisce uno dei valori di stato seguenti:

Codice restituito	Descrizione
NDIS_STATUS_SUCCESS	ProtocolUnbindAdapterEx non è stato associato correttamente da un adattatore miniport sottostante.
NDIS_STATUS_PENDING	ProtocolUnbindAdapterEx non ha completato l'operazione di annullamento dell'associazione e l'operazione verrà completata in modo asincrono. Il driver di protocollo deve chiamare il Funzione NdisCompleteUnbindAdapterEx al termine dell'operazione unbind.

Commenti

ProtocolUnbindAdapterEx è una funzione obbligatoria. Come reciproco della funzione ProtocolBindAdapterEx , NDIS chiama ProtocolUnbindAdapterEx per rilasciare le risorse allocate dal driver per le operazioni di I/O di rete specifiche di un'associazione. Un driver di protocollo non può eseguire un'operazione di associazione.

Prima di chiamare ProtocolUnbindAdapterEx, NDIS sospende l'associazione di protocollo. Per sospendere l'associazione, NDIS chiama la funzione ProtocolNetPnPEvent e specifica un evento NetEventPause .

ProtocolUnbindAdapterEx deve chiamare la funzione NdisCloseAdapterEx per chiudere l'associazione all'adattatore miniport sottostante. Se NdisCloseAdapterEx restituisce NDIS_STATUS_SUCCESS, l'operazione di chiusura è stata completata. Se NdisCloseAdapterEx restituisce NDIS_STATUS_PENDING, NDIS chiama il driver del protocollo Funzione ProtocolCloseAdapterCompleteEx al termine dell'operazione di chiusura.

Prima di chiamare NdisCloseAdapterEx, il driver del protocollo deve cancellare l'elenco di indirizzi multicast e i filtri pacchetti per l'associazione. Il driver di protocollo imposta l'elenco di indirizzi multicast di associazione su NULL e il filtro di pacchetti su zero. Per altre informazioni, vedere OID_802_3_MULTICAST_LIST e OID_GEN_CURRENT_PACKET_FILTER.

Se è stato specificato un modello di riattivazione, il driver del protocollo deve rimuoverlo con l'OID OID_PNP_REMOVE_WAKE_UP_PATTERN e cancellare i parametri di ridimensionamento laterale di ricezione con l'OID OID_GEN_RECEIVE_SCALE_PARAMETERS . Un driver di protocollo NDIS 6.20 e versioni successive deve rimuovere un modello di riattivazione LAN con l'OID OID_PM_REMOVE_WOL_PATTERN e rimuovere un offload del protocollo a basso consumo con l'OID OID_PM_REMOVE_PROTOCOL_OFFLOAD .

ProtocolUnbindAdapterEx non deve liberare la memoria in ProtocolBindingContext fino al completamento dell'operazione di chiusura. NDIS passa l'handle in ProtocolBindingContext a ProtocolCloseAdapterCompleteEx.

Se il driver del protocollo ha completato l'operazione di annullamento dell'associazione, ProtocolUnbindAdapterEx può restituire NDIS_STATUS_SUCCESS. Se NdisCloseAdapterEx restituisce NDIS_STATUS_PENDING, ProtocolUnbindAdapterEx deve attendere che NDIS chiami ProtocolCloseAdapterCompleteEx prima di poter restituire NDIS_STATUS_SUCCESS.

ProtocolUnbindAdapterEx può restituire NDIS_STATUS_PENDING per rinviare il completamento dell'operazione di debind a un secondo momento. Se ProtocolUnbindAdapterEx restituisce NDIS_STATUS_PENDING, il driver deve chiamare il Funzione NdisCompleteUnbindAdapterEx per completare l'operazione di annullamento dell'associazione. Se la funzione NdisCloseAdapterEx ha restituito NDIS_STATUS_PENDING, il driver può completare l'operazione unbind in ProtocolCloseAdapterCompleteEx. ProtocolUnbindAdapterEx può archiviare l'handle in UnbindContext nell'area di contesto in ProtocolBindingContext prima di chiamare NdisCloseAdapterEx. Se ProtocolUnbindAdapterEx ha archiviato l'handle, ProtocolCloseAdapterCompleteEx può passare l'handle a NdisCompleteUnbindAdapterEx per completare l'operazione di annullamento dell'associazione.

Non appena ProtocolUnbindAdapterEx chiama NdisCloseAdapterEx, l'handle ottenuto dalla funzione NdisOpenAdapterEx nel parametro NdisBindingHandle diventa non valido. ProtocolUnbindAdapterEx non può effettuare chiamate successive alle funzioni NdisXxx con questo handle. Il driver può ottenere indicazioni di stato e ricezione dall'adattatore miniport sottostante fino al completamento dell'operazione di chiusura.

NDIS chiama ProtocolUnbindAdapterEx in IRQL = PASSIVE_LEVEL.

Aggiornamento delle impostazioni di Risparmio energia e RSS

I driver di protocollo NDIS 6.0 e 6.1 devono eseguire le operazioni seguenti, se applicabile:

Rimuovere i modelli di riattivazione del risparmio energia lan (WOL) dalla scheda miniport con il OID_PNP_REMOVE_WAKE_UP_PATTERN OID.
Cancellare i parametri di ridimensionamento laterale di ricezione con OID_GEN_RECEIVE_SCALE_PARAMETERS OID.

I driver di protocollo NDIS 6.20 e versioni successive devono eseguire le operazioni seguenti:

Rimuovere i modelli WOL di risparmio energia dall'adattatore miniport con l'OID OID_PM_REMOVE_WOL_PATTERN .
Rimuovere gli offload del protocollo di risparmio energia dall'adattatore miniport con il OID_PM_REMOVE_PROTOCOL_OFFLOAD OID.

Esempi

Per definire una funzione ProtocolUnbindAdapterEx , è innanzitutto necessario fornire 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 con i tipi di funzione consente di eseguire l'analisi del codice per i driver, l'SDV ( Static Driver Verifier ) e altri strumenti di verifica rilevano gli errori ed è un requisito per la scrittura dei driver per il sistema operativo Windows.

Ad esempio, per definire una funzione ProtocolUnbindAdapterEx denominata "MyUnbindAdapterEx", usare il tipo PROTOCOL_UNBIND_ADAPTER_EX , come illustrato in questo esempio di codice:

PROTOCOL_UNBIND_ADAPTER_EX MyUnbindAdapterEx;

Implementare quindi la funzione come segue:

_Use_decl_annotations_
NDIS_STATUS
 MyUnbindAdapterEx(
    NDIS_HANDLE  UnbindContext,
    NDIS_HANDLE  ProtocolBindingContext
    )
  {...}

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

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

Requisiti

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