Room Connection

The iOS SDK provides the following methods:

• init(): To initialize a room.
• connect(): To connect a client application to a virtual room.
• joinRoom(): To quickly join a room.
• disconnect(): To close a session and disconnect a client endpoint from the session.

Initiate a Room

An RTC session occurs in a virtual room hosted on the EnableX platform and the iOS SDK allows client endpoint applications to connect to it. The process starts with initializing a room object by using the EnxRoom class.

Method: -(instancetype)init;

Sample Code

EnxRoom *room = [[EnxRoom alloc] init];

Connect to a Room

The EnxRoom.connect() method connects the client application to the virtual Room hosted on the EnableX server where the RTC session occurs. After initializing the Room, the client endpoint must connect to the Room to establish a bi-directional communication channel over a Web Socket.

As the communication takes place over the web sockets using Socket Events, any network issue leading to the disconnection of the web sockets will cause the communication to fail. In such cases, EnableX offers the option to automatically reconnect with the room.

Note: The automatic reconnection is not applicable when:

• The last participant has disconnected from the adhoc room.
• The moderator has dropped the participant from the room.
• The participant has explicitly disconnected from the room.

Class EnxRoom

Method: - (void)connect:(NSString *)token roomInfo:(NSDictionary *)roomInfo advanceOptions:(NSArray *)advanceOption;

Parameters

Delegate Methods

Sample Code

NSString *token = "XXX";
NSDictionary *roomInfo = { // Re-Connect Options
 @"allow_reconnect": true,
 @"number_of_attempts": 3,
 @"timeout_interval": 10000,
 @"audio_only": false
}; 

NSDictionary *advanceDict= @{
 @"id":@"battery_updates",
 @"enable":@YES
};

NSMutableArray *advanceOptionArray = [[NSMutableArray alloc] init];

[advanceOptionArray addObject:advanceDict];

advanceDict= @{
 @"id":@"notify-video-resolution-change",
 @"enable":@YES
};

[advanceOptionArray addObject:advanceDict]; 

// Initiates Room 
EnxRoom *room = [[EnxRoom alloc] init];

// Connects with Re-Connection & Advance Options
[room connect:token roomInfo:roomInfo advanceOptions:advanveOptionArray ];
 

//Delegate methods
-(void)room:(EnxRoom *)room didConnect:(NSDictionary *)roomMetadata{
      // Connected. Delegate receives room instance and Room Meta JSON.
}

-(void)room:(EnxRoom *)room didError:(NSString *)reason{
 // Connection failed. Find error
}

-(void)room:(EnxRoom *)room userDidJoined:(NSArray *)Data{
 // A new user connected. user JSON has user information
}

-(void)room:(EnxRoom *)room didActiveTalkerList:(NSArray *)Data{
      // List of talkers in the Room
      // Received after room connected.
}

Error Codes and Exceptions

Join a Room with a Stream

A typical process to connect to a room involves the following steps:

1. Initiate a room and connect to it.
2. Initiate streaming after connecting, which requires you to check media accessibility.
3. Publish a local stream.
4. Check if the stream is successfully published.

To successfully join a room, you need to ensure the success of each step before proceeding to the next step, thus making it a complex process. The EnxRtc.joinRoom() method allows you to quickly join a room and get started without following every step of this procedure.

Class: EnxRtc

Method: -(EnxStream *)joinRoom:(NSString *)token delegate:(id)delegate PublishStreamInfo: (NSDictionary *)publishStreamInfo;

Parameters

Returns: EnxStream JSON object containing the details of the published local stream.

Sample Code

NSDictionary* publishStreamInfo = {
         video: true,
         audio: true,
         data: true,
         attributes: { name: "XX" }
}

NSString* token = "XXX";

EnxRtc *enxRtc = [[EnxRtc alloc] init];
EnxStream *localStream = [enxRtc joinRoom:token delegate:self publishStreamInfo:publishStreamInfo];

//Delegate methods
-(void)room:(EnxRoom *)room didConnect:(NSDictionary *)roomMetadata{
	// Connected. Delegate receives room instance and Room Meta JSON.
}

-(void)room:(EnxRoom *)room didError:(NSString *)reason{
	// Connection failed. Find error
}

Disconnect from a Room

The EnxRoom.disconnect() method closes the session and disconnects client endpoints from the eoom. The media and signaling sockets are also released in this process.

Class: EnxRoom

Method: - (void)disconnect;

Delegate Methods

Sample Code

[room disconnect];

- (void)room:(EnxRoom *)room didRoomDisconnect:(NSArray * _Nullable)response {
    // You are disconnected
}
-(void)room:(EnxRoom *)room userDidDisconnected:(NSArray *)Data{
     // A user is disconnected
     // Data - User Information of disconnected user
}

Error Codes and Exceptions

Handle Network Disconnection and Reconnection

A client endpoint is connected with EnableX over a secured web socket, which is susceptible to network failures. The client endpoint is notified of the failure through the following callbacks:

Delegate Methods

Sample Code

- (void)room:(EnxRoom*)room didConnectionLost:(NSArray*)data {
	// Disconnected. Handle UI 
} 

- (void)room:(EnxRoom*)room didConnectionInterrupted:(NSArray*)data{
	// Interrupted. Handle UI 
}

EnableX provides the Auto-Reconnection functionality for disconnected endpoints to ensure a better user experience. To use this feature, you must Connect to the Room with Reconnection options. Note that this feature is not applicable under the following circumstances:

• The last participant has disconnected from the adhoc room.
• The moderator has dropped the participant from the room.
• The participant has explicitly disconnected from the room.

Delegate Methods

Sample Code

//To receive and handle reconnection events, 
// you need to pass an argument called roomInfo (its is an optional parameter) while connecting to the room through the room api - joinRoom() or connect(). For example,

NSDictionary *roomInfo = { 
	@"allow_reconnect": true,
	@"number_of_attempts": 3,
	@"timeout_interval": 10000,
	@"audio_only": false
}; 

//This will helps the end-point user to auto-reconnect to the same room.

NSDictionary *advanceDict= @{
	@"id":@"battery_updates",
	@"enable":@YES
};

NSMutableArray *advanceOptionArray = [[NSMutableArray alloc] init];

[advanceOptionArray addObject:advanceDict];

advanceDict= @{
	@"id":@"notify-video-resolution-change",
	@"enable":@YES
};

[advanceOptionArray addObject:advanceDict]; 


-(void)room:(EnxRoom*)room didUserReconnectSuccess:(NSDictionary*)data{
	// Got reconnected
}

- (void)room:(EnxRoom *)room didReconnect:(NSString *)reason{
	// Reconnecting 
}

Error Codes and Exceptions

Video Quality Adaption based on Bandwidth

EnableX offers Automatic Bandwidth Detection (ABWD) to ensure optimum audio and video communication based on the available bandwidth at the client endpoint. The ABWD detects a change in the available bandwidth when it cannot continue to support all the videos that are received and notifies the client endpoint with the onRoomBandwidthAlert callback. You can handle this event by reducing the number of active talker videos received or by switching to the audio-only mode. It helps users facing extremely poor network conditions to switch to the audio-only mode without disrupting the session.

Delegate Method: -room:didRoomBandwidthAlert

Notification is sent to the affected client endpoint when:

• Bandwidth at the endpoint reduces to a level where all the received videos cannot be supported.
• Bandwidth at the endpoint increases to a level where more videos than those currently being received can be supported.

Notification is not triggered for any bandwidth fluctuation that does not affect the number of videos being received at the client endpoint.

Sample Code

// To receive notification
-(void)room:(EnxRoom *_Nullable)room didRoomBandwidthAlert:(NSArray *_Nullable)data;

-room:didRoomBandwidthAlert JSON Payload:

Sample Code

[
	{ 	"bandwidth": 240,
		"stream_bandwidth": 80,
		"number_of_videos": 2
	}
]