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

# XGameEventWrite

> XGameEventWrite

# XGameEventWrite

写入一个游戏内事件，该事件可选择性地包含“维度”和“度量”数据字段。

## Syntax

```cpp theme={null}
HRESULT XGameEventWrite(  
         XUserHandle user,  
         const char *serviceConfigId,  
         const char *playSessionId,  
         const char* eventName,  
         const char* dimensionsJson,  
         const char* measurementsJson  
)  
```

### Parameters

*user*   \_In\_\
类型：XUserHandle

代表其发送事件的用户句柄。

\**serviceConfigId*   \_In\_z\_\
类型：char

此标题的 XBOX Live 服务配置 ID (SCID)。

\**playSessionId*   \_In\_z\_\
类型：char

玩耍会话 ID。这是游戏在每个游戏会话开始时创建的唯一 GUID，用于跟踪在单个玩耍会话中发送的事件集。

*eventName*   \_In\_z\_\
类型：char\*

事件名称。

*dimensionsJson*   \_In\_opt\_z\_\
类型：char\*

JSON 格式的维度数据字段。

*measurementsJson*   \_In\_opt\_z\_\
类型：char\*

JSON 格式的度量数据字段。

### Return value

类型：HRESULT

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

## Remarks

<Note>此函数在时间敏感型线程上调用是不安全的。有关详细信息，请参阅[时间敏感型线程](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)。</Note>

维度包括具有有限数量的已定义数值或字符串值的事件字段。维度示例：地图 ID、难度级别、角色或武器类别、游戏模式、布尔设置等。度量包括表示标量数值指标的事件字段。度量示例：得分、时间、计数器、位置等。示例：对于跟踪某个难度级别的最高对战得分的游戏内事件：难度级别应包括在维度中，而得分应包括在度量中。事件名称以及维度和度量中的事件字段名称必须与在标题的服务配置中声明的名称匹配。名称不区分大小写。如果 API 写入的事件名称与服务配置中的名称不匹配，服务会在不发出通知的情况下丢弃该事件。

<Note>度量只能具有数值，而维度可以具有更多类型的值。如果需要，可以完全使用 *dimensionsJson* 字段来写入事件。</Note>

## Requirements

**头文件：** XGameEvent.h

**库：** xgameruntime.lib

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

## Conceptual documentation

* [时间敏感型线程](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## See also

[XGameEvent](/reference/system/xgameevent/xgameevent_members)


## Related topics

- [XGameEvent](/zh-CN/reference/system/xgameevent/xgameevent_members.md)
- [XblEventsWriteInGameEvent](/zh-CN/reference/live/xsapi-c/events_c/functions/xbleventswriteingameevent.md)
- [PFEventsWriteEventsRequest](/zh-CN/services/playfab/api-references/c/pfeventstypes/structs/pfeventswriteeventsrequest.md)
- [PFEventsWriteEventsResponse](/zh-CN/services/playfab/api-references/c/pfeventstypes/structs/pfeventswriteeventsresponse.md)
- [PFEventsWriteEventsAsync](/zh-CN/services/playfab/api-references/c/pfevents/functions/pfeventswriteeventsasync.md)