> ## 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

注册回调以跟踪 Gaming Runtime 中的句柄生存期事件。

## Syntax

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

### Parameters

*callback*    \_In\_\
类型：[XSystemHandleCallback](/reference/system/xsystem/functions/xsystemhandlecallback)

将在句柄创建和销毁时调用的用户定义回调。若要禁用句柄跟踪，请为回调传入 NULL。

*context*    \_In\_opt\_\
类型：void \*

要传递给回调的用户定义上下文。

### Return value

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

成功时返回 **S\_OK**；否则，返回错误代码。有关错误代码列表，请参阅[错误代码](/reference/errorcodes)。

## Remarks

游戏开发者需要具备排查涉及不正确的句柄使用的错误的能力。大多数 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 外部的句柄。

## Requirements

**头文件：** XSystem.h

**库：** xgameruntime.lib

**受支持的平台：** Windows、XBOX One 系列主机和 XBOX Series 主机

## See also

[XSystem 成员](/reference/system/xsystem/xsystem_members)

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


## Related topics

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