PMRX_CREATE_V_NET_ROOT funzione di callback (mrx.h)

Articolo
10/13/2023

La routine MRxCreateVNetRoot viene chiamata da RDBSS per richiedere che il mini-redirector di rete crei una struttura V_NET_ROOT e, in alcuni casi, una struttura NET_ROOT.

Sintassi

PMRX_CREATE_V_NET_ROOT PmrxCreateVNetRoot;

NTSTATUS PmrxCreateVNetRoot(
  IN OUT PMRX_CREATENETROOT_CONTEXT Context
)
{...}

Parametri

Context

[in, out] Puntatore al contesto di callback usato dal mini-redirector di rete per notificare RDBSS al termine della chiamata. Ciò include la struttura RX_CONTEXT della richiesta in Context-RxContext>. Il parametro Context include la struttura V_NET_ROOT da costruire in Context-pVNetRoot>. Questa struttura V_NET_ROOT contiene un puntatore alla struttura NET_ROOT in pVNetRoot-pNetRoot>. La struttura NET_ROOT contiene anche un puntatore alla struttura SRV_CALL in pNetRoot-pSrvCall>.

Valore restituito

RDBSS prevede che MRxCreateVNetRoot restituisca STATUS_PENDING in caso di esito positivo o negativo. Questo comportamento risulta perché RDBSS prevede che questa chiamata venga completata in modo asincrono. Un mini-reindirizzamento di rete deve eseguire il mapping STATUS_SUCCESS a STATUS_PENDING come valore restituito per MRxCreateVNetRoot.

Lo stato di completamento finale viene restituito nei membri Context-VirtualNetRootStatus e Context-NetRootStatus>> una volta completata la chiamata e la routine nel membro Callback della struttura Context viene chiamata dal mini-reindirizzamento di rete. Questi membri contengono inizialmente STATUS_SUCCESS fino a quando il mini-reindirizzamento di rete modifica questo valore al completamento. Se la chiamata è stata completata correttamente, entrambi i membri contengono STATUS_SUCCESS.

Se non si crea una struttura V_NET_ROOT o NET_ROOT, viene restituito uno dei codici di errore comuni seguenti per il membroVirtualNetRootStatus o NetRootStatus (anche se sono possibili altri codici di errore):

Codice restituito	Descrizione
STATUS_CONNECTION_RESET	La connessione alla risorsa remota è stata reimpostata.
STATUS_IO_TIMEOUT	Si è verificato un timeout in una richiesta di I/O.
STATUS_RETRY	Un server di avvio remoto non è stato pronto per soddisfare la richiesta.
STATUS_UNEXPECTED_NETWORK_ERROR	Si è verificato in genere un errore di rete imprevisto causato da un handle non valido.

Commenti

Le due astrazione importanti usate nell'interfaccia tra RDBSS e un mini-reindirizzamento di rete sono la struttura SRV_CALL e la struttura NET_ROOT/V_NET_ROOT. Una struttura SRV_CALL corrisponde al contesto associato a un server con cui è stata stabilita una connessione. Una struttura NET_ROOT corrisponde a una condivisione in un server. Una struttura V_NET_ROOT può essere vista come parte dello spazio dei nomi sotto una struttura NET_ROOT richiesta da un mini-reindirizzamento di rete.

La creazione di una struttura NET_ROOT/V_NET_ROOT comporta in genere almeno un round trip di rete. Questa operazione può richiedere molto tempo per completare perché potrebbe essere necessario stabilire una connessione di rete con una risorsa remota. Per garantire che le operazioni asincrone continuino, la creazione di una struttura di NET_ROOT/V_NET_ROOT viene modellata come attività in due fasi. Ogni chiamata a un mini-reindirizzamento di rete per la creazione di una struttura di NET_ROOT/V_NET_ROOT viene seguita da una chiamata dal mini-reindirizzamento di rete a RDBSS che indica a RDBSS lo stato di completamento della richiesta al mini-reindirizzamento di rete. Poiché RDBSS prevede che MRxCreateVNetRoot venga completato in modo asincrono, RDBSS prevede che MRxCreateVNetRoot restituisca STATUS_PENDING. RDBSS riceverà una notifica usando la routine di callback al termine della chiamata.

MRxCreateVNetRoot deve gestire due casi di interesse:

Viene creata una nuova struttura V_NET_ROOT e la nuova struttura NET_ROOT associata.
Viene creata una nuova struttura V_NET_ROOT associata a una struttura NET_ROOT esistente.

Questi due casi possono essere distinti controllando se il contesto associato a una struttura NET_ROOT è NULL.

Un'implementazione mini-redirector di rete di MRxCreateVNetRoot dovrebbe restituire STATUS_PENDING alla chiamata iniziale. Al termine dell'elaborazione, il mini-reindirizzamento di rete chiamerà la routine di callback passata come parte del parametro Context per notificare a RDBSS che la chiamata è stata completata e restituire lo stato di completamento. La routine di callback che il mini-reindirizzamento di rete deve chiamare viene specificato come membro callback nella struttura di MRX_CREATENETROOT_CONTEXT passato come parametro Context . Lo stato di completamento finale della chiamata MRxCreateVNetRoot deve essere archiviato nei membri VirtualNetRootStatus e NetRootStatus del parametro Context . Si noti che lo stato separato viene restituito per le strutture NET_ROOT e V_NET_ROOT.

L'implementazione di MRxCreateVNetRoot in un mini-redirector di rete è complicata anche dalla necessità di handle di trasporto. Alcune interfacce correlate al trasporto richiedono la creazione e l'uso di un handle per tutte le comunicazioni. La creazione di una struttura NET_ROOT o V_NET_ROOT può richiedere la creazione di handle correlati al trasporto per le comunicazioni di rete. Poiché il processo di creazione di una connessione di rete può richiedere molto tempo, una volta stabilita una connessione, è consigliabile usare la connessione per la comunicazione il più a lungo possibile. Una volta stabilito un handle di trasporto in una risorsa di rete remota, può essere riutilizzato da qualsiasi numero di altre richieste dell'applicazione. Quando un'applicazione utente termina, gli handle associati al processo vengono eliminati. Per questo motivo, la definizione degli handle di trasporto nel contesto di un processo temporaneo in modalità utente che potrebbe essere di breve durata non ha senso. Pertanto, una struttura NET_ROOT o V_NET_ROOT normalmente deve essere inizializzata nel contesto di un processo noto che non scompare mentre questi handle di trasporto vengono usati per la comunicazione.

Un metodo usato per gestire questa operazione nei mini-reindirizzamenti di rete consiste nell'avere il processo di sistema RDBSS allocare questi handle di trasporto. Ciò influisce sul modo in cui viene eseguita la routine MRxCreateVNetRoot . Se la richiesta a MRxCreateVNetRoot è stata rilasciata nel contesto del processo di sistema RDBSS, questa chiamata può essere eseguita immediatamente e non deve essere inviata a una coda di lavoro. Tuttavia, per evitare problemi, se la richiesta a MRxCreateVNetRoot proviene da qualsiasi altro processo, la richiesta verrà inviata a una coda di lavoro di sistema usando RxDispatchToWorkerThread per l'esecuzione successiva. RDBSS userà successivamente uno dei thread di sistema per elaborare la richiesta della coda di lavoro ed eseguire MRxCreateVNetRoot. Ciò garantisce che tutti gli handle di trasporto siano di proprietà di un processo di sistema.

Un mini-reindirizzamento di rete può determinare se una chiamata a MRxCreateVNetRoot è stata ricevuta direttamente da RDBSS chiamando RxGetRDBSSProcess. RxGetRDBSSProcess restituisce il processo RDBBS e questo valore può essere confrontato con il processo corrente restituito chiamando IoGetCurrentProcess. Se la chiamata a MRxCreateVNetRoot non è stata avviata nel contesto del processo di sistema RDBSS, MRxCreateVNetRoot può restituire STATUS_PENDING e pubblicare la chiamata a una coda di lavoro usando RxDispatchToWorkerThread per l'esecuzione successiva da RDBSS. In genere, queste chiamate verranno inviate all'oggetto DelayedWorkQueue.

Si tratta del mini-redirector di rete per decidere come viene implementato MRxCreateVNetRoot . Se questo processo può richiedere molto tempo, questa chiamata deve essere completata in modo asincrono. Se sono necessari handle di trasporto, il mini-reindirizzamento di rete potrebbe volere un processo di sistema che è di lunga durata per stabilire questi handle.

Nel caso in cui non sia possibile stabilire la connessione, il mini-reindirizzamento di rete può provare a eseguire la transizione delle strutture di NET_ROOT e V_NET_ROOT in una modalità disconnessa (se supportata) e stabilire la connessione offline.

Al termine di MRxCreateVNetRoot , il parametro Context deve essere modificato con le NET_ROOT appropriate e V_NET_ROOT informazioni sulla struttura aggiornate dal mini-reindirizzamento di rete.