HXHG
Jump To… Overview Tasks msgId serverMessageId target targetAppKey fromAppKey fromUser fromType contentType content timestamp fromName targetType status isReceived flag isHaveRead + createSingleMessageWithContent:username: + createGroupMessageWithContent:groupId: + createChatRoomMessageWithContent:chatRoomId: + createGroupMessageWithContent:groupId:at_list: + createGroupAtAllMessageWithContent:groupId: + sendMessage: + sendMessage:optionalContent: + sendSingleTextMessage:toUser: + sendSingleTextMessage:toUser:appKey: + sendSingleImageMessage:toUser: + sendSingleImageMessage:toUser:appKey: + sendSingleVoiceMessage:voiceDuration:toUser: + sendSingleVoiceMessage:voiceDuration:toUser:appKey: + sendSingleFileMessage:fileName:toUser: + sendSingleFileMessage:fileName:toUser:appKey: + sendSingleLocationMessage:longitude:scale:address:toUser: + sendSingleLocationMessage:longitude:scale:address:toUser:appKey: + sendGroupTextMessage:toGroup: + sendGroupImageMessage:toGroup: + sendGroupVoiceMessage:voiceDuration:toGroup: + sendGroupFileMessage:fileName:toGroup: + sendGroupLocationMessage:longitude:scale:address:toGroup: + retractMessage:completionHandler: + forwardMessage:target:optionalContent: + fromJson: - init - isAtMe - isAtAll - getAt_List: - setMessageHaveRead: - getMessageUnreadCount - messageReadDetailHandler: - setFromName: - updateMessageExtraValue:forKey: - updateFlag: - toJsonString - isEqualToMessage:
# JMSGMessage Class Reference
| Inherits from | NSObject |
| Conforms to | NSCopying |
| Declared in | JMSGMessage.h |
## Overview
消息
本类 JMSGMessage 是 JMessage SDK 里的消息实体。 收到的消息、发送的消息、获取历史消息，其中的消息类，都是这个 JMSGMessage。
以下分别描述消息相关主要使用场景。
#### 获取历史消息
先基于聊天对象ID与会话类型，拿到会话对象，然后调用会话对象里的 [JMSGConversation allMessages:] 获取到某会话的全部历史消息列表。
#### 展示一条消息
发送者、接收者等基本属性都有相应的属性。消息内容则在一个 content 对象里，访问时先通过 contentType 拿到内容类型， 然后把 content 转型为相应的具体内容类型，再进一步可拿到具体的信息。
JMSGTextContent textContent = (JMSGTextContent )message.content;NSString msgText = textContent.text;
#### 接收消息
参考 JMessageDelegate 里的说明.
#### 发送消息
参考 JMessageDelegate 里的说明.
## Class APIs 类方法 - 创建与发送消息
### + createSingleMessageWithContent:username:
创建单聊消息（快捷接口）
+ (JMSGMessage \)createSingleMessageWithContent:(JMSGAbstractContent *)content username:(NSString *)username
#### Parameters
#### Declared In
JMSGMessage.h
### + createGroupMessageWithContent:groupId:
创建群聊消息
+ (JMSGMessage *)createGroupMessageWithContent:(JMSGAbstractContent *)content groupId:(NSString *)groupId
#### Parameters
#### Declared In
JMSGMessage.h
### + createChatRoomMessageWithContent:chatRoomId:
创建聊天室消息
+ (JMSGMessage *)createChatRoomMessageWithContent:(JMSGAbstractContent *)content chatRoomId:(NSString *)roomId
#### Parameters
content |
消息内容对象
|
roomId |
聊天室ID
|
#### Discussion
不关心会话时的直接创建聊天消息的接口。一般建议使用 JMSGConversation -> createMessageWithContent:
#### Declared In
JMSGMessage.h
### + createGroupMessageWithContent:groupId:at_list:
创建@人的群聊消息
+ (JMSGMessage *)createGroupMessageWithContent:(JMSGAbstractContent *)content groupId:(NSString *)groupId at_list:(NSArray<__kindofJMSGUser*> *)at_list
#### Parameters
#### Declared In
JMSGMessage.h
### + createGroupAtAllMessageWithContent:groupId:
创建@所有人的群聊消息
+ (JMSGMessage *)createGroupAtAllMessageWithContent:(JMSGAbstractContent *)content groupId:(NSString *)groupId
#### Parameters
#### Declared In
JMSGMessage.h
### + sendMessage:
发送消息（已经创建好的）
+ (void)sendMessage:(JMSGMessage *)message
#### Parameters
#### Discussion
此接口与 createMessage:: 相关接口配合使用，创建好后使用此接口发送。
#### Declared In
JMSGMessage.h
### + sendMessage:optionalContent:
发送消息（附带可选功能，如：控制离线消息存储、自定义通知栏内容、消息已读回执等）
+ (void)sendMessage:(JMSGMessage *)message optionalContent:(JMSGOptionalContent *)optionalContent
#### Parameters
#### Discussion
可选功能里可以设置离线消息存储、自定义通知栏内容、消息已读回执等，具体请查看 JMSGOptionalContent 类。
#### Declared In
JMSGMessage.h
### + sendSingleTextMessage:toUser:
发送单聊文本消息
+ (void)sendSingleTextMessage:(NSString *)text toUser:(NSString *)username
#### Parameters
text |
文本内容
|
username |
单聊对象 username
|
#### Discussion
快捷方法，不需要先创建消息而直接发送。
#### Declared In
JMSGMessage.h
### + sendSingleTextMessage:toUser:appKey:
发送跨应用单聊文本消息
+ (void)sendSingleTextMessage:(NSString *)text toUser:(NSString *)username appKey:(NSString *)userAppKey
#### Parameters
text |
文本内容
|
username |
单聊对象 username
|
#### Discussion
快捷方法，不需要先创建消息而直接发送。
#### Declared In
JMSGMessage.h
### + sendSingleImageMessage:toUser:
发送单聊图片消息
+ (void)sendSingleImageMessage:(NSData *)imageData toUser:(NSString *)username
#### Parameters
imageData |
图片数据
|
username |
单聊对象 username
|
#### Discussion
快捷方法，不需要先创建消息而直接发送。
#### Declared In
JMSGMessage.h
### + sendSingleImageMessage:toUser:appKey:
发送跨应用单聊图片消息
+ (void)sendSingleImageMessage:(NSData *)imageData toUser:(NSString *)username appKey:(NSString *)userAppKey
#### Parameters
imageData |
图片数据
|
username |
单聊对象 username
|
#### Discussion
快捷方法，不需要先创建消息而直接发送。
#### Declared In
JMSGMessage.h
### + sendSingleVoiceMessage:voiceDuration:toUser:
发送单聊语音消息
+ (void)sendSingleVoiceMessage:(NSData *)voiceData voiceDuration:(NSNumber *)duration toUser:(NSString *)username
#### Parameters
voiceData |
语音数据
|
duration |
语音时长
|
username |
单聊对象 username
|
#### Discussion
快捷方法，不需要先创建消息而直接发送。
#### Declared In
JMSGMessage.h
### + sendSingleVoiceMessage:voiceDuration:toUser:appKey:
发送跨应用单聊语音消息
+ (void)sendSingleVoiceMessage:(NSData *)voiceData voiceDuration:(NSNumber *)duration toUser:(NSString *)username appKey:(NSString *)userAppKey
#### Parameters
voiceData |
语音数据
|
duration |
语音时长
|
username |
单聊对象 username
|
#### Discussion
快捷方法，不需要先创建消息而直接发送。
#### Declared In
JMSGMessage.h
### + sendSingleFileMessage:fileName:toUser:
发送单聊文件消息
+ (void)sendSingleFileMessage:(NSData *)fileData fileName:(NSString *)fileName toUser:(NSString *)username
#### Parameters
fileData |
文件数据数据
|
fileName |
文件名
|
username |
单聊对象 username
|
#### Discussion
快捷方法，不需要先创建消息而直接发送。
#### Declared In
JMSGMessage.h
### + sendSingleFileMessage:fileName:toUser:appKey:
发送跨应用单聊文件消息
+ (void)sendSingleFileMessage:(NSData *)fileData fileName:(NSString *)fileName toUser:(NSString *)username appKey:(NSString *)userAppKey
#### Parameters
fileData |
文件数据数据
|
fileName |
文件名
|
username |
单聊对象 username
|
#### Discussion
快捷方法，不需要先创建消息而直接发送。
#### Declared In
JMSGMessage.h
### + sendSingleLocationMessage:longitude:scale:address:toUser:
发送单聊地理位置消息
+ (void)sendSingleLocationMessage:(NSNumber *)latitude longitude:(NSNumber *)longitude scale:(NSNumber *)scale address:(NSString *)address toUser:(NSString *)username
#### Parameters
latitude |
纬度
|
longitude |
经度
|
scale |
缩放比例
|
address |
详细地址
|
username |
单聊对象
|
#### Discussion
快捷方法，不需要先创建消息而直接发送。
#### Declared In
JMSGMessage.h
### + sendSingleLocationMessage:longitude:scale:address:toUser:appKey:
发送跨应用单聊地理位置消息
+ (void)sendSingleLocationMessage:(NSNumber *)latitude longitude:(NSNumber *)longitude scale:(NSNumber *)scale address:(NSString *)address toUser:(NSString *)username appKey:(NSString *)userAppKey
#### Parameters
latitude |
纬度
|
longitude |
经度
|
scale |
缩放比例
|
address |
详细地址
|
username |
单聊对象
|
userAppKey |
单聊对象的appKey
|
#### Discussion
快捷方法，不需要先创建消息而直接发送。
#### Declared In
JMSGMessage.h
### + sendGroupTextMessage:toGroup:
发送群聊文本消息
+ (void)sendGroupTextMessage:(NSString *)text toGroup:(NSString *)groupId
#### Parameters
text |
文本内容
|
groupId |
群聊目标群组ID
|
#### Discussion
快捷方法，不需要先创建消息而直接发送。
#### Declared In
JMSGMessage.h
### + sendGroupImageMessage:toGroup:
发送群聊图片消息
+ (void)sendGroupImageMessage:(NSData *)imageData toGroup:(NSString *)groupId
#### Parameters
imageData |
图片数据
|
groupId |
群聊目标群组ID
|
#### Discussion
快捷方法，不需要先创建消息而直接发送。
#### Declared In
JMSGMessage.h
### + sendGroupVoiceMessage:voiceDuration:toGroup:
发送群聊语音消息
+ (void)sendGroupVoiceMessage:(NSData *)voiceData voiceDuration:(NSNumber *)duration toGroup:(NSString *)groupId
#### Parameters
voiceData |
语音数据
|
duration |
语音时长
|
groupId |
群聊目标群组ID
|
#### Discussion
快捷方法，不需要先创建消息而直接发送。
#### Declared In
JMSGMessage.h
### + sendGroupFileMessage:fileName:toGroup:
发送群聊文件消息
+ (void)sendGroupFileMessage:(NSData *)fileData fileName:(NSString *)fileName toGroup:(NSString *)groupId
#### Parameters
fileData |
文件数据
|
fileName |
文件名
|
groupId |
群聊目标群组ID
|
#### Discussion
快捷方法，不需要先创建消息而直接发送。
#### Declared In
JMSGMessage.h
### + sendGroupLocationMessage:longitude:scale:address:toGroup:
发送群聊地理位置消息
+ (void)sendGroupLocationMessage:(NSNumber *)latitude longitude:(NSNumber *)longitude scale:(NSNumber *)scale address:(NSString *)address toGroup:(NSString *)groupId
#### Parameters
latitude |
纬度
|
longitude |
经度
|
scale |
缩放比例
|
address |
详细地址
|
groupId |
群聊目标群组ID
|
#### Declared In
JMSGMessage.h
### + retractMessage:completionHandler:
消息撤回
+ (void)retractMessage:(JMSGMessage *)message completionHandler:(JMSGCompletionHandler)handler
#### Parameters
message |
需要撤回的消息
|
handler |
结果回调
- resultObject 撤回后的消息
- error 错误信息
|
#### Discussion
注意：SDK可撤回3分钟内的消息
#### Declared In
JMSGMessage.h
### + forwardMessage:target:optionalContent:
消息转发
+ (void)forwardMessage:(JMSGMessage *)message target:(id)target optionalContent:(JMSGOptionalContent *JMSG_NULLABLE)optionalContent
#### Parameters
#### Discussion
注意：只能转发消息状态为 SendSucceed 和 ReceiveSucceed 的消息。
#### Declared In
JMSGMessage.h
## Message basic fields 消息基本属性
### msgId
消息ID：这个 ID 是本地生成的ID，不是服务器端下发时的ID。
@property (nonatomic, strong, readonly) NSString *msgId
#### Declared In
JMSGMessage.h
### serverMessageId
服务器端下发的消息ID.
@property (nonatomic, strong, readonly) NSString *serverMessageId
#### Discussion
一般用于与服务器端跟踪消息.
#### Declared In
JMSGMessage.h
### target
消息发送目标
@property (nonatomic, strong, readonly) id target
#### Discussion
与 [fromUser] 属性相对应. 根据消息方向不同:
- 收到的消息，target 就是我自己。
- 发送的消息，target 是我的聊天对象。 单聊是对方用户; 群聊是聊天群组, 也与当前会话的目标一致 [JMSGConversation target]
#### Declared In
JMSGMessage.h
### targetAppKey
消息发送目标应用
@property (nonatomic, strong, readonly) NSString *targetAppKey
#### Availability
2.1.0
#### Discussion
这是为了支持跨应用聊天, 而新增的字段.
单聊时目标是 username. 当该用户为默认 appKey 时, 则不填此字段. 群聊时目标是 groupId, 不填写此字段.
#### Declared In
JMSGMessage.h
### fromAppKey
消息来源用户 Appkey
@property (nonatomic, strong, readonly) NSString *fromAppKey
#### Availability
2.1.0
#### Discussion
这是为了支持跨应用聊天, 而新增的字段.
不管群聊还是单聊, from_id 都是发送消息的 username. 当该用户是默认 appKey 时, 则不填写此字段.
#### Declared In
JMSGMessage.h
### fromUser
消息来源用户
@property (nonatomic, strong, readonly) JMSGUser *fromUser
#### Discussion
与 [target] 属性相对应. 根据消息方向不同:
- 收到的消息, fromUser 是发出消息的对方. 单聊是聊天对象, 也与当前会话目标用户一致 [JMSGConversation target], 群聊是该条消息的发送用户.
- 发出的消息: fromUser 是我自己.
#### Declared In
JMSGMessage.h
### fromType
消息来源类型
@property (nonatomic, strong, readonly) NSString *fromType
#### Discussion
默认的用户之间互发消息，其值是 “user"。如果是 App 管理员下发的消息，是 "admin”
#### Declared In
JMSGMessage.h
### contentType
消息的内容类型
@property (nonatomic, assign, readonly) JMSGContentType contentType
#### Declared In
JMSGMessage.h
### content
消息内容对象
@property (nonatomic, strong, readonly) JMSGAbstractContent *content
#### Discussion
使用时应通过 contentType 先获取到具体的消息类型，然后转型到相应的具体类。
#### Declared In
JMSGMessage.h
### timestamp
消息发出的时间戳
@property (nonatomic, strong, readonly) NSNumber *timestamp
#### Discussion
这是服务器端下发消息时的真实时间戳，单位为毫秒
#### Declared In
JMSGMessage.h
### fromName
消息中的fromName
@property (nonatomic, strong, readonly) NSString *fromName
#### Discussion
消息的发送方展示名称
#### Declared In
JMSGMessage.h
## Message addOn fields 消息附加属性
### targetType
聊天类型。当前支持的类型：单聊，群聊
@property (nonatomic, assign, readonly) JMSGConversationType targetType
#### Declared In
JMSGMessage.h
### status
消息状态
@property (nonatomic, assign, readonly) JMSGMessageStatus status
#### Discussion
一条发出的消息，或者收到的消息，有多个状态会下。具体定义参考 JMSGMessageStatus 的定义。
#### Declared In
JMSGMessage.h
### isReceived
当前的消息是不是收到的。
@property (nonatomic, assign, readonly) BOOL isReceived
#### Discussion
是收到的，则是别人发给我的。UI 上一般展示在左侧。 如果不是收到侧的，则是发送侧的，是我对外发送的。
主要是在聊天界面展示消息列表时，需要使用此方法，来确认展示消息的方式与位置。 展示时需要发送方消息，不管是收到侧还是发送侧，都可以使用 fromUser 对象。
#### Declared In
JMSGMessage.h
### flag
消息标志
@property (nonatomic, strong, readonly) NSNumber *flag
#### Discussion
这是一个用于表示消息状态的标识字段, App 可自由使用, SDK 不做变更. 默认值为 0, App 有需要时可更新此状态.
使用场景:
- 语音消息有一个未听标志. 默认 0 表示未读, 已读时 App 更新为 1 或者其他.
- 某些 App 需要对一条消息做送达, 已读标志, 可借用这个字段.
#### Declared In
JMSGMessage.h
### isHaveRead
是否已读(只针对接收的消息)
@property (nonatomic, assign, readonly) BOOL isHaveRead
#### Discussion
该属性与实例方法 [-(void)setMessageHaveRead:] 是对应的。
注意：只有发送方调用 [+sendMessage:optionalContent:] 方法设置 message 需要已读回执，此属性才有意义。
#### Declared In
JMSGMessage.h
## Instance APIs 实例方法
### – init
默认的 init 方法不可用
- (instancetype)init
#### Discussion
如果已经得到 JMSGConversation 实例, 则可用以下方法来创建对象:
- conversation -> createMessageWithContent:
- conversation -> createMessageAsyncWithImageContent::
或者不创建 JMSGMessage 实例也可以直接发送消息. 请参考 JMSGConversation 里相关方法.
如果你的 App 不依赖 JMSGConversation 实例, 也可以直接调用 JMSGMessage 里的类方法 来创建 JMSGMessage 实例:
- JMSGMessage -> createSingleMessageWithContent:
- JMSGMessage -> createGroupMessageWithContent:
或者直接也可以调用 JMSGMessage 类方法发消息而不必创建 JMSGMessage 对象.
#### Declared In
JMSGMessage.h
### – isAtMe
是否是@自己的消息（只针对群消息，单聊消息无@功能）
- (BOOL)isAtMe
#### Declared In
JMSGMessage.h
### – isAtAll
是否是@所有人的消息（只针对群消息，单聊消息无@功能）
- (BOOL)isAtAll
#### Declared In
JMSGMessage.h
### – getAt_List:
获取消息体中所有@对象（只针对群消息，单聊消息无@功能）
- (void)getAt_List:(JMSGCompletionHandler)handler
#### Parameters
handler |
结果回调。回调参数：
- resultObject 类型为 NSArray，数组里成员的类型为 JMSGUser 注意：如果该消息为@所有人消息时，resultObject 返回nil，可以通过 isAtAll 接口来判断是否是@所有人的消息
- error 错误信息
如果 error 为 nil, 表示获取成功 如果 error 不为 nil,表示获取失败
|
#### Discussion
从服务器获取，返回消息的所有@对象。
#### Declared In
JMSGMessage.h
### – setMessageHaveRead:
设置为已读
- (void)setMessageHaveRead:(JMSGCompletionHandler)handler
#### Parameters
handler |
回调
- resultObject 返回对应的 message，不过成功失败都会返回 message 对象
- error 不为 nil 表示操作失败
|
#### Discussion
注意: 只针对消息接收方有效
这是一个异步接口;
1、接收方：设置消息为已读状态后，isHaveRead 属性也会被设置为 YES，
2、发送方：会收到消息已读状态变更事件，SDK 会更新消息的未读人数。
注意：只有发送方调用 [+sendMessage:optionalContent:] 方法设置 message 需要已读回执，此方法才有效。
#### Declared In
JMSGMessage.h
### – getMessageUnreadCount
消息未读人数
- (NSInteger)getMessageUnreadCount
#### Discussion
只针对消息发送方有效
注意：只有发送方调用 [+sendMessage:optionalContent:] 方法设置 message 需要已读回执，此方法才有意义。
#### Declared In
JMSGMessage.h
### – messageReadDetailHandler:
已读未读用户列表
- (void)messageReadDetailHandler:(void ( ^ ) ( NSArray *JMSG_NULLABLE readUsers , NSArray *JMSG_NULLABLE unreadUsers , NSError *JMSG_NULLABLE error ))handler
#### Parameters
handler |
结果回调。回调参数:
- unreadUsers 未读用户列表
- readsUsers 读用户列表
- error 不为nil表示出错
|
#### Discussion
只针对消息发送方有效
注意：只有发送方调用 [+sendMessage:optionalContent:] 方法设置 message 需要已读回执，此方法才有意义。
#### Declared In
JMSGMessage.h
### – setFromName:
设置消息的 fromName(即:通知栏的展示名称)
- (void)setFromName:(NSString *JMSG_NULLABLE)fromName
#### Parameters
fromName |
本条消息在接收方通知栏的展示名称
|
#### Discussion
fromName填充在发出的消息体里，对方收到该消息通知时,在通知栏显示的消息发送人名称就是该字段的值.
#### Declared In
JMSGMessage.h
### – updateMessageExtraValue:forKey:
更新 message 中的extra
- (BOOL)updateMessageExtraValue:(id)value forKey:(NSString *)key
#### Parameters
value |
待更新的value,不能为null,类型只能为 NSNumber 和 NSString
|
key |
待更新value对应的key,不能为null
|
#### Discussion
如果 message 中没有该 key 对应的 extra 值，则会插入该新值
#### Declared In
JMSGMessage.h
### – updateFlag:
更新消息标志
- (void)updateFlag:(NSNumber *JMSG_NULLABLE)flag
#### Parameters
#### Discussion
参考 flag property 的说明.
#### Declared In
JMSGMessage.h
### – toJsonString
消息对象转换为 JSON 字符串的表示。
- (NSString *)toJsonString
#### Discussion
遵循 Message JSON 协议的定义。
#### Declared In
JMSGMessage.h
### + fromJson:
JSON 字符串 转换为 消息对象。
+ (JMSGMessage *JMSG_NULLABLE)fromJson:(NSString *JMSG_NONNULL)json
#### Discussion
遵循 Message JSON 协议的定义。失败时返回 nil
#### 注意：尽量不要自己随意拼接 json 字符串去转换，容易导致创建的 message 无法正常发送
#### Declared In
JMSGMessage.h
### – isEqualToMessage:
对象比较
- (BOOL)isEqualToMessage:(JMSGMessage *JMSG_NULLABLE)message
#### Parameters
#### Declared In
JMSGMessage.h
Copyright © 2019 HXHG. All rights reserved. Updated: 2019-01-08
Generated by appledoc 2.2.1 (build 1334).
