MINIPORT_ADD_DEVICE funzione di callback (ndis.h)

Articolo
08/07/2023

La funzione MiniportAddDevice consente a un driver miniport di stabilire un'area di contesto per un dispositivo aggiunto.

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

Sintassi

MINIPORT_ADD_DEVICE MiniportAddDevice;

NDIS_STATUS MiniportAddDevice(
  [in] NDIS_HANDLE NdisMiniportHandle,
  [in] NDIS_HANDLE MiniportDriverContext
)
{...}

Parametri

[in] NdisMiniportHandle

Handle NDIS che identifica l'adattatore miniport aggiunto dal gestore Plug and Play (PnP). NDIS passa anche questo handle all'oggetto Funzione MiniportInitializeEx .

[in] MiniportDriverContext

Handle per un'area di contesto allocata dal driver in cui il driver mantiene le informazioni sullo stato e sulla configurazione. Il driver miniport ha passato questa area di contesto al Funzione NdisMRegisterMiniportDriver .

Valore restituito

MiniportAddDevice restituisce uno dei valori seguenti:

Codice restituito	Descrizione
NDIS_STATUS_SUCCESS	Il driver miniport ha allocato correttamente le risorse necessarie per aggiungere il dispositivo.
NDIS_STATUS_RESOURCES	Il driver miniport non è riuscito ad allocare le risorse necessarie.
NDIS_STATUS_FAILURE	MiniportAddDevice non è riuscito per motivi diversi da risorse insufficienti.

Se MiniportAddDevice ha esito negativo, NDIS non chiamerà la funzione MiniportInitializeEx per inizializzare l'adattatore miniport.

Commenti

La funzione MiniportAddDevice è una funzione facoltativa. I driver Miniport che supportano MSI-X devono specificare un punto di ingresso per questa funzione nel NDIS_MINIPORT_PNP_CHARACTERISTICS struttura.

MiniportAddDevice può allocare un'area di contesto per la gestione IRP_MN_FILTER_RESOURCE_REQUIREMENTS Pacchetti di richieste di I/O (IRP)Handle di funzione MiniportFilterResourceRequirements. I driver Miniport specificano l'area di contesto inizializzando un NDIS_MINIPORT_ADD_DEVICE_REGISTRATION_ATTRIBUTES struttura e quindi chiamare Funzione NdisMSetMiniportAttributes . NDIS fornisce in seguito questo handle di contesto al MiniportRemoveDevice, Funzioni MiniportFilterResourceRequirements, MiniportStartDevice e MiniportInitializeEx . Per MiniportInitializeEx, l'handle di contesto viene passato nel membro MiniportAddDeviceContext del NDIS_MINIPORT_INIT_PARAMETERS struttura a cui punta il parametro MiniportInitParameters .

Se il driver miniport non riesce la chiamata a MiniportAddDevice dopo aver allocato l'area di contesto, il driver deve liberare l'area di contesto prima di tornare da MiniportAddDevice.

I driver Miniport devono usare un'area di contesto diversa per il membro MiniportAddDeviceContext della struttura NDIS_MINIPORT_ADD_DEVICE_REGISTRATION_ATTRIBUTES e il membro MiniportAdapterContext della struttura NDIS_MINIPORT_INIT_PARAMETERS . Aree di contesto separate garantiranno che le informazioni nell'area di contesto non vengano reinizializzate, che potrebbero verificarsi nella funzione MiniportInitializeEx se l'adattatore miniport viene interrotto e reinizializzato.

Quando il gestore PnP richiede che NDIS rimuovono il dispositivo, NDIS chiama la funzione MiniportRemoveDevice per annullare le operazioni eseguite da MiniportAddDevice .

NDIS chiama MiniportAddDevice in IRQL = PASSIVE_LEVEL.

Esempi

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

Ad esempio, per definire una funzione MiniportAddDevice denominata "MyAddDevice", usare il tipo di MINIPORT_ADD_DEVICE come illustrato nell'esempio di codice seguente:

MINIPORT_ADD_DEVICE MyAddDevice;

Implementare quindi la funzione come segue:

_Use_decl_annotations_
NDIS_STATUS
 MyAddDevice(
    NDIS_HANDLE  NdisMiniportHandle,
    NDIS_HANDLE  MiniportDriverContext
    )
  {...}

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