IM SDK for Cocos2d-x 使用指南

导入IM SDK

Android

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

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

    
    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和usc.jar是语音识别包,如没有使用语音识别功能则不需要添加;如果项目之前已经有Android-support依赖,可以不用引入包内的android-support-v4.jar。)

    yim.jar
    alisr.jar
    usc.jar
    android-support-v4.jar

  5. 修改proj.android/AndroidManifest.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" />
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
  <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
  <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  <uses-permission android:name="android.permission.READ_PHONE_STATE" />
  <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不正常

    @Override
    protected void onCreate(Bundle bundle)
    {
       //下面的两个调用顺序不能错
        com.youme.im.IMEngine.init(this);
        super.onCreate(bundle);           //super.onCreate是默认已经有的,不用再复制
    }
  2. 如果打包或生成APK时需要混淆,则需要在proguard.cfg文件中添加如下代码:

     -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
    AliyunNlsSdk.framework //如果是带语音转文字的sdk需要添加,该库是动态库,需要在General -> Embedded Binaries也进行添加。
    USCModule.framework //如果是带语音转文字的sdk需要添加。
    libBoringSSL.a //如果是带google语音转文字的sdk需要。
    libgoogleapis.a//如果是带google语音转文字的sdk需要。
    libgRPC-Core.a//如果是带google语音转文字的sdk需要。
    libgRPC-ProtoRPC.a//如果是带google语音转文字的sdk需要。
    libgRPC-RxLibrary.a//如果是带google语音转文字的sdk需要。
    libgRPC.a//如果是带google语音转文字的sdk需要。
    libnanopb.a//如果是带google语音转文字的sdk需要。
    libProtobuf.a//如果是带google语音转文字的sdk需要。

    • 如果接入带google语音识别的版本,需在Build Phases ->Copy Bundle Resources 里加入 gRPCCertificates.bundle
  6. 需要为iOS10以上版本添加录音权限配置 iOS 10 使用录音权限,需要在info新加Privacy - Microphone Usage Description键,值为字符串,比如“语音聊天需要录音权限”。 首次录音时会向用户申请权限。配置方式如图(选择Private-Microphone Usage Description)。 iOS10录音权限配置

  7. 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头文件

#include "YIM.h"

数据类型

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

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,通过它获取聊天室、消息管理器。

  • 原型:

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

  • 示例:

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

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

  • 示例:

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

初始化SDK

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

  • 接口:

      YIMErrorcode Init(const XCHAR* appKey, const XCHAR* appSecurity, const XCHAR* packageName);
  • 参数:
    appKey: 用户游戏产品区别于其它游戏产品的标识,可以在游密官网获取、查看。
    appSecurity: 用户游戏产品的密钥,可以在游密官网获取、查看。
    packageName:游戏包名。

  • 返回:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 示例:

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

设置监听

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

IYIMLoginCallback
IYIMMessageCallback
IYIMChatRoomCallback
IYIMDownloadCallback
IYIMContactCallback
IYIMAudioPlayCallback
IYIMLocationCallback
IYIMReconnectCallback
IYIMNoticeCallback
IYIMFriendCallback
IYIMUserProfileCallback

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

  • 接口原型:

      //登录和登出
      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);
  • 示例:

      //本文档示例中使用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", "");
         }
    
      }

重连回调

开始重连回调

  • 原型:

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

重连结果回调

  • 原型:

    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次。

  • 原型:

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

用户管理

用户登录

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

  • 原型:

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

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    class IYIMLoginCallback
    {
    public:
    virtual void OnLogin(YIMErrorcode errorcode, const XString& userID) {}
    };  
  • 回调参数:
    errorcode:错误码。
    userID:用户ID。

  • 示例:

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

用户登出

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

  • 原型:

      YIMErrorcode Logout();
  • 参数:
    无。

  • 返回:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    class IYIMLoginCallback
    {
    public:
    virtual void OnLogout(YIMErrorcode errorcode) {}
    };  
  • 回调参数:
    errorcode:错误码。

  • 示例:

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

被用户踢出通知

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

  • 原型:

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

用户信息

设置用户的详细信息

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

  • 原型:

      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:错误码,详细描述见错误码定义

获取指定用户的详细信息

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

  • 原型:

      YIMErrorcode GetUserInfo(const XCHAR* userID);
  • 参数:
    userID: 要查询的用户ID。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    class IYIMContactCallback
    {
    public:
      //用户信息字符串, 格式为json {"nickname":"","server_area_id":"","server_area":"","location_id":"","location":"","level":"","vip_level":""}
    virtual void OnGetUserInfo(YIMErrorcode errorcode, const XString& userID, const XString& userInfo) {}
    };  
  • 参数:
    errorcode:错误码。
    userID:用户ID。
    userInfo:用户详细信息。

查询用户在线状态

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

  • 原型:

      YIMErrorcode QueryUserStatus(const XCHAR* userID)
  • 参数:
    userID:要查询的用户ID。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    class IYIMContactCallback
    {
    public:    
    virtual void OnQueryUserStatus(YIMErrorcode errorcode, const XString&  userID, YIMUserStatus status) {}
    };  
  • 回调参数:
    errorcode:错误码,查询请求是否成功的通知。
    userID:查询的用户ID。
    status:登录状态,枚举类型,
    UserStatus.STATUS_ONLINE=0 //在线
    UserStatus.STATUS_OFFLINE=1 //离线
    (如查询的用户ID是未注册的,用户状态返回的是离线状态)

频道管理

加入频道

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

  • 原型:

      YIMErrorcode JoinChatRoom(const XCHAR* chatRoomID);
  • 参数:
    chatRoomID:请求加入的频道ID,仅支持数字、字母、下划线组成的字符串,区分大小写,长度限制为255字节。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    class IYIMChatRoomCallback
    {
    public:
    virtual void OnJoinChatRoom(YIMErrorcode errorcode, const XString&  strChatRoomID) {}
    };  
  • 回调参数:
    errorcode:错误码,详细描述见错误码定义
    strChatRoomID:频道ID。

  • 示例:

      YIMErrorcode ymErrorcode;
      ymErrorcode = MyIM::Inst()->GetChatRoomManager()->JoinChatRoom("123456");
      if( ymErrorcode != YIMErrorcode_Success )
      {
         printf("OnJoinChatRoom()  fail,errorcode is %d",  ymErrorcode);
      }
    
      #异步回调处理
      void MyIM::OnJoinChatRoom(YouMe.YIMErrorcode errorcode,
                               const XString&  strChatRoomID);
      {
         if( errorcode == YIMErrorcode_Success )
         {
            printf("join chat room success.");
         }
      }

离开频道

通过YIMChatRoomManagerLeaveChatRoom接口离开频道。

  • 原型:

      YIMErrorcode LeaveChatRoom(const XCHAR* strChatRoomID);
  • 参数:
    strChatRoomID:请求离开的频道ID。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    class IYIMChatRoomCallback
    {
    public:
    virtual void OnLeaveChatRoom(YIMErrorcode errorcode, const XString& chatRoomID) {}
    };  
  • 回调参数:
    errorcode:错误码,详细描述见错误码定义 chatRoomID:频道ID

  • 示例:

      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 XString&  chatRoomID);
      {
         if( errorcode == YIMErrorcode_Success )
         {
            printf("leave chat room success.");
         }
      }

离开所有频道

通过YIMChatRoomManagerLeaveAllChatRooms接口离开所有频道。

  • 原型:

      YIMErrorcode LeaveAllChatRooms();
  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    class IYIMChatRoomCallback
    {
    public:   
    virtual void OnLeaveAllChatRooms(YIMErrorcode errorcode) {}
    };      
  • 参数:
    errorcode:错误码。

用户进出频道通知

此功能默认不开启,需要的请联系我们开启此服务。联系我们,可以通过专属游密支持群或者技术支持的大群。

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

  • 原型:

    class IYIMChatRoomCallback
    {
    public:
    virtual void OnUserJoinChatRoom(const XString& chatRoomID, const XString& userID) {}
    };  
  • 参数:
    chatRoomID:频道ID。
    userID:用户ID。

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

  • 原型:

    class IYIMChatRoomCallback
    {
    public:
    virtual void OnUserLeaveChatRoom(const XString& chatRoomID, const XString& userID) {}
    };  
  • 参数:
    chatRoomID:频道ID。
    userID:用户ID。

获取房间成员数量

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

  • 原型:

      YIMErrorcode GetRoomMemberCount(const XCHAR* chatRoomID);
  • 参数:
    chatRoomID:频道ID(已成功加入此频道才能获取该频道的人数)。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    class IYIMChatRoomCallback
    {
    public:
    virtual void OnGetRoomMemberCount(YIMErrorcode errorcode, const XString& chatRoomID, unsigned int count) {}
    };  
  • 回调参数:
    errorcode:错误码。
    chatRoomID:频道ID。
    count:频道中的成员数量。

消息管理

接收消息

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

  • 原型:

    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-未播放。

  • 示例:

      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();
        }
      }

发送文本消息

可通过YIMMessageManagerSendTextMessage接口发送文本消息。异步返回结果通过IYIMMessageCallbackOnSendMessageStatus接口返回。

  • 原型:

      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:错误码,详细描述见错误码定义

  • 异步回调接口:

    class IYIMMessageCallback
    { 
    public:
    virtual void OnSendMessageStatus(XUINT64 requestID, YIMErrorcode errorcode, unsigned int 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。

  • 示例:

      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);
     }
  • 异步回调处理:

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

群发文本消息

可通过YIMMessageManagerMultiSendTextMessage接口群发文本消息,每次不要超过200个用户

  • 原型:

      //群发文本消息
      YIMErrorcode MultiSendTextMessage( const std::vector<XString>& vecReceiver, const XCHAR* text)
  • 参数:
    vecReceiver:接受消息的用户id列表。
    text:文本消息内容。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

发送礼物消息

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

  • 原型:

      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:错误码,详细描述见错误码定义

  • 异步回调接口:

    class IYIMMessageCallback
    {
    public:
    virtual void OnSendMessageStatus(XUINT64 requestID, YIMErrorcode errorcode, unsigned int 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。

发送自定义消息

可通过YIMMessageManagerSendCustomMessage接口发送自定义消息。异步返回结果通过IYIMMessageCallbackOnSendMessageStatus接口返回。注意:自定义消息可能包含\0终止符,发送和接收时都需要注意。

  • 原型:

      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:错误码,详细描述见错误码定义

  • 回调通知接口:

    class IYIMMessageCallback
    {
    public:
    virtual void OnSendMessageStatus(XUINT64 iRequestID, YIMErrorcode errorcode, unsigned int 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。

  • 示例:

    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);
    }
  • 异步回调处理:

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

发送文件消息

发送文件

可通过YIMMessageManagerSendFile接口发送文件消息。

  • 原型:

      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:错误码,详细描述见错误码定义

  • 回调通知接口:

    class IYIMMessageCallback
    {
    public:
    virtual void OnSendMessageStatus(XUINT64 iRequestID, YIMErrorcode errorcode, unsigned int 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。然后调用YIMMessageManagerDownloadFile接口下载文件。

  • 原型:

      //下载收到的语音消息文件
      YIMErrorcode DownloadFile(XUINT64 messageID, const XCHAR* savePath);
  • 参数:
    messageID:消息ID。
    savePath:文件保存路径(带文件名的全路径),比如"/sdcard/test.wav"如果目录不存在,SDK会自动创建。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    class IYIMDownloadCallback
    {
    public:
    virtual void OnDownload( YIMErrorcode errorcode, std::shared_ptr<IYIMMessage> msg, const XString& savePath ) {}
    };
  • 回调参数:
    msg:消息结构,IYIMMessage消息基类详细,查看 接收消息备注。
    errorcode:下载结果错误码。
    savePath:保存路径,如果没有权限问题,SDK会尝试自动创建。

语音消息管理

语音消息聊天简要流程:

  • 调用SendAudioMessage方法就开始录音,StopAudioMessage表示结束录音并发送,CancleAudioMessage表示取消本次录音发送。
  • 接收方接收语音消息通知后,调用方控制是否下载,调用下载接口就可以下载音频文件。
  • 开发者调用播放接口播放wav音频文件。

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

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

  • 原型:

      YIMErrorcode SetDownloadAudioMessageSwitch(bool download);
  • 参数:
    download:true-自动下载语音消息,false-不自动下载语音消息(默认)。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

设置语音识别的语言

SendAudioMessage提供语音识别功能,将语音识别为文字,默认输入语音为普通话,识别文字为简体中文,可通过YIMMessageManagerSetSpeechRecognizeLanguage函数设置语音识别的语言。此服务需要联系我们进行配置。

  • 原型:

      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:错误码,详细描述见错误码定义

发送语音消息

启动录音

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

  • 原型:

      // 启动录音带文字识别),开始录制语音消息,支持语音转文本
      YIMErrorcode SendAudioMessage(const XCHAR* receiverID, YIMChatType chatType, XUINT64* requestID);
  • 参数:
    receiverID:接收者ID,私聊传入用户ID,频道聊天传入频道ID。
    chatType:聊天类型,私聊/频道聊天,1是私聊,2是频道聊天。
    requestID:消息序列号,用于校验一条消息发送成功与否的标识。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 原型:

      //可通过`YIMMessageManager`的`SendOnlyAudioMessage`接口发送不带文字识别的语音消息,调用`StopAudioMessage`接口后自动停止录音并发送,或者调用`CancleAudioMessage`取消本次消息发送。    
      YIMErrorcode SendOnlyAudioMessage(const XCHAR* receiverID, YIMChatType chatType, XUINT64* requestID);
  • 参数:
    receiverID:接收者ID,私聊传入用户ID,频道聊天传入频道ID。
    chatType:聊天类型,私聊/频道聊天,1是私聊,2是频道聊天。
    requestID:消息序列号,用于校验一条消息发送成功与否的标识。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义
结束录音并发送

可通过YIMMessageManagerStopAudioMessage结束录音并发送录音文件。

  • 原型:

      YIMErrorcode StopAudioMessage(const XCHAR* extraParam);
  • 参数:
    extraParam:发送语音消息的附加参数,格式自定义,自己解析 (json、xml...),可为空字符串。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口: 结束录音并发送接口对应两个回调接口,若语音成功发送出去能得到两个回调通知,语音发送失败则只会得到发送语音结果回调

    class IYIMMessageCallback
    {
    public:  
    // 开始上传语音回调,(调用StopAudioMessage停止语音之后,成功发送语音消息之前),录音结束,开始发送录音的通知,这个时候已经可以拿到语音文件进行播放
    virtual void OnStartSendAudioMessage(XUINT64 requestID,YIMErrorcode errorcode,const XString& text, const XString& audioPath, unsigned int audioTime)  {}
    };  
    
    // 发送语音结果回调,自己的语音消息发送成功或者失败的通知
    virtual void OnSendAudioMessageStatus(XUINT64 requestID,YIMErrorcode errorcode,const XString& text,const XString& audioPath, unsigned int audioTime, unsigned int 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为禁言才有效)。

取消本次录音

可通过YIMMessageManagerCancleAudioMessage接口取消语音。

  • 原型:

      YIMErrorcode CancleAudioMessage();
  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

接收语音消息

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

  • 原型:

      //下载收到的语音消息文件
      YIMErrorcode DownloadFile(XUINT64 messageID, const XCHAR* savePath);
  • 参数:
    messageID:消息ID。
    savePath:文件保存路径(带文件名的全路径),比如"/sdcard/test.wav"如果目录不存在,SDK会自动创建。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    class IYIMDownloadCallback
    {
    public:
    virtual void OnDownload( YIMErrorcode errorcode, std::shared_ptr<IYIMMessage> msg, const XString& savePath ) {}
    };
  • 回调参数:
    msg:消息结构,IYIMMessage消息基类详细,查看 接收消息备注。
    errorcode:下载结果错误码。
    savePath:保存路径,如果没有权限问题,SDK会尝试自动创建。

语音播放

播放语音

可通过YIMManagerStartPlayAudio接口播放语音文件,目前只支持WAV格式。

  • 原型:

      YIMErrorcode StartPlayAudio(const XCHAR* path );
  • 参数:
    path: 音频文件绝对路径。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    class IYIMAudioPlayCallback
    {
    public:
    virtual void OnPlayCompletion(YIMErrorcode errorcode, const XString& path) {}
    };  
  • 参数:
    errorcode:错误码,errorcode == YIMErrorcode_Success表示正常播放结束,errorcode == YIMErrorcode_PTT_CancelPlay表示播放到中途被打断。
    path:被播放的音频文件地址。
停止语音播放

可通过YIMManagerStopPlayAudio接口停止播放语音文件。

  • 原型:

      YIMErrorcode StopPlayAudio();
  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义
设置语音播放音量

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

  • 原型:

      void SetVolume( float volume );
  • 参数:
    volume:音量值,取值范围0.0f - 1.0f,默认值为 1.0f
查询播放状态

可通过YIMManagerIsPlaying接口查询播放状态。

  • 原型:

      bool IsPlaying();
  • 返回值:
    是否正在播放,true正在播放,false没在播放。

录音缓存

设置录音缓存目录

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

  • 原型:

      static void SetAudioCacheDir(const XCHAR* audioCacheDir);
  • 参数:
    audioCacheDir:缓存录音文件的文件夹路径,如果目录不存在,SDK会自动创建。
获取当前设置的录音缓存目录

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

  • 原型:

      XString GetAudioCachePath();
  • 返回值:
    返回当前设置的录音缓存目录的完整路径,std::string型。
清空录音缓存目录

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

  • 原型:

      bool ClearAudioCachePath();
  • 返回值:
    true:表示清理成功,false:表示清理操作失败。

设置下载保存目录

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

  • 原型:

      YIMErrorcode SetDownloadDir(const XCHAR* path);
  • 参数:
    path:下载目录路径,必须保证该路径可写。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

设置只识别语音文字

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

  • 原型:

      YIMErrorcode SetOnlyRecognizeSpeechText(bool recognition);
  • 参数:
    recognition:true-只识别语音文字,false-识别语音文字并发送语音消息。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

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

    class IYIMMessageCallback
    {
    public:
    virtual void OnGetRecognizeSpeechText(XUINT64 requestID, YIMErrorcode errorcode, const XString& text) {}
    };  
  • 回调参数:
    requestID:序列号。
    errorcode:错误码。
    text:返回的语音识别文本内容。

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

可通过YIMMessageManagerSetVoiceMsgPlayed接口将接收的语音消息标记为已播放。

  • 原型:

      YIMErrorcode SetVoiceMsgPlayed(XUINT64 messageID, bool played);
  • 参数:
    messageID:语音消息ID。
    played:是否已播放,true为已播放,false为未播放。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

获取麦克风状态

可通过YIMManagerGetMicrophoneStatus接口获取麦克风的状态。(该接口会临时占用麦克风)。

  • 原型:

      void GetMicrophoneStatus();
  • 异步回调接口:

    class IYIMAudioPlayCallback
    {
    public:
    virtual void OnGetMicrophoneStatus(AudioDeviceStatus status) {}
    };  
  • 回调参数:
    status:麦克风状态值,枚举类型,
    STATUS_AVAILABLE=0 //可用
    STATUS_NO_AUTHORITY=1 //无权限
    STATUS_MUTE=2 //静音
    STATUS_UNAVAILABLE=3 // 不可用

录音上传

启动录音

可通过YIMMessageManagerStartAudioSpeech接口启动录音。

  • 原型:

      YIMErrorcode StartAudioSpeech(XUINT64* requestID, bool translate = true);
  • 参数:
    requestID:返回消息序列号。
    translate:是否进行语音转文字识别。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

停止录音并发送

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

  • 原型:

      YIMErrorcode StopAudioSpeech();
  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 相关接口: 取消录音,调用该接口后,此次录音不会上传。

      //取消本次录音
      YIMErrorcode MyIM::Inst()-> GetMessageManager()->CancleAudioMessage();
  • 异步回调接口:

    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下载录音文件

可通过YIMMessageManagerDownloadFile接口下载录音文件。

  • 原型:

      YIMErrorcode DownloadFile(const XCHAR* downloadURL, const XCHAR* savePath);
  • 参数:
    downloadURL:语音文件的url地址,从OnStopAudioSpeechStatus回调获得。
    savePath:下载语音文件的本地存放地址,带文件名的全路径。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    class IYIMDownloadCallback
    {
    public:
    virtual void OnDownloadByUrl( YIMErrorcode errorcode, const XString& strFromUrl, const XString& savePath );
    };
  • 回调参数:
    errorcode:错误码。
    strFromUrl:下载的语音文件url。
    strSavePath:本地存放地址。

消息屏蔽

屏蔽/解除屏蔽用户消息

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

  • 原型:

      YIMErrorcode BlockUser(const XCHAR* userID, bool block);
  • 参数:
    userID:需屏蔽/解除屏蔽的用户ID。
    block:true-屏蔽 false-解除屏蔽。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    class IYIMMessageCallback
    {
    public:
    virtual void OnBlockUser(YIMErrorcode errorcode, const XString& userID, bool block) {}
    };  
  • 回调参数:
    errorcode:错误码。
    userID:用户ID。
    block:true-屏蔽 false-解除屏蔽。

解除所有已屏蔽用户

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

  • 原型:

      YIMErrorcode UnBlockAllUser();
  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    class IYIMMessageCallback
    {
    public:
    virtual void OnUnBlockAllUser(YIMErrorcode errorcode) {}
    };  
  • 回调参数:
    errorcode:错误码。

获取被屏蔽消息用户

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

  • 原型:

      YIMErrorcode GetBlockUsers();
  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    class IYIMMessageCallback
    {
    public:
    virtual void OnGetBlockUsers(YIMErrorcode errorcode, std::list<XString> userList) {}
    };  
  • 回调参数:
    errorcode:错误码。
    userList:屏蔽用户ID列表。

消息功能设置

设置消息已读

可通过YIMMessageManagerSetMessageRead接口设置消息为已读。

  • 原型:

      YIMErrorcode SetMessageRead(XUINT64 messageID, bool read);
  • 参数:
    messageID:消息ID。
    read:是否已读,true为已读,false为未读。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

批量设置消息已读

可通过YIMMessageManagerSetAllMessageRead接口批量设置消息为已读。

  • 原型:

      YIMErrorcode SetAllMessageRead(const XCHAR* userID, bool read);
  • 参数:
    userID:发消息的用户ID;用户ID为空字符串时,将登录用户的所有消息设置为已读/未读;用户ID不为空字符串时,将接收的由该用户ID发送的消息设置为已读/未读。
    read:是否已读,true为已读,false为未读。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

切换获取消息模式

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

  • 原型:

      // 是否自动接收消息(true:自动接收(默认)   false:不自动接收消息,有新消息达到时,SDK会发出OnReceiveMessageNotify回调,调用方需要调用GetMessage获取新消息)
      YIMErrorcode SetReceiveMessageSwitch( const std::vector<XString>& vecRoomIDs, bool receive);
  • 参数:
    vecRoomIDs:频道ID的列表。
    receivetrue为自动接收消息,false为手动接收消息,默认为true

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

手动获取消息

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

  • 原型:

      YIMErrorcode GetNewMessage( const std::vector<XString>& vecRoomIDs );
  • 参数:
    vecRoomIDs:频道ID。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

新消息通知

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

  • 通知接口:

    class IYIMMessageCallback
    {
    public:
    virtual void OnReceiveMessageNotify( YIMChatType chatType, const XString& targetID ) {}
    };  
  • 参数:
    chatType:聊天类型,私聊/频道聊天,1是私聊,2是频道聊天。
    targetID:如果是频道聊天,该值为频道ID;私聊该值为空。

消息记录管理

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

可通过YIMMessageManagerSetRoomHistoryMessageSwitch接口设置是否保存频道聊天记录。(默认不保存)

  • 原型:

      YIMErrorcode SetRoomHistoryMessageSwitch(const std::vector<XString>& vecRoomIDs, bool save);
  • 参数:
    vecRoomIDs:频道ID列表。
    save:是否保存频道消息记录(默认不保存)true为保存,false为不保存,默认false。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

拉取频道最近聊天记录

可通过YIMMessageManagerQueryRoomHistoryMessageFromServer接口从服务器拉取频道最近的聊天历史记录。 这个功能默认不开启,需要的请联系我们修改服务器配置。联系我们,可以通过专属游密支持群或者技术支持的大群。

  • 原型:

      YIMErrorcode QueryRoomHistoryMessageFromServer(const XCHAR* roomID, int count = 0, int direction = 0)
  • 参数:
    roomID:频道id。
    count:消息数量(最大200条)。
    directon:历史消息排序方向 0:按时间戳升序 1:按时间戳逆序。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    class IYIMMessageCallback
    {
    public:   
    virtual void OnQueryRoomHistoryMessageFromServer(YIMErrorcode errorcode, const XString& roomID, int remain, std::list<std::shared_ptr<IYIMMessage> >& messageList) {}
    };   
  • 回调参数:
    errorcode:错误码。
    roomID: 房间ID。
    remain: 剩余消息数量。
    messageList:消息列表,IYIMMessage消息基类详细,查看 接收消息备注。

本地历史记录管理

查询本地聊天历史记录

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

  • 原型:

      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

  • 异步回调接口:

    class IYIMMessageCallback
    {
    public: 
    virtual void OnQueryHistoryMessage(YIMErrorcode errorcode, const XString& targetID, int remain, std::list<std::shared_ptr<IYIMMessage> > messageList) {}
    }; 
  • 回调参数:
    errorcode:错误码。
    targetID:用户ID/频道ID。
    remain:剩余历史消息条数。
    messageList:消息列表,IYIMMessage消息基类详细,查看 接收消息备注。
根据时间清理本地聊天历史记录

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

  • 原型:

      YIMErrorcode DeleteHistoryMessage(YIMChatType chatType = ChatType_Unknow, XUINT64 time = 0) ;
  • 参数:
    chatType:聊天类型,私聊/频道聊天,1是私聊,2是频道聊天。
    time:Unix timestamp,精确到秒,表示删除这个时间点之前的所有历史记录。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义
根据ID清理本地聊天历史记录

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

  • 原型:

      YIMErrorcode DeleteHistoryMessageByID(XUINT64 messageID);
  • 参数:
    messageID:如果指定了大于0的值,将删除指定消息id的历史记录。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义
根据用户ID或者频道ID清理指定的本地聊天历史记录

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

  • 原型:

      YIMErrorcode DeleteSpecifiedHistoryMessage(const XCHAR* targetID, YIMChatType chatType, const std::vector<XUINT64>& excludeMesList);
  • 参数:
    targetID:用户ID或者频道ID。
    chatType:聊天类型,私聊/频道聊天,1是私聊,2是频道聊天。
    excludeMesList:消息ID白名单。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义
根据用户ID或频道ID清理本地聊天历史记录

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

  • 原型:

     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:错误码,详细描述见错误码定义
获取最近私聊联系人列表

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

  • 原型:

      YIMErrorcode GetRecentContacts();
  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    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():额外信息。

高级功能

文本翻译

可通过YIMMessageManagerTranslateText接口将文本翻译成指定语言的文本,异步返回结果通过IYIMMessageCallbackOnTranslateTextComplete接口返回。

  • 原型

      YIMErrorcode TranslateText(unsigned int* requestID, const XCHAR* text, LanguageCode destLangCode, LanguageCode srcLangCode = LANG_AUTO);
  • 参数:
    requestID:请求ID(SDK生成返回)。
    text:待翻译文本。
    destLangCode:目标语言编码。
    srcLangCode:原文本语言编码。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    class IYIMMessageCallback
    {
    public:
      void OnTranslateTextComplete(YIMErrorcode errorcode, unsigned int requestID, const XString& text, LanguageCode srcLangCode, LanguageCode destLangCode) {}
    };    
  • 回调参数:
    errorcode:错误码,等于0才是操作成功。
    requestID:请求ID。
    text:翻译成指定语言的文本。
    srcLangCode:源语言编码。
    destLangCode:目标语言编码。

敏感词过滤

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

  • 原型:

      static XString FilterKeyword(const XCHAR* text, int* level);
  • 参数:
    text:消息原文。
    level:匹配的策略词等级,默认为0,0表示正常,其余值是按需求可配。

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

游戏切入后台与恢复

游戏切入后台通知

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

  • 原型:

      void OnPause(bool pauseReceiveMessage);
  • 参数:
    pauseReceiveMessage:是否暂停接收IM消息,true-暂停接收 false-不暂停接收。

游戏恢复运行通知

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

  • 原型:

      void OnResume();

用户举报和禁言

用户举报

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

  • 原型

      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:错误码,详细描述见错误码定义

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

  • 原型:

    class IYIMMessageCallback
    {
    public:
    virtual void OnAccusationResultNotify(AccusationDealResult result, const XString& userID, unsigned int accusationTime) {}
    };  
  • 回调参数:
    result:处理结果,枚举类型,
    ACCUSATIONRESULT_IGNORE=0 // 忽略
    ACCUSATIONRESULT_WARNING=1 // 警告
    ACCUSATIONRESULT_FROBIDDEN_SPEAK=2 // 禁言。
    userID:被举报用户ID。
    accusationTime:举报时间。

禁言查询

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

  • 原型:

      YIMErrorcode GetForbiddenSpeakInfo(); 
  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    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.公告撤销 仅针对置顶公告,公告显示时段撤销公告,客户端会收到公告撤销通知,界面进行更新。

接收公告

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

  • 原型:

    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():公告结束时间。

撤销公告

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

  • 原型:

    class IYIMNoticeCallback
    {
     public:
     virtual void OnCancelNotice(XUINT64 noticeID, const XString& channelID) {}
    };   
  • 参数:
    noticeID:公告ID。
    channelID:发布公告的频道ID。

查询公告

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

  • 原型:

      YIMErrorcode QueryNotice();
  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

地理位置

获取自己当前的地理位置

可通过YIMLocationManagerGetCurrentLocation接口请求获取自己当前地理位置。异步返回结果通过IYIMLocationCallbackOnUpdateLocation接口返回。

  • 原型:

      YIMErrorcode GetCurrentLocation();
  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    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类型,纬度。

获取附近的人

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

  • 原型:

      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:错误码,详细描述见错误码定义

  • 异步回调接口:

    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不自动监听地理位置的变化,如果调用方有需要可调用YIMLocationManagerSetUpdateInterval接口设置更新时间间隔,SDK会按设定的时间间隔监听位置变化并通知上层。调用该接口之前,需要调用GetCurrentLocation成功获取自己的地理位置。(如果应用对地理位置变化关注度不大,最好不要设置自动更新)。

  • 原型:

      void SetUpdateInterval(unsigned int interval);
  • 参数:
    interval:时间间隔(单位:分钟)。

获取与指定用户距离

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

  • 原型:

      YIMErrorcode GetDistance(const XCHAR* userID);
  • 参数:
    userID:用户ID。

  • 返回值:
    YIMErrorcode:错误码,详细描述见错误码定义

  • 异步回调接口:

    class IYIMLocationCallback
    {
    public:
    virtual void OnGetDistance(YIMErrorcode errorcode, const XString& userID, unsigned int distance) {}
    };  
  • 回调参数:
    errorcode:错误码。
    userID: 用户ID。
    distance: 距离(米)。

全球布点选择

必须在初始化之前调用, 根据游戏主要发行区域,选择合适的 IM 服务器区域。

  • 原型:

      static void YIMManager::SetServerZone(ServerZone zone);
  • 参数:
    zone:服务器区域,参考ServerZone枚举说明。

服务器部署地区定义

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 = 1 IM SDK未初始化
YIMErrorcode_NotLogin = 2 IM SDK未登录
YIMErrorcode_ParamInvalid = 3 无效的参数
YIMErrorcode_TimeOut = 4 超时
YIMErrorcode_StatusError = 5 状态错误
YIMErrorcode_SDKInvalid = 6 Appkey无效
YIMErrorcode_AlreadyLogin = 7 已经登录
YIMErrorcode_LoginInvalid = 1001 登录无效
YIMErrorcode_ServerError = 8 服务器错误
YIMErrorcode_NetError = 9 网络错误
YIMErrorcode_LoginSessionError = 10 登录状态出错
YIMErrorcode_NotStartUp = 11 SDK未启动
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 语音服务启动失败