Youme 游密
文档导航 Cocos2d C++

文档目录

本页目录

IM SDK for Cocos2d-x 使用指南

导入IM SDK

Android

  1. 将yim复制到Cocos2d-x开发工具生成的游戏目录根目录下。

  2. 对proj.android/app/jni/Android.mk文件进行如下修改，仅需修改标注部分，其余部分无需处理。

    MAKE
    
LOCAL_PATH := $(call my-dir)

include $(CLEAR_VARS)

$(call import-add-path,$(LOCAL_PATH)/../../cocos2d)
$(call import-add-path,$(LOCAL_PATH)/../../cocos2d/external)
$(call import-add-path,$(LOCAL_PATH)/../../cocos2d/cocos)

LOCAL_MODULE := cocos2dcpp_shared

LOCAL_MODULE_FILENAME := libcocos2dcpp

LOCAL_SRC_FILES := hellocpp/main.cpp \
   ../../Classes/Helloworld.cpp

LOCAL_C_INCLUDES := $(LOCAL_PATH)/../../Classes  \
# #########添加如下代码,添加头文件路径.注意上一行结尾处添加换行符\########
$(LOCAL_PATH)/../../../yim/include \
# ###############################################################

# _COCOS_HEADER_ANDROID_BEGIN
# _COCOS_HEADER_ANDROID_END

LOCAL_STATIC_LIBRARIES := cocos2dx_static
# #############添加如下代码,链接动态库##############################
LOCAL_SHARED_LIBRARIES := YIM
# ###############################################################

#_COCOS_LIB_ANDROID_BEGIN
#_COCOS_LIB_ANDROID_END

include $(BUILD_SHARED_LIBRARY)
####################### 包含YMSDK子配置 #########################
include $(LOCAL_PATH)/../../../yim/lib/android/Android.mk
################################################################

$(call import-module,.)

# _COCOS_LIB_IMPORT_ANDROID_BEGIN
# _COCOS_LIB_IMPORT_ANDROID_END

  3. 修改gradle.properties文件，将"PROP_BUILD_TYPE=cmake"改为"PROP_BUILD_TYPE=ndk-build"。

  4. 将 yim/lib/android/ 目录中如下文件复制到proj.android/app/libs/目录下。（其中alisr.jar和asr-v1.0.2.aar是语音识别包，如没有使用语音识别功能则不需要添加；如果项目之前已经有Android-support依赖，可以不用引入包内的android-support-v4.jar。）

yim.jar
alisr.jar
asr-v1.0.2.aar
android-support-v4.jar

  1. 修改proj.android/AndroidManifest.xml文件，确保声明了如下权限：
XML
    <!-- 添加到application节点内 -->
    <application xxxx>
        <receiver android:name="com.youme.im.NetworkStatusReceiver" android:label="NetworkConnection" >
              <intent-filter>
                  <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
              </intent-filter>
        </receiver>
    </application>
    <!-- 添加到跟application平级 -->
    <!-- 允许程序访问互联网 -->
    <uses-permission android:name="android.permission.INTERNET" />
    <!-- 允许程序获取 Wi-Fi 状态信息（Wi-Fi 是否启用） -->
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <!-- 允许程序获取网络信息状态（是否连接到网络） -->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <!-- 允许程序写入外部存储（存储 SDK 日志文件） -->
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <!-- 允许程序通过手机或耳机的麦克录制声音 -->
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <!-- 获取地理位置的权限，可选 -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

  1. 打开Eclipse，导入上一步的Android工程，在项目中第一个启动的AppActivity中的onCreate中增加以下Java代码： 注意必须把游密的初始化加到第一行，否则可能出现部分机型加载so不正常

    JAVA
    @Override
protected void onCreate(Bundle bundle)
{
   //下面的两个调用顺序不能错
    com.youme.im.IMEngine.init(this);
    super.onCreate(bundle);           //super.onCreate是默认已经有的，不用再复制
}

  2. 如果打包或生成APK时需要混淆，则需要在proguard.cfg文件中添加如下代码：

    SHELL
     -keep class com.youme.** {*;}
 -keep class com.iflytek.**
 -keepattributes Signature

iOS

  1. 将yim复制到Cocos2d-x开发工具生成的游戏目录 根目录下。
  2. 在Build Settings -> Search Paths -> Header Search Paths中添加头文件路径：../yim/include/。
  3. 在Build Settings -> Search Paths -> Framework Search Paths中添加框架文件路径：../yim/lib/ios/。
  4. 在Build Settings -> Search Paths -> Library Search Paths中添加库文件路径：../yim/lib/ios/。
  5. 在Build Phases -> Link Binary With Libraries添加如下依赖库：

libc++.1.tbd
libsqlite3.0.tbd
libresolv.9.tbd
SystemConfiguration.framework
libYouMeCommon.a
libyim.a
libz.tbd
CoreTelephony.framework
AVFoundation.framework
AudioToolbox.framework
CoreLocation.framework

  1. 需要为iOS10以上版本添加录音权限配置 iOS 10 使用录音权限，需要在info新加Privacy - Microphone Usage Description键，值为字符串，比如“语音聊天需要录音权限”。 首次录音时会向用户申请权限。配置方式如图(选择Private-Microphone Usage Description)。 iOS10录音权限配置

  2. LBS添加获取地理位置权限 若使用LBS，需要在info新加Privacy - Location Usage Description键，值为字符串，比如“查看附近的玩家需要获取地理位置权限”。首次使用定位时会向用户申请权限，配置方式如上图录音权限。

Windows

  1. 将yim复制到Cocos2d-x开发工具生成的游戏目录根目录下。

  2. 在项目 -> 属性 -> C/C++ -> 常规 -> 附加包含目录 中添加..\yim\include。

  3. 拷贝yim/lib/x86 目录下的 yim.dll， yim.lib， libusc.dll， jsoncpp-0.y.z.dll， libeay32.dll， nlscppsdk.dll， pthreadVC2.dll， ssleay32.dll拷贝到执行目录(如果是64位机器，使用yim/lib/x64)。

  4. 在项目->属性->链接器->输入->附加依赖库 中添加 yim.lib（该库是release模式下的 如果运行的时候是debug模式请添加yim_Debug.lib,如果不存在yim_Debug.lib则代表yim.lib通用）。

特别注意事项

  • C++版本的回调通知都是通过子线程调用，所以在收到回调后，不能直接操作UI，需要回到主线程后操作UI。
  • 重连有可能失败，所以一般收到OnLogout的通知后需要使用者判断游戏是否还在线，如果游戏还在线，就重新调用 登录->进频道 接口。
  • 初始化接口整个运行期间，只能调用一次。
  • 不同设备或者不同的运行期，消息id可能重复。
  • 返回值为YIMErrorcode的接口，如果返回了非YIMErrorcode_Success表示接口调用失败，就不会再有回调通知（如果是有回调的接口）。
  • 请务必使用游密SDK提供的android-support-v4.jar ，这样可以兼容targetSdkVersion="23"及其以上版本的录音授权模式，如果项目之前已经有Android-support依赖，可以不用引入SDK包内的android-support-v4.jar。

基本接口使用时序图

基本接口使用时序图

初始化

包含SDK头文件

C
#include "YIM.h"

数据类型

SDK 封装了Android、iOS、windows平台常用数据类型。开发者需要了解字符串和整数封装后的类型XString和XUINT64：

XString类型对应Android、iOS的std::string类型与windows的std::wstring类型。
XCHAR类型对应Android、iOS的char类型与windows的wchar_t类型。
XUINT64类型对应标准C++的unsigned long long类型。

SDK对象

IM SDK 功能主要类分为：SDK管理器，消息发送管理器，频道管理，具体的含义如下：

YIMManager:SDK管理器，负责初始化、登录、登出等功能。
YIMMessageManager：消息发送管理器，负责发送文本、自定义等不同类型消息。
YIMLocationManager：地理位置管理器。
YIMChatRoomManager：频道管理器，负责创建聊天频道。
YIMUserProfileManager：用户信息管理器，负责设置、获取用户信息。
YIMFriendManager：好友关系管理器，负责管理好友添加、删除。
IYIMLoginCallback：登录登出回调虚基类，负责处理登录、登出结果。
IYIMMessageCallback：消息回调虚基类，负责处理消息收发操作结果。
IYIMChatRoomCallback：聊天室管理回调虚基类，负责处理聊天室管理操作结果。
IYIMDownloadCallback：下载回调虚基类，负责处理下载完成操作结果。
IYIMContactCallback：最近私聊用户列表查询结果通知基类。
IYIMLocationCallback：LBS相关回调，负责位置相关处理。
IYIMAudioPlayCallback：语音播放回调基类。
IYIMReconnectCallback：重连回调基类。
IYIMNoticeCallback：公告回调基类。
IYIMReconnectCallback：重连回调基类。
IYIMFriendCallback：好友管理回调基类。
IYIMUserProfileCallback：用户信息管理回调基类。

获取SDK管理器

在工程的AppDelegate里面的以下方法中，添加SDK初始化代码。初始化SDK前需要创建SDK管理器YIMManager，通过它获取聊天室、消息管理器。

  • 原型：

    C
        // 获取游密IM管理器实例，是单例，多次调用仍然是返回同一个对象指针
    static YIMManager* CreateInstance ();

  • 返回：
    YIMManager实例。

  • 示例：

    C
      //本文档为方便演示接口使用示例。使用了一个类MyIM包装SDK管理器，以后就可以通过这个`MyIM::Inst()`引用IMSDK管理器。
  YIMManager * MyIM::Inst()
  {
      if(NULL == _instance)
      {
          _instance = YIMManager::CreateInstance();
      }
      return _instance;
  }

    MyIM::Inst()获得IMSDK管理器之后，就可以通过它获取聊天室，消息管理器。

  • 示例：

    C++
        // 获取频道管理器
    MyIM::Inst()->GetChatRoomManager();
    // 获取消息发送管理器
    MyIM::Inst()->GetMessageManager();
    // 获取地理位置管理器
    MyIM::Inst()->GetLocationManager();
    // 获取用户信息管理器
    MyIM::Inst()->GetUserProfileManager();
    // 获取好友关系管理器
    MyIM::Inst()->GetFriendManager();

初始化SDK

获得SDK管理器之后，紧跟着要调用YIMManager的Init接口进行初始化。初始化的函数主要功能是初始化IM SDK引擎。初始化接口的输入参数appKey和appSecurity需要根据实际申请得到的值进行替换, packageName目前传入空字符串即可。

  • 接口：

    C
        YIMErrorcode Init(const XCHAR* appKey, const XCHAR* appSecurity, const XCHAR* packageName);

  • 参数：
    appKey: 用户游戏产品区别于其它游戏产品的标识，可以在游密官网获取、查看。
    appSecurity: 用户游戏产品的密钥，可以在游密官网获取、查看。
    packageName：游戏包名。

  • 返回：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 示例：

    C++
        MyIM::Inst()->Init("YoumeAppkey"," YoumeAppSecurity", "");

设置监听

SDK内部所有的较长耗时的接口调用都会采用异步回调的方式返回结果，所以需要开发者实现:

IYIMLoginCallback
IYIMMessageCallback
IYIMChatRoomCallback
IYIMDownloadCallback
IYIMContactCallback
IYIMAudioPlayCallback
IYIMLocationCallback
IYIMReconnectCallback
IYIMNoticeCallback
IYIMFriendCallback
IYIMUserProfileCallback

然后把它们的实现对象设置到SDK管理器里。如果不设定就收不到相应事件的通知。建议初始化和设置监听在一起完成。

  • 接口原型：

    C++
        //登录和登出
    void SetLoginCallback(IYIMLoginCallback* pCallback);
    //设置消息回调
    void SetMessageCallback(IYIMMessageCallback* pCallback);
    //设置聊天室回调
    void SetChatRoomCallback(IYIMChatRoomCallback* pCallback);
    //设置下载回调
    void SetDownloadCallback(IYIMDownloadCallback* pCallback);
    //设置联系人回调
    void SetContactCallback(IYIMContactCallback* pCallback);
    //设置语音播放回调
    void SetAudioPlayCallback(IYIMAudioPlayCallback* pCallback);
    // 设置地理位置回调
    void SetLocationCallback(IYIMLocationCallback* pCallback);
    // 设置通知回调
     void SetNoticeCallback(IYIMNoticeCallback* pCallback);
    // 设置重连回调
    void SetReconnectCallback(IYIMReconnectCallback* pCallback);
    // 设置好友回调
     void SetFriendCallback(IYIMFriendCallback* pCallback);
     //设置用户信息回调
   void SetUserProfileCallback(IYIMUserProfileCallback* pCallback);

  • 示例：

    C++
        //本文档示例中使用class MyIM继承自这4个回调类。实现它们回调接口。
    class MyIM : public IYIMLoginCallback, IYIMMessageCallback, IYIMChatRoomCallback, IYIMDownloadCallback, IYIMContactCallback, IYIMAudioPlayCallback, IYIMLocationCallback, IYIMNoticeCallback, IYIMReconnectCallback, IYIMFriendCallback, IYIMUserProfileCallback
    {
       //建议初始化和设置监听在一起完成
       public: void Start ()
       {
          MyIM::Inst()->SetLoginCallback(this);
          MyIM::Inst()->SetMessageCallback(this);
          MyIM::Inst()->SetChatRoomCallback(this);
          MyIM::Inst()->SetDownloadCallback(this);
          MyIM::Inst()->SetContactCallback(this);
          MyIM::Inst()->SetAudioPlayCallback(this);
          MyIM::Inst()->SetLocationCallback(this);
          MyIM::Inst()->SetNoticeCallback(this);
          MyIM::Inst()->SetReconnectCallback(this);
          MyIM::Inst()->SetFriendCallback(this);
          MyIM::Inst()->SetUserProfileCallback(this);
          
          MyIM::Inst()->Init("YoumeAppkey"," YoumeAppSecurity", "");
       }

    }

重连回调

开始重连回调

  • 原型：

    C
    class IYIMReconnectCallback
{
  public:  
    //开始重连
  virtual void OnStartReconnect() {}
};

重连结果回调

  • 原型：

    C
    class IYIMReconnectCallback
{
  public: 
    //重连结果回调
  virtual void OnRecvReconnectResult(ReconnectResult result) {}
};

  • 参数：
    result：重连结果，枚举类型，
    RECONNECTRESULT_SUCCESS=0 //重连成功
    RECONNECTRESULT_FAIL_AGAIN=1 //重连失败，再次重连
    RECONNECTRESULT_FAIL=2 //最终重连失败

录音音量回调

音量值范围:0~1, 频率:1s ios 约2次，android 约8次。

  • 原型：

    C
    class IYIMMessageCallback
{
  public:
    //音量回调,音量值范围:0~1
  virtual void OnRecordVolumeChange(float volume) {}
};

  • 参数：
    volume：音量值。

获取 SDK 版本

  • 语法：
C++
static XString GetSDKVersion();
  • 功能：

通过 YIMManager::GetSDKVersion() 获取 SDK 版本字符串。

  • 参数说明：

无。

  • 返回值：

XString：SDK 版本字符串。

  • 异步回调：

无。

消息已读状态回调

  • 语法：
C++
virtual void OnUpdateReadStatus(const XCHAR* recvId, int chatType, XUINT64 msgSerial);
  • 功能：

在 IYIMUpdateReadStatusCallback 的实现类中接收对端的消息已读状态更新。

  • 参数说明：

recvId：接收端 ID。

chatType：聊天类型。

msgSerial：最后一条已读消息的消息 ID。业务侧可将该 ID 及之前的相应未读消息更新为已读。

  • 返回值：

无（void）。

  • 异步回调：

本接口本身是异步通知。

初始化 SDK 的扩展配置

  • 语法：
C++
virtual YIMErrorcode Init(const XCHAR* appKey, const XCHAR* appSecurity, const XCHAR* packageName, XCHAR* sdkValidDomain=NULL, XCHAR* drDomain=NULL, XCHAR* sdkValidBackupip=NULL, XCHAR* drBackupip=NULL) = 0;
  • 功能：

在初始化时指定验证和上报服务的域名及备用 IP。使用游密提供的配置值；普通接入沿用前文的初始化调用即可。

  • 参数说明：

基础参数含义与前文初始化接口一致。新增参数如下，未指定时使用NULL：

sdkValidDomain：SDK 验证服务域名。

drDomain：DR 上报服务域名。

sdkValidBackupip：SDK 验证服务的备用 IP。

drBackupip：DR 上报服务的备用 IP。

  • 返回值：

错误码，0 表示本次调用成功，非 0 表示调用失败，详见错误码定义。

  • 异步回调：

无。

用户管理

用户登录

完成以上的步骤后就可以使用IM功能了，IM用户登录IM后台服务器后即可以正常收发消息。通过YIMManager的Login接口登录IM，需要用户提供用户名、密码。登录为异步过程，通过回调函数返回是否成功，成功后方能进行后续操作。 用户首次登录会自动注册，如果后台已存在此用户名，则会校验密码是否与第一次相同（用户名和密码的格式见下方相关参数说明）。

  • 原型：

    C
        YIMErrorcode Login(const XCHAR* userID, const XCHAR* passwd ,const XCHAR* token);

  • 参数说明：
    userID ：用户ID，由调用者分配，不可为空字符串，只可由字母或数字或下划线组成，长度限制为255字节。
    passwd：用户密码，不可为空字符串，如无特殊要求可以设置为固定字符串。
    token：使用服务器token验证模式时使用该参数，否则使用空字符串：""，由restAPI获取token值。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMLoginCallback
{
  public:
  virtual void OnLogin(YIMErrorcode errorcode, const XCHAR * userID) {}
};

  • 回调参数：
    errorcode：错误码。
    userID：用户ID。

  • 示例：

    C
        YIMErrorcode ymErrorcode = MyIM::Inst()->Login("123456", "123456", "" );
    if(YIMErrorcode_Success == ymErrorcode)
    {
       printf("call Login()  success");
    }
    else
    {
       printf("call Login fail,不会有回调通知，errorcode is %d",  ymErrorcode);
    }

用户登出

如用户主动退出或需要进行用户切换，则需要调用登出操作，通过YIMManager的Logout接口登出。

  • 原型：

    C
        YIMErrorcode Logout();

  • 参数：
    无。

  • 返回：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMLoginCallback
{
  public:
  virtual void OnLogout(YIMErrorcode errorcode) {}
};

  • 回调参数：
    errorcode：错误码。

  • 示例：

    C
        //登出
    YIMErrorcode ymErrorcode = MyIM::Inst()->Logout();
    if(YIMErrorcode_Success == ymErrorcode)
    {
       printf("Logout()  Success");
    }
    else
    {
       printf("Logout()  fail，errorcode is %d",  ymErrorcode);
    }

被用户踢出通知

同一个用户ID在多台设备上登录时，后登录的会把先登录的踢下线，收到OnKickOff()通知。

  • 原型：

    C
    class IYIMLoginCallback
{
  public:
  virtual void OnKickOff() {}
};

用户信息

设置用户的详细信息

通过YIMManager的SetUserInfo接口设置用户信息后，在游密消息管理后台才能看到消息发送者的详细信息。

  • 原型：

    C
        YIMErrorcode SetUserInfo(const XCHAR* userInfo);

  • 参数：
    userInfo： 用户信息字符串， 格式为json {"nickname":"","server_area_id":"","server_area":"","location_id":"","location":"","level":"","vip_level":""} (可以添加其他字段)。
    nickName：用户昵称。
    server_area_id：游戏服ID。
    server_area：游戏服名称。
    location_id：游戏大区ID。
    location：游戏大区名。
    level：角色等级。
    vip_level：玩家VIP等级。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

获取指定用户的详细信息

可通过YIMManager的GetUserInfo接口获取指定用户的详细信息。

  • 原型：

    C
        YIMErrorcode GetUserInfo(const XCHAR* userID);

  • 参数：
    userID： 要查询的用户ID。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMContactCallback
{
  public:
    //用户信息字符串， 格式为json {"nickname":"","server_area_id":"","server_area":"","location_id":"","location":"","level":"","vip_level":""}
  virtual void OnGetUserInfo(YIMErrorcode errorcode, const XCHAR* userID, const XCHAR* userInfo) {}
};

  • 参数：
    errorcode：错误码。
    userID：用户ID。
    userInfo：用户详细信息。

查询用户在线状态

可通过YIMManager的QueryUserStatus接口查询用户的在线状态。

  • 原型：

    C
        YIMErrorcode QueryUserStatus(const XCHAR* userID)

  • 参数：
    userID：要查询的用户ID。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMContactCallback
{
  public:    
  virtual void OnQueryUserStatus(YIMErrorcode errorcode, const XCHAR* userID, YIMUserStatus status) {}
};

  • 回调参数：
    errorcode：错误码，查询请求是否成功的通知。
    userID：查询的用户ID。
    status：登录状态，枚举类型，
    UserStatus.STATUS_ONLINE=0 //在线
    UserStatus.STATUS_OFFLINE=1 //离线
    （如查询的用户ID是未注册的，用户状态返回的是离线状态）

频道管理

加入频道

通过YIMChatRoomManager的JoinChatRoom接口加入聊天频道，如果频道不存在则后台自动创建。有了这个ID就可以收发频道消息。开发者要保证频道号全局唯一，以避免用户进入错误频道。结果需要在开发者实现IYIMChatRoomCallback的OnJoinChatRoom里处理。

  • 原型：

    C
        YIMErrorcode JoinChatRoom(const XCHAR* chatRoomID);

  • 参数：
    chatRoomID ：请求加入的频道ID，仅支持数字、字母、下划线组成的字符串，区分大小写，长度限制为255字节。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMChatRoomCallback
{
  public:
  virtual void OnJoinChatRoom(YIMErrorcode errorcode, const XCHAR * strChatRoomID) {}
};

  • 回调参数：
    errorcode：错误码，详细描述见错误码定义。
    strChatRoomID：频道ID。

  • 示例：

    C
        YIMErrorcode ymErrorcode;
    ymErrorcode = MyIM::Inst()->GetChatRoomManager()->JoinChatRoom("123456");
    if( ymErrorcode != YIMErrorcode_Success )
    {
       printf("OnJoinChatRoom()  fail，errorcode is %d",  ymErrorcode);
    }

    // 异步回调处理
    void MyIM::OnJoinChatRoom(YIMErrorcode errorcode, const XCHAR * strChatRoomID)
    {
       if( errorcode == YIMErrorcode_Success )
       {
          printf("join chat room success.");
       }
    }

离开频道

通过YIMChatRoomManager的LeaveChatRoom接口离开频道。

  • 原型：

    C
        YIMErrorcode LeaveChatRoom(const XCHAR* strChatRoomID);

  • 参数：
    strChatRoomID ：请求离开的频道ID。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMChatRoomCallback
{
  public:
  virtual void OnLeaveChatRoom(YIMErrorcode errorcode, const XCHAR * chatRoomID) {}
};

  • 回调参数：
    errorcode：错误码，详细描述见错误码定义 chatRoomID：频道ID

  • 示例：

    C
        YIMErrorcode ymErrorcode;
    ymErrorcode = MyIM::Inst()->GetChatRoomManager()->LeaveChatRoom("123456");
    if(ymErrorcode != YIMErrorcode_Success)
    {
       printf("LeaveChatRoom()  fail，errorcode is %d",  ymErrorcode);
    }

    // 异步回调处理
    void MyIM::OnLeaveChatRoom(YIMErrorcode errorcode, const XCHAR * chatRoomID)
    {
       if( errorcode == YIMErrorcode_Success )
       {
          printf("leave chat room success.");
       }
    }

离开所有频道

通过YIMChatRoomManager的LeaveAllChatRooms接口离开所有频道。

  • 原型：

    C
        YIMErrorcode LeaveAllChatRooms();

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMChatRoomCallback
{
  public:   
  virtual void OnLeaveAllChatRooms(YIMErrorcode errorcode) {}
};

  • 参数：
    errorcode ：错误码。

用户进出频道通知

小频道(小于100人)内，当其他用户进入频道，会收到OnUserJoinChatRoom通知。

此功能默认不开启，需要的请联系游密开启此服务。

  • 原型：

    C
    class IYIMChatRoomCallback
{
  public:
  virtual void OnUserJoinChatRoom(const XCHAR * chatRoomID, const XCHAR * userID) {}
};

  • 参数：
    chatRoomID ：频道ID。
    userID：用户ID。

小频道(小于100人)内，当其他用户退出频道，会收到OnUserLeaveChatRoom通知。

  • 原型：

    C
    class IYIMChatRoomCallback
{
  public:
  virtual void OnUserLeaveChatRoom(const XCHAR * chatRoomID, const XCHAR * userID) {}
};

  • 参数：
    chatRoomID ：频道ID。
    userID：用户ID。

获取房间成员数量

可通过YIMChatRoomManager的GetRoomMemberCount接口获取进入频道的用户数量。

  • 原型：

    C
        YIMErrorcode GetRoomMemberCount(const XCHAR* chatRoomID);

  • 参数：
    chatRoomID ：频道ID(已成功加入此频道才能获取该频道的人数)。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMChatRoomCallback
{
  public:
  virtual void OnGetRoomMemberCount(YIMErrorcode errorcode, const XCHAR * chatRoomID, unsigned int count) {}
};

  • 回调参数：
    errorcode ：错误码。
    chatRoomID：频道ID。
    count：频道中的成员数量。

消息管理

接收消息

通过IYIMMessageCallback的OnRecvMessage接口被动接收消息。需要开发者实现。

  • 原型：

    C
    class IYIMMessageCallback
{
  public:
    //接收到用户发来的消息
  virtual void OnRecvMessage(std::shared_ptr<IYIMMessage> pMessage)  {}
};

  • 参数：
    pMessage：消息。

  • 备注：
    IYIMMessage 消息基类成员方法如下： GetSenderID()：消息发送者ID。
    GetReceiveID()：消息接收者ID。
    GetChatType()：聊天类型，私聊/频道聊天，1是私聊，2是频道聊天，3是群发消息。
    GetMessageID()：消息ID。
    GetMessageBody()->GetMessageType()：消息类型，枚举类型，
    MessageBodyType_Unknow = 0, //未知类型
    MessageBodyType_TXT = 1, //文本消息
    MessageBodyType_CustomMesssage = 2, //自定义消息
    MessageBodyType_Emoji = 3, //表情
    MessageBodyType_Image = 4, //图片
    MessageBodyType_Voice = 5, //语音
    MessageBodyType_Video = 6, //视频
    MessageBodyType_File = 7, //文件
    MessageBodyType_Gift = 8 //礼物
    GetCreateTime()：消息发送时间。
    GetDistance()：若是附近频道的消息，此值是该消息用户与自己的地理位置距离。
    IsRead()：消息是否已读。

    IYIMMessageBodyText继承IYIMMessageBodyBase类，类成员如下： GetMessageContent()：文本消息内容。
    GetAttachParam()： 发送文本附件信息。

    IYIMMessageBodyCustom继承IYIMMessageBodyBase类，类成员如下： GetCustomMessage()：自定义消息内容。

    IYIMMessageBodyFile继承IYIMMessageBodyBase类，类成员如下： GetFileName()：文件名。
    GetFileType()：文件类型，枚举类型，
    FileType_Other = 0 //其它
    FileType_Audio = 1 //音频（语音）
    FileType_Image = 2 //图片
    FileType_Video = 3 //视频
    GetFileSize()：文件大小。
    GetFileExtension()：文件扩展信息。
    GetExtraParam()：附加信息。
    GetLocalPath()：文件路径。

    IYIMMessageGift继承IYIMMessageBodyBase类，类成员如下： GetAnchor()：主播ID。
    GetGiftID()：礼物ID。
    GetGiftCount()：礼物数量。
    GetExtraParam()：附加参数。

    IYIMMessageBodyAudio继承IYIMMessageBodyBase类，类成员如下： GetText()：若使用的是语音转文字录音，此值为语音识别的文本内容，否则是""。
    GetAudioTime()：语音时长（单位：秒）。
    GetExtraParam()：发送语音时的附加参数。
    GetFileSize()：语音文件大小（单位：字节）。
    GetLocalPath()：语音文件本地存放路径。
    IsPlayed()：语音是否已播放，true-已播放，false-未播放。

  • 示例：

    C
        void MyIM::OnRecvMessage (std::shared_ptr<IYIMMessage> pMessage)
    {
      YIMMessageBodyType msgType = pMessage->GetMessageBody()->GetMessageType();
      if (msgType ==  YIMMessageBodyType::MessageBodyType_TXT)
      {
          // 文本消息
          IYIMMessageBodyText * pMsgText =  (IYIMMessageBodyText*)pMessage->GetMessageBody();
          printf("RecvMessage text is %s send is %s,  RevID is %s",
                  pMsgText->GetMessageContent(),
                  pMessage->GetReceiveID(),
                  pMessage->GetSenderID());
      }
      else if (msgType == YIMMessageBodyType::MessageBodyType_Voice)
      {
          // 语音消息
          IYIMMessageBodyAudio * pMsgVoice =  (IYIMMessageBodyAudio*)pMessage->GetMessageBody();
          printf("RecvMessage text is %s ,messageid is %llu ,param is %s ,audio time is %d",
                  pMsgVoice->GetText(),
                  pMessage->GetMessageID(),
                  pMsgVoice->GetExtraParam(),
                  pMsgVoice->GetAudioTime() );
          //下载语音文件示例
          MyIM::Inst()->GetMessageManager()->DownloadFile(pMessage->GetMessageID(), "/sdcard/audiocaches/123.wav");
      }else if(msgType == YIMMessageBodyType::MessageBodyType_Gift){
          // 礼物消息
          IYIMMessageGift *pMsgVoice =  (IYIMMessageGift*)pMessage->GetMessageBody();
      }
    }
C++

### 发送文本消息
可通过`YIMMessageManager`的`SendTextMessage`接口发送文本消息。异步返回结果通过`IYIMMessageCallback`的`OnSendMessageStatus`接口返回。

- 原型：

 ``` c
     YIMErrorcode SendTextMessage(const XCHAR* receiverID, YIMChatType chatType, const XCHAR* text, const XCHAR* attachParam, XUINT64* requestID);

  • 参数：
    receiverID ：接收者ID，私聊传入用户ID，频道聊天传入频道ID。
    chatType：聊天类型，私聊/频道聊天，1是私聊，2是频道聊天。
    text：聊天内容。
    attachParam：发送文本附加信息。
    requestID：消息序列号，用于校验一条消息发送成功与否的标识。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMMessageCallback
{ 
  public:
  virtual void OnSendMessageStatus(XUINT64 requestID, YIMErrorcode errorcode, XUINT64 sendTime, bool isForbidRoom, int reasonType, XUINT64 forbidEndTime, XUINT64 messageID) {}
};

  • 回调参数：
    requestID：消息序列号，用于校验一条消息发送成功与否的标识。
    errorcode：错误码，详细描述见错误码定义。
    sendTime：消息发送时间。
    isForbidRoom：若发送的是频道消息，显示在此频道是否被禁言，true-被禁言，false-未被禁言（errorcode为禁言才有效）。
    reasonType：若在频道被禁言，禁言原因类型，0-未知，1-发广告，2-侮辱，3-政治敏感，4-恐怖主义，5-反动，6-色情，7-其它（errorcode为禁言才有效）。
    forbidEndTime：若在频道被禁言，禁言结束时间（errorcode为禁言才有效）。
    messageID：服务器返回的消息id。

  • 示例：

    C
        YIMErrorcode ymErrorcode;
    XUINT64 iRequestID=0;
    ymErrorcode = MyIM::Inst()->GetMessageManager()->SendTextMessage("123456",                                                    YIMChatType::ChatType_PrivateChat,                                                    "Msg content!",                                                    &iRequestID);
   if(ymErrorcode != YIMErrorcode_Success)
   {
      printf("SendTextMessage() call failed，errorcode is %d",  ymErrorcode);
   }

  • 异步回调处理：

    C
        void MyIM::OnSendMessageStatus(XUINT64 iRequestID, YIMErrorcode errorcode, XUINT64 sendTime, bool isForbidRoom, int reasonType, XUINT64 forbidEndTime, XUINT64 messageID)
    {
       printf("OnSendMessageStatus request:iRequestID errorcode is %llu, %d:",
          iRequestID,
          errorcode) ;
    }

群发文本消息

可通过YIMMessageManager的MultiSendTextMessage接口群发文本消息，每次不要超过200个用户。

  • 原型：

    C
        //群发文本消息
    YIMErrorcode MultiSendTextMessage( const std::vector<XString>& vecReceiver, const XCHAR* text)

  • 参数：
    vecReceiver：接受消息的用户id列表。
    text：文本消息内容。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

发送礼物消息

可通过YIMMessageManager的SendGift接口给主播发送礼物消息，支持在游密主播后台查看礼物消息信息和统计信息。客户端还是通过OnRecvMessage接收消息。

  • 原型：

    C
        YIMErrorcode SendGift(const XCHAR* anchorID, const XCHAR* channel, int giftId, int giftCount, const char* extraParam, XUINT64* requestID)

  • 参数：
    anchorID：游密后台设置的对应的主播游戏id。
    channel：主播所进入的频道ID，通过JoinChatRoom进入此频道的用户可以接收到消息。
    giftId：礼物物品id，特别的是0表示只是留言。
    giftCount：礼物物品数量。
    extraParam：扩展内容json字符串，目前要求包含如下字段： {"nickname":"","server_area":"","location":"","score":"","level":"","vip_level":"","extra":""}。
    requestID：消息序列号。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMMessageCallback
{
  public:
  virtual void OnSendMessageStatus(XUINT64 requestID, YIMErrorcode errorcode, XUINT64 sendTime, bool isForbidRoom, int reasonType, XUINT64 forbidEndTime, XUINT64 messageID) {}
};

  • 回调参数：
    requestID：消息序列号，用于校验一条消息发送成功与否的标识。
    errorcode：错误码，详细描述见错误码定义。
    sendTime：消息发送时间。
    isForbidRoom：若发送的是频道消息，显示在此频道是否被禁言，true-被禁言，false-未被禁言（errorcode为禁言才有效）。
    reasonType：若在频道被禁言，禁言原因类型，0-未知，1-发广告，2-侮辱，3-政治敏感，4-恐怖主义，5-反动，6-色情，7-其它（errorcode为禁言才有效）。
    forbidEndTime：若在频道被禁言，禁言结束时间（errorcode为禁言才有效）。
    messageID：服务器返回的消息id。

发送自定义消息

可通过YIMMessageManager的SendCustomMessage接口发送自定义消息。异步返回结果通过IYIMMessageCallback的OnSendMessageStatus接口返回。注意：自定义消息可能包含\0终止符，发送和接收时都需要注意。

  • 原型：

    C
        YIMErrorcode SendCustomMessage(const XCHAR* receiverID, YIMChatType chatType, const char* content, unsigned int size, XUINT64 *requestID);

  • 参数：
    receiverID：接收者（用户ID或者频道ID）。
    chatType：聊天类型，私聊/频道聊天，1是私聊，2是频道聊天。
    content：自定义消息内容， 可以包含\0终止符。
    size：自定义消息内容长度。
    requestID：消息序列号，用于校验一条消息发送成功与否的标识。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 回调通知接口：

    C
    class IYIMMessageCallback
{
  public:
  virtual void OnSendMessageStatus(XUINT64 iRequestID, YIMErrorcode errorcode, XUINT64 sendTime, bool isForbidRoom, int reasonType, XUINT64 forbidEndTime, XUINT64 messageID) {}
};

  • 回调参数：
    requestID：消息序列号，用于校验一条消息发送成功与否的标识。
    errorcode：错误码，详细描述见错误码定义。
    sendTime：消息发送时间。
    isForbidRoom：若发送的是频道消息，显示在此频道是否被禁言，true-被禁言，false-未被禁言（errorcode为禁言才有效）。
    reasonType：若在频道被禁言，禁言原因类型，0-未知，1-发广告，2-侮辱，3-政治敏感，4-恐怖主义，5-反动，6-色情，7-其它（errorcode为禁言才有效）。
    forbidEndTime：若在频道被禁言，禁言结束时间（errorcode为禁言才有效）。
    messageID：服务器返回的消息id。

  • 示例：

    C
      char buffer[20] = {0};
  buffer[10] = 1;
  buffer[15] = 2;
  YIMErrorcode ymErrorcode;
  XUINT64 iRequestID=0;
  ymErrorcode = MyIM::Inst()->GetMessageManager()->SendCustomMessage("123456",                                                    YIMChatType::ChatType_PrivateChat,                                                    buffer,                                                    20,                                                    &iRequestID);
  if(ymErrorcode != YIMErrorcode_Success)
  {
      printf("SendTextMessage()  fail，errorcode is %d",  ymErrorcode);
  }

  • 异步回调处理：

    C
       void myIM::OnSendMessageStatus(XUINT64 iRequestID, YIMErrorcode errorcode, XUINT64 sendTime, bool isForbidRoom, int reasonType, XUINT64 forbidEndTime, XUINT64 messageID)
  {
      printf("OnSendMessageStatus request:iRequestID progress errorcode is %llu,  %d:",
          iRequestID,
          errorcode) ;
  }

发送文件消息

发送文件

可通过YIMMessageManager的SendFile接口发送文件消息。

  • 原型：

    C
        YIMErrorcode SendFile(const XCHAR* receiverID, YIMChatType chatType, const XCHAR* filePath, XUINT64* requestID, const XCHAR* extraParam, YIMFileType fileType = FileType_Other);

  • 参数：
    receiverID：接收方id。
    chatType：聊天类型，私聊/频道聊天，1是私聊，2是频道聊天。
    filePath：要发送的文件绝对路径，包括文件名。
    extraParam：额外信息，格式自己定义，自己解析。
    fileType：文件类型，枚举类型，
    FileType.FileType_Other=0 //其它
    FileType.FileType_Audio=1 //音频
    FileType.FileType_Image=2 //图片
    FileType.FileType_Video=3 //视频
    requestID：消息序列号。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 回调通知接口：

    C
    class IYIMMessageCallback
{
  public:
  virtual void OnSendMessageStatus(XUINT64 iRequestID, YIMErrorcode errorcode, XUINT64 sendTime, bool isForbidRoom, int reasonType, XUINT64 forbidEndTime, XUINT64 messageID) {}
};

  • 回调参数：
    requestID：消息序列号，用于校验一条消息发送成功与否的标识。
    errorcode：错误码，详细描述见错误码定义。
    sendTime：发送时间。
    isForbidRoom：是否房间被禁言，true房间被禁言，false玩家被禁言（errorcode为禁言才有效）。
    reasonType：禁言原因，参见YIMForbidSpeakReason（errorcode为禁言才有效）。
    forbidEndTime：禁言截止时间戳（errorcode为禁言才有效）。
    messageID：服务器返回的消息id。

下载文件

接收消息接口参考收消息通过GetMessageType()分拣出文件消息类型：MessageBodyType_File，用GetMessageID()获得消息ID。然后调用YIMMessageManager的DownloadFile接口下载文件。

  • 原型：

    C
        //下载收到的语音消息文件
    YIMErrorcode DownloadFile(XUINT64 messageID, const XCHAR* savePath);

  • 参数：
    messageID：消息ID。
    savePath：文件保存路径（带文件名的全路径），比如"/sdcard/test.wav"如果目录不存在，SDK会自动创建。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMDownloadCallback
{
  public:
  virtual void OnDownload(YIMErrorcode errorcode, std::shared_ptr<IYIMMessage> msg, const XCHAR * savePath) {}
};

  • 回调参数：
    msg：消息结构，IYIMMessage消息基类详细，查看 接收消息备注。
    errorcode：下载结果错误码。
    savePath：保存路径，如果没有权限问题，SDK会尝试自动创建。

消息屏蔽

屏蔽/解除屏蔽用户消息

可通过YIMMessageManager的BlockUser接口屏蔽/解除屏蔽用户消息，若屏蔽用户的消息，此屏蔽用户发送的私聊/频道消息都接收不到。

  • 原型：

    C
        YIMErrorcode BlockUser(const XCHAR* userID, bool block);

  • 参数：
    userID ：需屏蔽/解除屏蔽的用户ID。
    block ：true-屏蔽 false-解除屏蔽。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMMessageCallback
{
  public:
  virtual void OnBlockUser(YIMErrorcode errorcode, const XCHAR* userID, bool block) {}
};

  • 回调参数：
    errorcode ：错误码。
    userID ：用户ID。
    block ：true-屏蔽 false-解除屏蔽。

解除所有已屏蔽用户

可通过YIMMessageManager的UnBlockAllUser接口解除所有已屏蔽消息的用户。

  • 原型：

    C
        YIMErrorcode UnBlockAllUser();

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMMessageCallback
{
  public:
  virtual void OnUnBlockAllUser(YIMErrorcode errorcode) {}
};

  • 回调参数：
    errorcode：错误码。

获取被屏蔽消息用户

可通过YIMMessageManager的GetBlockUsers接口获取被屏蔽消息的用户。

  • 原型：

    C
        YIMErrorcode GetBlockUsers();

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMMessageCallback
{
  public:
  virtual void OnGetBlockUsers(YIMErrorcode errorcode, std::list<XString> userList) {}
};

  • 回调参数：
    errorcode：错误码。
    userList：屏蔽用户ID列表。

消息功能设置

设置消息已读

可通过YIMMessageManager的SetMessageRead接口设置消息为已读。

  • 原型：

    C
        YIMErrorcode SetMessageRead(XUINT64 messageID, bool read);

  • 参数：
    messageID：消息ID。
    read：是否已读，true为已读，false为未读。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

批量设置消息已读

可通过YIMMessageManager的SetAllMessageRead接口批量设置消息为已读。

  • 原型：

    C
        YIMErrorcode SetAllMessageRead(const XCHAR* userID, bool read);

  • 参数：
    userID：发消息的用户ID；用户ID为空字符串时，将登录用户的所有消息设置为已读/未读；用户ID不为空字符串时，将接收的由该用户ID发送的消息设置为已读/未读。
    read：是否已读，true为已读，false为未读。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

切换获取消息模式

可通过YIMMessageManager的SetReceiveMessageSwitch接口切换获取消息模式，在自动接收消息和手动接收消息间切换，默认是自动接收消息。

  • 原型：

    C
        // 是否自动接收消息(true:自动接收(默认)   false:不自动接收消息，有新消息达到时，SDK会发出OnReceiveMessageNotify回调，调用方需要调用GetMessage获取新消息)
    YIMErrorcode SetReceiveMessageSwitch( const std::vector<XString>& vecRoomIDs, bool receive);

  • 参数：
    vecRoomIDs：频道ID的列表。
    receive：true为自动接收消息，false为手动接收消息，默认为true。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义 。

手动获取消息

可通过YIMMessageManager的GetNewMessage接口手动获取消息。
在手动接收消息模式，需要调用该接口后才能收到 OnRecvMessage 通知。

  • 原型：

    C
        YIMErrorcode GetNewMessage( const std::vector<XString>& vecRoomIDs );

  • 参数：
    vecRoomIDs:频道ID。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

新消息通知

在手动接收消息模式，会通知有新消息。

  • 通知接口：

    C
    class IYIMMessageCallback
{
  public:
  virtual void OnReceiveMessageNotify(YIMChatType chatType, const XCHAR* targetID) {}
};

  • 参数：
    chatType：聊天类型，私聊/频道聊天，1是私聊，2是频道聊天。
    targetID：如果是频道聊天，该值为频道ID；私聊该值为空。

消息记录管理

设置是否保存频道聊天记录

可通过YIMMessageManager的SetRoomHistoryMessageSwitch接口设置是否保存频道聊天记录。（默认不保存）

  • 原型：

    C
        YIMErrorcode SetRoomHistoryMessageSwitch(const std::vector<XString>& vecRoomIDs, bool save);

  • 参数：
    vecRoomIDs：频道ID列表。
    save：是否保存频道消息记录（默认不保存）true为保存，false为不保存，默认false。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 单个频道的重载：

C++
virtual YIMErrorcode SetRoomHistoryMessageSwitch(const XCHAR* roomID, bool save) = 0;

roomID 为单个频道 ID，save 的含义、返回值与频道列表版本一致；无独立的设置结果回调。

拉取频道最近聊天记录

可通过YIMMessageManager的QueryRoomHistoryMessageFromServer接口从服务器拉取频道最近的聊天历史记录。

此功能默认不开启，需要的请联系游密开启此服务。

  • 原型：

    C
        YIMErrorcode QueryRoomHistoryMessageFromServer(const XCHAR* roomID, int count = 0, int direction = 0)

  • 参数：
    roomID：频道id。
    count：消息数量(最大30条)。
    directon：历史消息排序方向 0：按时间戳升序 1：按时间戳逆序。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMMessageCallback
{
  public:   
  virtual void OnQueryRoomHistoryMessageFromServer(YIMErrorcode errorcode, const XCHAR* roomID, int remain, std::list<std::shared_ptr<IYIMMessage> >& messageList) {}
};

  • 回调参数：
    errorcode：错误码。
    roomID： 房间ID。
    remain： 剩余消息数量，该参数已弃用，目前返回值都是0。
    messageList：消息列表，IYIMMessage消息基类详细，查看 接收消息备注。

  • 备注：该回调返回的消息记录会包括已屏蔽用户的消息。

按页拉取频道最近聊天记录

从服务器按页拉取频道最近的聊天历史记录。

此功能默认不开启，需要的请联系游密开启此服务。

  • 原型：

    C
    YIMErrorcode QueryRoomHistoryMessageFromServerByPage(const XCHAR* roomID, int count = 0, int direction = 0, XUINT64 lastMessageID = 0)

  • 参数：
    roomID：频道ID。
    count：消息数量(最大30条)。
    directon：历史消息排序方向 0：按时间戳升序 1：按时间戳逆序。
    lastMessageID：上一分页最后消息ID,第一页可传空。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMMessageCallback
{
  public:   
  virtual void OnQueryRoomHistoryMessageFromServer(YIMErrorcode errorcode, const XCHAR* roomID, int remain, std::list<std::shared_ptr<IYIMMessage> >& messageList) {}
};

  • 回调参数：
    errorcode：错误码。
    roomID： 房间ID。
    remain： 剩余消息数量，该参数已弃用，目前返回值都是0。
    messageList：消息列表，IYIMMessage消息基类详细，查看 接收消息备注。

  • 备注：该回调返回的消息记录会包括已屏蔽用户的消息。

本地历史记录管理

查询本地聊天历史记录

可通过YIMMessageManager的QueryHistoryMessage接口查询本地聊天历史记录。

  • 原型：

    C
        YIMErrorcode QueryHistoryMessage(const XCHAR* targetID, YIMChatType chatType, XUINT64 startMessageID = 0, int count = 30, int direction = 0);

  • 参数：
    targetID：用户ID或者频道ID。
    chatType：聊天类型，私聊/频道聊天，1是私聊，2是频道聊天。
    startMessageID：起始历史记录消息id（与requestid不同），为0表示首次查询，将倒序获取count条记录。
    count：最多获取多少条。
    direction：历史记录查询方向，startMessageID=0时,direction使用默认值0；startMessageID>0时，0表示查询比startMessageID小的消息，1表示查询比startMessageID大的消息。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 相关函数： 对于房间本地记录，需要先设置自动保存房间消息。SetRoomHistoryMessageSwitch

  • 异步回调接口：

    C
    class IYIMMessageCallback
{
  public: 
  virtual void OnQueryHistoryMessage(YIMErrorcode errorcode, const XCHAR* targetID, int remain, std::list<std::shared_ptr<IYIMMessage> > messageList) {}
};

  • 回调参数：
    errorcode：错误码。
    targetID：用户ID/频道ID。
    remain：剩余历史消息条数。
    messageList：消息列表，IYIMMessage消息基类详细，查看 接收消息备注。

根据时间清理本地聊天历史记录

可通过YIMMessageManager的DeleteHistoryMessage接口清理本地聊天历史记录。建议定期清理本地历史记录。

  • 原型：

    C
        YIMErrorcode DeleteHistoryMessage(YIMChatType chatType = ChatType_Unknow, XUINT64 time = 0) ;

  • 参数：
    chatType：聊天类型，私聊/频道聊天，1是私聊，2是频道聊天。
    time：Unix timestamp,精确到秒，表示删除这个时间点之前的所有历史记录。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

根据ID清理本地聊天历史记录

可通过YIMMessageManager的DeleteHistoryMessageByID接口清理本地聊天历史记录。建议定期清理本地历史记录。

  • 原型：

    C
        YIMErrorcode DeleteHistoryMessageByID(XUINT64 messageID);

  • 参数：
    messageID：如果指定了大于0的值，将删除指定消息id的历史记录。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

根据用户ID或者频道ID清理指定的本地聊天历史记录

可通过YIMMessageManager的DeleteSpecifiedHistoryMessage接口清理本地聊天历史记录。 可以根据用户ID或频道ID删除对应的本地聊天历史记录,保留消息ID白名单中的消息记录,白名单列表为空时删除与该用户ID或频道ID有关的所有本地聊天记录。

  • 原型：

    C
        YIMErrorcode DeleteSpecifiedHistoryMessage(const XCHAR* targetID, YIMChatType chatType, const std::vector<XUINT64>& excludeMesList);

  • 参数：
    targetID：用户ID或者频道ID。
    chatType：聊天类型，私聊/频道聊天，1是私聊，2是频道聊天。
    excludeMesList：消息ID白名单。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

根据用户ID或频道ID清理本地聊天历史记录

可通过YIMMessageManager的DeleteHistoryMessage接口清理本地聊天历史记录。 可以根据用户ID或者频道ID删除以指定的起始消息ID开始的n条本地聊天历史记录，起始消息ID和消息数量使用默认值时则删除所有消息。

  • 原型：

    C
       YIMErrorcode DeleteHistoryMessage(const XCHAR* targetID, YIMChatType chatType, XUINT64 startMessageID = 0, unsigned int count = 0);

  • 参数：
    targetID：用户ID或者频道ID。
    chatType：聊天类型，私聊/频道聊天，1是私聊，2是频道聊天。
    startMessageID：起始消息ID(默认值0表示最近的一条消息)。
    count：消息数量(默认值0表示删除所有消息)。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

获取最近私聊联系人列表

可通过YIMManager的GetRecentContacts接口获取最近私聊联系人列表，该接口是根据本地历史消息记录生成的最近联系人列表，按最后聊天时间倒序排列。该列表会受清理历史记录消息的接口影响。

  • 原型：

    C
        YIMErrorcode GetRecentContacts();

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMContactCallback
{
  public:   
  virtual void OnGetRecentContacts(YIMErrorcode errorcode, std::list<std::shared_ptr<IYIMContactsMessageInfo> >& contactList) {}
};

  • 回调参数：
    errorcode：错误码。
    contactList：最近联系人列表。

  • 备注：
    IYIMContactsMessageInfo类成员方法如下： GetContactID()：联系人ID。
    GetMessageType()：消息类型，枚举类型，
    MessageBodyType_Unknow = 0, //未知类型
    MessageBodyType_TXT = 1, //文本消息
    MessageBodyType_CustomMesssage = 2, //自定义消息
    MessageBodyType_Emoji = 3, //表情
    MessageBodyType_Image = 4, //图片
    MessageBodyType_Voice = 5, //语音
    MessageBodyType_Video = 6, //视频
    MessageBodyType_File = 7, //文件
    MessageBodyType_Gift = 8 //礼物
    GetMessageContent()：消息内容。
    GetCreateTime()：消息创建时间。
    GetNotReadMsgNum()：未读消息数量（此值有意义需结合SetMessageRead接口使用，可在收到消息后设置消息已读）。
    GetLocalPath()：本地路径（语音或文件消息）。
    GetExtra()：额外信息。

文本翻译

可通过YIMMessageManager的TranslateText接口将文本翻译成指定语言的文本，异步返回结果通过IYIMMessageCallback的OnTranslateTextComplete接口返回。

此功能默认不开启，需要的请联系游密开启此服务。

  • 原型

    C
        YIMErrorcode TranslateText(unsigned int* requestID, const XCHAR* text, LanguageCode destLangCode, LanguageCode srcLangCode = LANG_AUTO);

  • 参数：
    requestID：请求ID(SDK生成返回)。
    text：待翻译文本。
    destLangCode：目标语言编码。
    srcLangCode：原文本语言编码。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMMessageCallback
{
  public:
    void OnTranslateTextComplete(YIMErrorcode errorcode, unsigned int requestID, const XCHAR* text, LanguageCode srcLangCode, LanguageCode destLangCode) {}
};

  • 回调参数：
    errorcode：错误码，等于0才是操作成功。
    requestID：请求ID。
    text：翻译成指定语言的文本。
    srcLangCode：源语言编码。
    destLangCode：目标语言编码。

敏感词过滤

考虑到客户端可能需要传递一些自定义消息，关键字过滤方法就直接提供出来，客户端可以选择是否通过YIMManager的FilterKeyword接口选择是否过滤关键字，并且可以根据匹配到的等级进行过滤。比如level返回的值为'2'表示广告，那么可以在发送时选择不发送，接收方可以选择不展示。

  • 原型：

    C
        static XString FilterKeyword(const XCHAR* text, int* level);

  • 参数：
    text：消息原文。
    level：匹配的策略词等级，默认为0，0表示正常，其余值是按需求可配。

  • 返回值：
    过滤关键字后的消息，敏感字会替换为"*"。

发送消息已读确认

  • 语法：
C++
virtual YIMErrorcode SendMessageReadStatus(const XCHAR* userID, int chatType, XUINT64 messageID) = 0;
  • 功能：

通过 YIMMessageManager 向服务器发送消息已读确认。此接口用于向对端确认已读，与仅修改本地记录的 SetMessageRead 不同。

  • 参数说明：

userID：聊天对象 ID，私聊为对端用户 ID，频道聊天为频道 ID。

chatType：聊天类型，取值对应 YIMChatType。

messageID：已读消息的消息 ID。

  • 返回值：

错误码，0 表示本次调用成功，非 0 表示调用失败，详见错误码定义。

  • 异步回调：

本次确认没有独立结果回调；发送方通过已读状态回调接收更新。

文件上传进度回调

  • 语法：
C++
virtual void OnUploadProgress(XUINT64 requestID, float percent);
  • 功能：

在 IYIMMessageCallback 的实现类中接收文件上传进度，通过 YIMManager::SetMessageCallback 注册该对象。

  • 参数说明：

requestID：本次上传对应的消息序列号。

percent：当前上传百分比。

  • 返回值：

无（void）。

  • 异步回调：

本接口本身是异步通知；上传进度不代表消息发送成功，最终发送结果仍以消息发送结果回调为准。

游密支持将消息及用户登录、登出事件抄送至业务服务端。业务侧需提供 HTTP／HTTPS 接收地址，并联系游密配置所属应用及需要接收的事件类型。具体接入方式参见IM 服务端消息抄送接入指南。

语音消息

语音相关接口支持两种使用流程：通过 IM 将语音消息发送给指定用户或频道；录音并上传后获取文件下载链接，由业务侧自行使用。下文先介绍这两种流程，再介绍语音识别、播放、文件与缓存管理，以及麦克风状态查询。

语音消息收发

  • 调用 SendAudioMessage 或 SendOnlyAudioMessage 开始录音，调用 StopAudioMessage 结束录音并发送，或调用 CancleAudioMessage 取消本次录音。
  • 接收方收到语音消息通知后，可由 SDK 自动下载，或按消息 ID 手动下载音频文件。
  • 下载完成后，可调用 StartPlayAudio 播放语音；相关接口见语音播放。

开始录音并识别文字

可通过YIMMessageManager的SendAudioMessage接口发送带文字识别的语音消息，调用StopAudioMessage接口后自动停止录音并发送，或者调用CancleAudioMessage取消本次消息发送。 注意：语音消息最大的时长是1分钟（超过1分钟就自动发送）

  • 原型：

    C
        // 启动录音带文字识别，开始录制语音消息，支持语音转文本
    YIMErrorcode SendAudioMessage(const XCHAR* receiverID, YIMChatType chatType, XUINT64* requestID);

  • 参数：
    receiverID：接收者ID，私聊传入用户ID，频道聊天传入频道ID。
    chatType：聊天类型，私聊/频道聊天，1是私聊，2是频道聊天。
    requestID：消息序列号，用于校验一条消息发送成功与否的标识。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

开始录音不识别文字

可通过YIMMessageManager的SendOnlyAudioMessage接口开始录音，不进行语音转文字识别。录音结束后调用StopAudioMessage发送语音消息，或调用CancleAudioMessage取消本次录音。

  • 原型：

    C
        //可通过`YIMMessageManager`的`SendOnlyAudioMessage`接口发送不带文字识别的语音消息，调用`StopAudioMessage`接口后自动停止录音并发送，或者调用`CancleAudioMessage`取消本次消息发送。    
    YIMErrorcode SendOnlyAudioMessage(const XCHAR* receiverID, YIMChatType chatType, XUINT64* requestID);

  • 参数：
    receiverID：接收者ID，私聊传入用户ID，频道聊天传入频道ID。
    chatType：聊天类型，私聊/频道聊天，1是私聊，2是频道聊天。
    requestID：消息序列号，用于校验一条消息发送成功与否的标识。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

结束录音并发送

可通过YIMMessageManager的StopAudioMessage结束录音并发送录音文件。

  • 原型：

    C
        YIMErrorcode StopAudioMessage(const XCHAR* extraParam);

  • 参数：
    extraParam：发送语音消息的附加参数，格式自定义，自己解析 （json、xml...），可为空字符串。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口： 结束录音并发送涉及开始发送和发送结果两类回调。开始发送后仍可能失败，不能根据是否收到开始发送回调判断最终结果；最终成功或失败以发送语音结果回调为准。

    C
    class IYIMMessageCallback
{
 public:  
 // 开始上传语音回调，（调用StopAudioMessage停止语音之后，成功发送语音消息之前），录音结束，开始发送录音的通知，这个时候已经可以拿到语音文件进行播放
 virtual void OnStartSendAudioMessage(XUINT64 requestID, YIMErrorcode errorcode, const XCHAR * text, const XCHAR * audioPath, unsigned int audioTime)  {}
};  

 // 发送语音结果回调，自己的语音消息发送成功或者失败的通知
 virtual void OnSendAudioMessageStatus(XUINT64 requestID, YIMErrorcode errorcode, const XCHAR * text, const XCHAR * audioPath, unsigned int audioTime, XUINT64 sendTime, bool isForbidRoom, int reasonType, XUINT64 forbidEndTime, XUINT64 messageID) {}
};

  • 参数：
    errorcode：错误码，YIMErrorcode_Success 或者 YIMErrorcode_PTT_ReachMaxDuration 均表示成功。
    requestID：消息序列号，用于校验一条消息发送成功与否的标识。
    text：语音转文字识别的文本内容，如果没有用带语音转文字的接口，该字段为空字符串。
    audioPath：录音生成的wav文件的本地完整路径，比如"/sdcard/xxx/xxx.wav"。
    audioTime：录音时长（单位为秒）。

    sendTime：语音发送时间。
    isForbidRoom：若发送的是频道消息，表示在此频道是否被禁言，true-被禁言，false-未被禁言（errorcode为禁言才有效）。
    reasonType：禁言原因，0-未知，1-发广告，2-侮辱，3-政治敏感，4-恐怖主义，5-反动，6-色情，7-其它（errorcode为禁言才有效）。
    forbidEndTime：禁言截止时间戳（errorcode为禁言才有效）。
    messageID: 服务器返回的消息id。

取消录音

可通过YIMMessageManager的CancleAudioMessage接口取消本次录音。该接口也适用于录音与上传流程；取消后，此次录音不会上传。

  • 原型：

    C
        YIMErrorcode CancleAudioMessage();

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

设置是否自动下载语音消息

可通过YIMMessageManager的SetDownloadAudioMessageSwitch接口设置是否自动下载语音消息。 SetDownloadAudioMessageSwitch()在初始化之后，启动语音之前调用;若设置了自动下载语音消息，不需再调用DownloadFile()接口，收到语音消息时会自动下载，自动下载完成也会收到DownloadFile()接口对应的OnDownload()回调。

  • 原型：

    C
        YIMErrorcode SetDownloadAudioMessageSwitch(bool download);

  • 参数：
    download ：true-自动下载语音消息，false-不自动下载语音消息(默认)。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

按消息 ID 下载语音

接收消息接口参考收消息通过GetMessageType()分拣出语音消息类型：MessageBodyType_Voice，用GetMessageID()获得消息ID。然后调用YIMMessageManager的DownloadFile接口下载语音消息，然后调用方播放该文件。

  • 原型：

    C
        //下载收到的语音消息文件
    YIMErrorcode DownloadFile(XUINT64 messageID, const XCHAR* savePath);

  • 参数：
    messageID：消息ID。
    savePath：文件保存路径（带文件名的全路径），比如"/sdcard/test.wav"如果目录不存在，SDK会自动创建。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMDownloadCallback
{
  public:
  virtual void OnDownload(YIMErrorcode errorcode, std::shared_ptr<IYIMMessage> msg, const XCHAR * savePath) {}
};

  • 回调参数：
    msg：消息结构，IYIMMessage消息基类详细，查看 接收消息备注。
    errorcode：下载结果错误码。
    savePath：保存路径，如果没有权限问题，SDK会尝试自动创建。

录音与上传

调用 StartAudioSpeech 开始录音，调用 StopAudioSpeech 停止录音并上传。上传结果通过 OnStopAudioSpeechStatus 回调返回，包含音频文件的下载链接，业务侧可自行处理该链接。此流程不会自动发送 IM 消息。

开始录音

可通过YIMMessageManager的StartAudioSpeech接口启动录音。

  • 原型：

    C
        YIMErrorcode StartAudioSpeech(XUINT64* requestID, bool translate = true);

  • 参数：
    requestID：返回消息序列号。
    translate：是否进行语音转文字识别。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

停止录音并上传

可通过YIMMessageManager的StopAudioSpeech接口停止录音并上传，该接口只上传到服务器并异步返回音频文件的下载链接，下载链接指向的是AMR格式的音频文件，不会自动发送 IM 消息。 该接口对应StartAudioSpeech()。

  • 原型：

    C
        YIMErrorcode StopAudioSpeech();

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 取消录音：

    如需取消本次录音，调用取消录音中的 CancleAudioMessage；取消后此次录音不会上传。

  • 异步回调接口：

    C
    class IYIMMessageCallback
{
  public:
  virtual void OnStopAudioSpeechStatus( YIMErrorcode errorcode,std::shared_ptr<IAudioSpeechInfo> audioSpeechInfo ) {}
};

  • 参数：
    errorcode：错误码。
    audioSpeechInfo：录音信息。

  • 备注：
    IAudioSpeechInfo 类成员方法如下：
    GetRequestID()：消息ID。
    GetDownloadURL()：语音文件的下载地址。
    GetAudioTime()：录音时长，单位秒。
    GetFileSize()：文件大小，字节。
    GetLocalPath()：本地语音文件的路径。
    GetText()：语音识别结果，可能为空null or ""。

根据 URL 下载录音文件

可通过YIMMessageManager的DownloadFile接口下载录音文件。

  • 原型：

    C
        YIMErrorcode DownloadFile(const XCHAR* downloadURL, const XCHAR* savePath);

  • 参数：
    downloadURL：语音文件的url地址，从OnStopAudioSpeechStatus回调获得。
    savePath：下载语音文件的本地存放地址,带文件名的全路径。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMDownloadCallback
{
  public:
  virtual void OnDownloadByUrl( YIMErrorcode errorcode, const XString& strFromUrl, const XString& savePath );
};

  • 回调参数：
    errorcode：错误码。
    strFromUrl：下载的语音文件url。
    strSavePath：本地存放地址。

语音识别

设置语音识别的语言，以及是否只获取识别文字。

设置语音识别的语言

SendAudioMessage提供语音识别功能，将语音识别为文字，默认输入语音为普通话，识别文字为简体中文，可通过YIMMessageManager的SetSpeechRecognizeLanguage或SetSpeechRecognizeLanguageByCode函数设置语音识别的语言。

此功能默认不开启，需要的请联系游密开启此服务。

  • 原型：

    C
        YIMErrorcode SetSpeechRecognizeLanguage(SpeechLanguage language);

  • 参数：
    language：语言，枚举类型，
    SPEECHLANG_MANDARIN=0 //普通话
    SPEECHLANG_YUEYU=1 //粤语
    SPEECHLANG_SICHUAN=2 //四川话（windows不支持）
    SPEECHLANG_HENAN=3 //河南话（只支持iOS）
    SPEECHLANG_ENGLISH=4 //英语
    SPEECHLANG_TRADITIONAL=5 //繁体中文

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

按语言代码设置语音识别语言

  • 语法：
C++
virtual YIMErrorcode SetSpeechRecognizeLanguageByCode( const XCHAR* languageCode ) = 0;
  • 功能：

通过 YIMMessageManager 设置 Google 语音识别使用的语言。

  • 参数说明：

languageCode：语言代码，例如英语 en-US。

  • 返回值：

错误码，0 表示本次调用成功，非 0 表示调用失败，详见错误码定义。

  • 异步回调：

无。

设置只识别语音文字

可通过YIMMessageManager的SetOnlyRecognizeSpeechText接口设置只识别语音文字。此功能是为了只获取语音识别的文字，不发送语音消息，接口调用与发送语音消息相同，但在成功录音后仅会收到识别的语音文本通知,不会收到OnSendAudioMessage回调。
实现只识别语音文字功能的接口调用顺序：SetOnlyRecognizeSpeechText->SendAudioMessage->StopAudioMessage->OnGetRecognizeSpeechText。

  • 原型：

    C
        YIMErrorcode SetOnlyRecognizeSpeechText(bool recognition);

  • 参数：
    recognition ：true-只识别语音文字，false-识别语音文字并发送语音消息。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 获取语音识别文本的回调接口：

    C
    class IYIMMessageCallback
{
  public:
  virtual void OnGetRecognizeSpeechText(XUINT64 requestID, YIMErrorcode errorcode, const XCHAR* text) {}
};

  • 回调参数：
    requestID：序列号。
    errorcode：错误码。
    text：返回的语音识别文本内容。

语音播放

播放本地语音文件、控制播放音量和状态，并按业务需要设置语音消息的已播放标记。

播放语音

可通过YIMManager的StartPlayAudio接口播放语音文件，目前只支持WAV格式。

  • 原型：

    C
        YIMErrorcode StartPlayAudio(const XCHAR* path );

  • 参数：
    path： 音频文件绝对路径。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMAudioPlayCallback
{
  public:
  virtual void OnPlayCompletion(YIMErrorcode errorcode, const XCHAR * path) {}
};

  • 参数：
    errorcode：错误码，errorcode == YIMErrorcode_Success表示正常播放结束，errorcode == YIMErrorcode_PTT_CancelPlay表示播放到中途被打断。
    path：被播放的音频文件地址。

停止语音播放

可通过YIMManager的StopPlayAudio接口停止播放语音文件。

  • 原型：

    C
        YIMErrorcode StopPlayAudio();

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

设置语音播放音量

可通过YIMManager的SetVolume接口设置语音的播放音量。

  • 原型：

    C
        void SetVolume( float volume );

  • 参数：
    volume：音量值，取值范围0.0f - 1.0f，默认值为 1.0f。

查询播放状态

可通过YIMManager的IsPlaying接口查询播放状态。

  • 原型：

    C
        bool IsPlaying();

  • 返回值：
    是否正在播放,true正在播放，false没在播放。

将接收的语音消息标记为已播放

可通过YIMMessageManager的SetVoiceMsgPlayed接口将接收的语音消息标记为已播放。该接口只更新消息的播放标记，不会播放音频。

  • 原型：

    C
        YIMErrorcode SetVoiceMsgPlayed(XUINT64 messageID, bool played);

  • 参数：
    messageID：语音消息ID。
    played：是否已播放，true为已播放，false为未播放。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

文件与缓存管理

管理录音缓存目录和下载文件的保存目录。SetDownloadDir 同时适用于语音和普通文件的下载。

设置录音缓存目录

可通过YIMManager的SetAudioCacheDir接口设置录音的缓存目录，如果没有设置，SDK会在APP默认缓存路径下创建一个文件夹用于保存音频文件。 该接口建议初始化之后立即调用 。

  • 原型：

    C
        static void SetAudioCacheDir(const XCHAR* audioCacheDir);

  • 参数：
    audioCacheDir：缓存录音文件的文件夹路径，如果目录不存在，SDK会自动创建。

获取当前设置的录音缓存目录

可通过YIMManager的GetAudioCachePath接口获取当前设置的录音缓存目录。

  • 原型：

    C
        XString GetAudioCachePath();

  • 返回值：
    返回当前设置的录音缓存目录的完整路径,std::string型。

清空录音缓存目录

可通过YIMManager的ClearAudioCachePath接口 清理语音缓存目录(注意清空语音缓存目录后历史记录中会无法读取到音频文件，调用清理历史记录接口也会自动删除对应的音频缓存文件)。

  • 原型：

    C
        bool ClearAudioCachePath();

  • 返回值：
    true：表示清理成功，false：表示清理操作失败。

设置下载保存目录

可通过YIMMessageManager的SetDownloadDir接口设置下载的保存目录。下载保存目录是DownloadFile的默认下载目录，对下载语音消息和文件均适用；设置下载保存目录在初始化之后，启动语音之前调用，若设置了下载保存目录，调用YIMMessageManager的DownloadFile接口时，其中的savePath参数可以为空字符串（若savePath参数为空字符串时，下载语音消息和文件会生成以时间戳为前缀的文件）。

  • 原型：

    C
        YIMErrorcode SetDownloadDir(const XCHAR* path);

  • 参数：
    path：下载目录路径，必须保证该路径可写。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

获取麦克风状态

可通过YIMManager的GetMicrophoneStatus接口获取麦克风的状态。（该接口会临时占用麦克风）。

  • 原型：

    C
        void GetMicrophoneStatus();

  • 异步回调接口：

    C
    class IYIMAudioPlayCallback
{
  public:
  virtual void OnGetMicrophoneStatus(AudioDeviceStatus status) {}
};

  • 回调参数：
    status：麦克风状态值，枚举类型，
    STATUS_AVAILABLE=0 //可用
    STATUS_NO_AUTHORITY=1 //无权限
    STATUS_MUTE=2 //静音
    STATUS_UNAVAILABLE=3 // 不可用

游戏切入后台与恢复

游戏切入后台通知

可通过YIMManager的OnPause接口将游戏切入后台， 建议游戏切入后台时通知该接口，以便于得到更好重连效果； 调用OnPause(false),在游戏切入后台后,若IM是登录状态，依旧接收IM消息； 调用OnPause(true),游戏切入后台，即使IM是登录状态也不会接收IM消息；在游戏恢复运行时会主动拉取暂停期间未接收的消息，收到OnRecvMessage()回调。

  • 原型：

    C
        void OnPause(bool pauseReceiveMessage);

  • 参数：
    pauseReceiveMessage：是否暂停接收IM消息，true-暂停接收 false-不暂停接收。

游戏恢复运行通知

可通过YIMManager的OnResume接口恢复游戏运行。 建议游戏从后台激活到前台时通知该接口，以便于得到更好重连效果。

  • 原型：

    C
        void OnResume();

用户举报和禁言

用户举报

YIMMessageManager的Accusation接口提供举报功能，对用户违规的发言内容进行举报，管理员在后台进行审核处理并将结果通知用户。

  • 原型

    C
        YIMErrorcode Accusation(const XCHAR* userID, YIMChatType source, int reason, const XCHAR* description, const XCHAR* extraParam);

  • 参数：
    userID：被举报用户ID。
    source：来源（私聊/频道，1是私聊，2是频道聊天）。
    reason：原因，由用户自定义枚举。
    description：原因描述。
    extraParam：附加信息JSON格式 ({"nickname":"","server_area":"","level":"","vip_level":""}）。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 举报处理结果通知： 当管理员对举报进行审核处理后，会将举报处理结果通知用户。

  • 原型：

    C
    class IYIMMessageCallback
{
  public:
  virtual void OnAccusationResultNotify(AccusationDealResult result, const XCHAR* userID, unsigned int accusationTime) {}
};

  • 回调参数：
    result：处理结果，枚举类型，
    ACCUSATIONRESULT_IGNORE=0 // 忽略
    ACCUSATIONRESULT_WARNING=1 // 警告
    ACCUSATIONRESULT_FROBIDDEN_SPEAK=2 // 禁言。
    userID：被举报用户ID。
    accusationTime：举报时间。

禁言查询

可通过YIMMessageManager的GetForbiddenSpeakInfo接口查询所在频道的禁言状态。

  • 原型：

    C
        YIMErrorcode GetForbiddenSpeakInfo();

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMMessageCallback
{
  public:      
  virtual void OnGetForbiddenSpeakInfo( YIMErrorcode errorcode, std::vector< std::shared_ptr<IYIMForbidSpeakInfo> > vecForbiddenSpeakInfos ) {}
};

  • 回调参数：
    errorcode：错误码。
    vecForbiddenSpeakInfos：禁言状态列表,每一个代表一个频道的禁言状态。

  • 备注：
    IYIMForbidSpeakInfo 类成员方法如下：
    GetChannelID()：频道ID。
    GetIsForbidRoom()：此频道是否被禁言，true-被禁言，false-未被禁言。
    GetReasonType()：禁言原因类型，0-未知，1-发广告，2-侮辱，3-政治敏感，4-恐怖主义，5-反动，6-色情，7-其它。
    GetEndTime()：若被禁言，禁言结束时间。

公告管理

基本流程：申请开通公告功能->后台添加新公告然后设置公告发送时间,公告消息类型,发送时间,接收公告的频道等->(客户端流程) 设置对应监听-> 调用对应接口->回调接收。

公告功能简述

1.公告发送由后台配置，如类型、周期、发送时间、内容、链接、目标频道、次数、起始结束时间等。

2.公告三种类型：跑马灯，聊天框，置顶公告： (1) 跑马灯，聊天框公告可设置发送时间，次数和间隔（从指定时间点开始隔固定间隔时间发送多次，界面展示及显示时长由客户端决定）； (2) 置顶公告需设置开始和结束时间（该段时间内展示）。

3.三种公告均有一次性、周期性两种循环属性： 一次性公告，到达指定时间点，发送该条公告； 周期性公告，跟一次性公告发送规则一致，但是可以设置发送周期（在每周哪几天的指定时间发送）。

4.跑马灯与聊天框公告只有发送时间点在线的用户才能收到该公告，显示规则由客户端自己决定，两者区别主要是界面显示的区分。

5.置顶公告有显示起始和结束时间，表示该时段内显示，公告发送时间点在线的用户会收到该公告，公告发送时间点未在线用户，在公告显示时段登录，登录后可通过查询公告接口查到该公告。

6.公告撤销 仅针对置顶公告，公告显示时段撤销公告，客户端会收到公告撤销通知，界面进行更新。

接收公告

管理员在后台发布公告，当到达指定时间会收到该公告，界面根据不同类型的公告进行展示。

  • 原型：

    C
    class IYIMNoticeCallback
{
  public:
  virtual void OnRecvNotice(YIMNotice* notice) {}
};

  • 参数：
    notice：公告信息。

  • 备注：
    YIMNotice类成员方法如下：
    GetNoticeID()：公告ID，unsigned long long型。
    GetNoticeType()：公告类型，1-跑马灯公告 2-聊天框公告 3-置顶公告。
    GetChannelID()：发布公告的频道ID。
    GetContent()：公告内容。
    GetLinkText()：公告链接关键字。
    GetLinkAddr()：公告链接地址。
    GetBeginTime()：公告开始时间。
    GetEndTime()：公告结束时间。

撤销公告

对于某些类型的公告（如置顶公告），需要在界面展示一段时间，如果管理员在该时间段执行撤销该公告，会收到撤销公告通知，界面进行相应更新。

  • 原型：

    C
    class IYIMNoticeCallback
{
   public:
   virtual void OnCancelNotice(XUINT64 noticeID, const XCHAR* channelID) {}
};

  • 参数：
    noticeID：公告ID。
    channelID：发布公告的频道ID。

查询公告

公告在配置的时间点下发到客户端，对于某些类型的公告（如置顶公告）需要在某个时间段显示在，如果用户在公告下发时间点未在线，而在公告展示时间段内登录，应用可根据自己的需要决定是否展示该公告，可通过YIMManager的QueryNotice接口查询公告，结果通过上面的OnRecvNotice异步回调返回。

  • 原型：

    C
        YIMErrorcode QueryNotice();

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

地理位置

获取自己当前的地理位置

可通过YIMLocationManager的GetCurrentLocation接口请求获取自己当前地理位置。异步返回结果通过IYIMLocationCallback的OnUpdateLocation接口返回。

  • 原型：

    C
        YIMErrorcode GetCurrentLocation();

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMLocationCallback
{
  public:
  virtual void OnUpdateLocation(YIMErrorcode errorcode, std::shared_ptr<GeographyLocation> location) {}
};

  • 回调参数：
    errorcode：等于0才是操作成功。
    location：当前地理位置及行政区划信息。

  • 备注：
    GeographyLocation类成员方法如下：
    GetDistrictCode()：unsigned int类型，地理区域编码，可根据此参数组合附近频道id。
    GetCountry()：国家。
    GetProvince()：省份。
    GetCity()：城市。
    GetDistrictCounty()：区县。
    GetStreet()：街道。（目前只精确到区县，街道为保留字段）
    GetLongitude()：double类型，经度。
    GetLatitude()：double类型，纬度。

获取附近的人

可通过YIMLocationManager的GetNearbyObjects接口获取自己附近的人，若需要此功能，请联系游密开启LBS服务。若已开启服务，此功能生效的前提是自己和附近的人都获取了自己的地理位置，即调用了IM的获取当前地理位置接口。异步返回结果通过IYIMLocationCallback的OnGetNearbyObjects接口返回。

  • 原型：

    C
        YIMErrorcode GetNearbyObjects(int count, const XCHAR* serverAreaID, DistrictLevel districtlevel = DISTRICT_UNKNOW, bool resetStartDistance = false);

  • 参数：
    count：获取数量（一次最大200个）。
    serverAreaID：区服ID（对应设置用户信息中的区服，如果只需要获得本服务器的，要填；否则填""）。
    districtlevel：行政区划等级，枚举类型，
    DISTRICT_UNKNOW=0 //未知
    DISTRICT_COUNTRY=1 //国家
    DISTRICT_PROVINCE=2 //省份
    DISTRICT_CITY=3 //城市
    DISTRICT_COUNTY=4 //区县
    DISTRICT_STREET=5 //街道
    resetStartDistance：是否重置查找起始距离,true-从距自己0米开始查找，false-从上次查找返回的最远用户开始查找。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMLocationCallback
{
  public:
  virtual void OnGetNearbyObjects(YIMErrorcode errorcode, std::list< std::shared_ptr<RelativeLocation> >  neighbourList, unsigned int startDistance, unsigned int endDistance) {}
};

  • 回调参数：
    errorcode：等于0才是操作成功。
    neighbourList：附近的人地理位置信息列表。
    startDistance：查找起始距离。
    endDistance：查找终止距离。

  • 备注：
    RelativeLocation类成员方法如下：
    GetDistance()：与自己的距离。
    GetLongitude()：经度。
    GetLatitude()：纬度。
    GetUserID()：附近用户ID。
    GetCountry()：国家。
    GetProvince()：省份。
    GetCity()：城市。
    GetDistrictCounty()：区县。
    GetStreet()：街道。（目前只精确到区县，街道为保留字段）

地理位置更新

从资源和耗电方面的考虑，SDK不自动监听地理位置的变化，如果调用方有需要可调用YIMLocationManager的SetUpdateInterval接口设置更新时间间隔，SDK会按设定的时间间隔监听位置变化并通知上层。调用该接口之前，需要调用GetCurrentLocation成功获取自己的地理位置。（如果应用对地理位置变化关注度不大，最好不要设置自动更新）。

  • 原型：

    C
        void SetUpdateInterval(unsigned int interval);

  • 参数：
    interval：时间间隔（单位：分钟）。

获取与指定用户距离

可调用YIMLocationManager的GetDistance接口获取与指定用户距离；获取与指定用户距离之前，需要调用GetCurrentLocation成功获取自己的地理位置，指定的用户也调用GetCurrentLocation成功获取其地理位置。若指定的用户未成功获取到其地理位置，会返回无效的距离。

  • 原型：

    C
        YIMErrorcode GetDistance(const XCHAR* userID);

  • 参数：
    userID：用户ID。

  • 返回值：
    YIMErrorcode：错误码，详细描述见错误码定义。

  • 异步回调接口：

    C
    class IYIMLocationCallback
{
  public:
  virtual void OnGetDistance(YIMErrorcode errorcode, const XCHAR* userID, unsigned int distance) {}
};

  • 回调参数：
    errorcode：错误码。
    userID: 用户ID。
    distance: 距离（米）。

全球布点选择

必须在初始化之前调用， 根据游戏主要发行区域，选择合适的 IM 服务器区域。如果不调用该接口进行设置，默认的服务器区域是中国。

  • 原型：

    C
        static void YIMManager::SetServerZone(ServerZone zone);

  • 参数：
    zone：服务器区域，参考ServerZone枚举说明。

服务器部署地区定义

C
ServerZone.China = 0         // 中国
ServerZone.Singapore = 1     // 新加坡  
ServerZone.America = 2 	   // 美国
ServerZone.HongKong = 3 	   // 香港
ServerZone.Korea = 4 		   // 韩国
ServerZone.Australia = 5     // 澳洲
ServerZone.Deutschland = 6	// 德国
ServerZone.Brazil = 7  		// 巴西
ServerZone.India = 8  		   // 印度
ServerZone.Japan = 9		   // 日本
ServerZone.Ireland = 10	   // 爱尔兰
ServerZone.ServerZone_Unknow = 9999

错误码定义

错误码含义
YIMErrorcode_Success = 0成功
YIMErrorcode_EngineNotInit = 1IM SDK未初始化
YIMErrorcode_NotLogin = 2IM SDK未登录
YIMErrorcode_ParamInvalid = 3无效的参数
YIMErrorcode_TimeOut = 4超时
YIMErrorcode_StatusError = 5状态错误
YIMErrorcode_SDKInvalid = 6Appkey无效
YIMErrorcode_AlreadyLogin = 7已经登录
YIMErrorcode_LoginInvalid = 1001登录无效
YIMErrorcode_ServerError = 8服务器错误
YIMErrorcode_NetError = 9网络错误
YIMErrorcode_LoginSessionError = 10登录状态出错
YIMErrorcode_NotStartUp = 11SDK未启动
YIMErrorcode_FileNotExist = 12文件不存在
YIMErrorcode_SendFileError = 13文件发送出错
YIMErrorcode_UploadFailed = 14文件上传失败,上传失败 一般都是网络限制上传了
YIMErrorcode_UsernamePasswordError = 15,用户名密码错误
YIMErrorcode_UserStatusError = 16,用户状态为无效用户
YIMErrorcode_MessageTooLong = 17,消息太长
YIMErrorcode_ReceiverTooLong = 18,接收方ID过长（检查频道名）
YIMErrorcode_InvalidChatType = 19,无效聊天类型
YIMErrorcode_InvalidReceiver = 20,无效用户ID
YIMErrorcode_UnknowError = 21,未知错误
YIMErrorcode_InvalidAppkey = 22,AppKey无效
YIMErrorcode_ForbiddenSpeak = 23,被禁止发言
YIMErrorcode_CreateFileFailed = 24,创建文件失败
YIMErrorcode_UnsupportFormat = 25,支持的文件格式
YIMErrorcode_ReceiverEmpty = 26,接收方为空
YIMErrorcode_RoomIDTooLong = 27,房间名太长
YIMErrorcode_ContentInvalid = 28,聊天内容严重非法
YIMErrorcode_NoLocationAuthrize = 29,未打开定位权限
YIMErrorcode_UnknowLocation = 30,未知位置
YIMErrorcode_Unsupport = 31,不支持该接口
YIMErrorcode_NoAudioDevice = 32,无音频设备
YIMErrorcode_AudioDriver = 33,音频驱动问题
YIMErrorcode_DeviceStatusInvalid = 34,设备状态错误
YIMErrorcode_ResolveFileError = 35,文件解析错误
YIMErrorcode_ReadWriteFileError = 36,文件读写错误
YIMErrorcode_NoLangCode = 37,语言编码错误
YIMErrorcode_TranslateUnable = 38,翻译接口不可用
YIMErrorcode_SpeechAccentInvalid = 39,语音识别方言无效
YIMErrorcode_SpeechLanguageInvalid = 40,语音识别语言无效
YIMErrorcode_HasIllegalText = 41,消息含非法字符
YIMErrorcode_AdvertisementMessage = 42,消息涉嫌广告
YIMErrorcode_AlreadyBlock = 43,用户已经被屏蔽
YIMErrorcode_NotBlock = 44,用户未被屏蔽
YIMErrorcode_MessageBlocked = 45,消息被屏蔽
YIMErrorcode_LocationTimeout = 46,定位超时
YIMErrorcode_NotJoinRoom = 47,未加入该房间
YIMErrorcode_LoginTokenInvalid = 48,登录token错误
YIMErrorcode_CreateDirectoryFailed = 49,创建目录失败
YIMErrorcode_InitFailed = 50,初始化失败
YIMErrorcode_Disconnect = 51,与服务器断开
YIMErrorcode_TheSameParam = 52,设置参数相同
YIMErrorcode_QueryUserInfoFail = 53,查询用户信息失败
YIMErrorcode_SetUserInfoFail = 54,设置用户信息失败
YIMErrorcode_UpdateUserOnlineStateFail = 55,更新用户在线状态失败
YIMErrorcode_NickNameTooLong = 56,昵称太长(> 64 bytes)
YIMErrorcode_SignatureTooLong = 57,个性签名太长(> 120 bytes)
YIMErrorcode_NeedFriendVerify = 58,要好友验证信息
YIMErrorcode_BeRefuse = 59,添加好友被拒绝
YIMErrorcode_HasNotRegisterUserInfo = 60,未注册用户信息
YIMErrorcode_AlreadyFriend = 61,已经是好友
YIMErrorcode_NotFriend = 62,非好友
YIMErrorcode_NotBlack = 63,不在黑名单中
YIMErrorcode_PhotoUrlTooLong = 64,头像url过长(>500 bytes)
YIMErrorcode_PhotoSizeTooLarge = 65,头像太大（>100 kb）
YIMErrorcode_ChannelMemberOverflow = 66,达到频道人数上限
YIMErrorcode_ALREADYFRIENDS = 1000,服务器错误
YIMErrorcode_LoginInvalid = 1001,服务器错误登录无效
YIMErrorcode_PTT_Start = 2000,开始录音
YIMErrorcode_PTT_Fail = 2001,录音失败
YIMErrorcode_PTT_DownloadFail = 2002,语音消息文件下载失败
YIMErrorcode_PTT_GetUploadTokenFail = 2003,获取语音消息Token失败
YIMErrorcode_PTT_UploadFail = 2004,语音消息文件上传失败
YIMErrorcode_PTT_NotSpeech = 2005,没有录音内容
YIMErrorcode_PTT_DeviceStatusError = 2006,语音设备状态错误
YIMErrorcode_PTT_IsSpeeching = 2007,录音中
YIMErrorcode_PTT_FileNotExist = 2008,文件不存在
YIMErrorcode_PTT_ReachMaxDuration = 2009,达到语音最大时长限制
YIMErrorcode_PTT_SpeechTooShort = 2010,录音时间太短
YIMErrorcode_PTT_StartAudioRecordFailed = 2011,启动录音失败
YIMErrorcode_PTT_SpeechTimeout = 2012,音频输入超时
YIMErrorcode_PTT_IsPlaying = 2013,正在播放
YIMErrorcode_PTT_NotStartPlay = 2014,未开始播放
YIMErrorcode_PTT_CancelPlay = 2015,主动取消播放
YIMErrorcode_PTT_NotStartRecord = 2016,未开始语音
YIMErrorcode_PTT_NotInit = 2017,未初始化
YIMErrorcode_PTT_InitFailed = 2018,初始化失败
YIMErrorcode_PTT_Authorize = 2019,录音权限
YIMErrorcode_PTT_StartRecordFailed = 2020,启动录音失败
YIMErrorcode_PTT_StopRecordFailed = 2021,停止录音失败
YIMErrorcode_PTT_UnsupprtFormat = 2022,不支持的格式
YIMErrorcode_PTT_ResolveFileError = 2023,解析文件错误
YIMErrorcode_PTT_ReadWriteFileError = 2024,读写文件错误
YIMErrorcode_PTT_ConvertFileFailed = 2025,文件转换失败
YIMErrorcode_PTT_NoAudioDevice = 2026,无音频设备
YIMErrorcode_PTT_NoDriver = 2027,驱动问题
YIMErrorcode_PTT_StartPlayFailed = 2028,启动播放失败
YIMErrorcode_PTT_StopPlayFailed = 2029,停止播放失败
YIMErrorcode_PTT_RecognizeFailed = 2030,识别失败
YIMErrorcode_Fail = 10000语音服务启动失败