iOS and Mac

Introduction

Real-time messaging provides low latency, high concurrency, and high reliability. Use it for scenarios such as live chat and voice chat rooms.

The RTM feature in DingRTC operates within meetings. You must join a meeting before you can use the RTM feature.

Concepts

Session: A real-time messaging session identified by a unique `sessionId`. Sessions support `join`, `leave`, and `close` operations. You must create and join a session before you can send or receive real-time messages. DingRTC lets you create multiple sessions with different `sessionId`s, and each session operates independently.

Broadcast message: A message sent to all other members in a session.

Peer-to-peer message: A message sent to a specific user in a session, identified by their UserID.

Integration method

1. Before you join a meeting, retrieve the `DingRtmClient` instance from `RtcEngine`:

   DingRtmClient *rtmClient = [rtcEngine getRtmClient];

2. Set a callback listener for the `DingRtmClient` instance:

   //MARK: - DingRtmClientDelegate
   
   - (void)onRtmServerStateChanged:(DingRtmServerState)state error:(int)error {
   }
   
   - (void)onJoinSessionResult:(NSString *)sessionId result:(int)result {
   }
   
   - (void)onLeaveSessionResult:(NSString *)sessionId result:(int)result {
   }
   
   - (void)onCloseSessionResult:(NSString *)sessionId result:(int)result {
   }
   
   - (void)onRemovedFromSession:(NSString *)sessionId reason:(int)reason {
   }
   
   - (void)onSessionCreate:(NSString *)sessionId {
   }
   
   - (void)onSessionClose:(NSString *)sessionId {
   }
   
   - (void)onSessionRemoteUserJoin:(NSString *)sessionId uid:(NSString *)uid {
   }
   
   - (void)onSessionRemoteUserLeave:(NSString *)sessionId uid:(NSString *)uid {
   }
   
   - (void)onMessage:(NSString *)sessionId uid:(NSString *)uid broadcast:(BOOL)broadcast data:(NSData *)data {
   }

3. After joining the conference, the session initiator creates and joins a session:

   [rtmClient joinSession:sessionId]; // If the session does not exist, calling joinSession first creates the session and then joins it.

4. Other members in the meeting receive an `onSessionCreate` event notification. They can then join the same session:

   [rtmClient joinSession:sessionId]; // If the session exists, calling joinSession directly joins it.

5. You receive an `onSessionRemoteUserJoin` event notification when you join a session that already contains other members, or when another member joins your session. To send peer-to-peer messages, your application layer must maintain a list of members in the session:

   - (void)onSessionRemoteUserJoin:(NSString *)sessionId uid:(NSString *)uid {
       // The addSessionUser method is implemented by the application layer to add a new user to the session.
       [self addSessionUser:sessionId uid:uid];
   }

   When a member leaves the session, you receive an `onSessionRemoteUserLeave` event notification. You must then update the session member list accordingly:

   - (void)onSessionRemoteUserLeave:(NSString *)sessionId uid:(NSString *)uid {
       // The removeSessionUser method is implemented by the application layer to remove a user who has left the session.
       [self removeSessionUser:sessionId uid:uid];
   }

6. The SDK supports sending and receiving UTF-8 encoded strings and binary data. On iOS and Mac, use `NSData` as the parameter to transmit message data. To send a broadcast message:

   NSString *msg = @"test123";
   NSData *data = [msg dataUsingEncoding:NSUTF8StringEncoding];
   [rtmClient broadcastData:sessionId data:data];

   To send a peer-to-peer message:

   NSString *msg = @"test123";
   NSData *data = [msg dataUsingEncoding:NSUTF8StringEncoding];
   [rtmClient sendData:sessionId uid:userId data:data];

   To receive a message:

   - (void)onMessage:(NSString *)sessionId uid:(NSString *)uid broadcast:(BOOL)broadcast data:(NSData *)data {
       NSLog(@"onMessage, sessionId:%@, uid:%@, broadcast:%d, dataSize:%lu", sessionId, uid, broadcast, (unsigned long)data.length);
       // This assumes the sender sent the message in string format.
       NSString *msg = [[NSString alloc] initWithBytes:data.bytes length:data.length encoding:NSUTF8StringEncoding];
   }

7. If your client no longer needs the RTM feature, you can leave the session:

   [rtmClient leaveSession:sessionId];

   After leaving a session, you will not receive broadcast messages from other members in that session, and other members cannot send peer-to-peer messages to you.

8. If a session is no longer needed, you can close it:

   [rtmClient closeSession:sessionId];

   After a session is closed, all members of the session, including yourself, receive an `onSessionClose` event notification. The session is no longer active.

Notes

1. When you leave a meeting, the SDK clears all session information. The RTM feature becomes inactive.

2. If a remote user leaves the channel without calling `leaveSession`, you might not receive the `onSessionRemoteUserLeave` event notification for that user. When you receive the `onRemoteUserOffLineNotify` event for that user, your application layer must remove the user from all session member lists.

3. To avoid missing any callback messages, set the callback listener for the `DingRtmClient` instance before you join a meeting.