> ## 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/ja-jp/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/ja-jp/services/playfab/api-references/c/pfplatform/functions/pfplatformlocalstoragesethandlers.md) に渡した [PFLocalStorageHooks](https://docs.xbox.com/ja-jp/services/playfab/api-references/c/pfplatform/structs/pflocalstoragehooks.md) 構造体の `context` メンバー。`nullptr` にすることができます。PlayFab はこのポインターを所有しません。

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

データを識別します。通常はファイル パスです。このキーの下に格納されたデータを読み取ります。

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

読み取り操作の `XAsyncBlock`。

### 戻り値

型: HRESULT

`async` で非同期操作を開始した場合 (たとえば [XAsyncBegin](https://docs.xbox.com/ja-jp/reference/system/xasyncprovider/functions/xasyncbegin.md) を使用して) は、`S_OK` を返します。ハンドラーがエラーの HRESULT を返すと、PlayFab はその HRESULT でストレージ操作を失敗させ、`async` の完了を待機しません。そのため、エラーを返すのは `async` で操作を開始していない場合だけにしてください。ストレージ操作自体の結果は、[XAsyncComplete](https://docs.xbox.com/ja-jp/reference/system/xasyncprovider/functions/xasynccomplete.md) で `async` を完了することで報告します。

## 解説

このハンドラーをインストールするには、他の 2 つのストレージ ハンドラーと共に [PFLocalStorageHooks](https://docs.xbox.com/ja-jp/services/playfab/api-references/c/pfplatform/structs/pflocalstoragehooks.md) 構造体の `read` メンバーに設定し、[PFInitialize](https://docs.xbox.com/ja-jp/services/playfab/api-references/c/pfcore/functions/pfinitialize.md) を呼び出す前に、その構造体を [PFPlatformLocalStorageSetHandlers](https://docs.xbox.com/ja-jp/services/playfab/api-references/c/pfplatform/functions/pfplatformlocalstoragesethandlers.md) に渡します。3 つのハンドラーのいずれかが `nullptr` の場合、PFPlatformLocalStorageSetHandlers は `E_INVALIDARG` を返します。カスタム ハンドラーを設定しない場合、PlayFab は cstdio および `std::fstream` オブジェクトに基づく既定の実装を使用します。

読み取りの結果と、読み取ったデータのサイズ (バイト単位) を渡して、[XAsyncComplete](https://docs.xbox.com/ja-jp/reference/system/xasyncprovider/functions/xasynccomplete.md) で `async` を完了します。その後、PlayFab はデータをコピーするために `XAsyncGetResultSize` と `XAsyncGetResult` を呼び出します。そのため、プロバイダーは `XAsyncOp::GetResult` を受け取ったときに、[XAsyncProviderData](https://docs.xbox.com/ja-jp/reference/system/xasyncprovider/structs/xasyncproviderdata.md) の `buffer` メンバーにデータをコピーする必要があります。

`key` の下にデータが格納されていない場合、既定の実装は `S_OK` と結果サイズ 0 で操作を完了します。ハンドラーでも同じようにしてください。

PlayFab は、ストレージ操作を開始したスレッド上でこのハンドラーをインラインで呼び出す場合があるため、どのスレッドで実行されるかに依存しないでください。`async` のキューは、PlayFab が PFLocalStorageHooks の `queueHandle` メンバーから派生させたキューです。`queueHandle` が `nullptr` の場合、PlayFab は PFInitialize に渡したバックグラウンド キューから、またはそのキューも `nullptr` だった場合はプロセス タスク キューから、キューを派生させます。派生したキューのワーク コールバックと完了コールバックは、どちらも派生元のキューのワーク ポートで実行されます。

PlayFab はストレージ操作を一度に 1 つずつ実行し、現在の操作が完了した後でのみ次の操作を開始します。

PlayFab は、`async` で `XAsyncCancel` を呼び出すことで、保留中の操作をキャンセルできます。ストレージ操作をキャンセルできる場合は、プロバイダーで `XAsyncOp::Cancel` を処理してください。

`key` 引数と `async` 引数は PlayFab が所有し、操作が完了するまで有効です。`context` 引数はこの保証の対象外です。

## 要件

**ヘッダー:** PFPlatform.h

**ライブラリ:** PlayFabCore.lib

**サポートされているプラットフォーム:** Windows、XBOX One ファミリー本体および XBOX Series 本体

## 関連項目

[PFPlatform のメンバー](https://docs.xbox.com/ja-jp/services/playfab/api-references/c/pfplatform/pfplatform_members.md)

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

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

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

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

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


## Related topics

- [PFPlatformLocalStorageWriteAsyncHandler](https://docs.xbox.com/ja-jp/services/playfab/api-references/c/pfplatform/functions/pfplatformlocalstoragewriteasynchandler.md)
- [PFPlatformLocalStorageClearAsyncHandler](https://docs.xbox.com/ja-jp/services/playfab/api-references/c/pfplatform/functions/pfplatformlocalstorageclearasynchandler.md)
- [PFLocalStorageHooks](https://docs.xbox.com/ja-jp/services/playfab/api-references/c/pfplatform/structs/pflocalstoragehooks.md)
- [サービス C API の概要 - PFPlatform.h](https://docs.xbox.com/ja-jp/services/playfab/api-references/c/pfplatform/pfplatform_members.md)
- [XblLocalStorageReadHandler](https://docs.xbox.com/ja-jp/reference/live/xsapi-c/platform_c/functions/xbllocalstoragereadhandler.md)