好友列表API SmartFoxServer 2X

好友列表API

SmartFoxServer 2X提供了一套新的客户端和服务器API，专门用于管理好友和好友列表，包括持久性，自定义状态，在Buddy系统中上线/离线的能力，运行时和持久性Buddy变量，服务器端事件等。新的Buddy API（3.0版）松散地基于以前的SFS 1.x Buddy List框架，尽管我们现在提供了一种更简化的方法，更好的灵活性和更高级的功能。

如果您熟悉以前的系统，您将注意到以下差异：

基于文件的持久性：我们已经放弃了旧的数据库持久性模型，有利于更简单，更快速的基于文件的系统。持久化模型通常要简单得多，开发人员可以提供自己的定制存储类并使用自己喜欢的数据源。
相互添加/删除：此功能已从系统中删除。我们注意到，它为用户造成混乱，一般来说，它不能满足我们遇到的许多不同的要求。我们选择了一种更加简化的方法，为开发人员提供了实现自己的相互添加/删除功能的所有必要工具，而不会强制他们进入僵化的预制解决方案。由于拥有更丰富的服务器端Buddy事件，开发人员将能够在任何方向扩展Buddy List系统。

特别地，我们强烈建议您检查Game API子集提供的新的API。

“ 新功能

以下是在框架中添加的新功能和改进的快速概述：

在线状态：使用SFS 1.x，Buddy将每次登录该区域时都会上线，并且在任何时候都会退出登录时，将会脱机。使用SFS2X，在线状态完全由开发者控制。任何用户都可以在Buddy系统中进行联机和脱机，同时仍然在登录区域。此外，在线状态是持续的，所以下一次用户将再次登录时，他将处于与上一届会议期间离开时相同的在线/离线状态。

自定义状态：状态是在Zone配置中定义的自定义字符串，可用于通知当前Buddy“模式”。示例可以是：“可用”，“与我聊天”，“与我玩”，“占用”，“回到右边”等。这些状态应该从服务器端配置。在从客户端或服务器发送InitBuddyListRequest之后，它们将与最初的BuddyList一起发送给每个客户端。

昵称：每个Buddy的Buddy List都支持一个额外的昵称。这是通过Buddy变量进行处理，并持续存储。

增强的Buddy变量：Buddy变量现在更加灵活，支持所有常见的数据类型（Bool，Integer，Double，String）以及复杂对象（SFSObject / SFSArray），就像其他User / Room Variable对应项一样。

好友消息：而不是使用私人消息（SFS 1.x），好友可以使用一个新的特定类型的消息称为BuddyMessage。这更好地集成在好友列表系统中，并嵌入了处理被阻止的好友的逻辑，而不会“污染”Buddy不可知的通用公共/私人消息。强烈建议您使用“好友”（Buddy）消息来进行朋友之间的任何沟通。

Temp Buddies：临时好友被介绍来处理以下常见情况：
    用户Gonzo将User Piggy添加到他的好友列表中
    Gonzo向Piggy发消息
    小猪收到消息，但她对Gonzo一无所知。
    然后，Gonzo在Piggy的名单中被添加为Temp Buddy。这意味着Buddy将是短暂的，不会被保存，除非Piggy继续前进并调用addBuddy（'Gonzo'）。

服务器端事件：Buddy API在服务器端提供了许多有用的新事件，可以在您的Extension中使用它来处理特定情况：BUDDY_ADD，BUDDY_REMOVE，BUDDY_BLOCK，BUDDY_VARIABLES_UPDATE，BUDDY_ONLINE_STATE_UPDATE，BUDDY_MESSAGE，BUDDY_LIST_INIT。

»好友列表客户端API
添加好友

向当前用户添加新的好友是非常简单的：

// 'sfs' is our SmartFox class instance  'sfs'是我们的SmartFox类实例
sfs.addEventListener(SFSBuddyEvent.BUDDY_ERROR, onBuddyError)
sfs.addEventListener(SFSBuddyEvent.BUDDY_ADD, onBuddyListUpdate)

// The server will send a BUDDY_ADD event in response to this  服务器将发送一个BUDDY_ADD事件来响应这一点
sfs.send(new AddBuddyRequest("Kermit")); 

public function onBuddyListUpdate(evt:SFSEvent)
{
    // Populate the visual buddy list 填充视觉好友列表
    for each (var buddy:Buddy in sfs.buddyManager.buddyList)
    {
        // Do something with the objects in the list of buddies 与某些伙伴列表中的对象做某事
    }
}

private function onBuddyError(evt:SFSBuddyEvent):void
{
    trace("BuddyError: " + evt.params.errorMessage)
}

设置好友变量
sfs.addEventListener(SFSBuddyEvent.BUDDY_VARIABLES_UPDATE, onBuddyListUpdate)

// Setting one or more buddy variables设置一个或多个好友变量
sfs.send(new SetBuddyVariablesRequest([ new SFSBuddyVariable(“avatarPic”, “kermit-avatar,jpg”) ])

public function onBuddyListUpdate(evt:SFSEvent)
{
// Populate the visual buddy list填充视觉好友列表
for each (var buddy:Buddy in sfs.buddyManager.buddyList)
{
// Do something with the objects in the list of buddies与某些伙伴列表中的对象做某事
}
}
»好友列表服务器API

服务器端API提供了非常相似的界面来操纵好友列表。 所有与Buddy List相关的命令都可以在ISFSBuddyApi对象中找到。
获取Buddy API

SmartFoxServer sfs = SmartFoxServer.getInstance();
ISFSBuddyApi buddyApi = sfs.getAPIManager().getBuddyApi()

向用户添加好友

// This will add the User "Piggy" in the list of buddies for User "Kermit"  这将在用户“Kermit”的伙伴列表中添加用户“Piggy”
buddyApi.addBuddy(getParentZone(), "Kermit", "Piggy");

设置好友变量

简单的例子就是将Buddy添加到用户并通知客户端。 现在我们来看看如何设置一个好友变量：

// 1. Get a reference to the Owner of the BuddyList 获取BuddyList的所有者的引用
User owner = getParentZone().getUserByName("Kermit");

// 2. Create a list of variables 创建变量列表
List<BuddyVariable> vars = new ArrayList<BuddyVariable>();
vars.add( new SFSBuddyVariable("avatarPic", "kermit-avatar,jpg"));

// 3. Set the variable and disptach a client side event 设置变量并取消客户端事件
buddyApi.setBuddyVariables(owner, vars);

有关BuddyAPI的更多详细信息，我们建议您咨询服务器端javadoc。
»好友列表持久性
好友列表持久性委托给com.smartfoxserver.v2.buddylist.storage包下找到BuddyStorage接口的实现。 这是界面的骨架：

void init();
void destroy();

BuddyList loadList(String ownerName) throws SFSBuddyListNotFoundException, IOException;
void saveList(BuddyList buddyList) throws IOException;
List<BuddyVariable> getOfflineVariables(String buddyName) throws IOException;

BuddyListManager getBuddyListManager();
void setBuddyListManager(BuddyListManager buddyListManager);

在创建和销毁类时调用init（）和destroy（）方法，而BuddyListManager getter / setter用于维护对管理当前区域中的好友列表的BuddyListManager对象的引用。其余的方法代表了持久化机制的核心，这很简单。

loadList（String ownerName）：加载指定好友名称的好友列表。
saveList（BuddyList buddyList）：将传入的好友列表保存在存储系统中。
getOfflineVariables（String buddyName）：检索特定Buddy的脱机Buddy变量。在以下情况下需要此方法：
    用户Fozzie登录系统并加载他的好友列表
    对于不在线的Fozzie列表中的每个Buddy，我们将需要从存储系统直接加载它们的持久变量
    对于每个离线Buddy，好友列表管理器将会调用此方法

您将能够通过简单地将.jar文件放在SFS2X lib /文件夹中并在AdminTool（“区域配置器 - >好友列表”选项卡）中提供存储类的完全限定名称来提供自定义实现。

翻译自http://docs2x.smartfoxserver.com/AdvancedTopics/buddy-list-api