Edit

SpbRequestGetTransferParameters function (spbcx.h)

  • Article

The SpbRequestGetTransferParameters method retrieves the transfer parameters for an individual transfer in an I/O transfer sequence.

Syntax

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

Parameters

[in] SpbRequest

An SPBREQUEST handle to the I/O request from which to retrieve the transfer parameters. This parameter must be a handle to an IOCTL_SPB_EXECUTE_SEQUENCE request.

[in] Index

The index of a transfer in the I/O transfer sequence. For more information, see the following Remarks section.

[out, optional] TransferDescriptor

A pointer to a caller-allocated SPB_TRANSFER_DESCRIPTOR structure into which the method writes the transfer parameters. The TransferDescriptor parameter is optional and can be specified as NULL if the caller does not require the transfer parameters. For more information, see the Remarks section.

[out, optional] TransferBuffer

A pointer to a location into which the method writes a pointer to an MDL (or an MDL chain) that describes the physical memory in the transfer buffer. The caller must not modify the contents of this MDL. This parameter is optional and can be set to NULL if the MDL is not needed. For more information, see the following Remarks section.

Return value

None

Remarks

To request an I/O transfer sequence, a client (peripheral driver) of the SPB controller driver sends an IOCTL_SPB_EXECUTE_SEQUENCE request that contains a list of the transfers in the sequence. Your controller driver can call SpbRequestGetTransferParameters to obtain information about a particular transfer in the sequence.

The Index parameter is an index that identifies a particular transfer in the sequence. If N is the number of transfers in the sequence, valid indexes range from 0 to N–1. To determine the number of transfers in the sequence, call the SpbRequestGetParameters method. This method retrieves an SPB_TRANSFER_DESCRIPTOR structure that contains the request parameters. The TransferCount member of this structure specifies the number of transfers in the sequence.

If TransferDescriptor is non-NULL, the caller must call the SPB_TRANSFER_DESCRIPTOR_INIT function to initialize the structure before calling SpbRequestGetTransferParameters. After the structure is initialized, it can be reused as many times as needed without being reinitialized.

TransferBuffer is an optional pointer into which SpbRequestGetTransferParameters writes a pointer to an MDL that describes the physical page layout for the transfer buffer. The transfer buffer can be described by a single MDL or by an MDL chain. A simple buffer, which consists of a contiguous block of virtual memory, is described by a single MDL. If a transfer buffer is formatted as a scatter-gather list, each contiguous block of virtual memory in the buffer is described by an MDL in an MDL chain. For more information about MDLs, see Using MDLs.

Examples

//
// 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);
}

Requirements

Requirement Value
Minimum supported client Available starting with Windows 8.
Target Platform Universal
Header spbcx.h
Library Spbcxstubs.lib
IRQL <= DISPATCH_LEVEL

See also