Funzione SpbRequestGetTransferParameters (spbcx.h)

Articolo
02/07/2025

Il metodo spbRequestGetTransferParameters recupera i parametri di trasferimento per un singolo trasferimento in una sequenza di trasferimento di I/O .

Sintassi

void SpbRequestGetTransferParameters(
  [in]            SPBREQUEST              SpbRequest,
  [in]            ULONG                   Index,
  [out, optional] SPB_TRANSFER_DESCRIPTOR *TransferDescriptor,
  [out, optional] PMDL                    *TransferBuffer
);

Parametri

[in] SpbRequest

Un SPBREQUEST handle alla richiesta di I/O da cui recuperare i parametri di trasferimento. Questo parametro deve essere un handle per una richiesta di IOCTL_SPB_EXECUTE_SEQUENCE.

[in] Index

Indice di un trasferimento nella sequenza di trasferimento di I/O. Per altre informazioni, vedere la sezione Osservazioni seguente.

[out, optional] TransferDescriptor

Puntatore a una struttura SPB_TRANSFER_DESCRIPTOR allocata dal chiamante in cui il metodo scrive i parametri di trasferimento. Il parametro TransferDescriptor è facoltativo e può essere specificato come NULL se il chiamante non richiede i parametri di trasferimento. Per altre informazioni, vedere la sezione osservazioni.

[out, optional] TransferBuffer

Puntatore a una posizione in cui il metodo scrive un puntatore a un MDL (o una catena MDL) che descrive la memoria fisica nel buffer di trasferimento. Il chiamante non deve modificare il contenuto di questo MDL. Questo parametro è facoltativo e può essere impostato su NULL se il linguaggio MDL non è necessario. Per altre informazioni, vedere la sezione Osservazioni seguente.

Valore restituito

Nessuno

Osservazioni

Per richiedere una sequenza di trasferimento di I/O, un client (driver periferico) del driver del controller SPB invia una richiesta di IOCTL_SPB_EXECUTE_SEQUENCE che contiene un elenco dei trasferimenti nella sequenza. Il driver del controller può chiamare SpbRequestGetTransferParameters per ottenere informazioni su un determinato trasferimento nella sequenza.

Il parametro Index è un indice che identifica un particolare trasferimento nella sequenza. Se N è il numero di trasferimenti nella sequenza, gli indici validi sono compresi tra 0 e N-1. Per determinare il numero di trasferimenti nella sequenza, chiamare il metodo SpbRequestGetParameters. Questo metodo recupera una struttura SPB_TRANSFER_DESCRIPTOR che contiene i parametri della richiesta. Il membro TransferCount di questa struttura specifica il numero di trasferimenti nella sequenza.

Se TransferDescriptor è diverso da NULL, il chiamante deve chiamare la funzione SPB_TRANSFER_DESCRIPTOR_INIT per inizializzare la struttura prima di chiamare SpbRequestGetTransferParameters. Dopo l'inizializzazione della struttura, può essere riutilizzata quante volte necessario senza essere reinizializzata.

TransferBuffer è un puntatore facoltativo in cui SpbRequestGetTransferParameters scrive un puntatore a un MDL che descrive il layout di pagina fisico per il buffer di trasferimento. Il buffer di trasferimento può essere descritto da un singolo MDL o da una catena MDL. Un buffer semplice, costituito da un blocco contiguo di memoria virtuale, è descritto da un singolo MDL. Se un buffer di trasferimento viene formattato come elenco di raccolta a dispersione, ogni blocco contiguo di memoria virtuale nel buffer viene descritto da un MDL in una catena MDL. Per altre informazioni sugli mdls, vedere Using MDLs.

Esempi

//
// Note that this snippet shows a transfer completing synchronously. This
// is a horrible thing for a driver to do, but demonstrates the DDI nicely.
//

WDF_REQUEST_PARAMETERS parameters;
WDF_TRANSFER_DESCRIPTOR transfer;

WDF_REQUEST_PARAMETERS_INIT(&parameters);
WDF_TRANSFER_DESCRIPTOR_INIT(&transfer);

SpbRequestGetParameters(request, &parameters);

for (ULONG i = 0; i < parameters.SequenceCount; i += 1)
{
    WDFMEMORY buffer;

    SpbRequestGetTransferParameters(request, i, &transfer, &buffer);

    MyDriverPerformTransfer(deviceContext, 
                            request,
                            transfer,
                            buffer);
}

Fabbisogno

Requisito	Valore
client minimo supportato	Disponibile a partire da Windows 8.
piattaforma di destinazione	Universale
intestazione	spbcx.h
libreria	Spbcxstubs.lib
IRQL	<= DISPATCH_LEVEL

Condividi tramite