Condividi tramite

Funzione NdisMSetAttributesEx (ndis.h)

  • Articolo

Nota NDIS 5. x è stato deprecato e viene sostituito da NDIS 6. x. Per il nuovo sviluppo di driver NDIS, vedere Driver di rete a partire da Windows Vista. Per informazioni sulla conversione di NDIS 5. x driver per NDIS 6. x, vedere Conversione di driver NDIS 5.x in NDIS 6.0.

NdisMSetAttributesEx informa la libreria NDIS sulle funzionalità significative della scheda di interfaccia di rete o della scheda di interfaccia di rete virtuale del chiamante durante l'inizializzazione.

Sintassi

void NdisMSetAttributesEx(
  [in]           NDIS_HANDLE         MiniportAdapterHandle,
  [in]           NDIS_HANDLE         MiniportAdapterContext,
  [in, optional] UINT                CheckForHangTimeInSeconds,
  [in]           ULONG               AttributeFlags,
  [in, optional] NDIS_INTERFACE_TYPE AdapterType
);

Parametri

[in] MiniportAdapterHandle

Specifica l'input di handle per MiniportInitialize.

[in] MiniportAdapterContext

Specifica un handle per un'area del contesto residente allocata da MiniportInitialize.

[in, optional] CheckForHangTimeInSeconds

Specifica l'intervallo, espresso in secondi, in cui NDIS deve chiamare la funzione MiniportCheckForHang . Se un driver non ha risposto a una richiesta OID o ha inviato una richiesta entro due chiamate successive a MiniportCheckForHang, NDIS può chiamare la funzione MiniportReset del driver.

L'intervallo effettivo usato da NDIS quando si chiama MiniportCheckForHang è sempre un multiplo di 2 secondi. Ad esempio, se si specificano 5 secondi, l'intervallo effettivo sarà di circa 4 secondi.

Se si specifica zero per questo parametro, NDIS deve chiamare MiniportCheckForHang all'intervallo predefinito NDIS di 2 secondi.

Se il chiamante imposta NDIS_ATTRIBUTE_DESERIALIZE in AttributeFlags, NDIS non accoda gli invii in sospeso per il driver miniport. Al contrario, tale driver deserializzato deve gestire il proprio accodamento delle richieste di invio successive internamente ogni volta che dispone di risorse insufficienti per trasmettere immediatamente un invio in ingresso.

[in] AttributeFlags

Specifica una maschera di bit che può essere impostata con uno o più flag (ORed) dei flag seguenti:

  • NDIS_ATTRIBUTE_BUS_MASTER
    Impostare se la scheda di interfaccia di rete del chiamante è un dispositivo DMA master del bus.

  • NDIS_ATTRIBUTE_DESERIALIZE
    Impostare se il chiamante è un driver miniport deserializzato.

  • NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT
    Impostare se NDIS non deve tentare di eseguire il timeout dei pacchetti di invio in sospeso che contiene in coda al chiamante. I driver intermedi devono impostare questo flag, ma i driver della scheda di interfaccia di rete non devono essere impostati.

  • NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT
    Impostare se NDIS non deve tentare di eseguire il timeout della query in sospeso e impostare le richieste che contiene in coda al chiamante. I driver intermedi devono impostare questo flag, ma i driver della scheda di interfaccia di rete non devono essere impostati.

  • NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER
    Impostare se il chiamante è un driver intermedio.

  • NDIS_ATTRIBUTE_IGNORE_TOKEN_RING_ERRORS
    Impostare se NDIS non deve chiamare la funzione MiniportReset del driver dell'anello di token se sono indicati errori di token ring.

  • NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND
    Impostare se NDIS non deve chiamare la funzione MiniportHalt di un driver prima che il sistema passi a uno stato di bassa potenza (sospensione). I driver che si basano sullo stato gestito dall'hardware non devono impostare questo flag.

    Nota L'impostazione di questo flag disabilita la casella di controllo Consenti al computer di disattivare il dispositivo per risparmiare energia nella scheda Risparmio energia della finestra di dialogo Proprietà per la scheda di interfaccia di rete . Il risparmio energia è disabilitato anche se la scheda di interfaccia di rete è in grado di gestire il risparmio energia.

  • NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK
    Impostare se il driver può gestire la rimozione della scheda di interfaccia di rete senza notifica dell'utente. Un driver di questo tipo esporta una funzione MiniportPnPEventNotify . Il supporto di sistema per NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK è disponibile in Windows XP e nei sistemi operativi successivi.

  • NDIS_ATTRIBUTE_NOT_CO_NDIS
    Impostato da un driver in grado di supportare dispositivi sia orientati alla connessione che senza connessione per indicare che il dispositivo è un dispositivo senza connessione. Il supporto di sistema per NDIS_ATTRIBUTE_NOT_CO_NDIS è disponibile in Windows XP e nei sistemi operativi successivi.

  • NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS
    Impostato da un driver che usa NdisBufferVirtualAddressSafe, NdisGetFirstBufferFromPacketSafe e NdisQueryBufferSafe esclusivamente per accedere agli indirizzi virtuali di sistema per l'invio di buffer di pacchetti. NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS è impostato anche da un driver che usa esclusivamente indirizzi fisici per accedere a tali buffer. L'impostazione di NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS può migliorare le prestazioni perché il sistema operativo non dovrà eseguire il mapping dei buffer dei pacchetti agli indirizzi virtuali di sistema. Il supporto di sistema per NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS è disponibile in Windows XP e versioni successive.

  • NDIS_ATTRIBUTE_DO_NOT_BIND_TO_ALL_CO
    Impostato da un driver miniport CoNDIS che non fornisce servizi TAPI. L'impostazione di NDIS_ATTRIBUTE_DO_NOT_BIND_TO_ALL_CO impedisce a NDIS di eseguire il binding del driver miniport al driver proxy TAPI NDIS (NDPROXY). Per impostazione predefinita, NDIS associa NDPROXY a tutti i driver miniport CoNDIS.

[in, optional] AdapterType

Specifica il tipo di interfaccia del bus di I/O della scheda di interfaccia di rete del chiamante, che in genere è il tipo di bus di I/O in cui è connessa la scheda di interfaccia di rete, come uno dei seguenti:

  • NdisInterfaceInternal
    Specifica un'interfaccia interna specifica dell'host.

  • NdisInterfaceIsa
    Specifica l'interfaccia ISA.

  • NdisInterfaceEisa
    Specifica l'interfaccia EISA (Extended ISA).

  • NdisInterfaceMca
    Si riferisce al bus MCA, che non è più supportato.

  • NdisInterfaceTurboChannel
    Specifica l'interfaccia Turbo Channel.

  • NdisInterfacePci
    Specifica l'interfaccia PCI (Peripheral Component Interconnect).

  • NdisInterfacePcMcia
    Specifica l'interfaccia Personal Computer Memory Card International Association (PC Card).

Questo parametro è irrilevante per i driver intermedi, che devono passare zero per questo argomento a NdisMSetAttributesEx.

Valore restituito

nessuno

Osservazioni

Una funzione MiniportInitialize deve chiamare NdisMSetAttributesEx(o NdisMSetAttributes) prima di chiamare qualsiasi altra funzione NdisMRegisterXxx o NdisXxx che dipende dalle informazioni fornite a NdisMSetAttributesEx. Ad esempio, la chiamata di un driver NIC a NdisMAllocateMapRegisters avrà esito negativo se MiniportInitialize non ha ancora chiamato NdisMSetAttributesEx con attributeFlags impostato con NDIS_ATTRIBUTE_BUS_MASTER.

I driver intermedi devono chiamare NdisMSetAttributesEx, anziché NdisMSetAttributes e devono impostare NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER in AttributeFlags. L'impostazione di questo flag fa sì che NDIS consideri un driver intermedio come driver miniport full duplex, che impedisce che si verifichino deadlock rari ma intermittenti nel driver intermedio. Di conseguenza, ogni driver intermedio deve essere in grado di gestire invii e indicazioni simultanei.

I driver deserializzati devono anche chiamare NdisMSetAttributesEx e devono impostare NDIS_ATTRIBUTE_DESERIALIZE in AttributeFlags. NDIS non gestisce una coda di pacchetti di invio per un driver deserializzato, né serializza le chiamate alle funzioni MiniportXxx di un driver di questo tipo. Un driver deserializzato si assume la responsabilità di quanto segue:

  • Accettazione di tutte le richieste di invio in ingresso
  • Accodare i pacchetti di invio in ingresso internamente, se necessario, ad esempio, se un driver di scheda di interfaccia di rete deserializzato dispone attualmente di risorse insufficienti per trasmettere immediatamente un pacchetto di invio in ingresso
  • Sincronizzazione dell'accesso alle code interne in base alle esigenze tra le routine del driver
  • Completamento di tutti gli invii richiesti in modo asincrono chiamando successivamente NdisMSendComplete con ogni descrittore di pacchetti fornito dal protocollo passato alla relativa funzione Miniport(Co)Send(Packets)

NDIS presuppone che tutti i miniport orientati alla connessione siano driver deserializzati, indipendentemente dai flag AttributeFlag che passano a NdisMSetAttributesEx. Ovvero, qualsiasi driver che chiama NdisMRegisterMiniport con 0x05 come MajorNdisVersion deve essere un driver miniport deserializzato.

I driver di interfaccia di rete serializzati possono chiamare una di queste funzioni da MiniportInitialize, ma NdisMSetAttributes non consente al chiamante di regolare l'intervallo in cui vengono chiamate le funzioni MiniportCheckForHang e/o MiniportReset di un driver NIC.

Il valore di CheckForHangTimeInSeconds determina l'intervallo di timeout della libreria NDIS per gli invii, se presenti, e le richieste che contiene accodati al chiamante. Per impostazione predefinita, NDIS raggiunge il timeout degli invii in coda (solo per i driver serializzati) e le richieste al doppio dell'intervallo di check-for-hang, dopo di che chiama la funzione MiniportReset , a meno che il driver non imposti AttributeFlags con NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT e NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT quando chiama NdisMSetAttributesEx. I driver intermedi devono impostare questi flag quando si chiama NdisMSetAttributesEx perché tale driver non è in grado di determinare o controllare quando il driver della scheda di interfaccia di rete sottostante elabora gli invii e le richieste.

I driver NIC non devono impostare i flag NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT e NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT, anche se NDIS rispetterà tale specifica da un driver di interfaccia di rete serializzato. Tuttavia, i driver della scheda di interfaccia di rete possono modificare l'intervallo di timeout in base al quale vengono chiamate le funzioni MiniportReset specificando un checkForHangTimeInSeconds esplicito. Ad esempio, un driver NIC che emula Ethernet su un modem potrebbe non completare ogni pacchetto entro l'intervallo di timeout predefinito della libreria NDIS. Ogni volta che un pacchetto sembra scadere in una scheda di interfaccia di rete di questo tipo, NDIS presuppone che la scheda di interfaccia di rete non funzionasse più correttamente e chiami la funzione MiniportReset del driver. Per il driver di tale interfaccia di rete, la chiamata a NdisMSetAttributesEx con un controllo CheckForHangTimeInSeconds impostato su un valore maggiore di due impedisce la reimpostazione non necessaria e estende l'intervallo in cui la funzione MiniportCheckForHang , se presente, viene chiamata per testare lo stato operativo della scheda di interfaccia di rete.

Un driver intermedio deve impostare il flag di NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND. L'impostazione di questo flag impedisce a NDIS di arrestare il driver prima che il sistema passi a uno stato di bassa potenza (sospensione).

Un driver miniport legacy che gestisce una scheda di interfaccia di interfaccia di rete non compatibile con PnP può impostare il flag di NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND per impedire a NDIS di arrestare il driver prima della transizione del sistema a uno stato a bassa potenza. Se il driver miniport imposta questo flag, NDIS esegue una query sul driver miniport con OID_PNP_CAPABILITIES anche se il driver del bus per la scheda di interfaccia di rete del driver miniport potrebbe aver indicato che la scheda di interfaccia di rete non è a conoscenza del pm. Il driver miniport deve avere esito positivo sulla richiesta di OID_PNP_CAPABILITIES con NDIS_STATUS_SUCCESS. Nella struttura NDIS_PM_WAKE_UP_CAPABILITIES restituita da questo OID, il driver miniport deve specificare anche uno stato di alimentazione del dispositivo NdisDeviceStateUnspecified per ogni funzionalità di riattivazione. Quando il sistema passa a uno stato a bassa potenza, NDIS non chiamerà tale funzione MiniportHalt del driver miniport . Prima della transizione del sistema a uno stato di alimentazione inferiore, il driver miniport deve salvare qualsiasi contesto hardware gestito. Durante la ricezione di una richiesta di OID_PNP_SET_POWER allo stato D3, il driver miniport deve impostare la scheda di interfaccia di rete sullo stato appropriato per lo stato a bassa potenza. Durante la ricezione di una richiesta di OID_PNP_SET_POWER allo stato D0, il driver miniport deve impostare la scheda di interfaccia di rete sullo stato appropriato per lo stato di lavoro.

Un driver miniport che supporta la rimozione sorprendente del dispositivo (rimozione senza notifica tramite l'interfaccia utente) deve impostare NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK. In questo modo, NDIS chiama la funzione MiniportPnPEventNotify del driver con PnPEvent impostata su NdisDevicePnPEventSurpriseRemoved quando il dispositivo miniport viene rimosso senza notifica. Inoltre, l'impostazione NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK elimina la visualizzazione di una finestra di dialogo di avviso che chiede all'utente di arrestare il dispositivo prima di rimuoverlo.

Un driver miniport che può supportare dispositivi sia senza connessione che orientata alla connessione deve impostare NDIS_ATTRIBUTE_NOT_CO_NDIS se il dispositivo è un dispositivo senza connessione. In caso contrario, NDIS presuppone erroneamente che il relativo dispositivo sia orientato alla connessione poiché il driver registra funzioni di driver miniport orientate alla connessione con NdisMRegisterMiniport.

In generale, un driver di interfaccia di interfaccia di rete deve chiamare NdisMSetAttributesEx prima di chiamare qualsiasi funzione NdisXxx che dichiara le risorse hardware nel Registro di sistema per la scheda di interfaccia di rete, perché NDIS deve avere il valore AttributeFlags prima che tale chiamata venga eseguita e perché il driver in genere necessita della memoria in MiniportAdapterContext per archiviare le informazioni per queste chiamate. Questa restrizione implica che la funzione MiniportInitialize di un driver della scheda di interfaccia di rete non può chiamare il seguente NdisXxx prima di chiamare NdisMSetAttributesEx:

Prima di chiamare NdisMSetAttributesEx, tuttavia, la funzione MiniportInitialize di qualsiasi driver può chiamare Ndis.. Funzioni di configurazione per recuperare le informazioni di configurazione installate nel Registro di sistema. MiniportInitialize può anche chiamare le funzioni NdisReadXxx specifiche del bus, ad esempio NdisReadPciSlotInformation, purché la voce del Registro di sistema installata per il tipo di interfaccia del driver corrisponda alle chiamate NdisReadXxxMiniportInitialize specifiche del bus.

L'handle MiniportAdapterContext fornito a NdisMSetAttributesEx diventa un parametro di input per tutte le funzioni MiniportXxx registrate, insieme a MiniportInitialize, nella chiamata a NdisMRegisterMiniport o NdisIMRegisterLayeredMiniport. In genere, questo handle è un puntatore alla memoria residente, allocata da MiniportInitialize, in cui il driver mantiene lo stato di runtime specifico della scheda di interfaccia di rete.

  • Piattaforma di destinazione: universale
  • Versione: non supportata per i driver NDIS 6.0 in Windows Vista. Usare invece NdisMSetMiniportAttributes. Supportato per i driver NDIS 5.1 in Windows Vista e Windows XP.

Requisiti

Requisito Valore
Intestazione ndis.h (includere Ndis.h)
Libreria Ndis.lib
IRQL PASSIVE_LEVEL

Vedi anche