Funzione RxRegisterMinirdr (mrx.h)

Articolo
02/29/2024

RxRegisterMinirdr viene chiamato da un driver di mini-reindirizzamento di rete per registrare il driver con RDBSS, che aggiunge le informazioni di registrazione a una tabella di registrazione interna. RDBSS compila anche un oggetto dispositivo per il mini-redirector di rete.

Sintassi

NTSTATUS RxRegisterMinirdr(
  [out]     OUT PRDBSS_DEVICE_OBJECT *DeviceObject,
  [in, out] IN OUT PDRIVER_OBJECT    DriverObject,
  [in]      IN PMINIRDR_DISPATCH     MrdrDispatch,
  [in]      IN ULONG                 Controls,
  [in]      IN PUNICODE_STRING       DeviceName,
  [in]      IN ULONG                 DeviceExtensionSize,
  [in]      IN DEVICE_TYPE           DeviceType,
  [in]      IN ULONG                 DeviceCharacteristics
);

Parametri

[out] DeviceObject

Puntatore alla posizione in cui verrà archiviato l'oggetto dispositivo creato.

[in, out] DriverObject

Puntatore all'oggetto driver del driver del driver mini-redirector di rete. Ogni driver riceve un puntatore all'oggetto driver in un parametro per la routine DriverEntry . Questo oggetto driver verrà usato per creare l'oggetto dispositivo per il driver mini-redirector di rete.

[in] MrdrDispatch

Puntatore alla tabella dispatch per il mini-redirector di rete. Questa tabella dispatch include informazioni di configurazione per il mini-redirector di rete e una tabella di puntatori alle routine di callback implementate dal driver kernel del mini-redirector di rete. RDBSS effettua chiamate al driver mini-redirector di rete tramite questo elenco di routine di callback.

[in] Controls

Set di opzioni che determinano le funzionalità del driver mini-redirector di rete e il modo in cui RDBSS deve gestire la memorizzazione nella cache di inizializzazione e tabella dei nomi per il driver mini-redirector di rete. Queste opzioni possono includere qualsiasi combinazione dei bit seguenti:

RX_REGISTERMINI_FLAG_DONT_PROVIDE_UNCS

Quando questo flag è impostato, indica che il mini-redirector di rete non supporta i nomi UNC.

RX_REGISTERMINI_FLAG_DONT_PROVIDE_MAILSLOTS

Quando questo flag è impostato, indica che il mini-redirector di rete non supporta mailslots.

RX_REGISTERMINI_FLAG_DONT_INIT_DRIVER_DISPATCH

Quando questo flag è impostato, indica che il mini-redirector di rete non vuole che RDBSS inizializzi i punti di ingresso del driver di invio del mini-redirector in modo che puntino alle routine interne di RDBSS. Questa opzione viene usata solo in circostanze insolite. In genere RDBSS imposterà i punti di ingresso dell'invio del driver e l'invio rapido di I/O nell'oggetto driver del mini-reindirizzamento di rete in modo da puntare alle routine interne a RDBSS.

RX_REGISTERMINI_FLAG_DONT_INIT_PREFIX_N_SCAVENGER

Quando questo flag è impostato, indica che il mini-redirector di rete non vuole che RDBSS inizializzi la tabella dei nomi di rete interna e le strutture di dati scavenger per eseguire lo scavenging di questa tabella dei nomi. Questa opzione verrà impostata per un mini-redirector di rete che vuole gestire la memorizzazione nella cache per i nomi di condivisione di rete e non usare le funzionalità RDBSS per la memorizzazione nella cache dei nomi e lo scavenging.

[in] DeviceName

Puntatore a un buffer che contiene una stringa Unicode con terminazione zero che assegna un nome all'oggetto dispositivo. La stringa deve essere un nome di percorso completo. Questo parametro viene passato come DeviceName alla routine IoCreateDevice da RDBSS.

[in] DeviceExtensionSize

Dimensione specificata dal driver mini-redirector per il numero di byte da allocare per l'estensione del dispositivo dell'oggetto dispositivo. La struttura interna dell'estensione del dispositivo è definita dal driver. Questo parametro viene aggiunto alle dimensioni dell'estensione del dispositivo usata da RDBSS e passato come parametro DeviceExtensionSize alla routine IoCreateDevice da RDBSS.

[in] DeviceType

Tipo di dispositivo utilizzato quando viene creato l'oggetto dispositivo. Specifica una delle costanti definite dal sistema FILE_DEVICE_XXX che indicano il tipo di dispositivo o un valore definito dal fornitore per un nuovo tipo di dispositivo. Questo valore in genere è FILE_DEVICE_NETWORK_FILE_SYSTEM per i driver del mini-redirector di rete. Questo parametro viene passato come DeviceType alla routine IoCreateDevice da RDBSS.

[in] DeviceCharacteristics

Caratteristiche del dispositivo usate quando viene creato l'oggetto dispositivo. Specifica una o più costanti definite dal sistema, combinate, che forniscono informazioni aggiuntive sul dispositivo del driver. Questo valore deve includere FILE_REMOTE_DEVICE per i driver del mini-reindirizzamento di rete, ma potrebbe essere combinato con altre caratteristiche, ad esempio FILE_DEVICE_SECURE_OPEN. Questo parametro viene passato come DeviceCharacteristics alla routine IoCreateDevice da RDBSS.

Valore restituito

RxRegisterMinirdr restituisce STATUS_SUCCESS in caso di esito positivo o uno dei valori di errore seguenti in caso di errore:

Codice restituito	Descrizione
STATUS_INSUFFICIENT_RESOURCES	Risorse insufficienti per creare l'oggetto dispositivo.
STATUS_INVALID_PARAMETER	Alla routine è stato passato un parametro non valido. Questo errore verrà restituito se il parametro DeviceObject è un puntatore NULL .
STATUS_OBJECT_NAME_COLLISION	Si è verificato un conflitto di nomi quando si tenta di creare questo oggetto dispositivo.
STATUS_OBJECT_NAME_EXISTS	Esiste già un oggetto dispositivo con questo nome.
STATUS_UNSUCCESSFUL	La chiamata per creare l'oggetto dispositivo ha restituito un oggetto dispositivo NULL .

Commenti

Un mini-redirector di rete viene registrato con RDBSS ogni volta che il driver viene caricato dal kernel e annulla la registrazione con RDBSS quando il driver viene scaricato. Un driver non monolitico (mini-redirector di rete SMB) comunica con il Rdbss.sys, un altro driver kernel. Per un driver mini-redirector di rete monolitica che collega staticamente con Rdbsslib.lib, questa comunicazione è semplicemente una chiamata a una routine di libreria Rdbsslib.lib .

Un mini-reindirizzamento di rete informa RDBSS che è stato caricato chiamando RxRegisterMinirdr, la routine di registrazione esportata da RDBSS. Quando un driver mini-redirector di rete viene avviato per la prima volta (nella routine DriverEntry ), il driver chiama la routine RDBSS RxRegisterMinirdr per registrare il driver del mini-redirector di rete con RDBSS. In base ai parametri passati a RxRegisterMinirdr, RDBSS chiama IoCreateDevice per creare l'oggetto dispositivo per il driver del mini-redirector di rete.

Come parte di questo processo di registrazione, il mini-redirector di rete passa un parametro a RxRegisterMinirdr che è un puntatore a una struttura di grandi dimensioni, MINIRDR_DISPATCH, che contiene informazioni di configurazione per il mini-redirector di rete e una tabella dispatch di puntatori alle routine di callback implementate dal driver mini-redirector di rete. Questi dati di configurazione vengono usati per configurare le tabelle RDBSS interne da usare con questo mini-reindirizzamento di rete. RDBSS usa le routine di callback passate in questa struttura per comunicare con il mini-redirector di rete. Un mini-redirector di rete può scegliere di implementare solo alcune di queste routine di callback. Qualsiasi routine di callback non implementata deve essere impostata su un puntatore NULL nella tabella dispatch passata a RDBSS. Solo le routine di callback implementate dal mini-redirector di rete verranno chiamate da RDBSS.

Si noti che la routine RxRegisterMinirdr imposta tutte le routine di invio dei driver del driver mini-redirector di rete in modo che puntino alla routine di invio RDBSS di primo livello, RxFsdDispatch. Un mini-redirector di rete può eseguire l'override di questo comportamento salvando una copia dei relativi punti di ingresso di invio del driver, chiamando RxRegisterMinirdr e riscrivendo l'invio del driver con i propri punti di ingresso dopo la restituzione della chiamata a RxRegisterMinirdr . Un mini-redirector di rete può anche impedire che le routine di invio del driver vengano copiate dalla routine RxRegisterMinirdr se il bit RX_REGISTERMINI_FLAG_DONT_INIT_DRIVER_DISPATCH è impostato nel parametro Controls .

Se la chiamata RxRegisterMinirdr ha esito positivo, viene inizializzato un numero di membri in RDBSS_DEVICE_OBJECT puntato dal parametro DeviceObject , tra cui:

Il membro Dispatch è impostato sul parametro MrdrDispatch .
Il membro RegistrationControls è impostato sul parametro Controls .
Il membro DeviceName è impostato sul parametro DeviceName .
Il membro RegisterUncProvider è impostato su TRUE se il bit di RX_REGISTERMINI_FLAG_DONT_PROVIDE_UNCS nel parametro Controls non è stato impostato.
Il membro RegisterMailSlotProvider è impostato su TRUE se il bit RX_REGISTERMINI_FLAG_DONT_PROVIDE_MAILSLOTS nel parametro Controls non è stato impostato.
Il membro NetworkProviderPriority è impostato sulla priorità del provider di rete che verrà usata da MUP.

Se la chiamata RxRegisterMinirdr ha esito positivo e il bit RX_REGISTERMINI_FLAG_DONT_INIT_PREFIX_N_SCAVENGER nel parametro Controls non è impostato, vengono inizializzati alcuni altri membri in RDBSS_DEVICE_OBJECT puntati dal parametro DeviceObject , inclusi i seguenti:

La struttura dei membri pRxNetNameTable viene inizializzata.
Il membro RxNetNameTableInDeviceObject.IsNetNameTable è impostato su TRUE.
La struttura dei membri pRdbssScavenger viene inizializzata.

Se la chiamata RxRegisterMinirdr ha esito positivo, RDBSS imposta lo stato interno del mini redirector di rete in RDBSS su RDBSS_STARTABLE.

Il mini-redirector di rete non avvia effettivamente l'operazione finché non riceve una chiamata alla routine MRxStart , una delle routine di callback passate nella struttura MINIRDR_DISPATCH. La routine di callback MrxStart deve essere implementata dal driver del mini-redirector di rete se desidera ricevere callback per le operazioni, a meno che il mini-redirector di rete non mantenga i propri punti di ingresso di invio del driver. In caso contrario, RDBSS consentirà solo i pacchetti di richiesta di I/O seguenti attraverso il driver fino a quando MrxStart non restituisce correttamente:

Le richieste IRP per le operazioni di creazione del dispositivo e le operazioni del dispositivo in cui il parametro FileObject->FileName.Length in IRPSP è zero e il parametro FileObject->RelatedFileObject è NULL.

Per qualsiasi altra richiesta IRP, la routine dispatch RDBSS , RxFsdDispatch, restituirà uno stato di STATUS_REDIRECTOR_NOT_STARTED.

La routine dispatch RDBSS non riuscirà anche a tutte le richieste per i pacchetti di richiesta di I/O seguenti:

IRP_MJ_CREATE_MAILSLOT
IRP_MJ_CREATE_NAMED_PIPE

La routine MrxStart mini-redirector di rete viene chiamata da RDBSS quando viene chiamata la routine RxStartMiniRdr . RdBSS RxStartMinirdr viene in genere chiamato come risultato di una richiesta DICTL o IOCTL da un'applicazione o un servizio in modalità utente per avviare il mini-redirector di rete. La chiamata a RxStartMinirdr non può essere eseguita dalla routine DriverEntry del mini-redirector di rete dopo una chiamata a RxRegisterMinirdr perché alcune delle elaborazioni di avvio richiedono il completamento dell'inizializzazione del driver. Una volta ricevuta la chiamata RxStartMinirdr , RDBSS completa il processo di avvio chiamando la routine MrxStart del mini-redirector di rete. Se la chiamata a MrxStart restituisce esito positivo, RDBSS imposta lo stato interno del mini redirector in RDBSS su RDBSS_STARTED.