Condividi tramite


PROTOCOL_BIND_ADAPTER_EX funzione di callback (ndis.h)

NDIS chiama la funzione ProtocolBindAdapterEx di un driver di protocollo per richiedere al driver di eseguire l'associazione a un adattatore miniport.

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

Sintassi

PROTOCOL_BIND_ADAPTER_EX ProtocolBindAdapterEx;

NDIS_STATUS ProtocolBindAdapterEx(
  [in] NDIS_HANDLE ProtocolDriverContext,
  [in] NDIS_HANDLE BindContext,
  [in] PNDIS_BIND_PARAMETERS BindParameters
)
{...}

Parametri

[in] ProtocolDriverContext

Handle per un'area di contesto allocata dal driver in cui il driver mantiene le informazioni sullo stato e sulla configurazione. Il driver di protocollo ha passato questa area di contesto all'oggetto Funzione NdisRegisterProtocolDriver .

[in] BindContext

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

[in] BindParameters

Puntatore a una struttura NDIS_BIND_PARAMETERS creata da NDIS.

Valore restituito

ProtocolBindAdapterEx restituisce uno dei valori di stato seguenti:

Codice restituito Descrizione
NDIS_STATUS_SUCCESS
ProtocolBindAdapterEx ha completato correttamente l'associazione all'adattatore miniport sottostante.
NDIS_STATUS_PENDING
ProtocolBindAdapterEx non ha completato l'operazione di associazione e l'operazione verrà completata in modo asincrono. Il driver di protocollo deve chiamare il Funzione NdisCompleteBindAdapterEx al termine dell'operazione.
NDIS_STATUS_RESOURCES
ProtocolBindAdapterEx non è riuscito ad allocare le risorse richieste dal driver per eseguire operazioni di I/O di rete.
NDIS_STATUS_XXX o NTSTATUS_XXX
Il tentativo del driver di protocollo di configurare un'associazione non è riuscita. In genere, tale stato di errore viene propagato da una funzione NdisXxx o da una routine di supporto in modalità kernel.

Commenti

ProtocolBindAdapterEx è una funzione obbligatoria. NDIS chiama ProtocolBindAdapterEx per eseguire operazioni di associazione ogni volta che un adattatore miniport sottostante, a cui il driver del protocollo può essere associato, diventa disponibile.

ProtocolBindAdapterEx alloca memoria sufficiente per mantenere le informazioni sul contesto di associazione e chiama la funzione NdisOpenAdapterEx per associarsi all'adattatore miniport sottostante. ProtocolBindAdapterEx passa un puntatore alle informazioni sul contesto di associazione nel parametro ProtocolBindingContext di NdisOpenAdapterEx. ProtocolBindAdapterEx passa il valore al membro AdapterName dal parametro BindParameters come membro AdapterName del parametro OpenParameters di NdisOpenAdapterEx.

Prima che il driver chiami NdisOpenAdapterEx, il driver può passare il puntatore in BindParameters alla funzione NdisOpenConfigurationEx per leggere i parametri di configurazione associati a un adattatore miniport.

Dopo aver aperto correttamente l'adattatore miniport, il driver può passare l'handle dal parametro NdisHandle di NdisOpenAdapterEx a NdisOpenConfigurationEx per ottenere un handle nel percorso del Registro di sistema in cui vengono archiviati i parametri di configurazione per un'associazione di protocollo.

ProtocolBindAdapterEx passa NdisOpenAdapterEx a un puntatore di una matrice di valori di tipo medio che elenca i tipi di supporti supportati dal driver del protocollo. Questo elenco è un subset dei tipi di NDIS_MEDIUM . NDIS indica il tipo medio selezionato nel parametro SelectedMediumIndex della struttura in OpenParameters.

Se NdisOpenAdapterEx restituisce uno stato di errore, ProtocolBindAdapterEx restituisce lo stato di errore, rilascia tutte le risorse per associazione allocate dal driver del protocollo e restituisce immediatamente il controllo.

Se NdisOpenAdapterEx restituisce NDIS_STATUS_SUCCESS, ProtocolBindAdapterEx può allocare le risorse rimanenti necessarie al driver del protocollo per eseguire le operazioni di I/O di rete sull'associazione. Il driver può anche configurare qualsiasi informazione di contesto specifica dell'associazione usata dal driver per tenere traccia delle operazioni di I/O di rete.

Se NdisOpenAdapterEx restituisce NDIS_STATUS_PENDING, NDIS chiama il driver del protocollo Funzione ProtocolOpenAdapterCompleteEx al termine dell'operazione di apertura. ProtocolOpenAdapterCompleteEx può completare le operazioni di associazione. ProtocolBindAdapterEx può archiviare l'handle BindContext nell'area del contesto di associazione. NDIS passa ProtocolBindingContext come parametro di input alla funzione ProtocolOpenAdapterCompleteEx del driver.

Se NdisOpenAdapterEx restituisce NDIS_STATUS_PENDING, NDIS imposta il membro SelectedMediumIndex della struttura in corrispondenza del parametro OpenParameters e il valore del parametro NdisBindingHandle dopo la restituzione di NdisOpenAdapterEx . NDIS imposta questi valori prima di chiamare ProtocolOpenAdapterCompleteEx. Pertanto, il driver del protocollo deve archiviare la struttura dei parametri aperti e l'handle di associazione del protocollo nell'area di contesto in ProtocolBindingContext(o qualsiasi posizione valida fino a quando NDIS chiama ProtocolOpenAdapterCompleteEx).

Un driver di protocollo non può effettuare richieste OID su un'associazione fino al completamento dell'operazione di apertura. Poiché l'associazione si trova nello stato sospeso dopo il completamento dell'operazione di apertura, il driver del protocollo non può inviare richieste fino al riavvio dell'associazione da parte di NDIS.

Al termine dell'operazione di apertura, ProtocolBindAdapterEx può restituire NDIS_STATUS_SUCCESS per completare l'operazione di associazione. ProtocolBindAdapterEx può restituire NDIS_STATUS_PENDING per rinviare il completamento delle operazioni di associazione a un secondo momento. Se ProtocolBindAdapterEx restituisce NDIS_STATUS_PENDING, il driver deve chiamare il Funzione NdisCompleteBindAdapterEx al termine dell'operazione di associazione.

I driver di protocollo devono usare la struttura NDIS_BIND_PARAMETERS per determinare le funzionalità dell'adattatore miniport sottostante. Al termine dell'operazione di apertura, a seconda del supporto sottostante, il driver del protocollo può chiamare la funzione NdisOidRequest per eseguire una query sul driver miniport sottostante (o NDIS) sulle funzionalità aggiuntive dell'adattatore miniport. Per altre informazioni sulle richieste OID, vedere Richieste OID del driver del protocollo.

NDIS può chiamare un driver di protocollo Funzione ProtocolReceiveNetBufferLists dopo che il driver configura un filtro di pacchetti per l'associazione con OID_GEN_CURRENT_PACKET_FILTER OID. Se l'adattatore miniport sottostante non usa un filtro pacchetti per i pacchetti in ingresso, le indicazioni di ricezione vengono abilitate al termine dell'operazione di apertura. I driver di protocollo possono ricevere indicazioni sullo stato nella funzione ProtocolStatusEx al termine dell'operazione di apertura.

Ogni driver di protocollo deve allocare NET_BUFFER eNET_BUFFER_LIST pool di strutture sufficienti. Il driver alloca i descrittori di dati di rete da questi pool per le operazioni di invio successive.

Se ProtocolBindAdapterEx non può allocare le risorse necessarie per eseguire le operazioni di I/O di rete successive, deve liberare tutte le risorse già allocate e restituire un valore di errore appropriato.

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

Se il driver di protocollo apre correttamente l'adattatore miniport ma l'operazione di associazione ha esito negativo (ad esempio, a causa di una richiesta OID non riuscita), il driver deve chiudere l'adattatore miniport dal contesto di ProtocolBindAdapterEx o ProtocolUnbindAdapterEx. Ad esempio, il driver chiama NdisCloseAdapterEx da ProtocolBindAdapterEx e attende il completamento dell'operazione di chiusura prima che il driver torni da ProtocolBindAdapterEx. In alternativa, se il driver ha restituito NDIS_STATUS_PENDING da ProtocolBindAdapterEx, il driver può chiamare la funzione NdisUnbindAdapter e chiamare NdisCloseAdapterEx nella funzione ProtocolUnbindAdapterEx .

NDIS chiama ProtocolBindAdapterEx in IRQL = PASSIVE_LEVEL.

Esempi

Per definire una funzione ProtocolBindAdapterEx , è 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 ProtocolBindAdapterEx denominata "MyBindAdapterEx", usare il tipo PROTOCOL_BIND_ADAPTER_EX come illustrato nell'esempio di codice seguente:

PROTOCOL_BIND_ADAPTER_EX MyBindAdapterEx;

Implementare quindi la funzione come segue:

_Use_decl_annotations_
NDIS_STATUS
 MyBindAdapterEx(
    NDIS_HANDLE  ProtocolDriverContext,
    NDIS_HANDLE  BindContext,
    PNDIS_BIND_PARAMETERS  BindParameters
    )
  {...}

Il tipo di funzione PROTOCOL_BIND_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 garantisce che vengano utilizzate le annotazioni applicate al tipo di funzione PROTOCOL_BIND_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 in NDIS 6.0 e versioni successive.
Piattaforma di destinazione Windows
Intestazione ndis.h (include Ndis.h)
IRQL PASSIVE_LEVEL

Vedi anche

NDIS_BIND_PARAMETERS

NDIS_MEDIUM

NET_BUFFER

NET_BUFFER_LIST

NdisCloseAdapterEx

NdisCompleteBindAdapterEx

NdisOidRequest

NdisOpenAdapterEx

NdisOpenConfigurationEx

NdisRegisterProtocolDriver

NdisUnbindAdapter

OID_GEN_CURRENT_PACKET_FILTER

ProtocolOpenAdapterCompleteEx ProtocolReceiveNetBufferLists

ProtocolStatusEx

ProtocolUnbindAdapterEx