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

# PFPlatformLocalStorageClearAsyncHandler

> PlayFab 调用此存储处理程序来删除某个键下存储的数据；它会启动一个 XAsync 操作，该操作完成时没有结果负载。

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

## 语法

```cpp theme={null}
HRESULT STDAPIVCALLTYPE PFPlatformLocalStorageClearAsyncHandler(
    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) 结构的 `clear` 成员中设置它（同时设置另外两个存储处理程序），并在调用 [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 的结果大小。

默认实现会尝试删除以 `key` 命名的文件，即使删除失败（例如因为文件不存在），也会以 `S_OK` 完成。在你的处理程序中也请将缺少的键视为成功。

使用 [PFTraceEnableTraceToFile](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/pftrace/functions/pftraceenabletracetofile.md) 启用将跟踪输出到文件时，[PFInitialize](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/pfcore/functions/pfinitialize.md) 会针对跟踪文件调用此处理程序，并等待操作完成后再继续。在 PFInitialize 等待期间，运行该操作的队列的工作端口必须能够继续推进。如果你手动调度该工作端口，请从另一个线程调度它；仅调度完成端口是不够的。

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)

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


## Related topics

- [PFPlatformLocalStorageWriteAsyncHandler](https://docs.xbox.com/zh-CN/services/playfab/api-references/c/pfplatform/functions/pfplatformlocalstoragewriteasynchandler.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)
- [XblLocalStorageClearHandler](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/platform_c/functions/xbllocalstorageclearhandler.md)