大厅接口

大厅提供用户之间持久连接，通过实时更新共享游戏和用户状态。通常情况下，用户可以创建或加入大厅，与其他用户组队、选择游戏开始前的选项，并等待其他玩家加入后一起游戏。借助 大厅接口 ，用户可以创建、加入、离开和管理大厅。

要访问大厅接口，请通过平台接口函数 EOS_Platform_GetLobbyInterface 获取 EOS_HLobby 句柄。所有大厅接口函数都需要以此句柄作为其第一个参数。 EOS_HPlatform 句柄必须tick，以便在操作完成时触发相应的回调。

EOS_Lobby_CreateLobby 函数可以创建大厅。如需更多的属性详情，请参阅EOS_Lobby_CreateLobbyOptions。对函数 EOS_Lobby_CreateLobbyOptions 进行以下初始化：

操作完成后， EOS_Lobby_OnCreateLobbyCallback 将以 EOS_Lobby_CreateLobbyCallbackInfo 数据结构运行。如果数据结构的 ResultCode 字段显示成功，则 LobbyId 字段将包含新大厅的ID值，与大厅进一步交互时需要用到此值。

要销毁大厅，大厅的所有者必须以 EOS_Lobby_DestroyLobbyOptions 结构调用 EOS_Lobby_DestroyLobby ，此结构的初始化信息如下：

完成后， EOS_Lobby_OnDestroyLobbyCallback 回调函数将以 EOS_Lobby_DestroyLobbyCallbackInfo 数据结构运行。该数据结构指示销毁是否成功。大厅关闭后，其将自动删除所有剩余成员，并触发状态为 EOS_LMS_CLOSED 的成员状态更新。

大厅的生命周期通常遵循此顺序：

• 用户创建大厅。该用户自动加入大厅并成为首位成员兼所有者。
• 所有者设置大厅的初始状态，并且可以邀请用户加入。
• 其他用户加入和离开大厅。连接后，成员可以更新自己的状态信息，并且可以邀请其他用户。
• 大厅主人可以根据游戏状态更新具体数据。
• 所有者可以将成员移出大厅，也可以将所有者身份转移给其他成员。
• 用户可以在不离开或销毁大厅的情况下进行多轮游戏。你的游戏逻辑决定了一个大厅的生命时长。
• 最后，所有者销毁大厅。

使用有效的 EOS_HLobbyDetails 句柄调用 EOS_Lobby_JoinLobby ，会使用户尝试加入该句柄引用的大厅。一个用户可以同时处于多个大厅中；用户加入一个大厅时无需离开另一个大厅。加入新的大厅不会离开现有的大厅。离开或销毁一个大厅必须是显式的。

要离开大厅，请调用 EOS_Lobby_LeaveLobby 。如果要离开的用户是当前的大厅所有者，EOS将从其余用户中选择新的所有者。若有用户离开，以及所有权发生变更，所有成员都会收到通知。

大厅中的用户可以利用 EOS_Lobby_SendInvite 函数邀请其他用户加入。成功发送邀请后，将触发类型为 EOS_Lobby_OnSendInviteCallback 的回调。邀请到达时，目标用户将收到通知。然后，游戏使用 EOS_Lobby_AddNotifyLobbyInviteAccepted 来了解玩家何时点击覆层中的 接受（Accept） 按钮。关于 邀请（Invite） 按钮、社交叠加和大厅之间的交互，请参见社交覆层接入：使用大厅。关于Epic Games启动程序的邀请功能，请确保将你的部署映射到你的构件。

要拒绝邀请，请以 EOS_Lobby_RejectInviteOptions 结构调用 EOS_Lobby_RejectInvite ，其中包含以下信息：

完成后，EOS_Lobby_OnRejectInviteCallback 函数将以 EOS_Lobby_RejectInviteCallbackInfo 数据结构在本地触发。如果成功，邀请将从系统中永久删除。

若要保证本地缓存中包含所有待处理邀请，请以 EOS_Lobby_QueryInvitesOptions 结构调用 EOS_Lobby_QueryInvites 。此结构包含以下数据：

操作完成后，你的 EOS_Lobby_OnQueryInvitesCallback 将以 EOS_Lobby_QueryInvitesCallbackInfo 数据结构运行。成功时，本地缓存将包含指定用户的所有待处理邀请，你可以搜索这类邀请。若要在启动时发现用户离线期间发送的所有邀请，此函数将十分实用。在游戏期间，凭借注册通知，用户几乎不需要调用此函数。

要检查已缓存的邀请，首先以 EOS_Lobby_GetInviteCountOptions 结构调用 EOS_Lobby_GetInviteCount ，初始化如下：

此函数针对本地缓存运行，并立即返回一个 uint32_t ，指出缓存中待处理邀请的数量。然后，可以以 EOS_Lobby_GetInviteIdByIndexOptions 结构调用 EOS_Lobby_GetInviteIdByIndex，此结构包含以下数据：

EOS_Lobby_GetInviteIdByIndex 也会针对本地缓存运行，如果调用成功，将立即返回 EOS_Success 。成功后，你提供的输出参数将包含邀请数据的副本及其大小。不再需要缓冲时，需要由你进行清理。

只要用户已通过 EOS_Lobby_AddNotifyLobbyInviteReceived 注册回调，用户就会收到实时邀请。回调数据包含邀请的所有相关信息。此时，用户可以使用 EOS_Lobby_CopyLobbyDetailsHandleByInviteId 以 EOS_HLobbyDetails 形式获取邀请，用户必须拥有它才能加入大厅。关闭应用程序或离线时，使用 EOS_Lobby_RemoveNotifyLobbyInviteReceived 从通知列表中删除回调。

大厅拥有者可以随时移除大厅成员。为此，以 EOS_Lobby_KickMemberOptions 数据结构调用 EOS_Lobby_KickMember ，初始化如下：

操作完成后，将收到 EOS_Lobby_OnKickMemberCallback 函数调用，数据结构为 EOS_Lobby_KickMemberCallbackInfo 。此外，所有剩余的大厅成员将收到 EOS_LMSC_KICKED 事件的通知。

EOS_Lobby_CreateLobbySearch 可创建句柄（类型为 EOS_HLobbySearch ），可用于搜索设为可发现的大厅（详情请参见“权限级别”）。使用下面的函数配置此句柄，然后调用 EOS_LobbySearch_Find 执行。成功完成后，应用程序可以浏览搜索结果。多项搜索操作可以使用不同的句柄同时运行。

搜索完成后，使用 EOS_LobbySearch_GetSearchResultCount 获取给定 EOS_HLobbySearch 句柄的结果数。然后可以使用 EOS_LobbySearch_CopySearchResultByIndex 来请求个体结果的副本。数据副本使用完后，使用 EOS_LobbyDetails_Release 将其处理掉，以回收使用的内存。

如果用户知道准确的大厅ID，则可以使用 EOS_LobbySearch_SetLobbyId 直接搜索。与其他用户共享大厅ID会超出API的范围。

EOS_LobbySearch_SetTargetUserId 可获取已知用户ID，并返回代表目标用户所属大厅的搜索结果。

要查找大厅，最可靠的方法是搜索所需的设置子集。这可用于响应在用户接口中选择了一组过滤器的用户，可以基于用户的技能和其他因素在场景幕后自动完成，或者结合两种方法来完成。

EOS_LobbySearch_SetParameter 允许用户设置 EOS_Lobby_AttributeData ，并提供 EOS_EComparisonOp ，指示如何将该属性与服务中存储的所有现有大厅进行比较。 一个或多个此类调用将设置搜索参数，搜索参数之间存在隐式布尔值 AND 。

要限制可获取的最大搜索结果数，请使用 EOS_LobbySearch_SetMaxResults 函数。

要了解大厅，用户可以请求 EOS_HLobbyDetails 句柄。基于本地用户与大厅的连接，有三个函数可提供此信息：

• EOS_Lobby_CopyLobbyDetailsHandle 可供当前连接到大厅的用户使用。
• EOS_Lobby_CopyLobbyDetailsHandleByInviteId 需要大厅邀请。
• EOS_LobbySearch_CopySearchResultByIndex 适用于本地用户在搜索中找到的大厅。

成功完成上述任意操作之后将收到一个 EOS_HLobbyDetails 句柄，该柄可用于访问以下信息：

• 大厅ID ：大厅的唯一辨识符
• 大厅所有者 ：大厅的当前所有者
• 大厅成员 ：大厅的当前成员
• 权限级别 ：限制谁可以找到或加入大厅；请参见下面的“权限级别”
• 可用空间 ：当前可用的闲置插槽数
• 最大成员数 ：大厅任意时间可容纳的最大用户数
• 成员数（Member Count） ：大厅中的当前成员数量
• 大厅属性 ：与大厅关联的键值对
• 大厅成员属性 ：与每个用户关联的键值对
• 大厅成员平台 ：由服务器识别的单个用户的硬件平台。请注意，该值只为主机平台的大厅成员提供，否则返回一个占位符值。该占位符值表示无法准确识别给定用户的硬件平台。

要查找大厅所有者的ID，请调用 EOS_LobbyDetails_GetLobbyOwner 。要查找大厅成员的ID，请首先调用 EOS_LobbyDetails_GetMemberCount 检索当前成员数，然后遍历当前成员计数，并调用 EOS_LobbyDetails_GetMemberByIndex 。可通过 EOS_LobbyDetails_CopyInfo 函数以 EOS_LobbyDetails_Info 数据结构形式获取有关大厅的细节。你接收的 EOS_LobbyDetails_Info 将是EOS SDK缓存信息的副本。你拥有此数据，必须使用 EOS_LobbyDetails_Info_Release 函数将其释放，以避免内存泄漏。数据是快照，如果有关大厅的信息在收到后发生更改，数据将不会更新。

注意 ：你不能将上述API调用用于大厅搜索结果。

大厅的权限级别负责控制用户发现并加入大厅的条件。所有者可以随时调用 EOS_LobbyModification_SetPermissionLevel 更改权限级别。以下设置可用：

用户可以修改大厅，成员也可以修改自身的用户数据，方法是调用 EOS_Lobby_UpdateLobbyModification 以获取大厅修改句柄（类型为 EOS_HLobbyModification ）。

所有者可以调用 EOS_Lobby_PromoteMember ，将大厅的另一位成员升级为所有者。大厅只能设一位所有者，因此调用者将在此过程中丧失所有者身份。所有成员都会收到此事件的通知。

大厅和各个用户可以拥有应用程序专属的键值属性，该属性由 EOS_Lobby_Attribute 数据类型提供支持。这些属性必须用数字、字符串或布尔数据表示。 EOS_Lobby_Attribute 数据结构包含此信息。

大厅和大厅成员属性有公共和私有可视性。在公共可视性下，数据针对大厅属性对大厅外部的所有成员可见，并且数据针对大厅成员属性在大厅内可见。反过来，对于私有可视性，数据针对大厅属性在大厅内部可见，并且数据针对大厅成员属性仅对该成员可见。

大厅中的单个用户、或大厅本身最多可以拥有 EOS_LOBBYMODIFICATION_MAX_ATTRIBUTES 项属性。属性名称（Key 中）字段不得超过 EOS_LOBBYMODIFICATION_MAX_ATTRIBUTE_LENGTH 个字符。

当前的大厅所有者可以通过以下函数更改大厅：

已连接的用户可以使用以下函数修改自己的数据：

完成全部所需属性修改后，必须将这些更改提交到大厅，修改才会生效。调用 EOS_Lobby_UpdateLobby 完成此操作。操作结束后，修改完成，其他大厅成员将收到通知。你还将收到对回调函数的调用。

用户与大厅保持持久连接，并且会收到大厅生命周期内所发生事件的通知。注册通知可以在启动时完成，每次回调都会提供足够的信息，完整描述受影响的大厅。

大厅所有者更改大厅属性时，所有大厅成员都会收到通知。通知仅简单说明已发生变更。游戏应计算大厅中的所有可用数据，然后将其重新应用于游戏。

大厅成员更改大厅属性时，所有大厅成员都会收到通知。通知仅简单说明已发生变更。游戏应计算大厅中的所有可用数据，然后将其重新应用于游戏。

当用户在大厅进行下列活动时，系统会向大厅内的所有其他用户发出通知：

你可以借助EOS大厅在Epic服务器或你自己的后台服务器上创建语音聊天室。在比赛期间，或者在应用程序的大厅中，用户可以跨多个平台进行一对一或群组沟通。详情请参见大厅语音和语音接口。

使用EOS大厅RTC房间功能的应用无需考虑手动加入或离开语音室，这会由大厅系统自动处理。 如果成功创建了大厅并启用了RTC房间，只要本地用户还在大厅里，大厅系统就会自动加入并保持与RTC房间的连接。

应用程序可以使用 EOS_Lobby_IsRTCRoomConnected、 EOS_Lobby_AddNotifyRTCRoomConnectionChanged 和 EOS_Lobby_RemoveNotifyRTCRoomConnectionChanged 来获得所需信息。例如，在多人游戏大厅中与大厅RTC服务断开连接时，显示断开图标。

如需与 EOS_RTC_* 或 EOS_RTCAudio_* 系列函数交互，应用程序必须首先使用 EOS_Lobby_GetRTCRoomName 函数来获得与大厅相关的房间名称。 EOS_Lobby_GetRTCRoomName 最早可以在 EOS_Lobby_OnJoinLobbyCallback 或 EOS_Lobby_OnCreateLobbyCallback 中调用，此时结果参数为 EOS_Success 。 此时，应用应该注册特定于该大厅RTC房间的所有RTC通知，以免错过可能的通知，例如房间的现有成员（可能在这些通知后不久发生）。

RTC房间名称的用例：

• 注册通知时，例如谈话状态或房间成员身份
• 将本地用户的房间音频输出禁言或取消禁言时
• 屏蔽或取消屏蔽房间参与者时
• 设置本地音频设备设置

以下函数可以替换常用的 EOS_RTC_* 函数，但不兼容大厅，原因是该功能会内部处理，或者应用不再提供数据，或者该功能基于 EOS_RTCAdmin_* 函数。

作为大厅所有者，你可以使用 EOS_Lobby_HardMuteMemberOptions 数据结构调用 EOS_Lobby_HardMuteMember ，强制将某个现有大厅成员禁言。这个结构包含给定成员是否应该被禁言的信息。强制禁言会改变所有人对该大厅成员的语音接受状态，不管他们的本地禁言状态如何。

操作完成后，你的 EOS_Lobby_OnHardMuteMemberCallback 会使用 EOS_Lobby_HardMuteMemberCallbackInfo 数据结构运行。如果数据结构的 ResultCode 字段显示执行成功，它的 LobbyId 字段将显示大厅的ID值， TargetUserId 将包含更新了强制禁言状态的成员。

大厅为用户提供了持久连接，旨在通过实时更新来共享游戏和用户状态。通常，用户可以创建或加入大厅，以与其他用户聊天，组队、选择游戏开始前的设置选项、一起等待其他用户加入。有关节流、用量配额和最佳实践的一般信息，请参阅服务使用限制。

以下是大厅服务的一般限制：

此外还有根据每个用户情况而定的速率限制。请阅读以下限制，以免遭到节流：