> ## 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-TW/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-TW/services/playfab/api-references/c/pfplatform/functions/pfplatformlocalstoragesethandlers.md) 之 [PFLocalStorageHooks](https://docs.xbox.com/zh-TW/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-TW/reference/system/xasync/structs/xasyncblock.md)\*

寫入作業的 `XAsyncBlock`。

### 傳回值

類型：HRESULT

如果您已在 `async` 上啟動非同步作業 (例如使用 [XAsyncBegin](https://docs.xbox.com/zh-TW/reference/system/xasyncprovider/functions/xasyncbegin.md))，請傳回 `S_OK`。如果處理常式傳回失敗 HRESULT，PlayFab 會以該 HRESULT 讓儲存體作業失敗，且不會等待 `async` 完成，因此只有在您尚未於 `async` 上啟動作業時，才傳回失敗。請使用 [XAsyncComplete](https://docs.xbox.com/zh-TW/reference/system/xasyncprovider/functions/xasynccomplete.md) 完成 `async`，以回報儲存體作業本身的結果。

## 備註

若要安裝此處理常式，請在 [PFLocalStorageHooks](https://docs.xbox.com/zh-TW/services/playfab/api-references/c/pfplatform/structs/pflocalstoragehooks.md) 結構的 `write` 成員中設定它 (連同其他兩個儲存體處理常式)，並在呼叫 [PFInitialize](https://docs.xbox.com/zh-TW/services/playfab/api-references/c/pfcore/functions/pfinitialize.md) 之前，將該結構傳遞給 [PFPlatformLocalStorageSetHandlers](https://docs.xbox.com/zh-TW/services/playfab/api-references/c/pfplatform/functions/pfplatformlocalstoragesethandlers.md)。如果這三個處理常式中有任何一個為 `nullptr`，PFPlatformLocalStorageSetHandlers 會傳回 `E_INVALIDARG`。如果您未設定自訂處理常式，PlayFab 會使用以 cstdio 和 `std::fstream` 物件為基礎的預設實作。

使用 [XAsyncComplete](https://docs.xbox.com/zh-TW/reference/system/xasyncprovider/functions/xasynccomplete.md) 完成 `async`，並傳遞寫入作業的結果以及結果大小 0。

預設實作會將 `data` 附加至 `key` 的現有資料，而不會取代它。PlayFab 依賴此行為：使用 [PFTraceEnableTraceToFile](https://docs.xbox.com/zh-TW/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-TW/services/playfab/api-references/c/pfplatform/pfplatform_members.md)

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

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

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

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

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


## Related topics

- [PFPlatformLocalStorageClearAsyncHandler](https://docs.xbox.com/zh-TW/services/playfab/api-references/c/pfplatform/functions/pfplatformlocalstorageclearasynchandler.md)
- [PFPlatformLocalStorageReadAsyncHandler](https://docs.xbox.com/zh-TW/services/playfab/api-references/c/pfplatform/functions/pfplatformlocalstoragereadasynchandler.md)
- [PFLocalStorageHooks](https://docs.xbox.com/zh-TW/services/playfab/api-references/c/pfplatform/structs/pflocalstoragehooks.md)
- [Services C API overview - PFPlatform.h](https://docs.xbox.com/zh-TW/services/playfab/api-references/c/pfplatform/pfplatform_members.md)
- [XblLocalStorageWriteHandler](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/platform_c/functions/xbllocalstoragewritehandler.md)