SET_OPTIONS funzione di callback (ndis.h)

Articolo
08/07/2023

NDIS chiama la funzione XxxSetOptions di un driver per consentire al driver di registrare i servizi facoltativi. Questa funzione è definita come MiniportSetOptions per i driver miniport, ProtocolSetOptions per i driver di protocollo o FilterSetOptions per i driver di filtro.

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

Sintassi

SET_OPTIONS SetOptions;

NDIS_STATUS SetOptions(
  [in] NDIS_HANDLE NdisDriverHandle,
  [in] NDIS_HANDLE DriverContext
)
{...}

Parametri

[in] NdisDriverHandle

Handle che identifica un driver. NDIS restituisce questo handle al driver quando viene restituito dalla funzione di registrazione del driver ( NdisMRegisterMiniportDriver per i driver miniport, NdisRegisterProtocolDriver per i driver di protocollo e NdisFRegisterFilterDriver per i driver di filtro).

[in] DriverContext

Handle passato al driver NdisRegisterXxxDriver che identifica l'area del contesto del driver, dove Xxx è il tipo di driver (Miniport, Protocol o Filter).

Valore restituito

XxxSetOptions restituisce uno dei valori di stato seguenti:

Codice restituito	Descrizione
NDIS_STATUS_SUCCESS	XxxSetOptions ha registrato correttamente i servizi e le risorse facoltativi del driver.
NDIS_STATUS_RESOURCES	XxxSetOptions non è riuscito ad allocare le risorse richieste dal driver.
NDIS_STATUS_XXX o NTSTATUS_XXX	Il tentativo del driver di registrare le opzioni non è riuscito. In genere, tale stato di errore viene propagato da una funzione NdisXxx o da una routine di supporto in modalità kernel.

Commenti

XxxSetOptions è una funzione facoltativa. NDIS chiama XxxSetOptions nel contesto della chiamata del driver a Funzione NdisRegisterXxxDriver , dove Xxx è il tipo di driver (Miniport, Protocol o Filter).

XxxSetOptions registra i servizi facoltativi e può allocare altre risorse driver. Per registrare le funzioni Facoltative MiniportXxx, ProtocolXxx o FilterXxx , il driver chiama la funzione NdisSetOptionalHandlers . Il driver passa l'handle dal parametro NdisDriverHandle al parametro NdisHandle di NdisSetOptionalHandlers e passa una struttura di caratteristiche al parametro OptionalHandlers .

I driver Miniport possono essere applicati ai servizi facoltativi definiti nelle strutture di caratteristiche seguenti:

NDIS_MINIPORT_CO_CHARACTERISTICS

NDIS_MINIPORT_PNP_CHARACTERISTICS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

NDIS_PROVIDER_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS(vedere la documentazione di offload del camino TCP 6.0 NDIS 6.0)

NDIS_PROVIDER_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS(vedere la documentazione di offload del camino TCP NDIS 6.0)

I driver di protocollo possono essere applicati ai servizi facoltativi definiti nelle strutture di caratteristiche seguenti:

NDIS_PROTOCOL_CO_CHARACTERISTICS

NDIS_CO_CLIENT_OPTIONAL_HANDLERS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

Nella versione corrente di Windows non sono disponibili servizi driver di filtro facoltativi.

NDIS può chiamare le altre funzioni MiniportXxx, ProtocolXxx o FilterXxx in qualsiasi momento dopo la restituzione di XxxSetOptions. Il driver deve essere pronto per essere richiamato alla relativa funzione di inizializzazione:(MiniportInitializeEx per i driver miniport, ProtocolBindAdapterEx per i driver di protocollo e FilterAttach per i driver di filtro).

Per i driver miniport, gli adattatori miniport sono nello stato Arrestato prima che NDIS chiami MiniportInitializeEx. Per i driver di protocollo, le associazioni di protocollo si trovano nello stato Unbound prima che NDIS chiami ProtocolBindAdapterEx. Per i driver di filtro, i moduli di filtro si trovano nello stato Scollegato prima che NDIS chiami FilterAttach.

Se un tentativo di allocazione di risorse o servizi ha esito negativo, XxxSetOptions deve annullare tutte le allocazioni riuscite prima di restituire il controllo con uno stato diverso da NDIS_STATUS_SUCCESS.

Il miniport e i driver di filtro XxxDriverUnload devono annullare tutte le operazioni eseguite in XxxSetOptions

NDIS chiama XxxSetOptions in IRQL = PASSIVE_LEVEL.

Esempi

Per definire una funzione XxxSetOptions , è 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.

Nel file di intestazione Ndis.h la funzione di callback SET_OPTIONS viene definita come segue:

typedef SET_OPTIONS (*SET_OPTIONS_HANDLER);
typedef SET_OPTIONS (MINIPORT_SET_OPTIONS);
typedef SET_OPTIONS (PROTOCOL_SET_OPTIONS);
typedef SET_OPTIONS (FILTER_SET_OPTIONS);

Ciò consente a tutti i driver NDIS di implementare le funzioni di callback XxxSetOptions con la stessa sintassi. I driver miniport usano il tipo di MINIPORT_SET_OPTIONS , i driver di protocollo usano il tipo di PROTOCOL_SET_OPTIONS e i driver di filtro usano il tipo di FILTER_SET_OPTIONS .

Ad esempio, per definire una funzione MiniportSetOptions denominata "MySetOptions", usare il tipo di MINIPORT_SET_OPTIONS come illustrato nell'esempio di codice seguente:

MINIPORT_SET_OPTIONS MySetOptions;

Implementare quindi la funzione come segue:

_Use_decl_annotations_
NDIS_STATUS
 MySetOptions(
    NDIS_HANDLE  NdisDriverHandle,
    NDIS_HANDLE  DriverContext
    )
  {...}

Il tipo di funzione SET_OPTIONS è 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 SET_OPTIONS 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