PMRX_CREATE_V_NET_ROOT funzione di callback (mrx.h)

Articolo
02/07/2025

La routine MRxCreateVNetRoot viene chiamata da RDBSS per richiedere che il mini-reindirizzamento 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 utilizzato dal mini-redirector di rete per notificare a RDBSS quando la chiamata viene completata. 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-redirector di rete deve eseguire il mapping di STATUS_SUCCESS a STATUS_PENDING come valore restituito per MRxCreateVNetRoot.

Lo stato di completamento finale viene restituito in Context->VirtualNetRootStatus e Context->NetRootStatus membri una volta completata la chiamata e la routine nel membro callback della struttura Context viene chiamato dal mini-redirector di rete. Questi membri contengono inizialmente STATUS_SUCCESS fino a quando il mini-reindirizzamento di rete non 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 ilVirtualNetRootStatus o membro 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 è pronto per soddisfare la richiesta.
STATUS_UNEXPECTED_NETWORK_ERROR	Si è verificato un errore di rete imprevisto causato in genere da un handle non valido.

Osservazioni

Le due astrazioni importanti usate nell'interfaccia tra RDBSS e un mini-redirector 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 di 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. Il completamento di questa operazione può richiedere molto tempo 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 NET_ROOT/V_NET_ROOT viene modellata come attività in due fasi. Ogni chiamata a un mini-redirector di rete per la creazione di una struttura di NET_ROOT/V_NET_ROOT è seguita da una chiamata dal mini-redirector di rete a RDBSS che indica a RDBSS lo stato di completamento della richiesta al mini-reindirizzamento di rete. Poiché RDBSS prevede MRxCreateVNetRoot viene 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 di NET_ROOT esistente.

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

È prevista un'implementazione del mini-redirector di rete di MRxCreateVNetRoot restituirà STATUS_PENDING alla chiamata iniziale. Al termine dell'elaborazione, il mini-reindirizzamento di rete chiamerebbe 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 a cui deve essere chiamato il mini-redirector di rete viene specificata come membro callback nella struttura MRX_CREATENETROOT_CONTEXT passata come parametro Context. Lo stato di completamento finale della chiamata MRxCreateVNetRoot deve essere archiviato nella VirtualNetRootStatus e NetRootStatus membri 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 di NET_ROOT o di V_NET_ROOT può richiedere la creazione di handle correlati al trasporto per le comunicazioni di rete. Poiché il processo di stabilire una connessione di rete può richiedere molto tempo, una volta stabilita una connessione, è opportuno usare la connessione per la comunicazione il più a lungo possibile. Dopo aver stabilito un handle di trasporto in una risorsa di rete remota, può essere riutilizzato da un numero qualsiasi di altre richieste dell'applicazione. Quando un'applicazione utente termina, gli handle associati al processo vengono eliminati. Per questo motivo, la definizione di 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 scomparirà mentre questi handle di trasporto vengono utilizzati per la comunicazione.

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

Un mini-redirector 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 un'esecuzione successiva da RDBSS. In genere, queste chiamate verrebbero inviate al DelayedWorkQueue.

Spetta al mini-redirector di rete decidere come viene implementato MRxCreateVNetRoot. Se questo processo può richiedere una notevole quantità di tempo, questa chiamata deve essere completata in modo asincrono. Se sono necessari handle di trasporto, il mini-redirector di rete potrebbe volere un processo di sistema 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 NET_ROOT e V_NET_ROOT in una modalità disconnessa (se supportata) e stabilire la connessione offline.

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