Funzione NdisIMInitializeDeviceInstanceEx (ndis.h)

Articolo
02/26/2024

La funzione NdisIMInitializeDeviceInstanceEx avvia l'operazione di inizializzazione per un miniport virtuale e, facoltativamente, configura le informazioni sullo stato sul miniport virtuale per i driver di protocollo associati successivamente.

Sintassi

NDIS_STATUS NdisIMInitializeDeviceInstanceEx(
  [in]           NDIS_HANDLE  DriverHandle,
  [in]           PNDIS_STRING DriverInstance,
  [in, optional] NDIS_HANDLE  DeviceContext
);

Parametri

[in] DriverHandle

Il driver miniport gestisce il La funzione NdisMRegisterMiniportDriver restituisce in NdisMiniportDriverHandle .

[in] DriverInstance

Puntatore a un tipo di NDIS_STRING che descrive una stringa con conteggiata inizializzata dal chiamante nel set di caratteri predefinito del sistema. La stringa contiene il nome della chiave del Registro di sistema in cui il driver archivia informazioni su un miniport virtuale e, possibilmente, informazioni specifiche dell'associazione. Per i driver di Microsoft Windows 2000 e versioni successive, questa stringa contiene caratteri Unicode. Ovvero, per Windows 2000 e versioni successive, NDIS definisce il tipo di NDIS_STRING come tipo di UNICODE_STRING .

[in, optional] DeviceContext

Puntatore alla memoria fornita dal chiamante da configurare con informazioni sul contesto di dispositivo definite dal driver sul miniport virtuale, che ancora driver di protocollo di livello superiore che successivamente si associano a questo miniport virtuale. Questo parametro può essere NULL se il driver intermedio non ha un'area di contesto di dispositivo di questo tipo.

Valore restituito

NdisIMInitializeDeviceInstanceEx può restituire una delle opzioni seguenti:

Codice restituito	Descrizione
NDIS_STATUS_SUCCESS	NDIS ha avviato l'operazione di inizializzazione per il miniport virtuale del driver intermedio.
NDIS_STATUS_NOT_ACCEPTED	NdisIMInitializeDeviceInstanceEx non è riuscito perché il dispositivo specificato da DriverHandle è già stato inizializzato.

Commenti

Un driver intermedio NDIS deve chiamare NdisIMInitializeDeviceInstanceEx dalla relativa funzione ProtocolBindAdapterEx . Un errore di chiamata a NdisIMInitializeDeviceInstanceEx da un driver intermedio NDIS impedisce in modo efficace il caricamento del driver.

Prima di chiamare NdisIMInitializeDeviceInstanceEx, la funzione ProtocolBindAdapterEx del driver intermedio deve essere associata a tutti i driver miniport sottostanti necessari per il funzionamento del driver intermedio. La funzione ProtocolBindAdapterEx può allocare anche un'area in DeviceContext , eventualmente impostandola con informazioni intermedie determinate dal driver sulle funzionalità dell'adattatore miniport sottostante e raccolte da ProtocolBindAdapterEx. La funzione MiniportInitializeEx del driver intermedio potrebbe usare tali informazioni successivamente per configurare questa area di contesto con informazioni sul miniport virtuale del driver.

La chiamata del driver intermedio a NdisIMInitializeDeviceInstanceEx fa sì che NDIS chiami la funzione MiniportInitializeEx del driver intermedio, se NDIS riceve un IRP_MN_START_DEVICE IRP per avviare il dispositivo. Se NDIS non riceve tale IRP, NDIS non chiamerà la funzione MiniportInitializeEx del driver intermedio.

La chiamata a MiniportInitializeEx può verificarsi in un secondo momento e pertanto non è necessariamente all'interno del contesto della chiamata a NdisIMInitializeDeviceInstanceEx. Se NDIS non chiama mai MiniportInitializeEx per il miniport virtuale a cui viene fatto riferimento in una chiamata a NdisIMInitializeDeviceInstanceEx e il driver intermedio non richiede più il miniport virtuale, il driver intermedio deve chiamare il Funzione NdisIMCancelInitializeDeviceInstance per annullare l'inizializzazione del miniport virtuale. Si supponga, ad esempio, che un driver intermedio crei un miniport virtuale in risposta a un'associazione corretta a un adattatore miniport sottostante. Se tale associazione viene rimossa prima che NDIS chiami MiniportInitializeEx, il driver intermedio deve chiamare NdisIMCancelInitializeDeviceInstance per annullare l'inizializzazione del miniport virtuale.

MiniportInitializeEx alloca tutte le risorse richieste dal driver per eseguire operazioni di I/O di rete, ad esempio la chiamata a Funzione NdisMSetMiniportAttributes e per inizializzare il miniport virtuale del driver in uno stato operativo. I driver di protocollo di livello superiore possono quindi associarsi al miniport virtuale quando l'inizializzazione del driver intermedio viene completata correttamente.

Dopo che MiniportInitializeEx restituisce il controllo, l'area del contesto di dispositivo del driver intermedio, se presente, può contenere tutti i dati definiti dal driver intermedio che successivamente consentono a tutti i driver di protocollo di livello superiore associati allo stesso miniport virtuale di accedere alle informazioni in tale area di contesto. Un driver di protocollo di livello superiore può eseguire query sul contesto di dispositivo fornito dal driver intermedio con Funzione NdisIMGetBindingContext .

Prima che NDIS chiami la funzione MiniportInitializeEx di un driver intermedio, il driver può chiamare NdisIMCancelInitializeDeviceInstance per annullare l'operazione di inizializzazione.

Dopo che NDIS chiama la funzione MiniportInitializeEx di un driver intermedio, il driver deve chiamare NdisIMDeInitializeDeviceInstance per invertire l'operazione di inizializzazione.

Requisiti

Requisito	Valore
Client minimo supportato	Supportato per i driver NDIS 6.0 e NDIS 5.1 (vedere NdisIMInitializeDeviceInstanceEx (NDIS 5.1)) in Windows Vista. Supportato per i driver NDIS 5.1 (vedere NdisIMInitializeDeviceInstanceEx (NDIS 5.1)) in Windows XP.
Piattaforma di destinazione	Desktop
Intestazione	ndis.h (include Ndis.h)
Libreria	Ndis.lib
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	Irql_IM_Function(ndis)