会话接口

在线服务会话接口（Online Services Session Interface） 处理在线游戏会话的创建、销毁和管理。会话 表示游戏中的在线比赛，在玩家的计算机或专用服务器上运行。会话可以有以下加入策略：

• 仅限邀请（Invite Only） ：受到邀请的玩家可以加入会话。
• 仅限好友（Friends Only） ：会话成员的好友可以加入会话。
• 公共（Public） ：任何人都可以查找并加入会话。

你可以使用充当筛选器的一组属性来定义公共会话，允许玩家搜索特定游戏模式或地图。

API概述

下表概要说明了会话接口中包含的函数。

流程

会话生命周期

• 使用所需的设置创建新会话。
• 在会话生命周期的任意时刻，你都可以更新会话，反映它表示的在线比赛的属性更改。这些更改可以包括：
  • 就会话在搜索中的显示方式或它是否显示，改变相应的参数。
  • 游戏开始进行后，禁止新玩家加入会话。
• 发现该会话的玩家可以加入。
• 使用加入会话所获取的信息，新玩家可以连接到会话主机或专用服务器。
  • 连接之后，玩家需要向会话注册。此过程将由未来版本的引擎自动处理。
• 玩游戏。
• 游戏结束后，玩家可以离开会话或销毁会话（如果玩家是所有者或主机）。
• 从主机或服务器断开连接之后，需要从会话注销玩家。此过程将由未来版本的引擎自动处理。

创建

会话生命周期中的第一步是使用所需参数创建会话。这些参数包括在整个会话生命周期保持不变的一些参数（例如 CreateSession 函数中的 bIsLANSession 和 bAllowSanctionedPlayers ）以及你可以随时更新的一些参数（例如函数 SessionSettings 提供的选项）。

每个用户最多可以将一个会话设置为 在线状态会话（Presence Session） 。这意味着，它将显示在用户的在线状态信息中，并按照在线状态接口所公开的那样显示给好友和粉丝。如果用户是许多会话的成员，可以通过 SetPresenceSession 更改哪个会话显示为在线状态会话（此功能可能并非在所有平台实现中都可用）。

发现

用户可以通过几种不同的方式发现新会话：

搜索

利用 FindSessions ，用户可以定义搜索参数，例如匹配所需会话的自定义设置的标签，或特定用户ID，以查找其好友所在的会话。这会返回会话ID列表，每个ID表示缓存的会话信息，用户可以使用 GetSessionById 搜索和访问这些信息。

邀请

用户可以接收其他用户发送的会话邀请。收到邀请后，用户可以使用 GetSessionInviteById 访问邀请，查看有关会话的信息。此后，用户可决定是否使用邀请信息提供的会话ID加入会话。

在线状态

特定平台UI可能会向用户显示有关其好友已加入的会话的信息。

加入

用户通过搜索、邀请或在线状态获取有关会话的信息后，就可以调用 JoinSession ，尝试加入会话。他们还可以选择是否要使用 SetPresenceSession 将此新会话设置为其在线状态会话。

匹配

你也可以调用 StartMatchmaking 来加入会话。此函数相当于组合使用 CreateSession 和 FindSessions 。StartMatchmaking 会查找匹配预定义的一组搜索筛选器的会话，如果找不到，将使用给定信息创建会话。

加入会话后，你可以调用 IOnlineServices::GetResolvedConnectString ，这将返回加入比赛所需的特定于平台的连接信息。然后从此函数获取的字符串可以传递给 APlayerController::ClientTravel 或 UWorld::ServerTravel ，将玩家发送到比赛中。如果行程成功，玩家将添加到会话，并会调用 AddSessionMember ，向会话注册玩家。

邀请

加入会话（无论是通过创建会话还是直接加入会话）后，你可以使用 SendSessionInvite 将会话信息发送给其他玩家。这很适合用于让好友一起参加同一场在线比赛。玩家收到邀请后，可以访问其信息，即使用 GetAllSessionInvites 访问给定用户的所有邀请，或使用 GetSessionInviteById 获取有关特定邀请的信息。他们还可以调用 RejectSessionInvite 并传递对应邀请ID作为参数，从而拒绝会话邀请。

更新

你可以在会话生命周期的任意时刻调用 UpdateSessionSettings 来更新会话设置。这些设置包括但不限于：

• 会话中的最大玩家数量
• 会话的加入策略：
  • 仅限邀请
  • 仅限好友
  • 公共
• 仅限新玩家访问
• 添加、修改或删除自定义设置和用户定义的参数

离开并销毁

你可以调用 LeaveSession 来离开会话。会话所有者可以将额外的参数 bDestroySession 设置为 true ，在离开时从后端服务删除会话。这还会强制会话的所有其他成员离开。

示例

你可以通过OnlineServices实例的引用来访问会话接口。会话接口的功能将从此处公开。我们提供了访问会话接口以及执行同步和异步操作的几个示例。

按名称获取会话

	UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
	UE::Online::ISessionsPtr SessionsInterface = OnlineServices->GetSessionsInterface();
	UE::Online::FGetSessionByName::Params Params;
	Params.SessionName = FName(TEXT("MySession"));

	UE::Online::TOnlineResult<UE::Online::FGetSessionByName> Result = SessionsInterface->GetSessionByName(MoveTemp(Params));
	if(Result.IsOk())
	{
		TSharedRef<const UE::Online::ISession> Session = Result.GetOkValue().Session;
		// 现在我们可以从会话读取信息
	}

Copy full snippet

UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices(); UE::Online::ISessionsPtr SessionsInterface = OnlineServices->GetSessionsInterface(); UE::Online::FGetSessionByName::Params Params; Params.SessionName = FName(TEXT("MySession")); UE::Online::TOnlineResult<UE::Online::FGetSessionByName> Result = SessionsInterface->GetSessionByName(MoveTemp(Params)); if(Result.IsOk()) { TSharedRef<const UE::Online::ISession> Session = Result.GetOkValue().Session; // 现在我们可以从会话读取信息 }

操作说明

1. 调用 GetServices 而不指定参数，以使用默认在线服务：

   UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();

2. 访问默认在线服务的会话接口：

   UE::Online::ISessionsPtr SessionsInterface = OnlineServices->GetSessionsInterface();

3. 使用必要的参数调用 GetSessionByName ，初始化 FGetSessionByName 结构体：

   UE::Online::FGetSessionByName::Params Params; Params.SessionName = FName(TEXT("MySession"));

4. 调用 GetSessionByName ，传入上一步的参数，并保存结果：

            UE::Online::TOnlineResult<UE::Online::FGetSessionByName> Result = SessionsInterface->GetSessionByName(MoveTemp(Params));
   		
   Copy full snippet

   UE::Online::TOnlineResult<UE::Online::FGetSessionByName> Result = SessionsInterface->GetSessionByName(MoveTemp(Params));

5. 确保函数调用不会抛出错误并且结果可以访问之后，处理调用 GetSessionByName 的结果：

            if(Result.IsOk())
            {
                TSharedRef<const UE::Online::ISession> Session = Result.GetOkValue().Session;
                // 现在我们可以从会话读取信息
            }
   		
   Copy full snippet

   if(Result.IsOk()) { TSharedRef<const UE::Online::ISession> Session = Result.GetOkValue().Session; // 现在我们可以从会话读取信息 }

更新会话设置

	UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
	UE::Online::ISessionsPtr SessionsInterface = OnlineServices->GetSessionsInterface();

	UE::Online::FUpdateSessionSettings::Params Params;
	Params.LocalAccountId = AccountId;
	Params.SessionName = FName(TEXT("MySession"));
	Params.Mutations.bAllowNewMembers = false;

	SessionsInterface->UpdateSessionSettings(MoveTemp(Params))
	.OnComplete([this](const UE::Online::TOnlineResult<UE::Online::FUpdateSessionSettings>& Result)
	{
		if(Result.IsError())
		{
			const UE::Online::FOnlineError OnlineError = Result.GetErrorValue();
			// 更新不成功，处理OnlineError
			return;
		}
		// 更新成功
	});

Copy full snippet

UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices(); UE::Online::ISessionsPtr SessionsInterface = OnlineServices->GetSessionsInterface(); UE::Online::FUpdateSessionSettings::Params Params; Params.LocalAccountId = AccountId; Params.SessionName = FName(TEXT("MySession")); Params.Mutations.bAllowNewMembers = false; SessionsInterface->UpdateSessionSettings(MoveTemp(Params)) .OnComplete([this](const UE::Online::TOnlineResult<UE::Online::FUpdateSessionSettings>& Result) { if(Result.IsError()) { const UE::Online::FOnlineError OnlineError = Result.GetErrorValue(); // 更新不成功，处理OnlineError return; } // 更新成功 });

操作说明

1. 调用 GetServices 而不指定参数，以使用默认在线服务，并访问默认在线服务的会话接口：

            UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
            UE::Online::ISessionsPtr SessionsInterface = OnlineServices->GetSessionsInterface();
   		
   Copy full snippet

   UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices(); UE::Online::ISessionsPtr SessionsInterface = OnlineServices->GetSessionsInterface();

2. 使用必要的参数调用 UpdateSessionSettings ，初始化结构体：

            UE::Online::FUpdateSessionSettings::Params Params;
            Params.LocalAccountId = AccountId;
            Params.SessionName = FName(TEXT("MySession"));
            Params.Mutations.bAllowNewMembers = false;
   		
   Copy full snippet

   UE::Online::FUpdateSessionSettings::Params Params; Params.LocalAccountId = AccountId; Params.SessionName = FName(TEXT("MySession")); Params.Mutations.bAllowNewMembers = false;

3. 处理 UpdateSessionSettings.OnComplete 回调，在它生成错误时处理错误或查询的统计数据，或在它使用lambda函数返回正常时处理结果：

            SessionsInterface->UpdateSessionSettings(MoveTemp(Params))
            .OnComplete([this](const UE::Online::TOnlineResult<UE::Online::FUpdateSessionSettings>& Result)
            {
                if(Result.IsError())
                {
                    const UE::Online::FOnlineError OnlineError = Result.GetErrorValue();
                    // 更新不成功，处理OnlineError
                    return;
                }
                // 更新成功
            });
   		
   Copy full snippet

   SessionsInterface->UpdateSessionSettings(MoveTemp(Params)) .OnComplete([this](const UE::Online::TOnlineResult<UE::Online::FUpdateSessionSettings>& Result) { if(Result.IsError()) { const UE::Online::FOnlineError OnlineError = Result.GetErrorValue(); // 更新不成功，处理OnlineError return; } // 更新成功 });

从在线子系统转换代码

在线服务会话接口负责在线子系统会话接口拥有的所有代码。

更多信息

头文件

直接查阅 Sessions.h 头文件，根据需要了解更多信息。会话接口头文件 Sessions.h 位于以下目录中：

	UNREAL_ENGINE_ROOT\Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online

Copy full snippet

UNREAL_ENGINE_ROOT\Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online

如需有关如何获取UE源代码的说明，请参阅关于下载虚幻引擎源代码的文档。

函数参数和返回类型

请参阅在线服务概述页面的函数小节，了解函数参数和返回类型的说明，包括如何传递参数和处理函数返回时的结果。