====== IM SDK详解 ======
本文档将详细介绍云之讯IMSDK和TCPSDK的知识，包括架构、消息体系、消息收发流程等，您可以在阅读本文档后对云之讯IM有更深的了解，方便您更快的开发自己的产品。
{{ :imsdk详解01.png?nolink& }}\\
***IMSDK**
*IMSDk封装了会话、消息等各种IM业务对象，处理IM业务逻辑,对外提供IM业务能力接口。开发者调用SDK接口，快速集成IM业务能力。主要特点是接口清晰，利于理解。
***TCPSDK**
*TCPSDK为IMSDK提供了基本的通信能力,封装登陆云平台、异常重连等功能，并对外提供通信能力接口。IMSDK需要依赖于TCPSDK。
===== 一、IMSDK核心类 =====
**UCSIMClient**是IMSDK的核心类。IMSDK提供的所有能力，都需要通过UCSIMClient的实例去调用。
===== 二、会话实体类 =====
**UCSConversation** 是会话实体类，首先您需要充分的了解 UCSConversation（会话） 和 UCSMessage（消息） 两个实体类的关系。\\
会话实体类是用来存储本地会话的容器类，消息实体类是用来存储本地消息的容器类。会话有多种类型，可以是单聊会话，也可以是群组会话等，每一个 UCSConversation（会话）包含多条 UCSMessage（消息），关系如下图所示：\\
{{ :imsdk详解02.png?nolink& }}\\
通过 conversationType 和 targetId，您可以标识当前账号唯一的一个会话。ConversationType 枚举值意义和对应的 targetId 意义为：
^ 会话类型枚举值 ^ 类型说明 ^ targetId说明 ^
| UCS_IM_SOLOCHAT | 单聊，用户间一对一聊天 | 对方的userId |
| UCS_IM_GROUPCHAT | 群聊 |群Id |
| UCS_IM_DISCUSSIONCHAT | 讨论组聊天 | 讨论组Id |
| UCS_IM_SYSTEMMSG | 系统会话 | 系统账户的Id |
|UCS_IM_Broadcast |广播会话 | 广播账户的Id |
*通过一个 conversationType 和 targetId 组合，您可以确定一个唯一的会话。如当您需要发起单聊会话时，您需要传入 UCS_IM_SOLOCHAT 和 userId，当您需要发起群组聊天时，您需要传入 UCS_IM_GROUPCHAT 和 groupId，当您需要发起讨论组会话时，您需要传入 UCS_IM_DISCUSSIONCHAT 和 discussionId。
===== 三、消息实体类 =====
UCSMessage是一个消息实体类，包含了描述一条消息的所有属性。
*消息对应的会话类型(conversationType)。单聊会话、讨论组会话、群会话等。
*消息的内容类型(messageType)。文本、语音、图片、地图等
*消息接收者(receiveId)。如果这条消息是群组消息，receiveId是群id;如果这条消息是单聊消息，receveId是消息接收者的id;如果这条消息是讨论组消息，receveId是讨论组Id
*消息的唯一标识(messageId)。这个标识在每个账号上是唯一的。
*消息的方向(messageDirection)。这个属性可以用来判断消息是不是自己发出的。
*消息的发送者(senderUserId)。这条消息是谁发的
*发送者的昵称(senderNickName)。这个有可能为空,取决于客户端的APP Server有没有给云之讯平台传对应的昵称。
*消息发送状态(sentStatus)。这条消息的发送状态
*消息接收状态(receivedStatus)。这条消息在本地的接收状态。
*消息内容(content)。这个字段包含一个UCSMsgContent的子类的对象。如果这个会话对应的消息类型是文本，那么这个字段存储的就是一个UCSTextMsg类型的对象；如果是图片，就是一个UCSImageMsg类型的对象；如果是语音，就是一个UCSVoiceMsg类型的对象。开发者可以解析这个对象，然后自定义展示在UI上。
*objectName、extra。这两个是保留字段，暂时未使用。
UCSMessage所有的属性，开发者只需要进行读取就可以，不要进行赋值。
===== 四、消息内容类 =====
==== 1、UCSMsgContent 消息内容基类====
UCSMsgContent是一个消息内容的基类,作为UCSTextMsg、UCSImageMsg等消息内容类的父类。
pushContent 云之讯服务器下发的内容,比如收到一条文本消息，这个pushContent的内容为"您有一条新的文本消息"。
rawData 保留字段，未使用
消息内容类不同于消息实体类（UCSMessage），消息内容类代表一条具体的消息内容，而消息实体类是消息类的外层容器，消息实体对象是消息对象在本地存储的外层对象，消息实体对象除了包含消息对象外，还包括消息的方向、接收状态、接收时间、发送者等。\\
当前版本的消息分两种，普通的内容类消息，和通知类消息，接下来将分别仔细介绍。\\
^ 消息内容分类 ^ 对应的内容类 ^
| 内容类 | 表示一个用户间发送的包含具体内容的消息，需要展现在聊天界面上，如文字消息(UCSTextMsg)、语音消息(UCSVoiceMsg)等。 |
| 通知类 | 表示一个通知信息，可能展现在聊天界面上，如讨论组通知(UCSDiscussionNotification)。 |
==== 2、UCSTextMsg 文本内容类====
UCSTextMsg。用来发送文字类消息，其中可以表情。继承自UCSMsgContent，是一个文本内容类。
content是消息文字内容,您可以传入字节数不大于1500的任意文本。
extra暂时未被使用,您可以直接忽略。
为了使用方便，建议您直接使用类方法initWithContent:构建整个对象。
演示代码如下:
//给id为@"123456789"的用户发送一条文本消息
UCSTextMsg *textMessage = [UCSTextMsg initWithContent:@"文本消息内容,字节长度请不要超过1500"];
[[UCSIMClient sharedIM] sendMessage:UCS_IM_SOLOCHAT receiveId:@"123456789" msgType:UCS_IM_TEXT content:textMessage success:^(long long messageId) {
NSLog(@"文本消息发送成功");
} failure:^(UCSError *error, long long messageId) {
NSLog(@"文本消息发送失败,失败原因error:%@", error);
}];
==== 3、UCSVoiceMsg 语音内容类====
UCSVoiceMsg。语音内容类，继承自UCSMsgContent。发送语音时，填充 amrAudioData、duration这两个字段,voicePath不需要填充。接收语音时 或者 获取聊天记录时，voicePath、duration这两个字段有值,amrAudioData为空。\\
amrAudioData AMR格式的data。(发送语音的时，必填)
voicePath 语音的本地路径。(接收语音时，这个参数存放语音在本地的地址)
duration 语音时长。(发送语音时，必填)
extra 保留字段,暂时未被使用
为了使用方便，建议您直接使用initWithAmrAudioData:duration:构建整个对象。
演示代码如下:
//给id为@"28565844"的讨论组发送一条长度为10s的语音消息
UCSVoiceMsg *voiceMessage = [UCSVoiceMsg initWithAmrAudioData:voiceData duration:10.0];
[[UCSIMClient sharedIM] sendMessage:UCS_IM_DISCUSSIONCHAT receiveId:@"28565844" msgType:UCS_IM_VOICE content:voiceMessage success:^(long long messageId) {
NSLog(@"语音消息发送成功");
} failure:^(UCSError *error, long long messageId) {
NSLog(@"语音消息发送失败,失败原因error:%@", error);
}];
==== 4、UCSImageMsg 图片消息内容类 ====
UCSImageMsg。图片内容类，继承自UCSMsgContent。
thumbnailLocalPath 缩略图本地路径。
imageRemoteUrl 大图的远程url。自己发送的图片消息，这个字段为空。
imageLocalPath 大图的本地路径。收到的图片消息，这个字段为空。
originalImage 原图。(发送图片时，只需要给这个参数赋值就行，其他的参数不需要赋值)。发送时必填。
当收到别人的图片消息时，这个字段为空。获取图片可以通过imageRemoteUrl这个参数自定义下载。
当取出聊天的历史消息时，无论消息是发送的还是接收的，这个参数都为空。
自己发送的图片可以通过imageLocalPath这个参数去获取，接收的图片可以imageRemoteUrl这个参数去获取。
extra 保留字段,暂时未被使用
为了使用方便，建议您直接使用initWithOriginalImage:构建整个对象
演示代码如下:
//给id为@"abc"的群发送一张图片
UIImage *image = [UIImage imageNamed:@"test.jpg"];
UCSImageMsg * imageMessage = [UCSImageMsg initWithOriginalImage:image];
[[UCSIMClient sharedIM] sendMessage:UCS_IM_GROUPCHAT receiveId:@"abc" msgType:UCS_IM_IMAGE content:imageMessage success:^(long long messageId) {
NSLog(@"图片发送成功");
} failure:^(UCSError *error, long long messageId) {
NSLog(@"图片发送失败,失败原因error:%@", error);
}];
====5、UCSLocationMsg 地理位置内容类 ====
UCSLocationMsg。地理位置内容类，继承自UCSMsgContent。
latitude 纬度
longitude 经度
coord_type 坐标类型。如果开发者不使用可以置空。
address 地址信息
thumbnailImage 位置缩略图
为了使用方便，建议您直接使用initWithLatitude:longitude:address:locationImage:coord_type:构建整个对象
演示代码如下:
//给id为@"abc"的群发送一个地理位置信息
UIImage *locationImage = [UIImage imageNamed:@"位置缩略图.jpg"];
UCSLocationMsg *locationMessage = [UCSLocationMsg initWithLatitude:30.00 longitude:30.00 address:@"我的位置" locationImage:locationImage coord_type:nil]
[[UCSIMClient sharedIM] sendMessage:UCS_IM_GROUPCHAT receiveId:@"abc" msgType:UCS_IM_Location content:locationMessage success:^(long long messageId) {
NSLog(@"位置发送成功");
} failure:^(UCSError *error, long long messageId) {
NSLog(@"位置发送失败,失败原因error:%@", error);
}];
====6、UCSCustomMsg 自定义内容类 ====
UCSCustomMsg。自定义内容类。当您发送自定义消息时，需要将需要发送的内容转成NSData类型的字节流，接收者收到的同样是NSData类型的字节流，整个加密解密的过程由开发者自己处理，SDK仅仅作为一个传输的通道。
data 传输的字节流。大小请不要超过64K。
为了使用方便，建议您直接使用initWithData:构建整个对象
//给id为@"123456789"的讨论组发送一条自定义消息。
// base64加密这段文字，GTMBase64是一个开源加密库，开发者可以选择任意加密方式。
NSString *text = @"开发者可以根据自己的需求，将图片、语音、文本等数据加密成NSData类型的数据,构建自定义消息。云之讯SDK只负责传输这条消息，加密、解密的过程完全由开发者完成。"
NSString * base64Str = [GTMBase64 encodeBase64String:text];
NSData * data = [base64Str dataUsingEncoding:NSUTF8StringEncoding];
//构建自定义消息
UCSCustomMsg * customMsg = [[UCSCustomMsg alloc] initWithData:data];
[[UCSIMClient sharedIM] sendMessage:UCS_IM_DISCUSSIONCHAT receiveId:@"123456789" msgType:UCS_IM_Custom content:customMsg success:^(long long messageId) {
NSLog(@"发送成功");
} failure:^(UCSError *error, long long messageId) {
NSLog(@"发送失败,失败原因error:%@", error);
}]
====7、UCSDiscussionNotification 讨论组通知内容类 ====
UCSDiscussionNotification是讨论组通知内容类。讨论组通知由服务器下发，您不需要去发送通知。
operatorId 讨论组的id
extension 扩展字段，用于存储服务器下发扩展信息。比如“张三 移除了 李四”。