> ## 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-TW/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-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\*

識別資料。通常是檔案路徑。讀取儲存在此索引鍵下的資料。

**`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) 結構的 `read` 成員中設定它 (連同其他兩個儲存體處理常式)，並在呼叫 [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`，並傳遞讀取作業的結果以及您所讀取資料的大小 (以位元組為單位)。PlayFab 接著會呼叫 `XAsyncGetResultSize` 和 `XAsyncGetResult` 來複製資料，因此您的提供者在收到 `XAsyncOp::GetResult` 時，必須將資料複製到 [XAsyncProviderData](https://docs.xbox.com/zh-TW/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-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)

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

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


## Related topics

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