====== 好友管理 ======
好友管理能让您更好的体验 IM 功能，环信 Web IM SDK 支持好友体系管理，好友相关的操作如下：
  * 查询好友列表

  * 添加/删除好友请求

  * 添加好友
  
  * 处理好友请求
  
  * 删除好友
  
  * 黑名单

多种好友体系的管理操作，覆盖丰富的集成场景。

----
===== 参数解释 =====

^名称	^字段名	^数据类型	^描述^
|环信 ID	|username	|String	|环信 ID 是环信用户的唯一标识，在 AppKey 的范围内唯一|


===== 查询好友列表 =====


调用''getRoster''查询好友列表，示例代码如下：
<code javascript>
conn.getRoster({
  success: function ( roster ) {
    //获取好友列表，并进行好友列表渲染，roster格式为：
    /** [
          {
            jid:'asemoemo#chatdemoui_test1@easemob.com',
            name:'test1',
            subscription: 'both'
          }
        ]
    */
    for ( var i = 0, l = roster.length; i < l; i++ ) {
      var ros = roster[i];    
      if ( ros.subscription === 'both' || ros.subscription === 'to' ) {

      }
    }
  },    
});
</code>

**注意：**
  * 查询好友列表时，要注意 ''subscription (both, to, from)'' 为不同值的处理

  * 此处默认 ''both'' 和 ''to'' 的为好友，开发者自定义处理，保持跟 APP 端处理一致即可
  
  * ''ros.subscription'' 值为 ''both/to'' 为要显示的联系人，此处与 APP 需保持一致，才能保证两个客户端登录后的好友列表一致

=== API ===
示例中使用到的 API  
  * [[http://webim-h5.easemob.com/jsdoc/out/connection.html#getRoster|getRoster]]
  

----
===== 添加/删除好友请求 =====

  * 通过 SDK 的 ''subscribe'' 和 ''removeRoster'' 进行添加或者删除好友操作；
  
  * 登录用户通过注册 ''onPresence'' ，监听对方的添加或者删除好友请求，并做相应的处理。

<code javascript>
//easemobwebim-sdk中收到联系人订阅请求的处理方法，具体的type值所对应的值请参考xmpp协议规范
var handlePresence = function ( e ) {
  //（发送者希望订阅接收者的出席信息），即别人申请加你为好友
  if ( e.type === 'subscribe' ) {
  }

  //(发送者允许接收者接收他们的出席信息)，即别人同意你加他为好友
  if ( e.type === 'subscribed' ) {

  }
  
  //（发送者取消订阅另一个实体的出席信息）,即删除现有好友
  if ( e.type === 'unsubscribe' ) {

  }
  
  //（订阅者的请求被拒绝或以前的订阅被取消），即对方单向的删除了好友
  if ( e.type === 'unsubscribed' ) {

  }
};
</code>

**注意:**
  * 若''e.status''中含有''[resp:true]'',则表示为对方同意好友后反向添加自己为好友的消息，demo 中发现此类消息，默认同意操作，完成双方互为好友；

  * 如果不含有''[resp:true]''，则表示为正常的对方请求添加自己为好友的申请消息。

=== API ===
示例中使用到的 API  
  * [[http://webim-h5.easemob.com/jsdoc/out/connection.html#subscribe|subscribe]]
  
  * [[http://webim-h5.easemob.com/jsdoc/out/connection.html#removeRoster|removeRoster]]
  

----
===== 添加好友 =====
调用''subscribe''添加好友，示例代码如下：
<code javascript>
// 添加好友
var addFriends = function () {
    conn.subscribe({
        to: 'username',
        message: '加个好友呗!'   
    });
};
</code>
**注意：**
  * Demo 里面接收方没有展现出来这个''message''，在''status''字段里面。

=== API ===
示例中使用到的 API  
  * [[http://webim-h5.easemob.com/jsdoc/out/connection.html#subscribe|subscribe]]
  

----

===== 处理好友请求 =====

当收到**“添加好友”**的请求时，会有两种处理方式：
  * 同意添加对方为好友
  
  * 拒绝添加对方为好友

具体代码实现示例如下：


==== 同意添加对方为好友 ====

<code javascript>
conn.listen({
  onPresence: function ( message ) {
    handlePresence(message);
  }
});


//收到联系人订阅请求的处理方法，具体的type值所对应的值请参考xmpp协议规范
var handlePresence = function ( e ) {

  //对方收到请求加为好友
  if (e.type === 'subscribe') {
  
    /*同意添加好友操作的实现方法*/
    conn.subscribed({
      to: 'username',
      message : '[resp:true]'
    });
    conn.subscribe({//需要反向添加对方好友
      to: e.from,
      message : '[resp:true]'
    });
  }
}
</code>

==== 拒绝添加对方为好友 ====

<code javascript>
conn.listen({
  onPresence: function ( message ) {
    handlePresence(message);
  }
});


//收到联系人订阅请求的处理方法，具体的type值所对应的值请参考xmpp协议规范
var handlePresence = function ( e ) {

  //对方收到请求加为好友
  if (e.type === 'subscribe') {
  
    /*拒绝添加好友的方法处理*/
    conn.unsubscribed({
      to: 'username',
      message : 'rejectAddFriend'
    });
  }
}
</code>

=== API ===
示例中使用到的 API    
  * [[http://webim-h5.easemob.com/jsdoc/out/connection.html#listen|listen]]
  
  * [[http://webim-h5.easemob.com/jsdoc/out/connection.html#subscribed|subscribed]]

  * [[http://webim-h5.easemob.com/jsdoc/out/connection.html#subscribe|subscribe]]

  * [[http://webim-h5.easemob.com/jsdoc/out/connection.html#event:unsubscribed|unsubscribed]]  
  

----
===== 删除好友 =====
删除好友代码示例如下：
<code javascript>
// 删除好友
var removeFriends = function () {
    conn.removeRoster({
        to: 'username',
        success: function () {  // 删除成功
            conn.unsubscribed({
                to: 'username'
            });
        },
        error: function () {    // 删除失败
        }
    });
};
</code>

=== API ===
示例中使用到的 API
  * [[http://webim-h5.easemob.com/jsdoc/out/connection.html#removeRoster|removeRoster]]
  
  * [[http://webim-h5.easemob.com/jsdoc/out/connection.html#event:unsubscribed|unsubscribed]]

----

===== 黑名单 =====
集成黑名单操作中，有以下几种黑名单功能操作：
  * 将好友加入黑名单

  * 获取黑名单列表

  * 将好友移除黑名单
==== 将好友加入黑名单 ====

将好友加入黑名单后，对方好友列表依然可以看到己方，但无法向己方发送消息。

<code javascript>
 var list = {
 username_1:{
 jid: 'appKey_'+username_1+'@easemob.com',
 name: username_1,
 subscription: 'both',
 order: 2
 },
 username_2:{
 jid: 'appKey_'+username_2+'@easemob.com',
 name: username_2,
 subscription: 'both',
 order: 3,
 type: 'jid'
 },
 username_3:{
 jid: 'appKey_'+username_3+'@easemob.com',
 name: username_3,
 subscription: 'both',
 order: 4,
 type: 'jid'
 }
 }
var addToBlackList = function () {
    var list = {
        // user_1
        asdfghj: {
            jid: 'easemob-demo#chatdemoui_asdfghj@easemob.com',
            name: 'asdfghj',
            subscription: 'both',
            order: 2,
            type: 'jid'
        },
        // user_2
        wjy6: {
            jid: 'easemob-demo#chatdemoui_wjy6@easemob.com',
            name: 'wjy6',
            subscription: 'both',
            order: 3,
            type: 'jid'
        }
    };
    conn.addToBlackList({
        list: list,
        type: 'jid',
        success: function () {
            console.log('Add friend to black list success');
        },
        error: function () {
            console.log('Add friend to black list error');
        }
    });
}
</code>

**注意：**
  * ''list''的结构为''{username_1: {}, username_2: {}...}'';
  
  * 拉黑好友需要将拉黑后的黑名单里的好友信息全部传入，如黑名单此时已有A，B两位好友，现想将C也拉进黑名单，正确的操作是同时将ABC的信息都传入接口中;

  * ''jid'', ''username'', ''subscription''均在获取好友列表时已获取到，用户可根据好友列表动态获取这些参数，''order''不重复即可。

=== API ===
示例中使用到的 API
  * [[http://webim-h5.easemob.com/jsdoc/out/connection.html#addToBlackList|addToBlackList]]
  

----
==== 获取黑名单列表 ====

  * 调用''getBlacklist''函数获取好友黑名单列表；
  
  * 调用这个函数时，会回调''conn.listen''里的''onBlacklistUpdate''函数，具体细节请参照[[im:web:intro:basic|Web SDK基础功能]]。

<code javascript>
var getBlackList = function () {
    conn.getBlacklist();
};
</code>

=== API ===
示例中使用到的 API
  * [[http://webim-h5.easemob.com/jsdoc/out/connection.html#listen|listen]]
  
  * [[http://webim-h5.easemob.com/jsdoc/out/connection.html#getBlacklist|getBlacklist]]

----
==== 将好友移出黑名单 ====

  * 将好友移出黑名单的机制是，将移出后某好友后黑名单中的好友组成一个 list ，传入接口重建黑名单；
 
  * 例如，黑名单中有 ABC 三个人，需要移出 A ，则将 B 和 C 组合成一个 list 传入接口。
  
  * 若 list 为空，则清空黑名单。

<code javascript>
// 将好友从黑名单拉出来
var removeBlackList = function () {
    var list = [
        {
            wjy6: {
                jid: 'easemob-demo#chatdemoui_mengyuanyuan01@easemob.com',
                name: 'mengyuanyuan01',
                order: '2',
                type: 'jid'
            }
        },
        {
            mengyuanyuan: {
                jid: 'easemob-demo#chatdemoui_wjy6@easemob.com',
                name: 'wjy6',
                order: '4',
                type: 'jid',
            }
        }
    ];
    conn.removeFromBlackList({
        list: list,
        type: 'jid',
        success: function () {
            console.log('Remove from black list success.');
        },
        error: function () {
            console.log('Remove from black list error.')
        }
    });
};
</code>

=== API ===
示例中使用到的 API
  * [[http://webim-h5.easemob.com/jsdoc/out/connection.html#removeFromBlackList|removeFromBlackList]]

----
<WRAP group>
<WRAP half column>
上一页：[[im:applet:message|消息]]
</WRAP>

<WRAP half column>
下一页：[[im:applet:group|群组]]
</WRAP>
</WRAP>