Funzione NdisMSetAttributesEx (ndis.h)

  • Articolo

Nota NDIS 5. x è stato deprecato ed è 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. driver x a 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 del chiamante o della scheda di interfaccia di rete virtuale 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 dell'handle in MiniportInitialize.

[in] MiniportAdapterContext

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

[in, optional] CheckForHangTimeInSeconds

Specifica l'intervallo, 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 2-second.

Se il chiamante imposta NDIS_ATTRIBUTE_DESERIALIZE in AttributeFlags, NDIS non esegue la coda in sospeso per il driver miniport. Invece, tale driver deserializzato deve gestire la propria accodamento delle richieste di invio successive internamente ogni volta che ha risorse insufficienti per trasmettere immediatamente un invio in ingresso.

[in] AttributeFlags

Specifica una maschera 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 accodati 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 timeout di 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 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 della transizione del sistema 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 Power Management della finestra di dialogo Proprietà per la scheda di interfaccia di rete (NIC). La gestione energia è disabilitata anche se la scheda di interfaccia di rete è in grado di gestire la potenza.

  • NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK
    Impostare se il driver può gestire la rimozione della scheda di interfaccia di rete senza notifica utente. Tale driver esporta una funzione MiniportPnPEventNotify . Il supporto del 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 che può supportare dispositivi sia orientati alla connessione che senza connessione per indicare che il dispositivo è un dispositivo senza connessione. Il supporto del 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 del 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 NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS può migliorare le prestazioni poiché il sistema operativo non dovrà eseguire il mapping dei buffer dei pacchetti agli indirizzi virtuali di sistema. Il supporto del 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 NDIS_ATTRIBUTE_DO_NOT_BIND_TO_ALL_CO impedisce a NDIS di associazione 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 ISA (EISA) estesa.

  • NdisInterfaceMca
    Ciò fa riferimento al bus MCA, che non è più supportato.

  • NdisInterfaceTurboChannel
    Specifica l'interfaccia Turbo Channel.

  • NdisInterfacePci
    Specifica l'interfaccia Di interconnessione dei componenti periferici (PCI).

  • 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 di interfaccia di rete a NdisMAllocateMapRegisters avrà esito negativo se MiniportInitialize non ha ancora chiamato NdisMSetAttributesEx con l'attributoFlags 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 causa il trattamento di 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 simultanee.

I driver deserializzati devono anche chiamare NdisMSetAttributesEx e devono impostare NDIS_ATTRIBUTE_DESERIALIZE negli AttributiFlags. NDIS non gestisce una coda di pacchetti di invio per un driver deserializzato, né serializza le chiamate a tali funzioni MiniportXxx di un driver. Un driver deserializzato si rende responsabile del seguente:

  • Accettazione di tutte le richieste di invio in ingresso
  • Accodamento dei pacchetti di invio in ingresso, se necessario, ad esempio, se un driver di interfaccia di interfaccia di rete deserializzato attualmente ha 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 del pacchetto fornito dal protocollo passato alla funzione Miniport(Co)Send(Packets)

NDIS presuppone che tutti i miniport orientati alla connessione siano driver deserializzati, indipendentemente dagli attributiFlag 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 interfaccia di rete serializzati possono chiamare una di queste funzioni da MiniportInitialize, ma NdisMSetAttributes non consente al chiamante di modificare l'intervallo in cui viene chiamato il miniportCheckForHang di un driver di scheda di interfaccia di rete e/o le funzioni MiniportReset .

Il valore di CheckForHangTimeInSeconds determina l'intervallo di timeout della libreria NDIS sugli invii, se presente e le richieste che contiene accodamento al chiamante. Per impostazione predefinita, NDIS esegue il timeout in coda (solo per i driver serializzati) e le richieste al doppio dell'intervallo di blocco check-for-hang, dopo il quale chiama la funzione MiniportReset , a meno che il driver non imposta 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 può determinare o controllare quando il driver della scheda di interfaccia di rete sottostante elabora gli invii e le richieste.

I driver della scheda di interfaccia di rete non devono impostare i flag di NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT e NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT, anche se NDIS onorerà tale specifica da un driver di interfaccia di interfaccia di rete serializzato. Tuttavia, i driver della scheda di interfaccia di rete possono modificare l'intervallo di timeout in corrispondenza del quale vengono chiamate le funzioni MiniportReset specificando un controllo CheckForHangTimeInSeconds esplicito. Ad esempio, un driver di interfaccia di rete 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 timeout su tale scheda di interfaccia di rete, NDIS presuppone che la scheda di interfaccia di rete non funzionasse più correttamente e chiamare 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