Skip to main content

​
XSystemHandleTrack

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

​
Syntax

​
Parameters

callback    _In_
类型：XSystemHandleCallback 将在句柄创建和销毁时调用的用户定义回调。若要禁用句柄跟踪，请为回调传入 NULL。 context    _In_opt_
类型：void * 要传递给回调的用户定义上下文。

​
Return value

类型：HRESULT 成功时返回 S_OK；否则，返回错误代码。有关错误代码列表，请参阅错误代码。

​
Remarks

游戏开发者需要具备排查涉及不正确的句柄使用的错误的能力。大多数 GRTS API 使用与平台实现中内部对象生存期相对应的句柄。游戏经常遇到由开发者意外将无效句柄（NULL、先前已释放等）传递到这些 API 而导致的问题，从而导致主机游戏崩溃。开发者也可能会无意间泄漏句柄，导致过多的资源使用。句柄跟踪 API 的目标是让开发者能够诊断并修复这些问题。 该 API 有两个组件：主动和被动。GRTS 创建的所有句柄在调试和零售场景中都会被持续跟踪。每当句柄被传入我们的 API 时，平台都会执行验证以确保这些句柄对应于有效的内部对象。如果检测到无效句柄，平台会记录错误并调用 XErrorReport 通知开发者存在该问题。平台不会做任何额外的工作来抑制无效句柄的使用，并允许应用程序像在此功能之前那样崩溃。最后，在 XGameRuntimeUninitialize 时的任何句柄泄漏也将通过 XErrorReport 报告。目前，句柄跟踪系统不支持跟踪 GRTS 外部的句柄。

​
Requirements

头文件： XSystem.h 库： xgameruntime.lib 受支持的平台： Windows、XBOX One 系列主机和 XBOX Series 主机

​
See also

XSystem 成员 XSystemHandleCallback
最后修改于 2026年8月24日

相关主题

XSystemHandleCallbackXSystemPHEAP_TRACK_FREE_ROUTINE callbackPHEAP_TRACK_ALLOC_ROUTINE callbackPHEAP_TRACK_REALLOC_ROUTINE callback