> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DSTORAGE_REQUEST

> DSTORAGE_REQUEST

# DSTORAGE\_REQUEST

代表 DirectStorage 读取请求。

## Syntax

```cpp theme={null}
struct DSTORAGE_REQUEST {
    DSTORAGE_REQUEST_OPTIONS Options;

    union
    {
        void *Destination;

        struct
        {
            PULONG_PTR DestinationPageArray;

            UINT16 DestinationPageOffset;
        };
    };

    UINT32 DestinationSize;

    union
    {
        struct
        {
            IDStorageFileX *File;

            UINT64 FileOffset;
        };
        void *Source;

        struct
        {
            PULONG_PTR SourcePageArray;

            UINT16 SourcePageOffset;
        };
    };

    UINT32 SourceSize;

    UINT32 IntermediateSize;

    UINT64 CancellationTag;

    const CHAR *Name;
};
```

### Members

*Options*\
类型：[DSTORAGE\_REQUEST\_OPTIONS](/reference/system/dstorage/structs/dstorage_request_options)

此请求的各种选项。

*Destination*\
类型：void \*

用于接收此请求最终结果的缓冲区地址。

*DestinationPageArray*\
类型：PULONG\_PTR

在指定 *DestinationIsPhysicalPages* 时，用于接收此请求最终结果的页数组的地址。每个条目为一个 64-KB 页码。

*DestinationPageOffset*\
类型：UINT16

在指定 *DestinationIsPhysicalPages* 时，目标起始位置在 64-KB 页内的偏移量。

*DestinationSize*\
类型：UINT32

此请求最终结果的预期大小（以字节为单位）。如果请求不包含解压缩，则该值应等于 *SourceSize*。对于包含解压缩的请求，该值将大于 *SourceSize*。

*File*\
类型：IDStorageFileX \*

在 *SourceType* 为 `DSTORAGE_REQUEST_SOURCE_FILE` 时，从中执行此读取请求的文件。

*FileOffset*\
类型：UINT64

在 *SourceType* 为 `DSTORAGE_REQUEST_SOURCE_FILE` 时，读取请求在文件中起始位置的偏移量（以字节为单位）。如果指定了 *ZlibDecompress* 或 *BcpackMode*，则偏移量必须按 16 字节对齐。

\**Source*\
类型：void

在 *SourceType* 为 `DSTORAGE_REQUEST_SOURCE_MEMORY` 且未指定 *SourceIsPhysicalPages* 时，要读取的源缓冲区的地址。

*SourcePageArray*\
类型：PULONG\_PTR

在 *SourceType* 为 `DSTORAGE_REQUEST_SOURCE_MEMORY` 且指定了 *SourceIsPhysicalPages* 时，提供要读取的源缓冲区的页数组地址。每个条目为一个 64-KB 页码。

*SourcePageOffset*\
类型：UINT16

在 *SourceType* 为 `DSTORAGE_REQUEST_SOURCE_MEMORY` 且指定了 *SourceIsPhysicalPages* 时，源起始位置在 64-KB 页内的偏移量。

*SourceSize*\
类型：UINT32

要从文件或内存源读取的大小（以字节为单位）。

*IntermediateSize*\
类型：UINT32

在同时指定了 *ZlibDecompress* 和 *BcpackMode* 时，BCPack 压缩数据的字节数。

*CancellationTag*\
类型：UINT64

用于取消匹配的任意 UINT64 数值。

\**Name*\
类型：const CHAR

请求的可选名称。用于调试。如果指定，则在请求完成之前该字符串应可访问。

## Remarks

此结构由 [IDStorageQueueX::EnqueueRequest](/reference/system/dstorage/interfaces/IDStorageQueueX/methods/idstoragequeuex_enqueuerequest) 方法使用。`EnqueueRequest` 返回后即可重用该结构。

单个请求必须满足以下大小要求之一：

* DestinationSize 小于或等于 32MiB (**DSTORAGE\_MAX\_4K\_PAGE\_DESTINATION\_SIZE**)。

  **或**

* SourceSize（仅适用于内存到内存的请求）与 DestinationSize 之和的总内存使用量小于或等于 1GiB (**DSTORAGE\_MAX\_REQUEST\_SIZE**)，并且大于 32MiB 的内存缓冲区必须使用 64KiB 页或 2MiB 页。

有关详细信息，请参阅 [DirectStorage 概述](/build/console-features/storage/directstorage/directstorage-overview) 中的“EnqueueRequest”一节。

## Requirements

**头文件：** dstorage\_xs.h

**受支持的平台：** XBOX Series 主机

## See also

[DStorage](/reference/system/dstorage/dstorage_members)


## Related topics

- [DSTORAGE_REQUEST_OPTIONS](/zh-CN/reference/system/dstorage/structs/dstorage_request_options.md)
- [DStorage](/zh-CN/reference/system/dstorage/dstorage_members.md)
- [IDStorageQueueX::EnqueueRequest](/zh-CN/reference/system/dstorage/interfaces/IDStorageQueueX/methods/idstoragequeuex_enqueuerequest.md)
- [DirectStorage 概述](/zh-CN/build/console-features/storage/directstorage/directstorage-overview.md)
- [DSTORAGE_REQUEST_SOURCE_TYPE](/zh-CN/reference/system/dstorage/enums/dstorage_request_source_type.md)