PMRX_CREATE_SRVCALL funzione di callback (mrx.h)

Articolo
02/26/2024

La routine MRxCreateSrvCall viene chiamata da RDBSS per richiedere che il mini-redirector di rete crei una struttura SRV_CALL e stabilisca la connessione con un server.

Sintassi

PMRX_CREATE_SRVCALL PmrxCreateSrvcall;

NTSTATUS PmrxCreateSrvcall(
  IN OUT PMRX_SRV_CALL SrvCall,
  IN OUT PMRX_SRVCALL_CALLBACK_CONTEXT SrvCallCallBackContext
)
{...}

Parametri

SrvCall

[in, out] Puntatore alla struttura SRV_CALL da creare.

SrvCallCallBackContext

[in, out] Puntatore al contesto di callback usato dal mini-redirector di rete per notificare RDBSS al termine della richiesta MRxCreateSrvCall . Il parametro SrvCallCallBackContext punta a una struttura MRX_SRVCALLDOWN_STRUCTURE che contiene la struttura RX_CONTEXT per questa richiesta, nonché la routine callback che il mini-reindirizzamento chiama quando la richiesta MRxCreateSrvCall viene completata.

Valore restituito

RDBSS prevede che MRxCreateSrvCall 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 MRxCreateSrvCall.

Lo stato di completamento finale viene restituito nel membro SrvCallCallBackContext-Status> una volta completata la chiamata e la routine nel membro callback nella struttura MRX_SRVCALLDOWN_STRUCTURE viene chiamata dal mini-reindirizzamento di rete. Questo membro contiene inizialmente STATUS_BAD_NETWORK_PATH fino al completamento del mini-reindirizzamento della rete.

Il membro SrvCallCallBackContext-Status> contiene STATUS_SUCCESS sull'esito positivo dopo il completamento della chiamata o uno dei codici di errore comuni seguenti in caso di errore (anche se sono possibili altri codici di errore):

Codice restituito	Descrizione
STATUS_BAD_NETWORK_PATH	Il percorso di rete specificato non è valido.
STATUS_NETWORK_UNREACHABLE	La rete non è raggiungibile.

Commenti

Le due astrazioni importanti usate nell'interfaccia tra RDBSS e un mini-reindirizzamento di rete sono la struttura SRV_CALL e la struttura NET_ROOT. Una struttura SRV_CALL corrisponde al contesto associato a un server una volta stabilita una connessione. Una struttura NET_ROOT corrisponde a una condivisione in un server ,che può essere visualizzata anche come parte dello spazio dei nomi che è stato richiesto da un mini-reindirizzamento di rete.

La creazione di una struttura SRV_CALL 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 SRV_CALL viene modellata come attività a due fasi. Ogni chiamata a un mini-reindirizzamento di rete per la creazione di una struttura di SRV_CALL è accompagnata da una chiamata dal mini-reindirizzamento di rete a RDBSS che specifica lo stato di completamento della richiesta. RDBSS presuppone che MRxCreateSrvCall venga completato in modo asincrono. Pertanto RDBSS prevede che MRxCreateSrvCall restituisca STATUS_PENDING. RDBSS riceverà una notifica usando la routine di callback al termine della chiamata.

Un'implementazione del mini-reindirizzamento di rete di MRxCreateSrvCall dovrebbe restituire STATUS_PENDING alla chiamata iniziale. Al termine dell'elaborazione, il mini-reindirizzamento di rete chiama la routine di callback passata come parte del parametro SrvCallCallCallBackContext per notificare a RDBSS che la chiamata è stata completata e per restituire lo stato di completamento. La routine di callback che viene specificata come membro callback del mini-reindirizzamento di rete nel MRX_SRVCALLDOWN_STRUCTURE del parametro SrvCallCallBackContext . Lo stato di completamento finale della chiamata deve essere archiviato nel membro Stato del parametro SrvCallCallBackContext .

In caso di esito positivo, il mini-reindirizzamento di rete deve anche archiviare un valore nel membro RecommunicateContext del file SrvCallCallBackContext. Il valore archiviato nel membro RecommunicateContext è il valore che RDBSS passerà a MRxSrvCallWinnerNotify nel parametro RecommunicateContext se MRxCreateSrvCall ha avuto esito positivo. Il mini-reindirizzamento di rete deve anche riempire i dati appropriati nel parametro SrvCall per la struttura SRV_CALL creata. Si noti che il parametro SrvCall passato a MRxCreateSrvCall è lo stesso del membro SrvCall nel MRX_SRVCALLDOWN_STRUCTURE del parametro SrvCallCallBackContext . Questo stesso parametro SrvCall viene passato anche a MRxSrvCallWinnerNotify nel parametro SrvCall .

L'implementazione di MRxCreateSrvCall 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 SRV_CALL 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 breve non ha senso. Pertanto, una struttura SRV_CALL 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 risolvere i potenziali problemi relativi agli handle di trasporto consiste nell'avere il processo di sistema RDBSS allocare gli handle di trasporto. Ciò influisce sul modo in cui viene eseguita la routine MRxCreateSrvCall . Se la richiesta a MRxCreateSrvCall è stata rilasciata 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 a MRxCreateSrvCall 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 MRxCreateSrvCall. 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 MRxCreateSrvCall è stata ricevuta direttamente da RDBSS chiamando RxGetRDBSSProcess. RxGetRDBSSProcess restituirà il processo RDBBS e questo valore può essere confrontato con il processo corrente restituito usando IoGetCurrentProcess. Se la chiamata a MRxCreateSrvCall non è stata avviata nel contesto del processo di sistema RDBSS, MRxCreateSrvCall può restituire STATUS_PENDING e pubblicare la chiamata a una coda di lavoro usando RxDispatchToWorkerThreadper un'esecuzione successiva da RDBSS. In genere, queste chiamate verranno inviate all'oggetto DelayedWorkQueue.

Si tratta dello sviluppatore del mini-redirector di rete per decidere come viene implementato MRxCreateSrvCall . Se il processo per creare un SRV_CALL può richiedere molto tempo, MRxCreateSrvCall deve essere completato in modo asincrono. Se sono necessari handle di trasporto, il mini-reindirizzamento di rete deve trovare un processo di sistema che è di lunga durata per stabilire questi handle.

Al termine della chiamata, il parametro SrvCall deve essere modificato con le informazioni sulla struttura SRV_CALL aggiornate dal mini-reindirizzamento di rete.

Un mini-reindirizzamento di rete che indica il supporto come provider UNC riceverà un'attestazione di prefisso dal provider UNC multiplo (MUP) come chiamata a MRxCreateSrvCall. Per altre informazioni sulla denominazione UNC e MUP, vedere Supporto per la denominazione e l'MUP UNC.