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

쓰기 작업에 대한 `XAsyncBlock`입니다.

### 반환 값

형식: HRESULT

`async`에서 비동기 작업을 시작한 경우(예: [XAsyncBegin](https://docs.xbox.com/ko/reference/system/xasyncprovider/functions/xasyncbegin.md) 사용) `S_OK`를 반환하세요. 처리기가 실패 HRESULT를 반환하면 PlayFab은 해당 HRESULT로 스토리지 작업을 실패 처리하고 `async`가 완료될 때까지 기다리지 않으므로, `async`에서 작업을 시작하지 않은 경우에만 실패를 반환하세요. 스토리지 작업 자체의 결과는 [XAsyncComplete](https://docs.xbox.com/ko/reference/system/xasyncprovider/functions/xasynccomplete.md)로 `async`를 완료하여 보고하세요.

## 설명

이 처리기를 설치하려면 다른 두 스토리지 처리기와 함께 [PFLocalStorageHooks](https://docs.xbox.com/ko/services/playfab/api-references/c/pfplatform/structs/pflocalstoragehooks.md) 구조체의 `write` 멤버에 설정하고 [PFInitialize](https://docs.xbox.com/ko/services/playfab/api-references/c/pfcore/functions/pfinitialize.md)를 호출하기 전에 해당 구조체를 [PFPlatformLocalStorageSetHandlers](https://docs.xbox.com/ko/services/playfab/api-references/c/pfplatform/functions/pfplatformlocalstoragesethandlers.md)에 전달하세요. 세 처리기 중 하나라도 `nullptr`이면 PFPlatformLocalStorageSetHandlers는 `E_INVALIDARG`를 반환합니다. 사용자 지정 처리기를 설정하지 않으면 PlayFab은 cstdio 및 `std::fstream` 개체를 기반으로 하는 기본 구현을 사용합니다.

[XAsyncComplete](https://docs.xbox.com/ko/reference/system/xasyncprovider/functions/xasynccomplete.md)로 `async`를 완료하고, 쓰기 결과와 결과 크기 0을 전달하세요.

기본 구현은 `key`의 기존 데이터를 대체하지 않고 `data`를 기존 데이터에 추가합니다. PlayFab은 이 동작에 의존합니다. [PFTraceEnableTraceToFile](https://docs.xbox.com/ko/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/ko/services/playfab/api-references/c/pfplatform/pfplatform_members.md)

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

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

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

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

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


## Related topics

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