PROTOCOL_OID_REQUEST_COMPLETE funzione di callback (ndis.h)

Articolo
08/07/2023

La funzione ProtocolOidRequestComplete completa l'elaborazione di una richiesta OID avviata dal driver di protocollo per cui la funzione NdisOidRequest ha restituito NDIS_STATUS_PENDING.

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

Sintassi

PROTOCOL_OID_REQUEST_COMPLETE ProtocolOidRequestComplete;

void ProtocolOidRequestComplete(
  [in] NDIS_HANDLE ProtocolBindingContext,
  [in] PNDIS_OID_REQUEST OidRequest,
  [in] NDIS_STATUS Status
)
{...}

Parametri

[in] ProtocolBindingContext

Handle per un'area di contesto allocata dal driver del protocollo in cui il driver del protocollo mantiene lo stato di runtime per associazione. Il driver ha fornito questo handle quando ha chiamato la funzione NdisOpenAdapterEx .

[in] OidRequest

Puntatore alla struttura di NDIS_OID_REQUEST fornita dal driver del protocollo passata in precedenza alla funzione NdisOidRequest .

[in] Status

Stato finale della richiesta. Il driver sottostante o NDIS determina questo stato finale. Questo parametro determina le operazioni di ProtocolOidRequestComplete con le informazioni in OidRequest.

Valore restituito

nessuno

Osservazioni

ProtocolOidRequestComplete usa il valore di input di Status come indicato di seguito:

Se Status è NDIS_STATUS_SUCCESS, il membro ByteRead o ByteScritto della struttura NDIS_OID_REQUEST è stato impostato da NDIS o dal driver sottostante per specificare la quantità di informazioni fornite dal driver del protocollo dal buffer in InformationBuffer alla scheda di interfaccia di rete in un'operazione impostata o la quantità di informazioni restituite in InformationBuffer in risposta a un'operazione di query.
Se il driver del protocollo ha effettuato una query, ProtocolOidRequestComplete può usare i dati restituiti in InformationBuffer in qualsiasi modo determinato dal driver del protocollo, a seconda del valore del membro Oid .

Ad esempio, se il driver del protocollo ha avviato originariamente un OID_GEN_MAXIMUM_SEND_PACKETS query, ProtocolOidRequestComplete potrebbe configurare le variabili di stato nell'area ProtocolBindingContext per limitare il numero di invii in sospeso che il driver verrà configurato per le chiamate successive alla funzione NdisSendNetBufferLIsts .
Se Status è NDIS_STATUS_INVALID_LENGTH o NDIS_STATUS_BUFFER_TOO_SHORT, il membro BytesNeeded specifica il valore specifico dell'OID del membro InformationBufferLength necessario per eseguire l'operazione richiesta.
In queste circostanze, ProtocolOidRequestComplete può allocare spazio buffer sufficiente per la richiesta, configurare un'altra struttura NDIS_OID_REQUEST con l'oid richiesto InformationBufferLength e lo stesso Oid e riprovare la chiamata alla funzione NdisOidRequest.

ProtocolOidRequestComplete può ripetere le richieste per determinate altre NDIS_STATUS_ argomenti XXX , come descritto nel riferimento per la funzione NdisOidRequest .
Se Status è un valore NDIS_STATUS_ XXX che è un errore non recuperabile, ProtocolOidRequestComplete deve rilasciare la memoria allocata per la struttura NDIS_OID_REQUEST e determinare se il driver deve chiudere l'associazione o modificare le informazioni sullo stato specifiche del binding per gestire operazioni di I/O di rete continua sull'associazione.

Per le query e i set globali, la chiamata del driver miniport senza connessione sottostante alla funzione NdisMOidRequestComplete causa la chiamata alla funzione ProtocolOidRequestComplete . NDIS inoltra lo stato determinato dal driver miniport passato a NdisMOidRequestComplete come stato di input a ProtocolOidRequestComplete.

Per le query specifiche dell'associazione, NDIS chiama la funzione ProtocolOidRequestComplete stessa. Poiché la libreria NDIS gestisce le associazioni per tutti i driver miniport, NDIS può restituire informazioni specifiche dell'associazione solo sui driver sottostanti che segnalano il tipo medio come uno per cui il sistema fornisce una libreria di filtri. NDIS restituisce NDIS_STATUS_NOT_SUPPORTED per le query specifiche dell'associazione avviata dal driver del protocollo ad altri driver miniport.

Per altre informazioni sugli OID definiti dal sistema, vedere NDIS OID.

ProtocolOidRequestComplete può essere chiamato prima che il driver del protocollo abbia avuto tempo per controllare il codice di stato restituito da NdisOidRequest in Stato.

NDIS chiama ProtocolOidRequestComplete in IRQL <= DISPATCH_LEVEL.

Esempi

Per definire una funzione ProtocolOidRequestComplete , è 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 ProtocolOidRequestComplete denominata "MyOidRequestComplete ", usare il tipo di PROTOCOL_OID_REQUEST_COMPLETE come illustrato in questo esempio di codice:

PROTOCOL_OID_REQUEST_COMPLETE MyOidRequestComplete;

Implementare quindi la funzione come indicato di seguito:

_Use_decl_annotations_
VOID
 MyOidRequestComplete(
    NDIS_HANDLE  ProtocolBindingContext,
    PNDIS_OID_REQUEST  OidRequest,
    NDIS_STATUS  Status
    )
  {...}

Il tipo di funzione PROTOCOL_OID_REQUEST_COMPLETE è 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_OID_REQUEST_COMPLETE 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	<= DISPATCH_LEVEL