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 *)usernameParameters
content |
消息内容对象 |
|---|---|
username |
单聊用户 username 注意：1、单独调用此接口创建消息，SDK 不会本地保存消息，再调用发送接口时才会保存； 2、如果上层希望创建消息时就本地化保存，请使用 [JMSGConversation createMessageWithContent:] |
Declared In
JMSGMessage.h
+ createGroupMessageWithContent:groupId:
创建群聊消息
+ (JMSGMessage *)createGroupMessageWithContent:(JMSGAbstractContent *)content groupId:(NSString *)groupIdParameters
content |
消息内容对象 |
|---|---|
groupId |
群聊ID 注意：1、单独调用此接口创建消息，SDK 不会本地保存消息，再调用发送接口时才会保存； 2、如果上层希望创建消息时就本地化保存，请使用 [JMSGConversation createMessageWithContent:] |
Declared In
JMSGMessage.h
+ createChatRoomMessageWithContent:chatRoomId:
创建聊天室消息
+ (JMSGMessage *)createChatRoomMessageWithContent:(JMSGAbstractContent *)content chatRoomId:(NSString *)roomIdParameters
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_listParameters
content |
消息内容对象 |
|---|---|
groupId |
群聊ID |
at_list |
@对象的数组 注意：1、单独调用此接口创建消息，SDK 不会本地保存消息，再调用发送接口时才会保存； 2、如果上层希望创建消息时就本地化保存，请使用 [JMSGConversation createMessageWithContent:] |
Declared In
JMSGMessage.h
+ createGroupAtAllMessageWithContent:groupId:
创建@所有人的群聊消息
+ (JMSGMessage *)createGroupAtAllMessageWithContent:(JMSGAbstractContent *)content groupId:(NSString *)groupIdParameters
content |
消息内容对象 |
|---|---|
groupId |
群聊ID 注意：1、单独调用此接口创建消息，SDK 不会本地保存消息，再调用发送接口时才会保存； 2、如果上层希望创建消息时就本地化保存，请使用 [JMSGConversation createMessageWithContent:] |
Declared In
JMSGMessage.h
+ sendMessage:
发送消息（已经创建好的）
+ (void)sendMessage:(JMSGMessage *)messageParameters
message |
消息对象。 |
|---|
Discussion
此接口与 createMessage:: 相关接口配合使用，创建好后使用此接口发送。
Declared In
JMSGMessage.h
+ sendMessage:optionalContent:
发送消息（附带可选功能，如：控制离线消息存储、自定义通知栏内容、消息已读回执等）
+ (void)sendMessage:(JMSGMessage *)message optionalContent:(JMSGOptionalContent *)optionalContentParameters
message |
通过消息创建类接口，创建好的消息对象 |
|---|---|
optionalContent |
可选功能，具体请查看 JMSGOptionalContent 类 |
Discussion
可选功能里可以设置离线消息存储、自定义通知栏内容、消息已读回执等，具体请查看 JMSGOptionalContent 类。
Declared In
JMSGMessage.h
+ sendSingleTextMessage:toUser:
发送单聊文本消息
+ (void)sendSingleTextMessage:(NSString *)text toUser:(NSString *)usernameParameters
text |
文本内容 |
|---|---|
username |
单聊对象 username |
Discussion
快捷方法，不需要先创建消息而直接发送。
Declared In
JMSGMessage.h
+ sendSingleTextMessage:toUser:appKey:
发送跨应用单聊文本消息
+ (void)sendSingleTextMessage:(NSString *)text toUser:(NSString *)username appKey:(NSString *)userAppKeyParameters
text |
文本内容 |
|---|---|
username |
单聊对象 username |
userAppKey |
单聊对象 appkey |
Discussion
快捷方法，不需要先创建消息而直接发送。
Declared In
JMSGMessage.h
+ sendSingleImageMessage:toUser:
发送单聊图片消息
+ (void)sendSingleImageMessage:(NSData *)imageData toUser:(NSString *)usernameParameters
imageData |
图片数据 |
|---|---|
username |
单聊对象 username |
Discussion
快捷方法，不需要先创建消息而直接发送。
Declared In
JMSGMessage.h
+ sendSingleImageMessage:toUser:appKey:
发送跨应用单聊图片消息
+ (void)sendSingleImageMessage:(NSData *)imageData toUser:(NSString *)username appKey:(NSString *)userAppKeyParameters
imageData |
图片数据 |
|---|---|
username |
单聊对象 username |
userAppKey |
单聊对象 appkey |
Discussion
快捷方法，不需要先创建消息而直接发送。
Declared In
JMSGMessage.h
+ sendSingleVoiceMessage:voiceDuration:toUser:
发送单聊语音消息
+ (void)sendSingleVoiceMessage:(NSData *)voiceData voiceDuration:(NSNumber *)duration toUser:(NSString *)usernameParameters
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 *)userAppKeyParameters
voiceData |
语音数据 |
|---|---|
duration |
语音时长 |
username |
单聊对象 username |
userAppKey |
单聊对象 appkey |
Discussion
快捷方法，不需要先创建消息而直接发送。
Declared In
JMSGMessage.h
+ sendSingleFileMessage:fileName:toUser:
发送单聊文件消息
+ (void)sendSingleFileMessage:(NSData *)fileData fileName:(NSString *)fileName toUser:(NSString *)usernameParameters
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 *)userAppKeyParameters
fileData |
文件数据数据 |
|---|---|
fileName |
文件名 |
username |
单聊对象 username |
userAppKey |
单聊对象 appkey |
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 *)usernameParameters
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 *)userAppKeyParameters
latitude |
纬度 |
|---|---|
longitude |
经度 |
scale |
缩放比例 |
address |
详细地址 |
username |
单聊对象 |
userAppKey |
单聊对象的appKey |
Discussion
快捷方法，不需要先创建消息而直接发送。
Declared In
JMSGMessage.h
+ sendGroupTextMessage:toGroup:
发送群聊文本消息
+ (void)sendGroupTextMessage:(NSString *)text toGroup:(NSString *)groupIdParameters
text |
文本内容 |
|---|---|
groupId |
群聊目标群组ID |
Discussion
快捷方法，不需要先创建消息而直接发送。
Declared In
JMSGMessage.h
+ sendGroupImageMessage:toGroup:
发送群聊图片消息
+ (void)sendGroupImageMessage:(NSData *)imageData toGroup:(NSString *)groupIdParameters
imageData |
图片数据 |
|---|---|
groupId |
群聊目标群组ID |
Discussion
快捷方法，不需要先创建消息而直接发送。
Declared In
JMSGMessage.h
+ sendGroupVoiceMessage:voiceDuration:toGroup:
发送群聊语音消息
+ (void)sendGroupVoiceMessage:(NSData *)voiceData voiceDuration:(NSNumber *)duration toGroup:(NSString *)groupIdParameters
voiceData |
语音数据 |
|---|---|
duration |
语音时长 |
groupId |
群聊目标群组ID |
Discussion
快捷方法，不需要先创建消息而直接发送。
Declared In
JMSGMessage.h
+ sendGroupFileMessage:fileName:toGroup:
发送群聊文件消息
+ (void)sendGroupFileMessage:(NSData *)fileData fileName:(NSString *)fileName toGroup:(NSString *)groupIdParameters
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 *)groupIdParameters
latitude |
纬度 |
|---|---|
longitude |
经度 |
scale |
缩放比例 |
address |
详细地址 |
groupId |
群聊目标群组ID |
Declared In
JMSGMessage.h
+ retractMessage:completionHandler:
消息撤回
+ (void)retractMessage:(JMSGMessage *)message completionHandler:(JMSGCompletionHandler)handlerParameters
message |
需要撤回的消息 |
|---|---|
handler |
结果回调
|
Discussion
注意：SDK可撤回3分钟内的消息
Declared In
JMSGMessage.h
+ forwardMessage:target:optionalContent:
消息转发
+ (void)forwardMessage:(JMSGMessage *)message target:(id)target optionalContent:(JMSGOptionalContent *JMSG_NULLABLE)optionalContentParameters
message |
需要转发的消息 |
|---|---|
target |
|
optionalContent |
可选功能，具体请查看 JMSGOptionalContent 类 |
Discussion
注意：只能转发消息状态为 SendSucceed 和 ReceiveSucceed 的消息。
Declared In
JMSGMessage.h
Message basic fields 消息基本属性
msgId
消息ID：这个 ID 是本地生成的ID，不是服务器端下发时的ID。
@property (nonatomic, strong, readonly) NSString *msgIdDeclared In
JMSGMessage.h
serverMessageId
服务器端下发的消息ID.
@property (nonatomic, strong, readonly) NSString *serverMessageIdDiscussion
一般用于与服务器端跟踪消息.
Declared In
JMSGMessage.h
target
消息发送目标
@property (nonatomic, strong, readonly) id targetDiscussion
与 [fromUser] 属性相对应. 根据消息方向不同:
- 收到的消息，target 就是我自己。
- 发送的消息，target 是我的聊天对象。 单聊是对方用户; 群聊是聊天群组, 也与当前会话的目标一致 [JMSGConversation target]
Declared In
JMSGMessage.h
targetAppKey
消息发送目标应用
@property (nonatomic, strong, readonly) NSString *targetAppKeyAvailability
2.1.0
Discussion
这是为了支持跨应用聊天, 而新增的字段.
单聊时目标是 username. 当该用户为默认 appKey 时, 则不填此字段. 群聊时目标是 groupId, 不填写此字段.
Declared In
JMSGMessage.h
fromAppKey
消息来源用户 Appkey
@property (nonatomic, strong, readonly) NSString *fromAppKeyAvailability
2.1.0
Discussion
这是为了支持跨应用聊天, 而新增的字段.
不管群聊还是单聊, from_id 都是发送消息的 username. 当该用户是默认 appKey 时, 则不填写此字段.
Declared In
JMSGMessage.h
fromUser
消息来源用户
@property (nonatomic, strong, readonly) JMSGUser *fromUserDiscussion
与 [target] 属性相对应. 根据消息方向不同:
- 收到的消息, fromUser 是发出消息的对方. 单聊是聊天对象, 也与当前会话目标用户一致 [JMSGConversation target], 群聊是该条消息的发送用户.
- 发出的消息: fromUser 是我自己.
Declared In
JMSGMessage.h
fromType
消息来源类型
@property (nonatomic, strong, readonly) NSString *fromTypeDiscussion
默认的用户之间互发消息，其值是 “user"。如果是 App 管理员下发的消息，是 "admin”
Declared In
JMSGMessage.h
contentType
消息的内容类型
@property (nonatomic, assign, readonly) JMSGContentType contentTypeDeclared In
JMSGMessage.h
content
消息内容对象
@property (nonatomic, strong, readonly) JMSGAbstractContent *contentDiscussion
使用时应通过 contentType 先获取到具体的消息类型，然后转型到相应的具体类。
Declared In
JMSGMessage.h
timestamp
消息发出的时间戳
@property (nonatomic, strong, readonly) NSNumber *timestampDiscussion
这是服务器端下发消息时的真实时间戳，单位为毫秒
Declared In
JMSGMessage.h
fromName
消息中的fromName
@property (nonatomic, strong, readonly) NSString *fromNameDiscussion
消息的发送方展示名称
Declared In
JMSGMessage.h
Message addOn fields 消息附加属性
targetType
聊天类型。当前支持的类型：单聊，群聊
@property (nonatomic, assign, readonly) JMSGConversationType targetTypeDeclared In
JMSGMessage.h
status
消息状态
@property (nonatomic, assign, readonly) JMSGMessageStatus statusDiscussion
一条发出的消息，或者收到的消息，有多个状态会下。具体定义参考 JMSGMessageStatus 的定义。
Declared In
JMSGMessage.h
isReceived
当前的消息是不是收到的。
@property (nonatomic, assign, readonly) BOOL isReceivedDiscussion
是收到的，则是别人发给我的。UI 上一般展示在左侧。 如果不是收到侧的，则是发送侧的，是我对外发送的。
主要是在聊天界面展示消息列表时，需要使用此方法，来确认展示消息的方式与位置。 展示时需要发送方消息，不管是收到侧还是发送侧，都可以使用 fromUser 对象。
Declared In
JMSGMessage.h
flag
消息标志
@property (nonatomic, strong, readonly) NSNumber *flagDiscussion
这是一个用于表示消息状态的标识字段, App 可自由使用, SDK 不做变更. 默认值为 0, App 有需要时可更新此状态.
使用场景:
- 语音消息有一个未听标志. 默认 0 表示未读, 已读时 App 更新为 1 或者其他.
- 某些 App 需要对一条消息做送达, 已读标志, 可借用这个字段.
Declared In
JMSGMessage.h
isHaveRead
是否已读(只针对接收的消息)
@property (nonatomic, assign, readonly) BOOL isHaveReadDiscussion
该属性与实例方法 [-(void)setMessageHaveRead:] 是对应的。
注意：只有发送方调用 [+sendMessage:optionalContent:] 方法设置 message 需要已读回执，此属性才有意义。
Declared In
JMSGMessage.h
Instance APIs 实例方法
– init
默认的 init 方法不可用
- (instancetype)initDiscussion
如果已经得到 JMSGConversation 实例, 则可用以下方法来创建对象:
- conversation -> createMessageWithContent:
- conversation -> createMessageAsyncWithImageContent::
或者不创建 JMSGMessage 实例也可以直接发送消息. 请参考 JMSGConversation 里相关方法.
如果你的 App 不依赖 JMSGConversation 实例, 也可以直接调用 JMSGMessage 里的类方法 来创建 JMSGMessage 实例:
- JMSGMessage -> createSingleMessageWithContent:
- JMSGMessage -> createGroupMessageWithContent:
或者直接也可以调用 JMSGMessage 类方法发消息而不必创建 JMSGMessage 对象.
Declared In
JMSGMessage.h
– getAt_List:
获取消息体中所有@对象（只针对群消息，单聊消息无@功能）
- (void)getAt_List:(JMSGCompletionHandler)handlerParameters
handler |
结果回调。回调参数：
如果 error 为 nil, 表示获取成功 如果 error 不为 nil,表示获取失败 |
|---|
Discussion
从服务器获取，返回消息的所有@对象。
Declared In
JMSGMessage.h
– setMessageHaveRead:
设置为已读
- (void)setMessageHaveRead:(JMSGCompletionHandler)handlerParameters
handler |
回调
|
|---|
Discussion
注意: 只针对消息接收方有效
这是一个异步接口;
1、接收方：设置消息为已读状态后，isHaveRead 属性也会被设置为 YES，
2、发送方：会收到消息已读状态变更事件，SDK 会更新消息的未读人数。
注意：只有发送方调用 [+sendMessage:optionalContent:] 方法设置 message 需要已读回执，此方法才有效。
Declared In
JMSGMessage.h
– getMessageUnreadCount
消息未读人数
- (NSInteger)getMessageUnreadCountDiscussion
只针对消息发送方有效
注意：只有发送方调用 [+sendMessage:optionalContent:] 方法设置 message 需要已读回执，此方法才有意义。
Declared In
JMSGMessage.h
– messageReadDetailHandler:
已读未读用户列表
- (void)messageReadDetailHandler:(void ( ^ ) ( NSArray *JMSG_NULLABLE readUsers , NSArray *JMSG_NULLABLE unreadUsers , NSError *JMSG_NULLABLE error ))handlerParameters
handler |
结果回调。回调参数:
|
|---|
Discussion
只针对消息发送方有效
注意：只有发送方调用 [+sendMessage:optionalContent:] 方法设置 message 需要已读回执，此方法才有意义。
Declared In
JMSGMessage.h
– cancelSendingMessage
取消正在发送的消息
- (void)cancelSendingMessageAvailability
3.8.1
Discussion
在消息发送结果监听 [JMSGMessageDelegate onSendMessageResponse:error:] 里会返回对应的错误信息和错误码。
Declared In
JMSGMessage.h
– setFromName:
设置消息的 fromName(即:通知栏的展示名称)
- (void)setFromName:(NSString *JMSG_NULLABLE)fromNameParameters
fromName |
本条消息在接收方通知栏的展示名称 |
|---|
Discussion
fromName填充在发出的消息体里，对方收到该消息通知时,在通知栏显示的消息发送人名称就是该字段的值.
Declared In
JMSGMessage.h
– updateMessageExtraValue:forKey:
更新 message 中的extra
- (BOOL)updateMessageExtraValue:(id)value forKey:(NSString *)keyParameters
value |
待更新的value,不能为null,类型只能为 NSNumber 和 NSString |
|---|---|
key |
待更新value对应的key,不能为null |
Discussion
如果 message 中没有该 key 对应的 extra 值，则会插入该新值
Declared In
JMSGMessage.h
– updateFlag:
更新消息标志
- (void)updateFlag:(NSNumber *JMSG_NULLABLE)flagParameters
flag |
为 nil 时表示设置为 0. |
|---|
Discussion
参考 flag property 的说明.
Declared In
JMSGMessage.h
– toJsonString
消息对象转换为 JSON 字符串的表示。
- (NSString *)toJsonStringDiscussion
遵循 Message JSON 协议的定义。
Declared In
JMSGMessage.h
+ fromJson:
JSON 字符串 转换为 消息对象。
+ (JMSGMessage *JMSG_NULLABLE)fromJson:(NSString *JMSG_NONNULL)jsonDiscussion
遵循 Message JSON 协议的定义。失败时返回 nil
注意：尽量不要自己随意拼接 json 字符串去转换，容易导致创建的 message 无法正常发送
Declared In
JMSGMessage.h
– isEqualToMessage:
对象比较
- (BOOL)isEqualToMessage:(JMSGMessage *JMSG_NULLABLE)messageParameters
message |
待比较的消息对象 |
|---|
Declared In
JMSGMessage.h