MINIPORT_PAUSE funzione di callback (ndis.h)

Articolo
03/08/2024

NDIS chiama la funzione MiniportPause di un driver miniport per arrestare il flusso dei dati di rete tramite una scheda miniport specificata.

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

Sintassi

MINIPORT_PAUSE MiniportPause;

NDIS_STATUS MiniportPause(
  [in] NDIS_HANDLE MiniportAdapterContext,
  [in] PNDIS_MINIPORT_PAUSE_PARAMETERS PauseParameters
)
{...}

Parametri

[in] MiniportAdapterContext

Handle per un'area di contesto allocata dal driver miniport nella funzione MiniportInitializeEx . Il driver miniport utilizza questa area di contesto per mantenere le informazioni sullo stato per un adattatore miniport.

[in] PauseParameters

Puntatore a un oggetto NDIS_MINIPORT_PAUSE_PARAMETERS struttura che definisce i parametri di sospensione per l'adattatore miniport.

Valore restituito

MiniportPause restituisce uno dei valori di stato seguenti:

Codice restituito	Descrizione
NDIS_STATUS_SUCCESS	MiniportPause ha arrestato correttamente il flusso dei dati di rete attraverso la scheda miniport.
NDIS_STATUS_PENDING	MiniportPause non ha completato l'operazione di sospensione e l'operazione verrà completata in modo asincrono. Il driver miniport deve chiamare la funzione NdisMPauseComplete al termine dell'operazione.

Commenti

Un driver specifica il punto di ingresso MiniportPause quando chiama Funzione NdisMRegisterMiniportDriver .

NDIS sospende un adattatore miniport per arrestare il flusso di dati che potrebbe interferire con le operazioni PnP, ad esempio l'aggiunta o la rimozione di un driver di filtro o l'associazione o l'associazione di un driver di protocollo.

NDIS chiama la funzione MiniportPause di un driver miniport per avviare una richiesta di pausa per l'adattatore miniport specificato in MiniportAdapterContext. L'adattatore miniport rimane nello stato Sospensione fino al completamento dell'operazione di sospensione.

Per un adattatore miniport nello stato Sospensione , il driver miniport:

Attende tutte le chiamate al Funzione NdisMIndicateReceiveNetBufferLists da restituire.
Attende che NDIS restituisca la proprietà di tutte le strutture NET_BUFFER_LIST da ricevere indicazioni in sospeso al miniport driver Funzione MiniportReturnNetBufferLists .
Completa tutte le richieste di invio in sospeso e chiama il Funzione NdisMSendNetBufferListsComplete per tutte le richieste di invio in sospeso.
Rifiuta tutte le nuove richieste di invio effettuate al suo Funzione MiniportSendNetBufferLists immediatamente chiamando NdisMSendNetBufferListsComplete. Deve impostare lo stato completo in ogni NET_BUFFER_LIST su NDIS_STATUS_PAUSED.
Può fornire indicazioni sullo stato con Funzione NdisMIndicateStatusEx .
Deve gestire le richieste OID nella funzione MiniportOidRequest .
Non arrestare completamente l'adattatore miniport se l'adattatore miniport impedisce al driver di gestire le richieste o fornire indicazioni sullo stato.
Non deve liberare le risorse allocate dal driver durante l'inizializzazione.

NDIS non avvia altre operazioni PnP per l'adattatore miniport, ad esempio stop, initialize, power change, pause o a restart requests, while the miniport adapter is in the Pausing state. NDIS può avviare queste operazioni PnP dopo che un adattatore miniport è nello stato Sospeso .

Dopo che un driver miniport completa tutte le richieste di invio in sospeso e NDIS restituisce tutte le strutture di dati di rete ricevute (dalle indicazioni di ricezione in sospeso), il driver deve completare l'operazione di sospensione. Se il driver restituisce NDIS_STATUS_SUCCESS da MiniportPause, l'operazione di sospensione è stata completata. Se il driver restituisce NDIS_STATUS_PENDING, l'adattatore miniport può rimanere nello stato Sospensione e l'operazione di sospensione viene completata dopo che il driver chiama la funzione NdisMPauseComplete . Al termine dell'operazione di sospensione, l'adattatore miniport è nello stato Sospeso .

Per un adattatore miniport nello stato Sospeso , il driver miniport:

Deve rifiutare immediatamente tutte le richieste inviate a MiniportSendNetBufferLists chiamando NdisMSendNetBufferListsComplete. Deve impostare il membro Status in ogni NET_BUFFER_LIST su NDIS_STATUS_PAUSED.
Può gestire gli interrupt di ricezione (vedere la funzione MiniportInterrupt ) e interrompere i DPC (vedere la funzione MiniportInterruptDPC ), ma non deve indicare i dati di rete ricevuti.
Può fornire indicazioni sullo stato con la funzione NdisMIndicateStatusEx .
Deve gestire le richieste OID nella funzione MiniportOidRequest .
Deve gestire le richieste per modificare lo stato di alimentazione del dispositivo nel Funzione MiniportDevicePnPEventNotify .
Può gestire le chiamate alle funzioni NetTimerCallback .
Può gestire le richieste per reimpostare l'hardware nella funzione MiniportResetEx .

I driver Miniport non possono eseguire una richiesta di sospensione. Pertanto, se un driver miniport richiede risorse per gestire una richiesta di sospensione, deve preallocare le risorse durante l'inizializzazione.

NDIS chiama la funzione MiniportRestart per avviare una richiesta di riavvio per un adattatore miniport sospeso.

NDIS chiama MiniportPause in IRQL = PASSIVE_LEVEL.

Esempi

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

Ad esempio, per definire una funzione MiniportPause denominata "MyPause", usare il tipo MINIPORT_PAUSE , come illustrato nell'esempio di codice seguente:

MINIPORT_PAUSE MyPause;

Implementare quindi la funzione come segue:

_Use_decl_annotations_
NDIS_STATUS
 MyPause(
    NDIS_HANDLE  MiniportAdapterContext,
    PNDIS_MINIPORT_PAUSE_PARAMETERS  MiniportPauseParameters
    )
  {...}

Il tipo di funzione MINIPORT_PAUSE è 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 garantisce che vengano utilizzate le annotazioni applicate al tipo di funzione MINIPORT_PAUSE 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