Funzione NdisCoOidRequest (ndis.h)

Articolo
08/07/2023

La funzione NdisCoOidRequest inoltra una richiesta ai driver CoNDIS di destinazione per eseguire query o impostare informazioni specificate dall'OID del driver di destinazione.

Sintassi

NDIS_STATUS NdisCoOidRequest(
  [in]           NDIS_HANDLE       NdisBindingHandle,
  [in, optional] NDIS_HANDLE       NdisAfHandle,
  [in, optional] NDIS_HANDLE       NdisVcHandle,
  [in, optional] NDIS_HANDLE       NdisPartyHandle,
  [in, out]      PNDIS_OID_REQUEST OidRequest
);

Parametri

[in] NdisBindingHandle

Handle restituito dalla funzione NdisOpenAdapterEx che identifica l'adattatore di destinazione per l'associazione.

[in, optional] NdisAfHandle

Handle che identifica la famiglia di indirizzi condivisa tra il client, il gestore chiamate e NDIS. Questo handle è stato ottenuto come segue:

Se il chiamante è un client che effettua una richiesta al gestore chiamate, il client ha originariamente ottenuto questo handle da una chiamata riuscita all'oggetto Funzione NdisClOpenAddressFamilyEx .
Se il chiamante è un gestore chiamate autonomo o un gestore chiamate miniport (MCM) che effettua una richiesta a un client, il gestore chiamate o MCM ha originariamente ottenuto questo handle come parametro di input per la relativa funzione ProtocolCmOpenAf .

Per effettuare una richiesta da un client o da un gestore chiamate autonomo al driver miniport sottostante, questo parametro deve essere NULL.

[in, optional] NdisVcHandle

Handle che identifica la connessione virtuale (VC) per cui il chiamante richiede o imposta le informazioni, se la richiesta è specifica del vc. In caso contrario, se questo parametro è NULL, la richiesta non è specifica di VC. Per qualsiasi richiesta specifica di VC, il chiamante ha originariamente ottenuto questo handle quando ha creato vc con la funzione NdisCoCreateVc o come parametro di input per la relativa funzione ProtocolCoCreateVc . Per una richiesta specifica di VC indirizzata al driver miniport sottostante, questo handle identifica vc, mentre NdisAfHandle e NdisPartyHandle sono NULL.

[in, optional] NdisPartyHandle

Handle che identifica l'entità in un vc multipunto per cui il chiamante richiede o imposta le informazioni, se la richiesta è specifica dell'entità. In caso contrario, se questo parametro è NULL, la richiesta non è specifica dell'entità. Per qualsiasi richiesta specifica dell'entità, un client ha originariamente ottenuto questo handle da una chiamata riuscita alla funzione NdisClAddParty o alla funzione NdisClMakeCall o al gestore chiamate ottenuto questo handle come parametro di input per la relativa funzione ProtocolCmAddParty . Se NdisAfHandle è NULL, anche NdisPartyHandle è NULL.

[in, out] OidRequest

Puntatore a una struttura NDIS_OID_REQUEST che specifica l'operazione richiesta con un determinato codice OID_XXX per eseguire una query o impostare le informazioni.

Valore restituito

Il driver di destinazione determina il codice NDIS_STATUS_XXXrestituito da NdisCoOidRequest , in genere uno dei valori seguenti:

Codice restituito	Descrizione
NDIS_STATUS_SUCCESS	Operazione di richiesta completata.
NDIS_STATUS_PENDING	La richiesta viene gestita in modo asincrono e NDIS chiamerà il chiamante Funzione ProtocolCoOidRequestComplete al termine della richiesta.
NDIS_STATUS_INVALID_OID	Il codice OID_XXX specificato nel membro Oid della struttura NDIS_OID_REQUEST nel parametro OidRequest non è valido o non è supportato dal driver sottostante.
NDIS_STATUS_INVALID_LENGTH o NDIS_STATUS_BUFFER_TOO_SHORT	Il valore specificato nel membro InformationBufferLength del buffer strutturato NDIS_OID_REQUEST in OidRequest non corrisponde ai requisiti per il codice OID_XXX specificato. Se il buffer delle informazioni è troppo piccolo, il membro BytesNeeded di NDIS_OID_REQUEST contiene il valore corretto per InformationBufferLength, quando restituisce NdisCoOidRequest .
NDIS_STATUS_INVALID_DATA	I dati forniti in InformationBuffer nella struttura di NDIS_OID_REQUEST specificata non sono validi per il codice OID_XXX specificato.
NDIS_STATUS_NOT_SUPPORTED o NDIS_STATUS_NOT_RECOGNIZED	Il driver sottostante non supporta l'operazione richiesta.
NDIS_STATUS_RESOURCES	Impossibile soddisfare la richiesta a causa di una carenza di risorse. In genere, questo valore restituito indica che un tentativo di allocazione della memoria non è riuscito, ma non indica necessariamente che la stessa richiesta, se inviata in un secondo momento, avrà esito negativo per lo stesso motivo.
NDIS_STATUS_NOT_ACCEPTED	Il driver sottostante ha tentato l'operazione richiesta, in genere una richiesta impostata, ma l'operazione non è riuscita. Ad esempio, un tentativo di impostare troppi indirizzi multicast potrebbe causare la restituzione di questo valore da parte di NdisCoOidRequest .
NDIS_STATUS_CLOSING o NDIS_STATUS_CLOSING_INDICATING	Il driver sottostante non ha superato l'operazione richiesta perché è in corso un'operazione di chiusura.
NDIS_STATUS_RESET_IN_PROGRESS	Il driver miniport sottostante non può soddisfare la richiesta in questo momento perché sta reimpostando la scheda di interfaccia di rete interessata. La funzione ProtocolStatusEx del chiamante era o verrà chiamata con NDIS_STATUS_RESET_START per indicare che è in corso una reimpostazione. Questo valore restituito non indica necessariamente che la stessa richiesta, se inviata in un secondo momento, avrà esito negativo per lo stesso motivo.
NDIS_STATUS_FAILURE	Questo valore è in genere un valore predefinito non specificato restituito quando nessuna delle NDIS_STATUS_XXX più specifiche ha causato l'esito negativo della richiesta da parte del driver sottostante.
NDIS_STATUS_REQUEST_ABORTED	Il driver miniport ha interrotto l'elaborazione della richiesta. Ad esempio, NDIS ha chiamato miniport driver miniporte sottostante MiniportResetEx o Funzione MiniportCancelOidRequest .

Commenti

I client CoNDIS e i responsabili chiamate autonomi possono chiamare la funzione NdisCoOidRequest per inviare una richiesta OID per eseguire query o impostare le informazioni specificate dall'OID in un driver di destinazione. Il driver di destinazione può essere un altro driver di protocollo CoNDIS o un driver sottostante.

Il chiamante di NdisCoOidRequest deve allocare memoria sufficiente per contenere il buffer delle informazioni associato all'OID specificato. Il chiamante deve anche allocare e configurare il buffer in OidRequest prima di chiamare NdisCoOidRequest. Entrambi i buffer devono essere allocati da un pool non di paging perché il driver di destinazione può essere eseguito in irQL generato durante l'elaborazione della richiesta.

Alcuni errori restituiti da NdisCoOidRequest sono recuperabili, tra cui:

NDIS_STATUS_INVALID_OID
NDIS_STATUS_INVALID_LENGTH
NDIS_STATUS_BUFFER_TOO_SHORT
NDIS_STATUS_INVALID_DATA
NDIS_STATUS_RESOURCES
NDIS_STATUS_RESET_IN_PROGRESS

Ovvero, un driver può modificare il pacchetto in OidRequest in modo appropriato per correggere il codice OID_XXX o le dimensioni o il contenuto del buffer in InformationBuffer e inviare di nuovo il pacchetto di richiesta a NdisCoOidRequest. Lo stesso pacchetto potrebbe essere soddisfatto quando il driver lo invia nuovamente a NdisCoOidRequest se la chiamata originale indicava una reimpostazione in corso o che una carenza di risorse, che potrebbe essere temporanea, impediva l'esecuzione di tale richiesta.

A seconda del valore del parametro NdisAfHandle , i client e i gestori chiamate autonomi chiamano NdisCoOidRequest per comunicare tra loro o con il driver miniport orientato alla connessione sottostante.

Se un driver passa NULL per NdisVcHandle, la richiesta è globale, indipendentemente dal fatto che la richiesta venga indirizzata al client, al gestore chiamate o al driver miniport. Ad esempio, se il chiamante fornisce un valore non NULL per NdisVcHandle, una richiesta OID OID_GEN_CO_RCV_CRC_ERROR a un driver miniport orientato alla connessione sottostante restituisce il numero di errori di controllo della ridondanza ciclico (CRC) rilevati per un determinato vc. Per la stessa richiesta con NULL per NdisVcHandle, il driver miniport sottostante restituisce il numero totale di errori CRC rilevati per tutti i computer virtuali.

I client e i gestori chiamate autonomi devono chiamare la funzione NdisOidRequest per tutti gli OID che non sono orientati alla connessione, ad esempio quelli restituiti in una query OID_GEN_SUPPORTED_LIST , che viene comunemente eseguita durante l'inizializzazione dopo che il driver del protocollo è associato al driver della scheda di interfaccia di rete sottostante.

Se NdisCoOidRequest restituisce NDIS_STATUS_PENDING, la richiesta viene gestita in modo asincrono e NDIS chiamerà il driver Funzione ProtocolCoOidRequestComplete al termine della richiesta. Se NdisCoOidRequest restituisce qualsiasi altro stato, la richiesta viene completata quando NdisCoOidRequest restituisce e NDIS non chiama ProtocolCoOidRequestComplete.

Per altre informazioni sui set di IDE definiti da usare con NdisCoOidRequest e NdisOidRequest, vedere NDIS OID.

Solo i client e i gestori di chiamate autonomi, che sono driver di protocollo, possono chiamare NdisCoOidRequest. I MCM chiamano la funzione NdisMCmOidRequest per comunicare con i client.

Requisiti

Requisito	Valore
Client minimo supportato	Supportato in NDIS 6.0 e versioni successive.
Piattaforma di destinazione	Desktop
Intestazione	ndis.h (include Ndis.h)
Libreria	Ndis.lib
IRQL	<= DISPATCH_LEVEL
Regole di conformità DDI	Irql_Connection_Function(ndis)