> ## 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.

# PFPlatformLocalStorageWriteAsyncHandler

> PlayFab 调用此存储处理程序将数据缓冲区写入某个键下；它会启动一个 XAsync 操作，该操作完成时没有结果负载。

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

## 语法

```cpp theme={null}
HRESULT STDAPIVCALLTYPE PFPlatformLocalStorageWriteAsyncHandler(
    void* context,
    const char* key,
    size_t dataSize,
    void const* data,
    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\*

标识数据。通常为文件路径。将数据写入此键下。

**`dataSize`**   `_In_` size\_t

`data` 的大小（以字节为单位）。

**`data`**   `_In_reads_bytes_(dataSize)` void const\*

要写入的数据。

**`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) 结构的 `write` 成员中设置它（同时设置另外两个存储处理程序），并在调用 [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`，并传递写入操作的结果和大小为 0 的结果大小。

默认实现会将 `data` 追加到 `key` 的现有数据之后，而不是替换现有数据。PlayFab 依赖此行为：使用 [PFTraceEnableTraceToFile](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/pftrace/functions/pftraceenabletracetofile.md) 启用将跟踪输出到文件时，PlayFab 会先清除一次跟踪文件，然后将每条跟踪消息作为单独的写入操作写入同一个键。请在你的处理程序中也执行追加操作，否则跟踪文件只会保留最后一条消息。

`data` 在操作完成之前保持有效。如果之后仍需要它，请复制一份。

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)

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

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


## Related topics

- [PFPlatformLocalStorageClearAsyncHandler](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/pfplatform/functions/pfplatformlocalstorageclearasynchandler.md)
- [PFPlatformLocalStorageReadAsyncHandler](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/pfplatform/functions/pfplatformlocalstoragereadasynchandler.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)
- [XblLocalStorageWriteHandler](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/platform_c/functions/xbllocalstoragewritehandler.md)