MINIPORT_PAUSE funzione di callback (ndis.h)

Articolo
03/08/2024

NDIS chiama la funzione MiniportPause del driver miniport per arrestare il flusso di 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 seguenti.

Sintassi

MINIPORT_PAUSE MiniportPause;

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

Parametri

[in] MiniportAdapterContext

Handle in un'area di contesto allocata dal driver miniport nella funzione MiniportInitializeEx . Il driver miniport usa 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 di dati di rete tramite 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 una funzione miniport driver MiniportPause per avviare una richiesta di sospensione per l'adattatore miniport specificato in MiniportAdapterContext. L'adattatore miniport rimane nello stato di sospensione fino al completamento dell'operazione di sospensione.

Per un adattatore miniport nello stato di sospensione , il driver miniport:

Attende tutte le chiamate all'oggetto Funzione NdisMIndicateReceiveNetBufferLists da restituire.
Attende che NDIS restituisca la proprietà di tutte le strutture NET_BUFFER_LIST da ricevere indicazioni per il miniport driver Funzione MiniportReturnNetBufferLists .
Completa tutte le richieste di invio in sospeso e chiama Funzione NdisMSendNetBufferListsComplete per tutte le richieste di invio in sospeso.
Rifiuta tutte le nuove richieste di invio effettuate al relativo 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 l'oggetto Funzione NdisMIndicateStatusEx .
Deve gestire le richieste OID nella funzione MiniportOidRequest .
Non arrestare completamente l'adattatore miniport se l'arresto dell'adattatore miniport impedisce al driver di gestire le richieste o fornire indicazioni sullo stato.
Non liberare le risorse allocate dal driver durante l'inizializzazione.

NDIS non avvia altre operazioni PnP per l'adattatore miniport, ad esempio arresta, inizializzazione, cambio di alimentazione, sospensione o riavvio, mentre l'adattatore miniport si trova nello stato di sospensione. NDIS può avviare queste operazioni PnP dopo che una scheda miniport è nello stato sospeso .

Dopo che un driver miniport completa tutte le richieste di invio in sospeso e NDIS restituisce tutte le strutture dati di rete ricevute (da 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 viene completata. Se il driver restituisce NDIS_STATUS_PENDING, l'adattatore miniport può rimanere nello stato di 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 si trova nello stato Sospeso .

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

Deve rifiutare tutte le richieste inviate a MiniportSendNetBufferLists immediatamente chiamando NdisMSendNetBufferListsComplete. Deve impostare il membro Status in ogni NET_BUFFER_LIST su NDIS_STATUS_PAUSED.
Può gestire gli interruzioni (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 nell'oggetto 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 avere esito negativo a una richiesta di sospensione. Pertanto, se un driver miniport richiede qualsiasi risorsa 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 una scheda miniport sospesa.

NDIS chiama MiniportPause in IRQL = PASSIVE_LEVEL.

Esempi

Per definire una funzione MiniportPause , è prima necessario specificare 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 usando i tipi di funzione consente l'analisi del codice per i driver, il verifica driver statico (SDV) e altri strumenti di verifica trovano errori ed è un requisito per la scrittura di 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 indicato di seguito:

_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 durante l'esecuzione degli 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 usate 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 per i driver NDIS.

Per informazioni su 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 (includere Ndis.h)
IRQL	PASSIVE_LEVEL