虚幻引擎中的在线状态接口 | 虚幻引擎 5.5 文档

登录在线服务后，你可能想查找有关你的好友和在线结识的其他用户的信息。例如，在许多在线服务上，你都可以查看其他用户是否在线、他们当前正在玩什么游戏、他们是否可以加入比赛等信息。在线服务在线状态接口（Online Services Presence Interface） 包含所有与跨在线服务的平台特有用户状态相关的功能，包括查询和更新用户的在线状态以及侦听变化。

本文档提供了API概述和代码示例，以及从在线子系统在线状态接口转换代码的技巧。

API 概述

函数

下表概要说明了在线状态接口中包括的函数。

函数	说明
查询
`QueryPresence`	使用提供的 `TargetAccountId` 获取用户的在线状态。
`BatchQueryPresence`	获取提供的 `TargetAccountId` 列表中每个用户的在线状态。
获取
`GetCachedPresence`	使用接口内缓存的所提供 `TargetAccountId` 检索用户的在线状态。
更新
`UpdatePresence`	更新用户的在线状态。
`PartialUpdatePresence`	仅使用指定的在线状态设置更新用户的在线状态。
事件监听
`OnPresenceUpdated`	将根据用户在线状态的更新结果触发事件。

枚举类

在线状态接口定义了三个枚举类，分别表示用户的状态（EUserPresenceStatus）、可加入性（EUserPresenceJoinability）和游戏状态（EUserPresenceGameStatus）。这些枚举类表示 FUserPresence 结构体的三个主要成员。请参阅本页面的主结构体分段，了解详细信息。

EUserPresenceStatus

枚举器	说明
`Offline`	用户离线。
`Online`	用户在线。
`Away`	用户离开。
`ExtendedAway`	用户已离开至少两个小时（可能取决于平台）。
`DoNotDisturb`	用户不想被打扰。
`Unknown`	默认用户在线状态。

EUserPresenceJoinability

枚举器	说明
`Public`	任何人都可以发现并加入此会话。
`FriendsOnly`	试图加入的人必须是某个大厅成员的好友。
`InviteOnly`	试图加入的人必须先得到邀请。
`Private`	用户目前不接受邀请。
`Unknown`	默认用户可加入性在线状态。

EUserPresenceGameStatus

枚举器	说明
`PlayingThisGame`	用户正在玩与你相同的游戏。
`PlayingOtherGame`	用户正在玩与你不同的游戏。
`Unknown`	默认用户游戏在线状态。

主结构体

FUserPresence

FUserPresence结构体是在线状态接口中的主要对象，包含所有与用户在线状态有关的必要信息。

成员	类型	说明
`AccountId`	`FAccountId`	具有此在线状态的用户。
`Status`	`EUserPresenceStatus`	用户在线状态。（默认值为 `EUserPresenceStatus::Unknown` 。）
`Joinability`	`EUserPresenceJoinability`	用户会话状态。（默认值为 `EUserPresenceJoinability::Unknown` 。）
`GameStatus`	`EUserPresenceGameStatus`	用户游戏状态。（默认值为 `EUserPresenceGameStatus::Unknown` 。）
`StatusString`	`FString`	用户在线状态的字符串表示形式。
`RichPresenceString`	`FString`	当前游戏状态的游戏定义表示形式。
`Properties`	`FPresenceProperties`	会话密钥。

类型 FPresenceProperties 是 TMap<FString, FPresenceVariant> 的typedef，其中 FPresenceVariant 是一个 FString 。

示例

我们现在举例来演示 UpdatePresence、QueryPresence 和 GetPresence。UserA 使用默认平台服务更新其在线状态，然后 UserB 在 UserA 的在线状态更新后查询其在线状态。如果查询成功返回结果，则 UserB 检索 UserA 的在线状态。

代码

UserAPresence.cpp

UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
UE::Online::IPresencePtr PresenceInterface = OnlineServices->GetPresenceInterface();

TSharedRef<UE::Online::FUserPresence> Presence = MakeShared<UE::Online::FUserPresence>();
Presence->AccountId = UserA;
Presence->Status = UE::Online::EUserPresenceStatus::Online;
Presence->Joinability = UE::Online::EUserPresenceJoinability::Public;
Presence->RichPresenceString = TEXT("Exploring the Great Citadel");
Presence->Properties.Add(TEXT("advanced_class"), TEXT("advanced_class_assassin"));

UE::Online::FUpdatePresence::Params Params;
Params.LocalAccountId = AccountId;
Params.Presence = Presence;

PresenceInterface->UpdatePresence(MoveTemp(Params))
.OnComplete([](const UE::Online::TOnlineResult<UE::Online::FUpdatePresence> Result)
{
	if(Result.IsOk())
	{
		// 我们成功了 - UserB现在可以查询在线状态
	}
	else
	{
		// 我们失败了 - 检查Result.GetErrorValue();中的错误状态
	}
});

UserBPresence.cpp

UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
UE::Online::IPresencePtr PresenceInterface = OnlineServices->GetPresenceInterface();

PresenceInterface->QueryPresence({UserA})
.OnComplete([](const UE::Online::TOnlineResult<UE::Online::FQueryPresence> Result)
{
	if(Result.IsOk())
	{
		// 我们成功了 - 现在使用GetPresence实际查看在线状态对象

		UE::Online::TOnlineResult<UE::Online::FGetPresence> GetPresenceResult = PresenceInterface->GetPresence({UserB});
		if(GetPresenceResult.IsOk())
		{
			TSharedRef<const UE::Online::FUserPresence> Presence = GetPresenceResult.GetOkValue().Presence;

			// Presence->RichPresenceString现在将是"探索大城堡"
			// Presence->Properties现在将包含{advanced_class: advanced_class_assassin}
			// 等等...
		}
		else
		{
			// 我们失败了 - 通过GetPresenceResult.GetErrorValue();检查错误状态
		}

	}
	else
	{
		//我们失败了 - 检查Result.GetErrorValue();中的错误状态
	}
});

讲解

两个用户都通过不指定参数调用 GetServices 检索默认在线服务，并访问在线状态接口：

UserAPresence.cpp和UserBPresence.cpp
```
 UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
 UE::Online::IPresencePtr PresenceInterface = OnlineServices->GetPresenceInterface();
```
UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices(); UE::Online::IPresencePtr PresenceInterface = OnlineServices->GetPresenceInterface();
UserA 初始化名为 Presence 的 FUserPresence 结构体。请注意，我们使用的是上述在线状态接口提供的两个枚举： EUserPresenceStatus 和 EUserPresenceJoinability 。

UserAPresence.cpp
```
 TSharedRef<UE::Online::FUserPresence> Presence = MakeShared<UE::Online::FUserPresence>();
 Presence->AccountId = UserA;
 Presence->Status = UE::Online::EUserPresenceStatus::Online;
 Presence->Joinability = UE::Online::EUserPresenceJoinability::Public;
 Presence->RichPresenceString = TEXT("Exploring the Great Citadel");
 Presence->Properties.Add(TEXT("advanced_class"), TEXT("advanced_class_assassin"));
```
TSharedRef<UE::Online::FUserPresence> Presence = MakeShared<UE::Online::FUserPresence>(); Presence->AccountId = UserA; Presence->Status = UE::Online::EUserPresenceStatus::Online; Presence->Joinability = UE::Online::EUserPresenceJoinability::Public; Presence->RichPresenceString = TEXT("Exploring the Great Citadel"); Presence->Properties.Add(TEXT("advanced_class"), TEXT("advanced_class_assassin"));
UserA 初始化名为 Params 的 FUpdatePresence::Params 结构体，其参数将传递给 UpdatePresence ：

UserAPresence.cpp
```
 UE::Online::FUpdatePresence::Params Params;
 Params.LocalAccountId = AccountId;
 Params.Presence = Presence;
```
UE::Online::FUpdatePresence::Params Params; Params.LocalAccountId = AccountId; Params.Presence = Presence;
UserA 调用 UpdatePresence 并通过 OnComplete 回调处理结果：

UserAPresence.cpp
```
 PresenceInterface->UpdatePresence(MoveTemp(Params))
 .OnComplete([](const UE::Online::TOnlineResult<UE::Online::FUpdatePresence> Result)
 {
     if(Result.IsOk())
     {
         // 我们成功了 - UserB现在可以查询在线状态
     }
     else
     {
         // 我们失败了 - 检查Result.GetErrorValue();中的错误状态
     }
 });
```
PresenceInterface->UpdatePresence(MoveTemp(Params)) .OnComplete([](const UE::Online::TOnlineResult<UE::Online::FUpdatePresence> Result) { if(Result.IsOk()) { // 我们成功了 - UserB现在可以查询在线状态 } else { // 我们失败了 - 检查Result.GetErrorValue();中的错误状态 } });
UserB 查询 UserA 的在线状态。在查询的 OnComplete 回调内，UserB 首先检查以确保 QueryPresence 返回的是 "Ok" 状态。若是，则 UserB 可以安全地检索 UserA 的在线状态，并相应地处理 GetPresence 的结果或错误：

UserBPresence.cpp
```
 PresenceInterface->QueryPresence({UserA})
 .OnComplete([](const UE::Online::TOnlineResult<UE::Online::FQueryPresence> Result)
 {
     if(Result.IsOk())
     {
         // 我们成功了 - 现在使用GetPresence实际查看在线状态对象

         UE::Online::TOnlineResult<UE::Online::FGetPresence> GetPresenceResult = PresenceInterface->GetPresence({UserB});
         if(GetPresenceResult.IsOk())
         {
             // 我们成功了！
         }
         else
         {
             // 我们失败了 - 通过GetPresenceResult.GetErrorValue();检查错误状态
         }

     }
     else
     {
         // 我们失败了 - 检查Result.GetErrorValue();中的错误状态
     }
 });
```
PresenceInterface->QueryPresence({UserA}) .OnComplete([](const UE::Online::TOnlineResult<UE::Online::FQueryPresence> Result) { if(Result.IsOk()) { // 我们成功了 - 现在使用GetPresence实际查看在线状态对象 UE::Online::TOnlineResult<UE::Online::FGetPresence> GetPresenceResult = PresenceInterface->GetPresence({UserB}); if(GetPresenceResult.IsOk()) { // 我们成功了！ } else { // 我们失败了 - 通过GetPresenceResult.GetErrorValue();检查错误状态 } } else { // 我们失败了 - 检查Result.GetErrorValue();中的错误状态 } });

如果所有函数调用的返回结果均未出错，则 UserB 现在会看到 UserA 更新后的状态，并且 UserB 可以选择根据该状态做出决定。例如，UserB 可以通过访问 GetPresenceResult 看到 UserA 处于在线状态，并且其可加入性状态为公开。设置此状态后，UserB 可以决定加入 UserA，与其一起 "探索大城堡"。

从在线子系统转换代码

在线服务插件是在线子系统插件的更新版本，在可预见的未来将彼此共存。在线服务在线状态接口的API功能与在线子系统在线状态接口的API功能大致一对一对应。一些注意事项包括：

SetPresence 已重命名为 UpdatePresence，更充分地体现了函数的异步性。
UpdatePresence 和 QueryPresence 不再重载。
我们建议改用它们的重命名函数 PartialUpdatePresence 和 BatchQueryPresence 。
- UpdatePresence 和 QueryPresence 的重载已分别重命名为 PartialUpdatePresence 和 BatchQueryPresence 。
为 QueryPresence 指定了 bListenToChanges 参数。
- 这会将特定用户添加到 OnPresenceUpdated 事件。
- 默认情况下，该参数设置为true。

在线服务在线状态接口