PROTOCOL_CO_OID_REQUEST_COMPLETE funzione di callback (ndis.h)

Articolo
03/05/2024

La funzione ProtocolCoOidRequestComplete completa l'elaborazione di una richiesta OID CoNDIS asincrona.

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

Sintassi

PROTOCOL_CO_OID_REQUEST_COMPLETE ProtocolCoOidRequestComplete;

void ProtocolCoOidRequestComplete(
  [in]      NDIS_HANDLE ProtocolAfContext,
  [in]      NDIS_HANDLE ProtocolVcContext,
  [in]      NDIS_HANDLE ProtocolPartyContext,
  [in, out] PNDIS_OID_REQUEST OidRequest,
  [in]      NDIS_STATUS Status
)
{...}

Parametri

[in] ProtocolAfContext

Handle che identifica un'area di contesto della famiglia di indirizzi . Se il driver è un client, ha fornito questo handle quando ha chiamato il Funzione NdisClOpenAddressFamilyEx per connettersi al gestore chiamate. Se il driver è un gestore chiamate o un gestore chiamate miniport (MCM), ha fornito questo handle dalla relativa funzione ProtocolCmOpenAf .

[in] ProtocolVcContext

Handle che identifica la connessione virtuale attiva (VC) per cui il driver ha richiesto o impostato le informazioni, se la richiesta è specifica del vc. In caso contrario, questo parametro è NULL.

[in] ProtocolPartyContext

Handle che identifica l'entità in un vc multipunto per cui il driver ha richiesto o impostato le informazioni, se la richiesta è specifica dell'entità. In caso contrario, questo parametro è NULL.

[in, out] OidRequest

Puntatore alla struttura NDIS_OID_REQUEST fornita dal driver passata in precedenza alla funzione NdisCoOidRequest o NdisMCmOidRequest .

[in] Status

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

Valore restituito

nessuno

Osservazioni

NDIS chiama la funzione ProtocolCoOidRequestComplete per completare l'elaborazione del client CoNDIS, del gestore chiamate o della richiesta OID MCM per cui la funzione NdisCoOidRequest o la funzione NdisMCmOidRequest ha restituito NDIS_STATUS_PENDING.

Per registrare ProtocolCoOidRequestComplete come client, un driver inizializza un NDIS_CO_CLIENT_OPTIONAL_HANDLERS struttura e la passa al parametro OptionalHandlers della funzione NdisSetOptionalHandlers . Per registrare ProtocolCoOidRequestComplete come gestore chiamate, un driver inizializza un NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS struttura e la passa al parametro OptionalHandlers di NdisSetOptionalHandlers.

Il driver di destinazione è il driver che ha risolto la richiesta di informazioni OID. Chiamata del driver di destinazione a NdisMCoOidRequestComplete, NdisCoOidRequestComplete o La funzione NdisMCmOidRequestComplete ha causato la chiamata della funzione ProtocolCoOidRequestComplete . NDIS inoltra il valore del parametro Status passato a queste funzioni come parametro Status di input a ProtocolCoOidRequestComplete.

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

Se Status è NDIS_STATUS_SUCCESS, il membro BytesRead o BytesWritten della struttura NDIS_OID_REQUEST che il parametro OidRequest punta a specificare la quantità di informazioni trasferite dal buffer nel membro InformationBuffer di NDIS_OID_REQUEST al driver di destinazione o la quantità di informazioni restituite rispettivamente in InformationBuffer.
Se il driver ha effettuato una richiesta di query, ProtocolCoOidRequestComplete può usare i dati restituiti in InformationBuffer in base al valore specificato nel membro Oid di NDIS_OID_REQUEST.
Se Status è NDIS_STATUS_INVALID_LENGTH o NDIS_STATUS_BUFFER_TOO_SHORT, il membro BytesNeeded della struttura NDIS_OID_REQUEST che OidRequest punta a specifica il valore specifico dell'OID del membro InformationBufferLength di NDIS_OID_REQUEST necessario per eseguire l'operazione richiesta.
In queste circostanze , ProtocolCoOidRequestComplete può allocare spazio buffer sufficiente per la richiesta, configurare un'altra struttura NDIS_OID_REQUEST con il valore richiesto per InformationBufferLength e ripetere la richiesta OID.
Se Status è un valore NDIS_STATUS_ XXX che rappresenta un errore irreversibile, ProtocolCoOidRequestComplete deve rilasciare la memoria per la struttura NDIS_OID_REQUEST. ProtocolCoOidRequestComplete deve anche determinare se il driver deve chiudere l'associazione o modificare le informazioni sullo stato specifiche dell'associazione per gestire le operazioni di I/O di rete continue sull'associazione.

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

ProtocolCoOidRequestComplete può essere chiamato prima che il driver abbia avuto il tempo di controllare il codice di stato restituito da NdisCoOidRequest o NdisMCmOidRequest .

NDIS chiama ProtocolCoOidRequestComplete in IRQL <= DISPATCH_LEVEL.

Esempi

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

PROTOCOL_CO_OID_REQUEST_COMPLETE MyCoOidRequestComplete;

Implementare quindi la funzione come segue:

_Use_decl_annotations_
VOID
 MyCoOidRequestComplete(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  ProtocolPartyContext,
    PNDIS_OID_REQUEST  OidRequest,
    NDIS_STATUS  Status
    )
  {...}

Il tipo di funzione PROTOCOL_CO_OID_REQUEST_COMPLETE è 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_CO_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 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	<= DISPATCH_LEVEL (vedere la sezione Osservazioni)