Advance Features iOS SDK covers API capabilities to build feature-rich End-Point Applications. as Moderator Controls.

Table of Contents

Switch Source Media Devices of Published Stream

A user may want to switch to alternate Media Devices for his published stream. EnableX API allows Media Device switching on the fly.

The APIs allows you to switch between Rear and Front Camera and to alternate available Microphone.

Switch between Rear & Front Camera

If user looks to switch between Rear and Front Camera as a source for published Stream, use EnxSream.switchCamera() method.

Class: EnxStream

Method: - (NSException*) switchCamera;

[localstream switchCamera];

Switch to alternate Microphone

If user looks to switch Micrcophone used to create published Stream to an alternate Microphone, use EnxRoom.switchMediaDevice() method. This API requires name of the new device to switch to. You can use EnxRoom.getDevices() method to fetch a list of microphones and create a UI for new device selection.

Class: EnxRoom

Method: – (void)switchMediaDevice:(NSString *)mediaName

Parameters: mediaName– String, Target Microphone Device Name

Delegate Method: - didNotifyDeviceUpdate: – When Audio Device Update is complete. Returns with switched Microphone Device Name

[room switchMediaDevice:@”mediaName”];

-(void)didNotifyDeviceUpdate:(NSString *)updates{
	// updates would carry new device name
}

Configure Stream

Availability: iOS SDK v.1.5.6+

If you like to re-configure your stream by adding new or udpating existing specification parameters of a stream. Please use EnxStream.updateConfiguration() method to update the parameters of a stream. Both remote and local streams can use this method of updating the stream parameters.

ClassEnxStream

Method-(void)updateConfiguration:(NSDictionary *_Nonnull) data

Parametersdata– Dictionary Object containing new configuration options

 -(void)updateConfiguration:(NSDictionary *_Nonnull) data;

// The data Dictionary object may be like the following
/*
data = {
     @"maxVideoBW": @"900",
     @"minVideoBW": @"150",
     @"maxAudioBW": @"150",
     @"minAudioBW":@"150"
 };
*/

Mute / Unmute Audio in a Stream

Use EnxStream.muteSelfAudio() method to mute and unmute audio from Local Stream. When a user mutes or unmutes audio from own Published Stream, all other connected users of the room are notified with – stream:didRemoteStreamAudioMute:  and  stream:didRemoteStreamAudioUnMute: callbacks respectively. Listen to these events to update related UI elements.

Class: EnxStream

Methods: - (void) muteSelfAudio:(BOOL)isMuted; – Pass true to mute, false to unmute audio

Callbacks:

  • - didRemoteStreamAudioMute: – To all participants notifying user has muted audio
  • - didRemoteStreamAudioUnMute: – To all participants notifying user has unmuted audio
  • - didAudioEvent: – To self that audio is either muted or unmuted
[localStream muteSelfAudio:true]; // To mute audio on local stream
[localStream muteSelfAudio:false]; // To unmute audio on  local stream

// This delegate method to self. Audio is muted/unmuted.
-(void)didAudioEvent:(NSDictionary *)data{
 //data is { "msg":"Audio On", "result":0 }
}

// This delegate method is for others Clients to notify that a user
// has muted his Audio
-(void)stream:(EnxStream *)stream didRemoteStreamAudioMute:(NSArray *)data{
 /* data is 
 [ {
  "result":0,
  "clientId":"XXX",
  "msg":"user muted audio"
  },
  "<null>"
 ]
 */
}

// This delegate method is for others Clients to notify that a user
// has unmuted his Audio
-(void)stream:(EnxStream *)stream didRemoteStreamAudioUnMute:(NSArray *)data{
 /* data is 
 [ {
  "result":0,
  "clientId":"XXX",
  "msg":"user unmuted audio"
  },
  "<null>"
 ]
 */
}

Note: In case of error, <null> is received at 1st Index, and Error Info at 2nd Index

Mute / Unmute Video in a Stream

Use EnxStream.muteSelfVideo() method to mute and unmute video from Local Stream. When a user mutes or unmutes video from own Published Stream, all other connected users of the room are notified with – stream:didRemoteStreamVideoMute:  and  stream:didRemoteStreamVideoUnMute: callbacks respectively. Listen to these events to update related UI elements.

Class: EnxStream

Methods: - (void) muteSelfVideo:(BOOL)isMuted; – Pass true to mute, false to unmute video

Callbacks:

  • - didRemoteStreamVideoMute: – To all participants notifying user has muted video
  • - didRemoteStreamVideoUnMute: – To all participants notifying user has unmuted video
  • - didVideoEvent: – To self that videois either muted or unmuted
[localStream muteSelfVideo:true]; // To mute video on local stream
[localStream muteSelfVideo:false]; // To unmute video on  local stream

// This delegate method to self. Video is muted/unmuted.
-(void)didVideoEvent:(NSDictionary *)data{
 //data is { "msg":"Video On", "result":0 }
}

// This delegate method is for others Clients to notify that a user
// has muted his Video
-(void)stream:(EnxStream *)stream didRemoteStreamVideoMute:(NSArray *)data{
 /* data is 
 [ {
  "result":0,
  "clientId":"XXX",
  "msg":"user muted video"
  },
  "<null>"
 ]
 */
}

// This delegate method is for others Clients to notify that a user
// has unmuted his Video
-(void)stream:(EnxStream *)stream didRemoteStreamVideoUnMute:(NSArray *)data{
 /* data is 
 [ {
  "result":0,
  "clientId":"XXX",
  "msg":"user unmuted video"
  },
  "<null>"
 ]
 */
}

Note: In case of error, <null> is received at 1st Index, and Error Info at 2nd Index

Send Chat Data

INFO! EnableX Android SDK 1.4.2 support an advance version of Public & Private Messaging API. Therefore, you are discouraged to use this Stream based Messaging. It will be deprecated in future version.

You may implement basic text-chat communication using EnableX API. The Text-Data is carried on a separate data track in a published Stream and received by all subscribers of the stream.

  • Notes to send message:
    • You must initiate your stream with data track enabled using the JSON Payload as {data: true}
    • You must publish your stream into the room before you can use the EnxStream.sendData() method.
  • Notes to receive message:
    • You must subscribe to the remote stream
    • Use delegate method – didReceiveData:  to receive any incoming message.

Class: EnxStream

Method: -(NSException *)sendData:(NSDictionary *)data – to send out message to all

Parameter:

  • message – Message Body
  • sender – Sender’s Name
  • timestamp – Time Stamp in UTC – when the message was originated

Delegate Method: – didReceiveData: to all participants in the room

NSDictionary *data = @{   
   @"sender": @"Your Name",
   @"message": @"Hello World",
   @"timestamp": @"date/time of message origin in UTC"
}

[stream sendData:data];		// Send to all

-(void)didReceive:(NSDictionary *)data{
	//data received as { message : { from : "", message : "", timestamp : ""}}
}

Important Note! EnableX 1.3.* doesn’t support private messaging. Using this API you may only do Public Chat / Messaging. As chat data is carried with the published stream you may not send chat messages unless your stream is published.

Private, Public & Group Messaging

This is an advance messaging feature between Session participants. You can do following type of messaging in a session among participants:

  • Public Messaging: To send message to all connected users.
  • Private Messaging: To send message to a specific user.
  • Group Messaging: To send message to more than one specified users.

Messaging feature neither require the sender to publish his Stream, nor receivers to subscribe.

Class: EnxRoom

Method: -(void)sendMessage:(NSString *)message isBroadCast:(BOOL)broadcast recipientIDs:(NSArray *)clientIds;

Parameters:

  • message – String type message.
  • isBroadCast – Boolean. Use true for Public Broadcast, Use false for private messaging to one or more recipients.
  • recipientIDs– Array of ClientIDs whom you wish to send private messages.

Delegate Method:

  • - room:didReceiveChatDataAtRoom: – Upto iOS SDK v1.5.2. Deprecated in v1.5.3.
  • - room:didMessageReceived: – iOS SDK v1.5.3+
NSArray *clientArray = [NSArray arrayWithObjects:@"xxx",@"xxx", nil]

// Private message to one or selected Recipients
[room sendMessage:[NSString stringWithFormat:@"%@",text] isBroadCast:true recipientIDs:clientArray]; 

// Users Receive Message through Callback 
// Available till v1.5.2. Deprecated in v1.5.3
- (void)room:(EnxRoom *)room didReceiveChatDataAtRoom:(NSArray *)data {
    // data contains incoming message
}

// Users Receive Message through Callback 
// Available from v1.5.3.
- (void)room:(EnxRoom *)room didMessageReceived:(NSArray *)data {
    // data contains incoming message
}

File Sharing

Availability: iOS SDK v1.5.3+

EnableX File Share API allows users of a RTC session to send and receive file(s) to/from each other. Using the available APIs, you can initiate file transfer to share, cancel a file transfer, get notified on a shared file and receive/download shared file.

Upload File to share

The file sharing process starts with a user initiating a file transfer to EnableX Server. To initiate a file transfer use EnxRoom.sendFiles() method.

Class: EnxRoom

Method: -(void) shareFiles:(EnxFilePosition)position isBroadcast:(BOOL)isBroadcast clientIds:(NSArray *_Nullable)clientIds

Parameters:

  • position– EnxFilePosition. Enumerated values: Top, Bottom, Center. Position of File Selection UI.
  • isBroadcast – Boolean. Set it to true to share file among all participants in the Session. Set it to false to share to selected participants.
  • clientIds– List of Client IDs. This is to share the file among specified participants only. If broadcast is set to true, clientIds is ignored. If broadcast is set to false, you must pass clientIds.

Delegate Methods at Sender End:

  • -room:didInitFileUpload: – To notify sender that file upload process is initiated
  • -room:didFileUploaded: – To notify sender that file has been uploaded
  • -room:didFileUploadFailed: – To notify sender that file upload process has failed

Delegate Methods at Receiver End:

  • -room:didFileUploadStarted: – To notify intended receiver that a file is being uploaded
  • -room:didFileAvailable: – To notify intended received that a file is ready to download
[room shareFiles:Top isBroadcast:true clientIds:nil];

// To intended receiver - A new file upload started
- (void)room:(EnxRoom *_Nonnull)room didFileUploadStarted:(NSArray *_Nullable)data {
    // data contains incoming file information
}

// To intended receiver - A file is available for download 
-(void)room:(EnxRoom *_Nonnull)room didFileAvailable:(NSArray *_Nullable)data {
    // data contains incoming file information
}

// To sender - File upload process started
- (void)room:(EnxRoom *_Nonnull)room didInitFileUpload:(NSArray *_Nullable)data {
    // data contains file information
}

// To sender - File upload is complete
- (void)room:(EnxRoom *_Nonnull)room didFileUploaded:(NSArray *_Nullable)data {
	// data contains file information
}

// To sender - File upload has failed
- (void)room:(EnxRoom *_Nonnull)room didFileUploadFailed:(NSArray *_Nullable)data {
	// data contains error information
}

Error Codes: Upload process may encounter error. You will be notified with JSON Object with error code:

Error CodeError Description
5091File Sharing not available in this context
5092Too many files to upload. Max allowed File: 1
1185Too large file. Max allowed Size: NNNN
1182Failed to upload file

Download shared File

Intended Recipients needs to download each file shared with them individually. Therefore, recipient needs to know information on the available files to download to initiate a download process.

Know files to download

Room Lookup: To know what all files are available for download, you may call EnxRoom.getAvailableFiles(), it returns a JSON Object with all files available for download

Method: -(NSArray*)getAvailableFiles

[room getAvailableFiles];

When New File is available: A receive end point is notified as and when a file is made available for download using delegate method -room:didFileAvailable:

// To intended receiver - A file is available for download 
-(void)room:(EnxRoom *_Nonnull)room didFileAvailable:(NSArray *_Nullable)data {
    // data contains incoming file information
}

Initiate File Download

As you know about the file(s) to download, you need to initiate download individually using EnxRoom.downloadFile() method.

Class: EnxRoom

Method: -(void)downloadFile:(NSDictionary *_Nonnull)file autoSave:(BOOL)flag

Parameters:

  • file– File Object to be downloaded.
  • autoSave – Whether to save the file automatically. If not to be saved automatically, you would receive Base64 encoded RAW data to handle file saving processes manually. If auto-saving is on, file will be saved on Photo Gallery.

Note: Auto Saving option has restrictions on file types. Only Image and Video files will be saved. However, other files type will be treated as autoSave off i.e. you would receive Base64 encoded RAW data to handle file saving processes manually.

Callbacks at Receiver End:

  • -room:didFileDownloaded: – To notify file has been downloaded with either Base64 Raw data to be saved (When auto-saving is false) or saved file path.
  • -room:didFileDownloadFailed: – To notify download failure
[room downloadFile:fileObject autoSave:true];

// To receiver - File has been downloaded
- (void)room:(EnxRoom *_Nonnull)room didFileDownloaded:(NSString *_Nullable)data {
	// Handle FileObject with download information
}

// To receiver - File download has failed
- (void)room:(EnxRoom *_Nonnull)room didFileDownloadFailed:(NSArray *_Nullable)data {
 // Handle download error
}

Error Codes: Download process may encounter error. You will be notified with JSON Object with error code:

Error CodeError Description
5089Storage Access denied
5090Failed to save file
1183Failed to download file
1181File Download not available in this context

Share Screen

A Client End Point can start a Screen-Share using EnxRoom.startScreenShar() method. The method creates a stream of Mobile Screen @ 6fps to publish to the Room. EnxRoom.stopScreenShare() method stops the ongoing Screen Share. Screen Share continues even when the Application goes into background.

When a user starts or stops Screen Share, all connected users of the room are notified with  - room:didScreenShareStarted: and  - room:didScreenSharedStopped: callbacks. As Screen-Share is also a Stream, you can play it using a Video Player. Screen Share is carried on Stream ID# 11. Client End Point must subscribe to this Stream ID to receive and play it locally.

Note: You need to enable screen share while defining a room with { "settings": { "screen_share": true; }) in JSON Payload. Know more…

Class: EnxRoom

Methods:

  • -(void)startScreenShare; – To start screen share (Iinitiaze Screen Stream and Publish into th Room)
  • -(void)sendVideoBuffer:(CMSampleBufferRef)sampleBuffer; – After publishing Screen Stream, this method passes captchured buffer frame to Media Server.
  • -(void)stopScreenShare; – To stop ongoing screen share.

Delegate Methods:

  • - room:didStartScreenShareACK: To acknowledge that share has started to the the moderator who initiated share
  • - room:didStopScreenShareACK: To acknowledge that share has stopped to the the moderator who stopped share
  • - room:didScreenSharedStarted:  – To all others when Share Screen started
  • - room:didScreenSharedStopped: – To all others when Share Screen stopped
[enxRoom startScreenShare]; // Start Screen Share
[enxRoom sendVideoBuffer: sampleBuffer]; // Pass captchured buffer frame to media
[enxRoom startScreenShare]; // Stop Screen Share

-(void)room:(EnxRoom *)room didStartScreenShareACK:(NSArray *)Data{
	// Acknowledge that Share started to the the moderator 
	// who started share 
}

-(void)room:(EnxRoom *)room didStopScreenShareACK:(NSArray *)Data{
	// Acknowledge that Share stopped to the the moderator 
	// who stopped share 
}

// All others are notified that a Share has started
-(void)room:(EnxRoom *)room didScreenSharedStarted:(EnxStream *_Nullable)stream{
	stream.enxPlayer.frame = yourFrame;
	[yourView addSubview:stream.enxPlayer];
}

// All others are notified that Screen Share has stopped
-(void)room:(EnxRoom *)room didScreenSharedStopped:(EnxStream *_Nullable)stream{
	[stream.enxPlayer removeFromSuperview];
}

Note: In case of error, <null> is received at 1st Index, and Error Info at 2nd Index

Use Canvas Streaming

Your application may require Canvas Streaming. Canvas Streaming helps you publish any UIView into the Room.

Start Canvas Streaming

You can use EnxRoom.startCanvas() method to start canvas streaming.

Important Notes!

  • You need to enable a Room to use Canvas Streaming in it. To enable Canvas Streaming, use { settings: { canvas: true; }} in the JSON Payload to create Room.
  • Once Canvas Streaming gets started, all participants are notified with Delegate Method canvasStarted.
  • Canvas Stream is carried on Stream ID# 21. Client End Point must subscribe to this Stream ID to receive and play it locally.

Method(void) startCanvas:(UIView*_Nonnull)view

Parameter:

  • UIView: The UIView that will be used for Canvas Streaming

Observers:

  • - room:didStartCanvasACK – to the publisher know that a Canvas Streaming has started
  • - room:didCanvasStarted: – to notify all that a Canvas Streaming has started
[room startCanvas: UIView];

// Callback method for Publisher to
// acknowledge that Canvas Streaming has started
-(void)room:(EnxRoom *_Nullable)room didStartCanvasACK:(NSArray *_Nullable)Data; 

// Callback method for all participants in 
// the room to notify that canvas streaming has started
-(void)room:(EnxRoom*)room didCanvasStarted:(EnxStream *_Nullable)stream{
	stream.enxPlayer.frame = yourFrame;
	[yourView addSubview:stream.enxPlayer];
}

-(void)room:(EnxRoom *)room didStartCanvasACK:(NSArray *)Data{
	// Acknowledge that Canvas Stream started to the user 
	// who started canvas streaming 
}

Stop Canvas Streaming

An ongoing canvas streaming may be stopped using EnxRoom.stopCanvas() method. When streaming is stopped, all participants in the room are notified using an event.

Method-(void)stopCanvas;

Observers

  • - room:didStopCanvasACK – to the publisher know that a Canvas Streaming has stopped
    - room:didCanvasStopped: – to notify all that a Canvas Streaming has stopped
[room stopCanvas];

// Callback method for Publisher to
// acknowledge that Canvas Streaming has stopped
-(void)room:(EnxRoom *_Nullable)room didStoppedCanvasACK:(NSArray *_Nullable)Data; 

// All others are notified that Canvas Streaming has stopped
-(void)room:(EnxRoom *)room didCanvasStopped:(EnxStream *_Nullable)stream{
	[stream.enxPlayer removeFromSuperview];
}

Receive & Play Canvas Streams

A published Canvas Streaming can be received at other participant end-points to play the stream.

When a user starts or stops Canvas Streaming, all connected users of the room are notified with  - room:canvasStarted: and - room:canvasStopped: . As at the receiving side, Canvas Streaming is also a Video Stream, you can play it using a Video Player. Note that Canvas Stream is carried on Stream ID# 21. Client End Point must subscribe to this Stream ID to receive and play it locally.

Observers:

  • - room:canvasStarted: – to know that a Canvas Streaming has started
  • - room:canvasStopped: – to know that a Canvas Streaming has stopped
// You are notified when Canvas Streaming started
-(void)room:(EnxRoom *)room canvasStarted:(NSArray *)Data{
	/*Data is 
	[	{ 
			"clientId" : "XXXX", 
			"name" : "Canvas Streaming from Web",
			"result" : 0, 
			"streamId" : 21
		},
		"<null>"
	]
	*/


	NSDictionary *responseDict = Data[0];
	
	// Get remote stream from streamid
	NSString *streamId = *responseDict[@”streamId”];
	EnxStream *stream = room.streamsByStreamId[streamId]; 
	  
	// init player view
	EnxPlayerView *playerView = [[EnxPlayerView alloc] initWithFrame:frame];
	[stream attachRenderer:playerView];
	[playerView setDelegate:self];
}


// You are notified when Canvas Streaming stopped
-(void)room:(EnxRoom *)room canvasStopped:(NSArray *)Data{
	/* Data is 
	[	{ 
			"clientId" : "XXXX", 
			"name" : "Canvas Streaming from Web",
			"result" : 0, 
			"streamId" : 21
		},
		"<null>"
	]
	*/

	// Update your UI here.

}

Note: In case of error, <null> is received at 1st Index, and Error Info at 2nd Index

Receive Streaming Stats

For Streaming Quality analysis, you may opt to receive Streaming Stats and get them displayed on respective Player. Once opted, you will receive Stats for all Streams received at the end point from the Room. You will receive following important information on Streams:

  • Publishing Resolution
  • Bandwidth at Publisher End
  • Receiving Resolution
  • Receiving Bandwidth consumed
  • Available Bandwidth at Receiver
  • … there are more

ClassEnxRoom

Method-(void)enableStats:(BOOL)isEnabled – To enable disable streaming stats for all streams in the Room.

Parameter: isEnabled – Boolean Parameter. Pass true to enable, false to disable

Delegate Method:

  • -didAcknowledgeStats:– Acknowledges that stream stats is enabled or disabled
  • -didReceiveStats: – When all streams’ stats is received
// To enable stats at Room Level
[enxRoom enableStats:true];

// To get to know stats has been enabled or disabled 
-(void)didAcknowledgeStats: ( NSArray * _Nonnull)subUnSubResponse{

} 

//Delegate to receive room level stats
-(void)didReceiveStats: ( NSArray * _Nonnull)statsData{

}

Further you may opt to receive stream specific stats only being played on a player. However to receive individual stream stats, you would require to enable stats at room level too.

ClassEnxPlayerView

Method: -(void)enablePlayerStats:(BOOL)isEnabled – To enable disable streaming stats for a individual stream

Parameter:isEnabled – Boolean Parameter. Pass true to enable, false to disable

Delegate Method-didPlayerStats:– When Player’s stream stats is received

// To enable stats player's stream stats
[enxPlayer enablePlayerStats:true];

//Delegate to receive player's stream stats
-(void)didPlayerStats: ( NSArray * _Nonnull)statsData{
 
} 

Annotation

Availability: iOS SDK v1.5.6+

Using Annotation API user can annotate on a Remote Stream. To implement Annotation, all you need to know how to add Annotation Toolbar, how to start and Stop Annotation and handle related Delegate Methods

Note: For Annotation feature to work, you need to enable Canvas Streaming while defining a Room; use { settings: { canvas: true; }}

Annotation Toolbar

To initiate Annotation Toolbar, use below code snippets:

EnxToolBar *toolBar = [[EnxToolBar alloc] initWithFrame:CGRectMake(X, Y, width, height)];

Start / Stop Annotation

You need to use given methods to start and stop annotation.

ClassEnxRoom

Methods:

  • -(void)startAnnotation:(EnxStream *_Nonnull)stream – To start Annotation on given Stream Object
  • -(void)stopAnnotation – To stop Annotation

Parameter: EnxStream: Stream Object on which Annotation will start

Delegate Methods:

  • -room:didStartAnnotationACK:(NSArray *_Nullable)Data – Acknolwedgement to the Annotator that Annotation has started
  • -room:didAnnotationStarted:(NSArray *_Nullable)Data – Notification to all others that Annotation has started
  • -room:didStoppedAnnotationACK:(NSArray *_Nullable)Data – Acknolwedgement to the Annotator that Annotation has stopped
  • -room:didAnnotationStopped:(NSArray *_Nullable)Data – Notification to all others that Annotation has stopped
// Start Annotation
-(void)startAnnotation:(EnxStream*_Nonnull)stream;

// Stop Annotation
-(void)stopAnnotation;  

// Notification to all - Annotation started
-(void)room: (EnxRoom *_Nullable) room didAnnotationStarted: (NSArray *_Nullable) Data; 

// Acknowlegement to Annotator - Annotation started
-(void)room: (EnxRoom *_Nullable) room didStartAnnotationACK: (NSArray *_Nullable) Data; 

// Notification to all - Annotation stopped
-(void)room: (EnxRoom *_Nullable) room didAnnotationStopped: (NSArray *_Nullable) Data; 

// Acknowlegement to Annotator - Annotation stopped
-(void)room: (EnxRoom *_Nullable) room didStoppedAnnotationACK: (NSArray *_Nullable) Data; 

Error Codes: Annotation process may encounter error. You will be notified with JSON Object with error code:

Error CodeError Description
5093Annotation Access denied
5104Annotations is already in progress
5106Annotations is starting
5108Annotation Stream is not valid
5109Annotation Stream publishing failed

Opt to receive desired Video Quality

The Client End Point may opt to receive the desired video quality for available bandwidth. You may create UI based on the enumerated values of video quality as explained below.

Class: EnxRoom

Method: - (void)setReceiveVideoQuality:(NSString*)videoQuality;

Parameter:  videoQuality – Enumerated String Constants viz. AutoHDSDLD. Set it to Auto if you want EnableX to decide optimum quality for you dynamically.

Delegate Method: -room:didSetVideoQuality:

[room setReceiveVideoQuality:@"HD"];

Use Custom Signaling

Your Application might require to send instructions, data to one or more recipient connected in a Session to deploy new features, business workflow. For example, you wan to create a Polling mechanism among participants. EnableX supports Custom Signaling method through which you can build such utility that requires passing of messages among participants.

Using Custom Signaling Method, you might send message to all or selected participants in a Room. You can define your custom data structure to pass to meet your business requirement.

Method: -(void)sendUserData:(NSDictionary *)Message isBroadCast:(BOOL)broadcast recipientIDs:(NSArray *)clientIds;

Parameters:

  • Message – Dictionary Message containing custom keys. This object is passed to Recipients as is. EnableX doesn’t enforce it’s structure. Be advised to define keys effectively for signaling needs.
  • isBroadCast – Boolean. Use true for Public Broadcast, Use false for signaling to one or more recipients.
  • recipientIDs – Array of ClientIDs whom you wish to send signal.

Delegate Method

  • - room:didReceiveChatDataAtRoom: – Upto iOS SDK v1.5.2. Deprecated in v1.5.3.
  • - room:didUserDataReceived: – iOS SDk v1.5.3+

Message Dictionary Sample:

// Example: Important Information you can put with custom keys
// You may define the JSONObject as per your business needs

NSDictionary* message = @{
    "sender": "Sender's Name",
    "message": "Message body",
    "custom_key": "Data"
}

To send & receive Custom Signaling

NSArray *clientArray = [NSArray arrayWithObjects:@"xxx",@"xxx", nil]

// Signaling to one or selected Recipients
[room sendUserData: message broadCast:false recipientIDs:clientArray]; 

// Users receive Signal through Callback 
// Available till v1.5.2. Deprecated in v1.5.3
- (void)room:(EnxRoom *)room didReceiveChatDataAtRoom:(NSArray *)data {
    // data contains incoming message
}

// Users receive Signal through Callback 
// Available from v1.5.3.
- (void)room:(EnxRoom *)room didUserDataReceived:(NSArray *)data {
    // data contains incoming message
}

Break-Out Room

Break-Out Rooms are meant for discussion aside off the main Video Room. i.e. the Parent Room. A Creator or Owner of the Break-Out Room may invite one or more users from Parent Room to the Break-Out Room. The invited users would be notified about the request and they are required to accept the request to join the Break-Out room. Users moving out of the Parent Room will be treated as “paused” user in the Parent Room until they return.

Consider the following points while implementing Break-Out Room feature in your Application:

  • Break-Out room can be created by user from the Parent Room only. One can’t create another Break-Out Room being already within a Break-Out Room.
  • A Break-Out Room may be defined with a max allowed participant in it. Your Break-Out Room Size is limited to Parent Room’s maximum allowed Active Talkers minus one person e.g. Users in Break-Out < Max Active Talker of Parent Room.
  • Break-Out room currently supports only Audio Call with Screen Share and Canvas Streaming support.
  • The Creator/Owner of a Break-Out has right to invite/add other users into the Room capped at Break-Out Room-Size.

Create Break-Out Room

Use the following method to create a Break-Out Room. The creator owns the Break-Out Room and has right to invite users into it.

Method: -(void)createBreakOutRoom:(NSDictionary* _Nonnull) RoomDefinition;

Parameters:

  • RoomDefinition – Required. Dictionary to define the Room Parameter.
    • participants – Numeric. Required. No. of Participants (Limited to maximum allowed Active Talkers). Range: Min: 2. Max: max_active_talkers of Parent Room – 1
    • audio – Boolean. Required. Set to true to enable Audio Communication in Break-Out Room.
    • video – Boolean. Required. Set to true to enable Video Communication in Break-Out Room. Currently this is not supported.
    • canvas – Boolean. Required. Set to true to enable Canvas Streaming in Break-Out Room.
    • share – Boolean. Required. Set to true to enable Screen Share in Break-Out Room.
    • max_rooms – Numeric. Required. Total number of Break-Out room instance needed.

Delegate Methods:

  • -room:didAckCreateBreakOutRoom – To get result of Create Break-Out Room as JSON Array
NSDictionary *dict = @{
	@"participants" :@2, 
	@"audio" : @true,
	@"video": @false , 
	@"canvas":@false, 
	@"share":@false, 
	@"max_rooms":@1
};

[EnxRoom createAndInviteBreakoutRoom:dict];

- (void)room:(EnxRoom *_Nullable)room didAckCreateBreakOutRoom:(NSArray *_Nullable)data {
	// data is JSON with created Break-Out Room Information, e.g.
	/*		
	[
		{	msg: {​​
					rooms: [ 
						xxx, xxx
					]
			},
			result: 0
		|
	]
	*/
} 

Invite Users to join a Break-Out Room

Creator or Owner of a Break-Out Room may invite one or more users from Parent Room to join the Break-Out Room. The following method must be used from the Parent Room to to invite users to Break-Out Room. Note that this method is not available for execution from a Break-Out Room.

Method: -(void)inviteToBreakOutRoom:(NSDictionary * _Nonnull) Invitee;

Parameters:

  • Invitee – Dictionary to define the Invitees to a Break-Out Room.
    • clients – Array of ClientIds of users who are being invited.
    • room_id – String. Room-ID of the Break-Out Room to which the users are being invited

Delegate Methods:

  • -room:didAckInviteBreakOutRoom – To get result of invitation process.
  • -room:didInvitationForBreakoutRoom – Invited Users get notified that they are being invited to join a Break-Out Room.
NSDictionary *invitee = @{
	@"clients" : [ clientId1, clientId2], 
	@"room_id" : @"RoomID"
};

[EnxRoom inviteToBreakOutRoom:invitee];

- (void)room:(EnxRoom *_Nullable)room didAckInviteBreakOutRoom:(NSArray *_Nullable)data {
	// data is the result of invitation process, e.g.
	/*		
	{	"msg": "Success",
		"result": 0,
	}
	*/
} 

- (void)room:(EnxRoom *_Nullable)room didInvitationForBreakoutRoom:(NSArray *_Nullable)data {
	// data carries the invitation details, e.g.
	/*		
	{	"result": 0,
	}
	*/
}

Create Break-Out Room & Auto-Invite Users

To support some use-cases where auto-assignment of users into different Break-Out Room is required, you may use this method. This method creates a Break-Out Room with given specification and invites users to join a room at random depending on room’s capacity.

Method: -(void)createAndInviteBreakoutRoom:(NSDictionary* _Nonnull) RoomDefinition;

Parameters:

  • RoomDefinition – Dictionary to define the Room Parameters as explained above.

Delegate Methods:

  • -room:didAckCreateAndInviteBreakOutRoom – To get result in JSON Array
NSDictionary *dict = @{
	@"participants" :@2, 
	@"audio" : @true,
	@"video": @false , 
	@"canvas":@false, 
	@"share":@false, 
	@"max_rooms":@2
};

[EnxRoom createAndInviteBreakoutRoom:dict];

- (void)room:(EnxRoom *_Nullable)room didAckCreateAndInviteBreakOutRoom:(NSArray *_Nullable)data {
	// data is JSON with created Break-Out Room Information, e.g.
	/*		
	[
		{	msg: {​​
					rooms: [ 
						xxx, xxx
					]
			},
			result: 0
		|
	]
	*/
}

Join a Break-Out Room

Being invited, a user may join a Break-Out room by using the method given below. This method may be used from the Parent Room only. Note that a user may only join one Break-Out Room at any given point. Subsequently the user exits the Break-Out Room to join back the Parent Room. Further, a user is now allowed to join any other Break-Out Room.

Method: -(void)joinBreakOutRoom:(NSDictionary* _Nonnull)Joinee withStreamInfo:(NSDictionary* _Nullable)streamInfo;

Parameters:

  • Joinee– Dictionary to define the Joinee to a Break-Out Room.
    • role – String. Required. Enumerated Values: participant, moderator.
    • room_id – String. Required. Room-ID of the Break-Out Room to which the user is joining.
  • streamInfo – Dictionary to define stream information while joining the Room.
    • audio – Boolean. Set true to join with Audio.
    • video – Boolean. Set true to join with Video. This is not available now.

Delegate Methods:

  • -room:didConnectedBreakoutRoom – Succeeded to join Break-Out Room
  • -room:didFailedJoinBreakOutRoom – Failed to join Break-Out Room
  • - room:didUserJoinedBreakoutRoom: – On getting connected to Breeak-Out Room, all other users in the room are notified about the new user joined.
NSDictionary *Joinee = @{
	@"role" : @"participant", 
	@"room_id" : @"RoomID"
};

NSDictionary *StreamInfo = @{
	@"audio" : @true, 
	@"room_id" : @false
};

[EnxRoom joinBreakOutRoom:Joinee StreamInfo];

- (void)room:(EnxRoom *_Nullable)room didConnectedBreakoutRoom:(NSDictionary *_Nullable)roomMetadata  {
	// roomMetadata contains meta information of the Room 
} 

- (void)room:(EnxRoom *_Nullable)room didFailedJoinBreakOutRoom:(NSArray *_Nullable)data {
	// data contains reasons of failed connection
}

- (void)room:(EnxRoom *_Nullable)room didUserJoinedBreakoutRoom:(NSArray *_Nullable)data {
	// data contains new joinee user's information 
	/*
	{	"clientId": "String",
		"room": "String";
	}
	*/
}

Pause/Resume Parent Room

User may pause the Parent Room after joining the Break-Out Room. Pausing mutes audio and video of Parent Room. On the other hand, user may need to join back or resume session with Parent Room. For explicit pause and resume Parent Rooms Session by using given methods below. Further a user automatically joins back the Parent Room after getting disconnected from the Beak-Out Room.

Method: 

  • - (void) pause – To pause Parent Room
  • - (void) resume – To resume Parent Room

Delegate Methods:

  • - room:didAckPause – Acknowledges the user on pausing Parent Room
  • - room:didAckResume – Acknowledges the user on resume with Parent Room
[EnxRoom pause];	// Pause Parent Room
[EnxRoom resume];	// Resume Parent Room

- (void)room:(EnxRoom *_Nullable)room didAckPause:(NSArray *_Nullable)data{
	// data carries info related to pausing
	/*
	{	"msg": "Room muted",
		"result": 0
	}
	*/
};

- (void)room:(EnxRoom *_Nullable)room didAckResume:(NSArray *_Nullable)data {
	// data carries info related to resume
	/*
	{	"msg": "Room unmuted",
		"result": 0
	}
	*/
};

Mute/Unmute Parent Room

User may like to mute audio and/or video of the Parent Room after joining the Break-Out Room. On the other hand, user may need to unmute audio and/or video of Parent Room after disconnecting from Break-Out Room and resuming with Parent Room.

Method: 

  • -(void)muteRoom:(NSDictionary * _Nonnull)muteInfo – To mute audio/video of Parent Room
  • -(void)unmuteRoom:(NSDictionary * _Nonnull)unmuteInfo– To unmute audio/video of Parent Room

Parameters:

  • mutetInfo – Dictionary to define Audio/Video Mute on the Parent Room.
    • audio – Boolean. Set true mute Audio.
    • video – Boolean. Set true to mute Video.
  • unuteteInfo – Dictionary to define Audio/Video Unmute on the Parent Room.
    • audio – Boolean. Set true unmute Audio.
    • video – Boolean. Set true to unmute Video.

Delegate Methods:

  • - room:didAckMuteRoom – To acknowledge Room muted
  • - room:didAckUnmuteRoom – To acknowledge Room unmuted
NSDictionary *MuteInfo = @{
	@"audio" : @true, 
	@"video" : @true
};

NSDictionary *UnmuteInfo = @{
	@"audio" : @true, 
	@"video" : @true
};

[EnxRoom muteRoom:MuteInfo];

[EnxRoom unmuteRoom:UnmuteInfo];

- (void)room:(EnxRoom *_Nullable)room didAckMuteRoom:(NSArray *_Nullable)data {
	// data contains muting status
} 

- (void)room:(EnxRoom *_Nullable)room didAckUnmuteRoom:(NSArray *_Nullable)data {
	// data contains unmuting status
}

Disconnect from Break-Out Room

User may need to disconnect from Break-Out Room to join back or resume with Parent Room. Use the following method:

Method: - (void)disconnect

Delegate Methods:

  • -room:didDisconnectedBreakoutRoom – The disconnected user is notified that he has successfully disconnected from the Break-Out Room.
  • -room:didUserDisconnectedFromBreakoutRoom – All Users of the Parent Room are notified about the user got disconnected from Break-Out Room.
[EnxRoom disconnect]; 

- (void)room:(EnxRoom *_Nullable)room didDisconnectedBreakoutRoom:(NSArray *_Nullable) data {
	// data carries info related to disconnection
	/*
	{	"moderatorId": "",
		"msg": "Breakout Room disconnected",
		"result": 0
	}
	*/
};

- (void)room:(EnxRoom *_Nullable)room didUserDisconnectedFromBreakoutRoom:(NSArray *_Nullable) data {
	// data carries info related to disconnected user
	/*
	{	"clientId": "String",
		"name": "String",
		"room": "breakout-Development"
	}
	*/
};

Handle Destroyed Break-Out Room

When all connected user in a Break-Out Room get disconnected, the Break-Out Room is destroyed automatically and he creator/owner or the Room is notified by a Delegate Method.:

Delegate Methods:

  • -room:didDestroyedBreakoutRoom – The owner is notified when Room gets destroyed.
- (void)room:(EnxRoom *_Nullable)room didDestroyedBreakoutRoom:(NSArray *_Nullable)data {
	// data carries destroyed room infomration 
	/* 
	{	"room_id": "String"
	}
	*/
}

Change to Audio only call

If you want change to a audio-only call, i.e. you neither want to receive anyone’s video not want to publish your video; you may use EnxRoom.setAudioOnlyMode() method. This method acts as a toggle to switch between audio-only and audio-video call.

This opt-in is only for the specific End-Point and doesn’t affect others in the room.

Class: EnxRoom

Method: - (void)setAudioOnlyMode:(BOOL)check;

Parameter: BOOL AudioOnly

  • true: audio-only call
  • false: audio-video call
[room setAudioOnlyMode:true];   // Switched to Audio-Only call
[room setAudioOnlyMode:false];  // Switched back to Audio-Video call

Handle Audio Device Updates

If any audio device e.g. Bluetooth Audio, Ear Phone or Head Phone connected or attached to the Mobility Device, EnableX callbacks notifies such events to the Application; so they can be handled effectively.

Delegate Method: - (void)didNotifyDeviceUpdate:(NSString*)updates; – User is notified when there is a new Audio Device attached/connected or detached/disconnected.

- (void)didNotifyDeviceUpdate:(NSString*)updates  {
  // Device attached or detached
}

Handle Application Switch from Foreground to Background

User may switch to different application pushing your RTC Application to Background and vice versa. You need to handle such activity using following methods:

Class: EnxRoom

Methods:

  • - (void)stopVideoTracksOnApplicationBackground:(BOOL)flag – When application goes to Background you may stop publishing Video Track by passing true.
  • - (void)startVideoTracksOnApplicationForeground:(BOOL)flag; – When application comes back to Foreground you may restart publishing Video Track by passing true.
 // To stop Video Track when application goes to Background 
[room stopVideoTracksOnApplicationBackground:true]; 

// To resume Video Track when application comes back to Foreground 
[room   startVideoTracksOnApplicationForeground:true];     

Make Outbound PSTN/SIP Call

Being within EnableX Session, you may initiate an Outbound Call to PSTN Number or SIP URI inviting the called participant to join the session on accepting the call.

Class: EnxRoom

Method: -(void)makeOutboundCall:(NSString*_Nonnull)dialout_number callerId:(NSString *)callerId;r,String cli_number)

Parameters:

  • dialout_number – String. It either a PSTN Number or SIP URI to dial-out
  • callerId– Calling Line Identification Number to be added as originator of the Call. In case of PSTN Phone Numbers, this will be validated against your purchased number or opted Shared Number. In case if the CLI does not match, the call will fail with an error “CLI mismatch”

Delete Method:

  • -room:didOutBoundCallInitiated: Notifies that Dialout call has been initiated
  • -room:didDialStateEvents: Status of the Dialout Process is notified as and when received from Gateway. The JSON Response returns following status codes: initiated, calling, connecting, connected, terminated
[enxRoom makeOutboundCall:"9999999999"  callerId:"8888888888"];	// Make a Call
 
-(void)room:(EnxRoom *)room didOutBoundCallInitiated:(NSArray *)Data{
	// Acknowledge that Call has been initiated
}

-(void)room:(EnxRoom *)room didDialStateEvents:(EnxOutBoundCallState)state{
	// Notifies repeatedly status of Dialout Process 
}

Error Codes – Failure Conditions to accept Dial-Out request

Error CodeDescription
1141Dial-Out request is already in progress
1142CLI doesn’t match with configured phone number

Share Log with EnableX to audit

To share Console Log with EnableX Tech Team for auditing purpose, use EnxRoom.postClientLogs() . The method sends latest 200KB of Console Log to EnableX.

Class: EnxRoom

Method: - (void)postClientLogs; – To upload log to EnableX Server

NOTE: To use this API client end point first need to enable logs using below method:

// To enable logging
EnxLogger *logger = [EnxLogger sharedInstance];
[logger startLog];


[room postclientLogs]; // Post log to EnableX

Explore iOS SDK