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,只能为 JMSGUserJMSGGroup

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