> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XSystemHandleTrack

> XSystemHandleTrack

# XSystemHandleTrack

게이밍 런타임에서 핸들 수명 이벤트를 추적할 콜백을 등록합니다.

## 구문

```cpp theme={null}
HRESULT XSystemHandleTrack(
  XSystemHandleCallback callback,
  void * context
)
```

### 매개 변수

*callback*    \_In\_\
형식: [XSystemHandleCallback](/reference/system/xsystem/functions/xsystemhandlecallback)

핸들 생성 및 삭제 시 호출될 사용자 정의 콜백입니다. 핸들 추적을 사용하지 않도록 설정하려면
콜백에 NULL을 전달합니다.

*context*    \_In\_opt\_\
형식: void \*

콜백에 전달할 사용자 정의 컨텍스트입니다.

### 반환 값

형식:  [HRESULT](https://learn.microsoft.com/openspecs/windows_protocols/ms-erref/0642cb2f-2075-4469-918c-4441e69c548a)

성공하면 **S\_OK**를 반환하고, 그렇지 않으면 오류 코드를 반환합니다. 오류 코드 목록은
[오류 코드](/reference/errorcodes)를 참조하세요.

## 설명

게임 개발자는 잘못된 핸들 사용과 관련된 버그를 문제 해결할 수 있어야 합니다.
대부분의 GRTS API는 플랫폼 구현의 내부 개체 수명에 해당하는 핸들을 활용합니다.
게임은 개발자가 실수로 유효하지 않은(NULL, 이미 해제된 등) 핸들을 이러한 API에 제공하여
타이틀 크래시로 이어지는 문제를 자주 겪습니다. 개발자는 또한 실수로 핸들이 누수되어
과도한 리소스 사용으로 이어질 수 있습니다. 핸들 추적 API의 목표는 개발자가
이러한 문제를 진단하고 수정할 수 있도록 지원하는 것입니다.

이 API에는 능동 및 수동의 두 가지 구성 요소가 있습니다. GRTS에서 만든 모든 핸들은
디버그 및 소매 시나리오 모두에서 지속적으로 추적됩니다. 핸들이 API에 전달될 때마다
플랫폼은 이러한 핸들이 유효한 내부 개체에 해당하는지 확인하기 위한 유효성 검사를 수행합니다.
잘못된 핸들이 감지되면 플랫폼이 오류를 기록하고
[XErrorReport](/reference/system/xerror/functions/xerrorsetoptions)를 호출하여 개발자에게 문제를 알립니다. 플랫폼은
잘못된 핸들 사용을 억제하기 위한 추가 노력을 하지 않으며 이 기능이 도입되기 전과 마찬가지로
애플리케이션이 크래시되도록 허용합니다. 마지막으로
[XGameRuntimeUninitialize](/reference/system/xgameruntimeinit/functions/xgameruntimeuninitialize) 시점의 모든 핸들 누수도
[XErrorReport](/reference/system/xerror/functions/xerrorsetoptions)를 통해 보고됩니다. 현재 핸들 추적 시스템은 GRTS 외부의
핸들에 대한 추적을 지원하지 않습니다.

## 요구 사항

**헤더:** XSystem.h

**라이브러리:** xgameruntime.lib

**지원 플랫폼:** Windows, XBOX One 제품군 콘솔 및 XBOX Series 콘솔

## 함께 보기

[XSystem 멤버](/reference/system/xsystem/xsystem_members)

[XSystemHandleCallback](/reference/system/xsystem/functions/xsystemhandlecallback)


## Related topics

- [XSystemHandleCallback](/ko/reference/system/xsystem/functions/xsystemhandlecallback.md)
- [XSystem](/ko/reference/system/xsystem/xsystem_members.md)
- [PHEAP_TRACK_FREE_ROUTINE callback](/ko/reference/system/xmem/functions/pheap_track_free_routine.md)
- [PHEAP_TRACK_ALLOC_ROUTINE callback](/ko/reference/system/xmem/functions/pheap_track_alloc_routine.md)
- [PHEAP_TRACK_REALLOC_ROUTINE callback](/ko/reference/system/xmem/functions/pheap_track_realloc_routine.md)