IM SDK for Cocos2d-x 使用指南

导入IM SDK

Android

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

对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

修改gradle.properties文件，将"PROP_BUILD_TYPE=cmake"改为"PROP_BUILD_TYPE=ndk-build"。
将 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
修改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.RECORD_AUDIO" />
  <!-- 获取地理位置的权限，可选 -->
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

打开Eclipse，导入上一步的Android工程，在项目中第一个启动的AppActivity中的onCreate中增加以下Java代码： 注意必须把游密的初始化加到第一行，否则可能出现部分机型加载so不正常
```
@Override
protected void onCreate(Bundle bundle)
{
   //下面的两个调用顺序不能错
    com.youme.im.IMEngine.init(this);
    super.onCreate(bundle);           //super.onCreate是默认已经有的，不用再复制
}
```
如果打包或生成APK时需要混淆，则需要在proguard.cfg文件中添加如下代码：
```
 -keep class com.youme.** {*;}
 -keep class com.iflytek.**
 -keepattributes Signature
```

iOS

将yim复制到Cocos2d-x开发工具生成的游戏目录 根目录下。
在Build Settings -> Search Paths -> Header Search Paths中添加头文件路径：../yim/include/。
在Build Settings -> Search Paths -> Framework Search Paths中添加框架文件路径：../yim/lib/ios/。
在Build Settings -> Search Paths -> Library Search Paths中添加库文件路径：../yim/lib/ios/。
在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 -> Frameworks,libraries,and Embedded Content处将其改成Embed & Sign。
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需要。 UniSoundSDKDynamic.xcframework //如果是带云知声语音转文字的sdk需要添加，该库是动态库，需要在General -> Frameworks,libraries,and Embedded Content处将其改成Embed & Sign。 CFNetwork.framework //如果是带云知声语音转文字的sdk需要。
Security.framework //如果是带云知声语音转文字的sdk需要。
libicucore.A.tbd //如果是带云知声语音转文字的sdk需要。
- 如果接入带google语音识别的版本，需在Build Phases ->Copy Bundle Resources 里加入 gRPCCertificates.bundle。
需要为iOS10以上版本添加录音权限配置 iOS 10 使用录音权限，需要在info新加Privacy - Microphone Usage Description键，值为字符串，比如“语音聊天需要录音权限”。首次录音时会向用户申请权限。配置方式如图(选择Private-Microphone Usage Description)。
LBS添加获取地理位置权限 若使用LBS，需要在info新加Privacy - Location Usage Description键，值为字符串，比如“查看附近的玩家需要获取地理位置权限”。首次使用定位时会向用户申请权限，配置方式如上图录音权限。

Windows

将yim复制到Cocos2d-x开发工具生成的游戏目录根目录下。
在项目 -> 属性 -> C/C++ -> 常规 -> 附加包含目录中添加..\yim\include。
拷贝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)。
在项目->属性->链接器->输入->附加依赖库中添加 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平台常用数据类型。开发者需要了解字符串和整数封装后的类型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，通过它获取聊天室、消息管理器。

原型：

  // 获取游密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管理器之后，紧跟着要调用YIMManager的Init接口进行初始化。初始化的函数主要功能是初始化IM SDK引擎。初始化接口的输入参数appKey和appSecurity需要根据实际申请得到的值进行替换, 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后台服务器后即可以正常收发消息。通过YIMManager的Login接口登录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);
  }

用户登出

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

原型：
```
  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() {}
};

用户信息

设置用户的详细信息

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

原型：

  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接口获取指定用户的详细信息。

原型：

  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：用户详细信息。

查询用户在线状态

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

原型：

  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是未注册的，用户状态返回的是离线状态）

频道管理

加入频道

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

原型：

  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.");
     }
  }

离开频道

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

原型：

  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.");
     }
  }

离开所有频道

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

原型：
```
  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。

获取房间成员数量

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

原型：

  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：频道中的成员数量。

消息管理

接收消息

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

原型：

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

发送文本消息

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

原型：

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

群发文本消息

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

原型：

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

参数：
vecReceiver：接受消息的用户id列表。
text：文本消息内容。
返回值：
YIMErrorcode：错误码，详细描述见错误码定义。

发送礼物消息

可通过YIMMessageManager的SendGift接口给主播发送礼物消息，支持在游密主播后台查看礼物消息信息和统计信息。客户端还是通过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, 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终止符，发送和接收时都需要注意。

原型：

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

示例：

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, XUINT64 sendTime, bool isForbidRoom,  int reasonType, XUINT64 forbidEndTime, XUINT64 messageID)
{
    printf("OnSendMessageStatus request:iRequestID progress errorcode is %llu,  %d:",
        iRequestID,
        errorcode) ;
}

发送文件消息

发送文件

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

原型：

  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, 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接口下载文件。

原型：

  //下载收到的语音消息文件
  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音频文件。

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

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

原型：

  YIMErrorcode SetDownloadAudioMessageSwitch(bool download);

参数：
download：true-自动下载语音消息，false-不自动下载语音消息(默认)。
返回值：
YIMErrorcode：错误码，详细描述见错误码定义。

设置语音识别的语言

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

原型：

  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：错误码，详细描述见错误码定义。

发送语音消息

启动录音

可通过YIMMessageManager的SendAudioMessage接口发送带文字识别的语音消息，调用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：错误码，详细描述见错误码定义。

结束录音并发送

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

原型：

  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, 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接口取消语音。

原型：
```
  YIMErrorcode CancleAudioMessage();
```
返回值：
YIMErrorcode：错误码，详细描述见错误码定义。

接收语音消息

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

原型：

  //下载收到的语音消息文件
  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会尝试自动创建。

语音播放

播放语音

可通过YIMManager的StartPlayAudio接口播放语音文件，目前只支持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：被播放的音频文件地址。

停止语音播放

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

原型：
```
  YIMErrorcode StopPlayAudio();
```
返回值：
YIMErrorcode：错误码，详细描述见错误码定义。

设置语音播放音量

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

原型：
```
  void SetVolume( float volume );
```
参数：
volume：音量值，取值范围0.0f - 1.0f，默认值为 1.0f。

查询播放状态

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

原型：
```
  bool IsPlaying();
```
返回值：
是否正在播放,true正在播放，false没在播放。

录音缓存

设置录音缓存目录

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

原型：

  static void SetAudioCacheDir(const XCHAR* audioCacheDir);

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

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

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

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

清空录音缓存目录

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

原型：
```
  bool ClearAudioCachePath();
```
返回值：
true：表示清理成功，false：表示清理操作失败。

设置下载保存目录

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

原型：

  YIMErrorcode SetDownloadDir(const XCHAR* path);

参数：
path：下载目录路径，必须保证该路径可写。
返回值：
YIMErrorcode：错误码，详细描述见错误码定义。

设置只识别语音文字

可通过YIMMessageManager的SetOnlyRecognizeSpeechText接口设置只识别语音文字。此功能是为了只获取语音识别的文字，不发送语音消息，接口调用与发送语音消息相同，但在成功录音后仅会收到识别的语音文本通知,不会收到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：返回的语音识别文本内容。

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

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

原型：

  YIMErrorcode SetVoiceMsgPlayed(XUINT64 messageID, bool played);

参数：
messageID：语音消息ID。
played：是否已播放，true为已播放，false为未播放。
返回值：
YIMErrorcode：错误码，详细描述见错误码定义。

获取麦克风状态

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

原型：
```
  void GetMicrophoneStatus();
```

异步回调接口：

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

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

录音上传

启动录音

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

原型：

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

参数：
requestID：返回消息序列号。
translate：是否进行语音转文字识别。
返回值：
YIMErrorcode：错误码，详细描述见错误码定义。

停止录音并发送

可通过YIMMessageManager的StopAudioSpeech接口停止录音并发送，该接口只上传到服务器并异步返回音频文件的下载链接，下载链接指向的是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下载录音文件

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

原型：

  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：本地存放地址。

消息屏蔽

屏蔽/解除屏蔽用户消息

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

原型：

  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-解除屏蔽。

解除所有已屏蔽用户

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

原型：
```
  YIMErrorcode UnBlockAllUser();
```
返回值：
YIMErrorcode：错误码，详细描述见错误码定义。

异步回调接口：

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

回调参数：
errorcode：错误码。

获取被屏蔽消息用户

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

原型：
```
  YIMErrorcode GetBlockUsers();
```
返回值：
YIMErrorcode：错误码，详细描述见错误码定义。

异步回调接口：

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

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

消息功能设置

设置消息已读

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

原型：

  YIMErrorcode SetMessageRead(XUINT64 messageID, bool read);

参数：
messageID：消息ID。
read：是否已读，true为已读，false为未读。
返回值：
YIMErrorcode：错误码，详细描述见错误码定义。

批量设置消息已读

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

原型：

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

参数：
userID：发消息的用户ID；用户ID为空字符串时，将登录用户的所有消息设置为已读/未读；用户ID不为空字符串时，将接收的由该用户ID发送的消息设置为已读/未读。
read：是否已读，true为已读，false为未读。
返回值：
YIMErrorcode：错误码，详细描述见错误码定义。

切换获取消息模式

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

原型：

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

参数：
vecRoomIDs：频道ID的列表。
receive：true为自动接收消息，false为手动接收消息，默认为true。
返回值：
YIMErrorcode：错误码，详细描述见错误码定义。

手动获取消息

可通过YIMMessageManager的GetNewMessage接口手动获取消息。
在手动接收消息模式，需要调用该接口后才能收到 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；私聊该值为空。

消息记录管理

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

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

原型：

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

参数：
vecRoomIDs：频道ID列表。
save：是否保存频道消息记录（默认不保存）true为保存，false为不保存，默认false。
返回值：
YIMErrorcode：错误码，详细描述见错误码定义。

拉取频道最近聊天记录

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

原型：

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

参数：
roomID：频道id。
count：消息数量(最大30条)。
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：剩余消息数量，该参数已弃用，目前返回值都是0。
messageList：消息列表，IYIMMessage消息基类详细，查看接收消息备注。
备注：该回调返回的消息记录会包括已屏蔽用户的消息。

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

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

原型：

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

参数：
roomID：频道ID。
count：消息数量(最大30条)。
directon：历史消息排序方向 0：按时间戳升序 1：按时间戳逆序。
lastMessageID：上一分页最后消息ID,第一页可传空。
返回值：
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：剩余消息数量，该参数已弃用，目前返回值都是0。
messageList：消息列表，IYIMMessage消息基类详细，查看接收消息备注。
备注：该回调返回的消息记录会包括已屏蔽用户的消息。

本地历史记录管理

查询本地聊天历史记录

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

原型：

  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消息基类详细，查看接收消息备注。

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

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

原型：

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

参数：
chatType：聊天类型，私聊/频道聊天，1是私聊，2是频道聊天。
time：Unix timestamp,精确到秒，表示删除这个时间点之前的所有历史记录。
返回值：
YIMErrorcode：错误码，详细描述见错误码定义。

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

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

原型：

  YIMErrorcode DeleteHistoryMessageByID(XUINT64 messageID);

参数：
messageID：如果指定了大于0的值，将删除指定消息id的历史记录。
返回值：
YIMErrorcode：错误码，详细描述见错误码定义。

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

可通过YIMMessageManager的DeleteSpecifiedHistoryMessage接口清理本地聊天历史记录。可以根据用户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清理本地聊天历史记录

可通过YIMMessageManager的DeleteHistoryMessage接口清理本地聊天历史记录。可以根据用户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：错误码，详细描述见错误码定义。

获取最近私聊联系人列表

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

原型：
```
  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()：额外信息。

高级功能

文本翻译

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

原型

  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：目标语言编码。

敏感词过滤

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

原型：

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

参数：
text：消息原文。
level：匹配的策略词等级，默认为0，0表示正常，其余值是按需求可配。
返回值：
过滤关键字后的消息，敏感字会替换为"*"。

游戏切入后台与恢复

游戏切入后台通知

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

原型：

  void OnPause(bool pauseReceiveMessage);

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

游戏恢复运行通知

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

原型：
```
  void OnResume();
```

用户举报和禁言

用户举报

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

原型

  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：举报时间。

禁言查询

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

原型：

  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。

查询公告

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

原型：
```
  YIMErrorcode QueryNotice();
```
返回值：
YIMErrorcode：错误码，详细描述见错误码定义。

地理位置

获取自己当前的地理位置

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

原型：
```
  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类型，纬度。

获取附近的人

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

原型：

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

原型：

  void SetUpdateInterval(unsigned int interval);

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

获取与指定用户距离

可调用YIMLocationManager的GetDistance接口获取与指定用户距离；获取与指定用户距离之前，需要调用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	语音服务启动失败

选择语言

IM-Cocos2d-C++

开发指引

API Guides

常见问题

服务器RestAPI

IM SDK for Cocos2d-x 使用指南

导入IM SDK

Android

iOS

Windows

特别注意事项

基本接口使用时序图

初始化

包含SDK头文件

数据类型

SDK对象

获取SDK管理器

初始化SDK

设置监听

重连回调

开始重连回调

重连结果回调

录音音量回调

用户管理

用户登录

用户登出

被用户踢出通知

用户信息

设置用户的详细信息

获取指定用户的详细信息

查询用户在线状态

频道管理

加入频道

离开频道

离开所有频道

用户进出频道通知

获取房间成员数量

消息管理

接收消息

发送文本消息

群发文本消息

发送礼物消息

发送自定义消息

发送文件消息

发送文件

下载文件

语音消息管理

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

设置语音识别的语言

发送语音消息

启动录音

结束录音并发送

取消本次录音

接收语音消息

语音播放

播放语音

停止语音播放

设置语音播放音量

查询播放状态

录音缓存

设置录音缓存目录

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

清空录音缓存目录

设置下载保存目录

设置只识别语音文字

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

获取麦克风状态

录音上传

启动录音

停止录音并发送

根据url下载录音文件

消息屏蔽

屏蔽/解除屏蔽用户消息

解除所有已屏蔽用户

获取被屏蔽消息用户

消息功能设置

设置消息已读

批量设置消息已读

切换获取消息模式