SET_OPTIONS funzione di callback (ndis.h)
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.
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 |
|---|---|
|
XxxSetOptions ha registrato correttamente i servizi e le risorse facoltativi del driver. |
|
XxxSetOptions non è riuscito ad allocare le risorse richieste dal driver. |
|
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);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 |