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

# PFPlatformLocalStorageReadAsyncHandler

> PlayFab 调用此存储处理程序来读取某个键下存储的数据；它会启动一个 XAsync 操作，该操作完成时返回读取的字节数。

PlayFab 需要从存储中读取数据时调用的读取存储处理程序。请将其实现为 [XAsyncProvider](https://docs.xbox.com/zh-CN/reference/system/xasyncprovider/functions/xasyncprovider.md)。

## 语法

```cpp theme={null}
HRESULT STDAPIVCALLTYPE PFPlatformLocalStorageReadAsyncHandler(
    void* context,
    const char* key,
    XAsyncBlock* async
);
```

### 参数

**`context`**   `_In_opt_` void\*

你传递给 [PFPlatformLocalStorageSetHandlers](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/pfplatform/functions/pfplatformlocalstoragesethandlers.md) 的 [PFLocalStorageHooks](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/pfplatform/structs/pflocalstoragehooks.md) 结构的 `context` 成员。可以为 `nullptr`。PlayFab 不拥有此指针。

**`key`**   `_In_z_` const char\*

标识数据。通常为文件路径。读取此键下存储的数据。

**`async`**   `_Inout_` [XAsyncBlock](https://docs.xbox.com/zh-CN/reference/system/xasync/structs/xasyncblock.md)\*

读取操作的 `XAsyncBlock`。

### 返回值

类型：HRESULT

如果你已在 `async` 上启动异步操作（例如使用 [XAsyncBegin](https://docs.xbox.com/zh-CN/reference/system/xasyncprovider/functions/xasyncbegin.md)），则返回 `S_OK`。如果处理程序返回失败 HRESULT，PlayFab 会以该 HRESULT 使存储操作失败，并且不会等待 `async` 完成，因此只有在尚未在 `async` 上启动操作时才返回失败。存储操作本身的结果应通过使用 [XAsyncComplete](https://docs.xbox.com/zh-CN/reference/system/xasyncprovider/functions/xasynccomplete.md) 完成 `async` 来报告。

## 备注

若要安装此处理程序，请在 [PFLocalStorageHooks](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/pfplatform/structs/pflocalstoragehooks.md) 结构的 `read` 成员中设置它（同时设置另外两个存储处理程序），并在调用 [PFInitialize](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/pfcore/functions/pfinitialize.md) 之前将该结构传递给 [PFPlatformLocalStorageSetHandlers](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/pfplatform/functions/pfplatformlocalstoragesethandlers.md)。如果三个处理程序中有任何一个为 `nullptr`，PFPlatformLocalStorageSetHandlers 将返回 `E_INVALIDARG`。如果未设置自定义处理程序，PlayFab 将使用基于 cstdio 和 `std::fstream` 对象的默认实现。

使用 [XAsyncComplete](https://docs.xbox.com/zh-CN/reference/system/xasyncprovider/functions/xasynccomplete.md) 完成 `async`，并传递读取操作的结果和所读取数据的大小（以字节为单位）。PlayFab 随后会调用 `XAsyncGetResultSize` 和 `XAsyncGetResult` 来复制数据，因此你的提供程序在收到 `XAsyncOp::GetResult` 时，必须将数据复制到 [XAsyncProviderData](https://docs.xbox.com/zh-CN/reference/system/xasyncprovider/structs/xasyncproviderdata.md) 的 `buffer` 成员中。

如果 `key` 下没有存储数据，默认实现会以 `S_OK` 和大小为 0 的结果大小完成操作。请在你的处理程序中执行相同的操作。

PlayFab 可能在启动存储操作的线程上以内联方式调用此处理程序，因此不要依赖它在哪个线程上运行。`async` 的队列是 PlayFab 从 PFLocalStorageHooks 的 `queueHandle` 成员派生的队列。如果 `queueHandle` 为 `nullptr`，PlayFab 会从你传递给 PFInitialize 的后台队列派生该队列；如果该队列也为 `nullptr`，则从进程任务队列派生。派生队列的工作回调和完成回调都在其来源队列的工作端口上运行。

PlayFab 一次只运行一个存储操作，并且只有在当前操作完成后才会启动下一个操作。

PlayFab 可以通过对 `async` 调用 `XAsyncCancel` 来取消挂起的操作。如果你的存储操作可以取消，请在提供程序中处理 `XAsyncOp::Cancel`。

`key` 和 `async` 参数由 PlayFab 拥有，并在操作完成之前保持有效。`context` 参数不在此保证范围内。

## 要求

**头文件：** PFPlatform.h

**库：** PlayFabCore.lib

**支持的平台：** Windows、XBOX One 系列主机和 XBOX Series 主机

## 另请参阅

[PFPlatform 成员](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/pfplatform/pfplatform_members.md)

[PFLocalStorageHooks](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/pfplatform/structs/pflocalstoragehooks.md)

[PFPlatformLocalStorageSetHandlers](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/pfplatform/functions/pfplatformlocalstoragesethandlers.md)

[XAsyncProvider](https://docs.xbox.com/zh-CN/reference/system/xasyncprovider/functions/xasyncprovider.md)

[PFPlatformLocalStorageWriteAsyncHandler](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/pfplatform/functions/pfplatformlocalstoragewriteasynchandler.md)

[PFPlatformLocalStorageClearAsyncHandler](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/pfplatform/functions/pfplatformlocalstorageclearasynchandler.md)


## Related topics

- [PFPlatformLocalStorageWriteAsyncHandler](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/pfplatform/functions/pfplatformlocalstoragewriteasynchandler.md)
- [PFPlatformLocalStorageClearAsyncHandler](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/pfplatform/functions/pfplatformlocalstorageclearasynchandler.md)
- [PFLocalStorageHooks](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/pfplatform/structs/pflocalstoragehooks.md)
- [服务 C API 概览 - PFPlatform.h](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/pfplatform/pfplatform_members.md)
- [XblLocalStorageReadHandler](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/platform_c/functions/xbllocalstoragereadhandler.md)