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

content

消息内容对象
username

单聊用户 username

注意：

1、单独调用此接口创建消息，SDK 不会本地保存消息，再调用发送接口时才会保存；

2、如果上层希望创建消息时就本地化保存，请使用 [JMSGConversation createMessageWithContent:]

Declared In

JMSGMessage.h

+ createGroupMessageWithContent:groupId:

创建群聊消息

+ (JMSGMessage *)createGroupMessageWithContent:(JMSGAbstractContent *)content groupId:(NSString *)groupId

Parameters

content

消息内容对象
groupId

群聊ID

注意：

1、单独调用此接口创建消息，SDK 不会本地保存消息，再调用发送接口时才会保存；

2、如果上层希望创建消息时就本地化保存，请使用 [JMSGConversation createMessageWithContent:]

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

content

消息内容对象
groupId

群聊ID
at_list

@对象的数组

注意：

1、单独调用此接口创建消息，SDK 不会本地保存消息，再调用发送接口时才会保存；

2、如果上层希望创建消息时就本地化保存，请使用 [JMSGConversation createMessageWithContent:]

Declared In

JMSGMessage.h

+ createGroupAtAllMessageWithContent:groupId:

创建@所有人的群聊消息

+ (JMSGMessage *)createGroupAtAllMessageWithContent:(JMSGAbstractContent *)content groupId:(NSString *)groupId

Parameters

content

消息内容对象
groupId

群聊ID

注意：

1、单独调用此接口创建消息，SDK 不会本地保存消息，再调用发送接口时才会保存；

2、如果上层希望创建消息时就本地化保存，请使用 [JMSGConversation createMessageWithContent:]

Declared In

JMSGMessage.h

+ sendMessage:

发送消息（已经创建好的）

+ (void)sendMessage:(JMSGMessage *)message

Parameters

message

消息对象。

Discussion

此接口与 createMessage:: 相关接口配合使用，创建好后使用此接口发送。

Declared In

JMSGMessage.h

+ sendMessage:optionalContent:

发送消息（附带可选功能，如：控制离线消息存储、自定义通知栏内容、消息已读回执等）

+ (void)sendMessage:(JMSGMessage *)message optionalContent:(JMSGOptionalContent *)optionalContent

Parameters

message

通过消息创建类接口，创建好的消息对象
optionalContent

可选功能，具体请查看 JMSGOptionalContent 类

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

message

需要转发的消息
target

目标 target，只能为 JMSGUser 或 JMSGGroup
optionalContent

可选功能，具体请查看 JMSGOptionalContent 类

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 有需要时可更新此状态.

使用场景:

  1. 语音消息有一个未听标志. 默认 0 表示未读, 已读时 App 更新为 1 或者其他.
  2. 某些 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

flag

为 nil 时表示设置为 0.

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

message

待比较的消息对象

Declared In

JMSGMessage.h