Advance Features of iOS SDK cover API capabilities to build feature-rich Client endpoint Applications. For exclusive APIs entitled to the Moderator refer to Moderator Controls.

Table of Contents

Pre-Call Test

Availability: iOS SDK v1.9.6+ | Compatibility iOS 13+

The EnxRtc.clientDiagnostics() method acts as a Diagnostic Tool to detect any issue causing the RTC to fail. The API runs through predefined test cases related to WebRTC issues and reports asynchronously through an Event as it passes through each test. These test cases are organized in “Test Groups” as shown below:

  • Microphone*
    • Audio capture
  • Camera*
    • Check resolution 320×240
    • Check resolution 640×480
    • Check resolution 1280×720
    • Check supported resolutions
  • Network
    • UDP enabled with TURN server
    • TCP enabled with TURN server
    • IPv6 enabled with TURN server
    • UDP enabled with STUN server
    • TCP enabled with STUN server
    • IPv6 enabled with STUN server
  • Connectivity
    • Relay connectivity with TURN server
    • Reflexive connectivity with TURN server
    • Host connectivity with TURN server
    • Reflexive connectivity with STUN server
    • Host connectivity with STUN server
  • Throughput
    • Data throughput with TURN server
  • Bandwidth*
    • Video bandwidth with TURN server
    • Audio bandwidth with TURN Server
  • Signaling
    • Signaling connectivity with TURN server

Note: * marked Test Groups, viz. Camera, Microphone & Bandwidth; are not available on SDK v1.9.6.

You can also build a UI to initiate the tests and generate a diagnostic report using this API.

Class:EnxRtc

Method: -(void)clientDiagnostics:(NSDictionary *_Nonnull)Options;

Parameters:

  • Options – NSDictionary with Client preferences for the execution of Test cases. The Keys are explained below:
    • testNames – Array of Test Group names. e.g. [ "microphone", "camera", "network", "connectivity", "throughput", "bandwidth", "signalling"]
      • To test only selected Test Groups, add selected Test Group names e.g.,["microphone", "camera"]
      • To test all the Test Groups, use ["all"].
    • audioDeviceId – Optional. Device Id of input Audio device
    • videoDeviceId – Optional. Device Id of input Video device
    • regionId – Optional. Array of region Ids of ICE Servers, e.g. ["IN", "SG", "US", "DE"]. Get Region-ID list from Portal
    • testDurationDataThroughput – Optional. Test duration of data throughput in seconds [Range: 1-30 sec. Default: 2 sec]
    • testDurationVideoBandwidth – Optional. Test duration of video bandwidth in seconds [Range: 1-30 sec. Default: 10 sec]
    • testDurationAudioBandwidth – Optional. Test duration of audio bandwidth in seconds [Range: 1-30 sec. Default: 10 sec]
    • stop – Optional. Boolean. Set to true to stop the test cases which are already in execution.

Delegate Methods:

  • -didClientDiagnosisFailed: – Notification of Diagnosis failure when API is called with the wrong parameter or a repeated attempt to call the API is made while the previous request is under process.
  • -didClientDiagnosisStopped: – Notification sent when the API execution is stopped explicitly through Method Call.
  • -didClientDiagnosisFinished: – Notification sent when the API completes execution of all the test cases. This returns a JSON Object with a complete test result of all the test cases.
  • -didClientDiagnosisStatus: – Notification sent with the test result of each test case as the API passes through the execution of each test till the completion or till stopped explicitly. This returns a JSON Object with test results.

Request for diagnostics:

var Options = {
     testNames: ['microphone', 'camera'],
     audioDeviceId: 'XXX',
     videoDeviceId: 'XXX',
     regionId: ['IN'],
     testDurationDataThroughput: 2,
     testDurationVideoBandwidth: 30,
     testDurationAudioBandwidth: 30,
     stop: false
};

[Enxrtc clientDiagnostics: Options]; // Execute Test 
[Enxrtc setDelegate:self];

// Test Execution finished
-(void)didClientDiagnosisFinished:(NSArray * _Nullable)data;
// Handle JSON from data
// It contains complete test result. A response example given later

// Test Execution has failed
-(void)didClientDiagnosisFailed:(NSArray * _Nullable)data;
// Handle error message from data.
// Response example:
/* 
- Invalid argument.
- Diagnosis is already in progress. Few resources are in use and may not be accessible.
*/

// Test Execution has stopped
-(void)didClientDiagnosisStopped:(NSArray * _Nullable)data;
// Handle info message from response.message
// Response example:
/* 
- Diagnosis stopped.
- Diagnosis not running.
*/ 

// Intermediate Test Result of each  Test Case 
-(void)didClientDiagnosisStatus:(NSArray * _Nullable)data;
// Handle JSON in response.message
// It contains complete test result. A response example given later

Response at the beginning of the Test: -didClientDiagnosisStatus:

{
  "test_group": "microphone",
  "test_case": "audio_capture",
  "status": "started",
  "output": ""
}

Intermediate Response after finishing a test case: -didClientDiagnosisStatus:

{
"test_group": "microphone",
"test_case": "audio_capture",
"status": "finished",
"output": {
"audio_capture": {
"result": "success",
"execution_time": "241 ms",
"success": [
{
"message": "Audio track created using device=Default - Microphone Array (Synaptics Audio)"
},
{
"message": "Active audio input channels: 2"
}
],
"error": [],
"warning": [],
"info": [
{
"message": "Channel 0 levels: -38.3 dB (peak), -48.4 dB (RMS)"
},
{
"message": "Channel 1 levels: -38.3 dB (peak), -48.4 dB (RMS)"
},
{
"message": "Stereo microphone detected."
}
]
}
}
}

Final Response after completion of all the test cases: -didClientDiagnosisFinished:

{
"microphone": {
"audio_capture": {
"result": "success",
"execution_time": "241 ms",
"success": [
{
"message": "Audio track created using device=Default - Microphone Array (Synaptics Audio)"
},
{
"message": "Active audio input channels: 2"
}
],
"error": [],
"warning": []
}
},
"network": {
"udp_enabled": {
"IN": {
"TURN": {
"result": "success",
"execution_time": "241 ms",
"success": [
{
"message": "Gathered candidate of Type: relay Protocol: udp Address: 104.211.155.197"
}
],
"error": [],
"warning": [],
"server": {
"region": "IN",
"url": "turns:ts.enablex.io:443"
}
}
}
},
"tcp_enabled": {
"IN": {
"TURN": {
"result": "success",
"execution_time": "241 ms",
"success": [
{
"message": "Gathered candidate of Type: relay Protocol: udp Address: 104.211.155.197"
}
],
"error": [],
"warning": [],
"server": {
"region": "IN",
"url": "turns:ts.enablex.io:443"
}
}
}
}
}
}

Test Result Explanation

Test GroupTest CaseServerResultMessage
MicrophoneAudio CaptureN/ASuccessAudio track created using device #device#
SuccessActive audio input channels #channel#
FailureWebAudio run failure:
FailureNo audio track in returned stream
FailureNo active input channels detected
FailureNo active input channels detected. Microphone is most likely muted or broken, please check if muted in the sound settings or physically on the device. Then re-run the test.
FailureMicrophone input level is low, increase input volume or move closer to the microphone.
FailuregetUserMedia failed with error #error#
Cameracheck resolution 240N/ASuccessCaptured video using expected resolution
SuccessAverage FPS above threshold
FailuregetUserMedia failed with error #error#
FailureNo video track in returned stream
FailureVideo track ended, camera stopped working
FailureLow average sent FPS
FailureIncorrect captured resolution
FailureCould not analyze any video frame
FailureCamera delivering lots of black frames
FailureCamera delivering lots of frozen frames
Cameracheck resolution 480SuccessCaptured video using expected resolution
SuccessAverage FPS above threshold
FailuregetUserMedia failed with error #error#
FailureNo video track in returned stream
FailureVideo track ended, camera stopped working
FailureLow average sent FPS
FailureIncorrect captured resolution
FailureCould not analyze any video frame
FailureCamera delivering lots of black frames
FailureCamera delivering lots of frozen frames
Cameracheck resolution 720SuccessCaptured video using expected resolution
SuccessAverage FPS above threshold
FailuregetUserMedia failed with error #error#
FailureNo video track in returned stream
FailureVideo track ended, camera stopped working
FailureLow average sent FPS
FaiiureIncorrect captured resolution
FailureCould not analyze any video frame
FailureCamera delivering lots of black frames
FailureCamera delivering lots of frozen frames
Cameracheck supported resolutionsN/ASuccessSuccess Supported resolution #resolution#
FailureNo video track in returned stream
FailureVideo track ended, camera stopped working
Networkudp enabledTURNSuccessSupported resolution #resolution#
FailureNo video track in returned stream
FailureVideo track ended, camera stopped working
Networkudp enabledSTUNSuccessGathered candidate of Type: relay Protocol: udp Address: #IP#
FailureFailed to gather specified candidates
FailureFailed to create peer connection: #<error#
Networktcp enabledTURNSucessGathered candidate of Type: relay Protocol: udp Address: #IP#
FailureFailed to gather specified candidates
FailureFailed to create peer connection: #<error#
Networktcp enabledSTUNSuccessGathered candidate of Type: relay Protocol: udp Address: #IP#
FailureFailed to gather specified candidates
FailureFailed to create peer connection: #<error#
Networkipv6 enabledTURNSuccessGathered candidate of Type: relay Protocol: udp Address: #IP#
FailureFailed to gather IPv6 candidates, it might not be setup/supported on the network
FailureFailed to gather IPv6 candidates, it might not be setup/supported on the network
Networkipv6 enabledSTUNSuccessGathered candidate of Type: relay Protocol: udp Address: #IP#
FailureFailed to gather IPv6 candidates, it might not be setup/supported on the network
FailureFailed to gather IPv6 candidates, it might not be setup/supported on the network
Connectivityrelay connectivityTURNSuccessData successfully transmitted between peers
FailureInvalid data transmitted
FailureTime out
Connectivityrelay connectivitySTUNSuccessData successfully transmitted between peers
FailureInvalid data transmitted
FailureTime out
Connectivityreflexive connectivityTURNSuccessData successfully transmitted between peers
FailureInvalid data transmitted
FailureTime out
Connectivityreflexive connectivitySTUNSuccessData successfully transmitted between peers
FailureInvalid data transmitted
FailureTime out
Connectivityhost connectivityTURNSuccessData successfully transmitted between peers
FailureInvalid data transmitted
FailureTime out
Connectivityhost connectivitySTUNSuccessData successfully transmitted between peers
FailureInvalid data transmitted
FailureTime out
ThroughputData ThroughputTURNSuccessTotal transmitted: #n# kilo-bits in #t# seconds
FailureTimed out
BandwidthVideo BandwidthTURNSuccessVideo resolution: #Width# x #Height#
FailureCamera failure: #Width# x #Height#. Cannot test bandwidth without a working camera
FailuregetUserMedia failed with error #error#
FailureFrame rate mean is 0, cannot test bandwidth without a working camera
FailureCould not gather stats
FailureOnly Firefox and Chrome getStats implementations are supported
BandwidthAudio BandwidthTURNSubject to qualityAverage Audio bandwidth <value>
Subject to qualityPackets lost: <value>
Subject to qualityRTT Average: <value>
FailuregetUserMedia() failed with error <error>
FailureOnly Firefox and Chrome getStats() implementations are supported
SignalingSignaling ConnectivitySuccessToken created successfully
FailureToken creation failed due to error: #error#
FailureRoom not joined due to error: #error#
SuccessRoom joined successfully

Switch Source Media Devices of Published Stream

The following APIs allow you to switch to alternate Media Devices after having published Stream, thus facilitating a switch on the fly.

Switch between Rear & Front Camera

The EnxStream.switchCamera() method allows you to switch between Rear and Front Camera as a source for the published Stream.

Class: EnxStream

Method: - (NSException*) switchCamera;

[localstream switchCamera];

Error Code / Exceptions

CodeDescription
5021Unable to switch Camera in Audio-only call mode.
5097Unable to switch Camera in a Chat-Only Room. Non-Contextual Method Call.

Switch to alternate Microphone

The EnxRoom.switchMediaDevice() method is used to switch the Audio source of the published Stream to an alternate Microphone. This method requires name of the Audio device to switch to, which needs to be retrieved using EnxRoom.getDevices() method.

Class: EnxRoom

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

Parameters: mediaName – String. Target Microphone Device Name.

Delegate Method: - didNotifyDeviceUpdate: – Acknowledgment sent with the new Audio Device ID after Audio Device update is complete.

[room switchMediaDevice:@”mediaName”];

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

Update Stream Configuration

Availability: iOS SDK v.1.5.6+

The EnxStream.updateConfiguration() method is used to reconfigure a Stream by adding new or updating existing attributes of the Stream. This API is applicable to both Remote and Local Streams.

ClassEnxStream

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

Parametersdata– New Stream configuration options Dictionary Object.

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

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

Error Codes / Exceptions

CodeDescription
5113Invalid JSON Object passed as parameter.
5114Unable to update Stream when Canvas Streaming is on. Non-Contextual Method Call.

Mute / Unmute Audio in a Stream

The EnxStream.muteSelfAudio() method is used to mute/unmute Audio of the Local Stream.

Class: EnxStream

Methods: - (void) muteSelfAudio:(BOOL)isMuted;

Parameter: isMuted – BOOL. Pass true to mute, false to unmute Audio.

Callbacks:

  • - didRemoteStreamAudioMute: – Notification to everyone in the Room when a user mutes self Audio.
  • - didRemoteStreamAudioUnMute: – Notification to everyone in the Room when a user unmutes self Audio.
  • - didAudioEvent: – Acknowledgment to the user when self Audio is muted/unmuted.
[localStream muteSelfAudio:true]; // To mute audio of local stream
[localStream muteSelfAudio:false]; // To unmute audio of local stream

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

// This delegate method is to announce in the Room 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 to announce in the Room 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>"
 ]
 */
}

Error Codes / Exceptions:

CodeDescription
5058Repeated muteSelfAudio() call made while a previous mute request is in process.
5059Repeated muteSelfAudio() call made while a previous unmute request is in process.
5060Repeated muteSelfAudio() call made after Audio has been muted already.
5061Trying to unmute Audio without muting it first.
5062Unable to unmute Audio as Audio hard-muted by the Moderator.

Note: In case of error, <null> is received at the first Index and Error Info at the second Index.

Mute / Unmute Video in a Stream

The EnxStream.muteSelfVideo() method is used to mute/unmute Video of the Local Stream.

Class: EnxStream

Methods: - (void) muteSelfVideo:(BOOL)isMuted;

Parameter: isMuted – BOOL. true to mute, false to unmute Video.

Callbacks:

  • - didRemoteStreamVideoMute: – Notification to everyone in the Room when a user mutes self Video.
  • - didRemoteStreamVideoUnMute: – Notification to everyone in the Room when a user unmutes self Video.
  • - didVideoEvent: – Acknowledgment to the user when self Video is muted/unmuted.
[localStream muteSelfVideo:true]; // To mute video of local stream.
[localStream muteSelfVideo:false]; // To unmute video of 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 to announce in the Room 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 to announce in the Room 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>"
 ]
 */
}

Error Codes / Exceptions:

CodeDescription
5020Unable to process muteSelfVideo() when the user has denied Camera permission.
5071Repeated muteSelfVideo() call made while a previous request is in process.
5063Repeated muteSelfVideo() call made after Video has been muted already.
5064Repeated muteSelfVideo() call made after Video has been unmuted already.
5065When the user tries to unmute Video without muting it first. Non-Contextual Method call.
5066Unable to unmute Video as Video hard-muted by the Moderator.
5070Unable to unmute Video in Audio-only call mode.

Note: In case of error, <null> is received at the first Index and Error Info at the second Index.

Private, Public & Group Messaging

The EnxRoom.sendMessage() is used to exchange messages between Session participants. It allows you to exchange the following types of messages:

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

The Messaging feature does not require the sender to publish Local Stream or the receiver to subscribe to Remote Stream.

Class: EnxRoom

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

Parameters:

  • message – String type message.
  • isBroadCast – Boolean. Set to true for Public Messaging, false for Private Messaging.
  • recipientIDs – Array of Client IDs to receive messages. Applicable for Group and Private Messaging.

Delegate Method:

  • - room:didMessageReceived: – Receives message in JSONObject.
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 from v1.5.3.
- (void)room:(EnxRoom *)room didMessageReceived:(NSArray *)data {
    // data contains incoming message
}

File Sharing

Availability: iOS SDK v1.5.3+

Compatibility: iOS 13+

The following APIs allow users in an RTC session to send and receive file(s) with each other. Using these APIs, you can initiate a file transfer, cancel a file transfer, be notified of the availability of a file for download, and receive/download a shared file.

Upload File to share

The EnxRoom.sendFiles() method is used to initiate a file transfer to EnableX Server.

Class: EnxRoom

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

Parameters:

  • position – EnxFilePosition. Enumerated values: Top, Bottom, Center. Placement of File Selection UI.
  • isBroadcast – Boolean. Set it to true to share file(s) with all the participants in the Session and false to share file(s) with the intended user(s).
  • clientIds – List of Client IDs intended to receive the file(s). This parameter is not applicable if isBroadcast parameter is set to true.

Delegate Methods at Sender End:

  • -room:didInitFileUpload: – Notification to the sender when the file upload process is initiated.
  • -room:didFileUploaded: – Notification to the sender when the file has been uploaded.
  • -room:didFileUploadFailed: – Notification to the sender when the file upload process fails.

Delegate Methods at Receiver End:

  • -room:didFileUploadStarted: – Notification to the intended receiver when a file is being uploaded.
  • -room:didFileAvailable: – Notification to the intended receiver when 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
}

Cancel File Upload

The EnxRoom.cancelUpload() method allows you to cancel an ongoing file upload job initiated by you.

Class: EnxRoom

Method: -(void)cancelUpload:(int)jobID

Parameter:

jobId – Numeric. The Id of the file upload job.

 [EnxRoom cancelUpload jobId];

The EnxRoom.cancelAllUploads() method allows you to cancel all ongoing file uploads initiated by you.

Method: -(void)cancelAllUploads – No Parameter required.

[EnxRoom cancelAllUploads];

Callback:

didFileUploadCancelled: – Acknowledgment to the user when the file upload is canceled.

- (void)room:(EnxRoom *_Nonnull)room
didFileUploadCancelled:(NSArray *_Nullable)data

Error Codes / Exceptions:

CodeDescription
5089Storage Access denied.
5090Failed to save file.
5091File-Sharing not available in this context.
5092Too many files to upload. Max 1 file allowed per request.
1185File size exceeds the max allowed size.
1182Failed to upload file.
5098Unable to cancel file upload after file upload complete.
5099Failed to cancel upload as invalid Upload ID passed as a parameter.
5100Failed to upload a possibly corrupt file.
5102Cancel upload not available without Web View. Non-Contextual Method Call.

Download shared File

The process of downloading shared file(s) comprises two steps:

  • Know file(s) available for download.
  • Initiate download on the available file(s).

Know files available for download

Room Lookup: The EnxRoom.getAvailableFiles() method returns a JSON Object with all the files available for download.

Class: EnxRoom

Method: -(NSArray*)getAvailableFiles

[room getAvailableFiles];

Delegate method -room:didFileAvailable: The intended receiver is notified when a file is available for download.

// 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

The EnxRoom.downloadFile() method is used to initiate the file download using the file information received above.

Class: EnxRoom

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

Parameters:

  • file– File Object to be downloaded.
  • autoSave – BOOL. Set it to true to save the file automatically in which case you receive the saved file’s path. When set to false, you receive Base64 encoded RAW data to handle the file saving process manually.

Note: Auto Saving option is applicable for Images and Video files only. The other file types need to be saved manually using Base64 encoded RAW data.

Callbacks at Receiver End:

  • -room:didFileDownloaded: – Notification sent when the file has been downloaded with or without auto-saving.
  • -room:didFileDownloadFailed: – Notification sent when download fails.
[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
}

Cancel File Download

The EnxRoom.cancelDownload() allows you to cancel the ongoing file download job taking place at your endpoint.

Class: EnxRoom

Method: -(void)cancelDownload:(int)jobID;

Parameter:

jobId – Numeric. The Id of the file download job.

[EnxRoom cancelDownload:jobId];

The EnxRoom.cancelAllDownloads() method allows you to cancel all ongoing file downloads taking place at your endpoint.

Method: -(void)cancelAllDownloads – No Parameter required.

[EnxRoom cancelAllDownloads];

Callback:

didFileDownloadCancelled: – Acknowledgment to the user when the file download is canceled.

- (void)room:(EnxRoom *_Nonnull)room
didFileDownloadCancelled:(NSArray *_Nullable)data;

Error Codes / Exceptions:

CodeDescription
5089Storage Access denied.
5090Failed to save file.
1183Failed to download file.
1181File Download not available in this context
5101File already downloaded.

Share Screen

To support Screen-Sharing in the Room, you need to enable Screen-Sharing during Room Creation by setting: { "screen_share": true; }) in the JSON Payload. To receive Shared Screen, you need to subscribe to the Screen-Share Stream ID# 101 and play it on the Video Player.

Start Screen Sharing

The EnxRoom.startScreenShare() method is used to create a Screen-Sharing Stream @ 6fps to publish in the Room. Screen Sharing continues even when the Application runs in the background.

Class: EnxRoom

Methods:

  • -(void)startScreenShare;
  • -(void)sendVideoBuffer:(CMSampleBufferRef)sampleBuffer; – After publishing Shared-Screen Stream, this method passes the captured buffer frame to the Media Server.

Delegate Methods:

  • - room:didStartScreenShareACK: – Acknowledgment to the user who initiated screen-share.
  • - room:didScreenSharedStarted:  – Notification to everyone in the Room when Screen-Sharing starts.
[enxRoom startScreenShare]; // Start Screen Share
[enxRoom sendVideoBuffer: sampleBuffer]; // Pass captchured buffer frame to media

-(void)room:(EnxRoom *)room didStartScreenShareACK:(NSArray *)Data{
	// Acknowledge that Share started to the the moderator 
	// who started 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];
}

Stop Screen Sharing

The EnxRoom.stopScreenShare() method is used to stop the ongoing Screen-Sharing.

Class: EnxRoom

Method: -(void)stopScreenShare;

Delegate Methods:

  • - room:didStopScreenShareACK: – Acknowledgment to the user who initiated screen-share.
  • - room:didScreenSharedStopped: – Notification to everyone in the Room when Screen-Sharing stops.
[enxRoom stopScreenShare]; // Stop Screen Share

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

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

Error Codes / Exceptions

CodeDescription
5107Repeated startScreenShare() call made while previous request is in process.
1170Screen-Sharing not supported in your subscription.

Note: In case of error, <null> is received at the first Index and Error Info at the second Index.

Use Canvas Streaming

Canvas Streaming allows you to publish any view into the Room. To support Canvas Streaming in the Room, you need to enable canvas during Room Creation by setting: { canvas: true; }} in the JSON Payload.

Start Canvas Streaming

The EnxRoom.startCanvas() method is used to start canvas streaming.

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

Parameter:

UIView – The UI View to be used for Canvas Streaming.

Delegate Methods:

  • - room:didStartCanvasACK: – Acknowledgment to the publisher when Canvas Streaming starts.
  • - room:didCanvasStarted: – Notification to everyone in the Room when Canvas Streaming starts.
[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 to the Publisher that Canvas Stream started.
	
}

Error Codes / Exceptions

CodeDescription
5105Repeated startCanvas() call when Canvas Streaming is already active.
5107Repeated startCanvas() call when a previous request is in process.
5103Canvas Streaming or Screen Share already active in the Room.
5110Failed to publish Canvas Stream

Stop Canvas Streaming

The EnxRoom.stopCanvas() method is used to stop Canvas Streaming.

Class: EnxRoom

Method-(void)stopCanvas;

Delegate Methods

  • - room:didStopCanvasACK: – Acknowledgment to the publisher when Canvas Streaming stops.
  • - room:didCanvasStopped: – Notification to everyone in the Room when Canvas Streaming stops.
[room stopCanvas];

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

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

Receive & Play Canvas Streams

To receive Canvas Streaming, you need to subscribe to the Canvas Stream ID# 102. Once subscribed, you can play it like any other Video Stream using a Video Player.

// 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" : 102
		},
		"<null>"
	]
	*/


	NSDictionary *responseDict = Data[0];
	
	// Get remote stream using 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" : 102
		},
		"<null>"
	]
	*/

	// Update your UI here.

}

Note: In case of error, <null> is received at the first Index and Error Info at the second Index.

Enable Streaming Statistics in the Room

The EnxRoom.enableStats() method allows you to receive Statistics for all the Streams being received in the Room. The statistics help you analyze the streaming quality of all the Streams by providing information about the Streams such as:

  • Publishing Resolution
  • Bandwidth at Publisher’s end
  • Receiving Resolution
  • Receiving Bandwidth consumed
  • Available Bandwidth at Receiver’s end

ClassEnxRoom

Method-(void)enableStats:(BOOL)isEnabled 

Parameter:

isEnabled – BOOL. Set to true to enable stats and false to disable them.

Delegate Method:

  • -didAcknowledgeStats:– Acknowledgment to the user when stream stats are enabled or disabled.
  • -didReceiveStats: – Notification to the user 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{

}

Receive Stream Statistics for Individual Streams

The EnxPlayerView.enablePlayerStats() method allows you to individually receive statistics of Streams being played on the player. Please note, to receive individual stream stats, you also need to enable stats at room level using EnxRoom.enableStats() method.

ClassEnxPlayerView

Method: -(void)enablePlayerStats:(BOOL)isEnabled

Parameter:

isEnabled – BOOL. Set to true to enable stats and false to disable.

Delegate Method

-didPlayerStats:– Notification to the user when player’s stream stats is received.

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

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

Error Codes / Exceptions

CodeDescription
5075Repeated Stream Stats Subscription request as a previous request is in process.
5076Repeated Stream Stats Unsubscription request as a previous request is in process.
5077Repeated Stream Stats request while Stream stats is already subscribed.
5078Unsubscribing Stream Stats is not permitted without subscribing to it.
5079Unable to unsubscribe to Stream Stats while Subscription request is in process.
5080Stream Stats Unsubscription request is in process.

Be Notified of the Talkers in the Room

Availability: iOS SDK v1.9.5+

The subscribeForTalkerNotification() method allows you to receive notification for the talkers in the Room or the participants acting as a source of the noise. You can utilize this method for UI display or for debugging. Note that the list of talkers received could be longer than the Active Talkers list, because Active Talkers list received with onActiveTalkersUpdated delegate is limited to the max_active_talkers setting of the Room.

ClassEnxRoom

Method: -(void)subscribeForTalkerNotification:(BOOL)enabled – To subscribe or unsubscribe notification

Parameters:

  • enabled: BOOL. Set to true to subscribe to Talker Notification and false to unsubscribe.

Delegate Methods:

  • - room:didAckSubscribeTalkerNotification: – Acknowledgment to the subscriber when Talker Notification subscribed successfully.
  • - room:didAckUnsubscribeTalkerNotification: – Acknowledgment to the subscriber when Talker Notification unsubscribed successfully.
  • - room:didTalkerNotification: – Notification to the subscriber received with JSON Object carrying the details of users from whom speech or sound is detected.
[room subscribeForTalkerNotification:true];	// To subscribe
[room subscribeForTalkerNotification:false];	// To unsubscribe

// Acknowledgement on Talker Subscription
-(void)room:(EnxRoom *_Nullable)room didAckSubscribeTalkerNotification:(NSArray *_Nullable)data;
/*
data example:
({	"result": { 
		"result": 0,
		"msg": "Success"
	},
	"id": "talker-notification”
})
*/

// Acknowledgement on Talker Unsubscription
-(void)room:(EnxRoom *_Nullable)room didAckUnsubscribeTalkerNotification:(NSArray *_Nullable)data;
/*
data example:
({	"result": { 
		"result": 0,
		"msg": "Success"
	},
	"id": "talker-notification”
})
*/

// Receive Talker Notification on Subscription
-(void)room:(EnxRoom *_Nullable)room didTalkerNotification:(NSArray *_Nullable)data;

Response JSON Payload: - room:didTalkerNotification:

  • data: An array of objects. Each object consists of an array of users who are talking and an array of users who are merely a source of noise.
    • speech: It contains users, an array of client information who are talking with their clientId and speechType (Intensity) as low, media high
    • noise: An array of clientIds producing noise.
{
  "type": "talker-notification",
  "data": [
    {
      "speech": true,
      "users": [
        {
          "speechType": "high"
          "clientId": "xxxxx"
        },
        {
          "speechType": "medium"
	  "clientId": "yyyyy"
        },
        {
          "speechType": "low"
	  "clientId": "zzz"
        }
      ]
    },
    {
      "noise": true,
      "users": [
        {
          "clientId": "sssss"
        },
        {
          "clientId": "uuuuu"
        }
      ]
    }
  ]
}

Error Codes / Exceptions:

CodeDescription
5128Repeated subscription request call while a previous request is in process.
5129Repeated unsubscription request call while a previous request is in process.
5130Talker Notification already subscribed.
5131Illegible attempt to unsubscribe Talker Notification without subscribing first.

Annotation

Availability: iOS SDK v1.5.6+

The Annotation feature allows you to annotate on a Remote Stream. To support Annotations, you need to enable Canvas Streaming during Room Creation by setting: { canvas: true; }} in the JSON payload. To implement Annotation, you need to add Annotation Toolbar before you can start Annotations.

Add Annotation Toolbar

Initiate Annotation Toolbar using the following code in XML:

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

Start Annotation

The EnxRoom.startAnnotation() is used to start Annotation on a given Stream object.

ClassEnxRoom

Method:

  • -(void)startAnnotation:(EnxStream *_Nonnull)stream 

Parameter: 

EnxStream – Stream Object to be annotated.

Delegate Methods:

  • -room:didStartAnnotationACK:(NSArray *_Nullable)Data – Acknowledgment to the Annotator when Annotation starts.
  • -room:didAnnotationStarted:(NSArray *_Nullable)Data – Notification to everyone in the Room when Annotation starts.
// 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; 

Stop Annotation

The EnxRoom.stopAnnotation() method is used to stop Annotations.

Method:

-(void)stopAnnotation 

Delegate Methods:

  • -room:didStoppedAnnotationACK:(NSArray *_Nullable)Data – Acknowledgment to the Annotator when Annotation stops.
  • -room:didAnnotationStopped:(NSArray *_Nullable)Data – Notification to everyone in the Room when Annotation stops.

Error Codes / Exceptions: 

CodeDescription
5093Annotation Access denied.
5104Repeated startAnnotation() call made while Annotations already active in the Room.
5106Repeated startAnnotation() call made while a previous request is in process.
5108Invalid Stream passed to startAnnotation().
5109Failed to publish Annotation Stream.
5112Annotation support available in Landscape Mode only.
5094Repeated stopAnnotation() call made while a previous request is in process.

Receive desired Video Quality

The EnxRoom.setReceiveVideoQuality() method allows you to set the desired video quality at the available bandwidth for Remote Streams to be received at the Client endpoint. You can utilize this API to create UI with enumerated values that allow the user to choose the desired video quality to be received.

Class: EnxRoom

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

Parameter: 

videoQuality – Enumerated String Constants (AutoHDSDLD). Set to Auto to allow EnableX to choose the optimum quality dynamically based on the available bandwidth.

Delegate Method: -room:didSetVideoQuality:

[room setReceiveVideoQuality:@"HD"];

Error Codes / Exceptions

CodeDescription
5057Stream already set with the desired Quality.

Quality Adjustment based on available Bandwidth

EnableX offers Automatic Bandwidth Detection (ABWD) to ensure optimum Audio/ 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 being received and notifies the Client endpoint with Callback onRoomBandwidthAlert. You can handle this event by choosing to reduce the number of Active Talker’s Videos being received or by switching to audio-only mode.

This helps users facing extremely poor network conditions to go into 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 Videos being received 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.
// To receive notification
-(void)room:(EnxRoom *_Nullable)room didRoomBandwidthAlert:(NSArray *_Nullable)data; 

-room:didRoomBandwidthAlert JSON Payload:

  • bandwidth – Updated (Reduced or Increased) Bandwidth at the Client endpoint.
  • number_of_videos – Number of Videos that can be supported at the available bandwidth.
[
	{ 	"bandwidth": 240,
		"stream_bandwidth": 80,
		"number_of_videos": 2
	}
]

Use Custom Signaling

The EnxRoom.sendUserData() method allows you to send customized data adhering to a structure not bound by EnableX message structure, to one or more users connected in a session. This allows your application to send not just messages but also structured instructions, polls, or any data that requires a customized data structure as per your business requirement.

Class: EnxRoom

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

Parameters:

  • Message – Dictionary containing custom keys. This object is passed to the Recipients without any structure enforcement. Be advised to define keys effectively for signaling needs.
  • isBroadCast – BOOL. Set to true for Public Broadcast and false for signaling to one or more recipients.
  • recipientIDs – Array of Client IDs of recipients of the message when not broadcasting.

Delegate Method

  • - room:didUserDataReceived: – Receives signaling in JSONObject. Available from iOS SDk v1.5.3 onwards.

Message Dictionary Sample:

// Example: You can put important information 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
}

Error Codes / Exceptions

CodeDescription
5127Exceeding maximum allowed data transfer rate of 100Kb.

Break-Out Room

Break-Out Rooms allow users to participate in a discussion outside of the main Video Room i.e. the Parent Room.

The process of breaking-out takes place in the following manner:

  • A creator or owner of the Break-Out Room invites one or more users from the Parent Room to the Break-Out Room.
  • The invited users get notified about the request and need to accept the request to join the Break-Out room.
  • Users moving out of the Parent Room are treated as “paused” users in the Parent Room until they return.

The implementation of Break-Out Room must be carried out with the following considerations:

  • Break-Out room can be created by a user from the Parent Room only.
  • A user cannot create another Break-Out Room while being within a Break-Out Room.
  • A Break-Out Room can be created with a limit to the maximum allowed participants in it. In any case, the maximum allowed participants in the Break-Out Room must be less than the maximum Active Talkers in the Parent Room.
  • Break-Out room currently supports only Audio Call with Screen Share and Canvas Streaming support.

Create Break-Out Room

The EnxRoom.createBreakOutRoom() method is used to create a Break-Out Room.

Class: EnxRoom

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

Parameters:

  • RoomDefinition – Required. JSON Object with Room definition parameters defined as following keys:
    • participants – Numeric. Required. Total number of Participants in the Break-Out Room. 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. (This is currently 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-Sharing in Break-Out Room.
    • max_rooms – Numeric. Required. The total number of Break-Out rooms to be created.

Delegate Methods:

  • -room:didAckCreateBreakOutRoom – Acknowledgment to the creator with Break-Out Room returned as a JSON object when created.

Response Body:

{	msg: {​​
		  rooms: [ 
				xxx, xxx
			 ]
	     },
		result: 0
}
  • -room:didBreakoutRoomCreated – Notification to all the Moderators in the Parent Room when a Break-Out Room is created.

Response Body:

{ 
    id = "breakout-room-created"; 
    msg =     { 
        clientId = "68d0388c-5630-4f16-883a-8bc2a138a905"; 
        roomId = 61249702a7282c251ec8d840;
    }; 
}, 
NSDictionary *dict = @{
	@"participants" :@2, 
	@"audio" : @true,
	@"video": @false , 
	@"canvas":@false, 
	@"share":@false, 
	@"max_rooms":@1
};

// Create Break-Out Room
[EnxRoom createBreakOutRoom:dict];

// Acknowledgment to the creator
- (void)room:(EnxRoom *_Nullable)room didAckCreateBreakOutRoom:(NSArray *_Nullable)data {
	// data in JSON with created Break-Out Room Information.		
}

// Notification to all the Moderators
- (void)room:(EnxRoom *_Nullable)room didBreakoutRoomCreated:(NSArray *_Nullable)data; 
 

Error Codes / Exceptions

CodeDescription
5067Break-Out Room not supported in a Room in lecture-mode.

Invite Users to join a Break-Out Room

The EnxRoom.inviteToBreakOutRoom() method allows the Creator/Owner of a Break-Out Room to invite one or more users from the Parent Room to join the Break-Out Room. This method must be invoked from the Parent Room and NOT from the Break-Out Room.

Class: EnxRoom

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

Parameters:

  • Invitee – Dictionary with invitation details.
    • clients – Array of Client IDs of users to be invited.
    • room_id – String. Room ID of the Break-Out Room to which the users are being invited.

Delegate Methods:

  • -room:didAckInviteBreakOutRoom – Acknowledgment to the Creator with JSON object returned as a response to the invitation process.

Response Body:

{	
       "msg": "Success",
       "result": 0,
}
  • -room:didInvitationForBreakoutRoom – Notification to the invited users when they are invited to join a Break-Out Room.

Response Body:

{	
      "result": 0,
}
  • -room:didBreakoutRoomInvited – Notification to all the Moderators in the Parent Room when a user is invited to a Break-Out Room.

Response Body:

{ 

    id = "breakout-room-invited"; 
    msg =     { 
                   clientId = "12f31157-e62a-43f6-8719-f98b3da40978"; 
                   roomId = 6124b82e98533871c791a788; 
              }; 
}
NSDictionary *invitee = @{
	@"clients" : [ clientId1, clientId2], 
	@"room_id" : @"RoomID"
};

// Invite user to Break-Out Room.
[EnxRoom inviteToBreakOutRoom:invitee];

// Acknowledgment to the Creator
- (void)room:(EnxRoom *_Nullable)room didAckInviteBreakOutRoom:(NSArray *_Nullable)data {
	// data is the result of invitation process, e.g.
} 

// Notification to the invited users
- (void)room:(EnxRoom *_Nullable)room didInvitationForBreakoutRoom:(NSArray *_Nullable)data {
	// data carries the invitation details, e.g.
}

// Notification to the Moderator(s)
- (void)room:(EnxRoom *_Nullable)room didBreakoutRoomInvited:(NSArray *_Nullable)data; {
}

Create Break-Out Room & Auto-Invite Users

The EnxRoom.createAndInviteBreakoutRoom() is used to support certain use-cases where auto-assignment of users into different Break-Out Rooms is required. This method creates a Break-Out Room with given specifications and invites users to join a Break-Out Room randomly depending on the Room’s capacity.

Class: EnxRoom

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

Parameters:

Delegate Methods:

  • -room:didAckCreateAndInviteBreakOutRoom – Acknowledgment to the creator with the result of invitation in a 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
		|
	]
	*/
}

Error Codes / Exceptions

CodeDescription
5067Break-Out Room not supported in a Room in lecture mode.

Join a Break-Out Room

The EnxRoom.joinBreakOutRoom() method allows users to join a Break-Out room on being invited by the creator. A user can join a Break-Out Room from the Parent Room only and can join only one Break-Out Room at a time, thus allowing the user to join another Break-Out Room only after rejoining the Parent Room first.

Class: EnxRoom

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

Parameters:

  • Joinee– Dictionary with details required to join the Break-Out Room.
    • role – String. Required. Enumerated Values: participant, moderator.
    • room_id – String. Required. Room-ID of the Break-Out Room being joined.
  • streamInfo – Dictionary with Stream information while joining the Break-Out Room.
    • audio – BOOL. Set to true to join with Audio.
    • video – BOOL. Set to true to join with Video. This is currently not supported.

Delegate Methods:

  • - room:didConnectedBreakoutRoom – Acknowledgment to the Joiner when Break-Out Room joined successfully.
  • - room:didFailedJoinBreakOutRoom – Notification to the Joiner when fails to join the Break-Out Room.
  • - room:didUserJoinedBreakoutRoom: – Notification to everyone in the Break-Out Room when a new user joins the Room.
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";
	}
	*/
}

Reject Break-Out Room Invitation

The EnxRoom.rejectBreakOutRoom() allows the invited user to reject the invitation to join a Break-Out Room.

Class: EnxRoom

Method: -(void)rejectBreakOutRoom:(NSString *_Nonnull)roomId

Parameter:

roomId – The Break-Out Room identifier to which the user is invited.

Delegate Methods:

  • -room:didAckRejectBreakoutRoom – Acknowledgment to the user who rejected the invitation when the request to reject is successfully processed.

Response Body:

{ 
         “result” : 0/1,   // 0 for success and 1 for failure 
         “msg” : “success/failure” 
} 
  • didBreakoutRoomInviteRejected – Notification to all the Moderators in the Parent Room when a user rejects an invitation to a Break-Out Room.
// User rejects break-out room invitation.
[EnxRoom rejectBreakOutRoom:@”RoomID”];

// Acknowledgment to the user when invitation rejected.
- (void)room:(EnxRoom *_Nullable)room didAckRejectBreakoutRoom:(NSArray *_Nullable)data; 

// Notification to the Moderators in the Parent Room when invitation rejected.
- (void)room:(EnxRoom *_Nullable)room didBreakoutRoomInviteRejected:(NSArray *_Nullable)data 

Pause/Resume Parent Room

The EnxRoom.pause() method allows the user to pause the Parent Room after joining the Break-Out Room.

The EnxRoom.resume() method is used to resume the Parent Room if it was paused while joining the Break-Out Room.

Method: 

  • - (void) pause
  • - (void) resume

Delegate Methods:

  • - room:didAckPause – Acknowledgment to the user when the Parent Room is paused.
  • - room:didAckResume – Acknowledgment to the user when the Parent Room is resumed.
[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

The EnxRoom.muteRoom() method allows the user to mute Audio and/or Video of the Parent Room after joining the Break-Out Room.

The EnxRoom.unmuteRoom() is used to unmute Audio and/or Video of the Parent Room after disconnecting from Break-Out Room and resuming the Parent Room.

Class: EnxRoom

Methods: 

  • -(void)muteRoom:(NSDictionary * _Nonnull)muteInfo
  • -(void)unmuteRoom:(NSDictionary * _Nonnull)unmuteInfo

Parameters:

  • mutetInfo – Dictionary with options to mute Audio and Video separately.
    • audio – BOOL. Set to true mute Audio.
    • video – BOOL. Set to true to mute Video.
  • unuteteInfo – Dictionary with options to unmute Audio and Video separately.
    • audio – Boolean. Set to true unmute Audio.
    • video – Boolean. Set to true to unmute Video.

Delegate Methods:

  • - room:didAckMuteRoom – Acknowledgment to the user when the Parent Room is muted.
  • - room:didAckUnmuteRoom – Acknowledgment to the user when the Parent Room is 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

The EnxRoom.disconnect() method allows the user to disconnect from the Break-Out Room. A user joins back in the Parent Room automatically after getting disconnected from the Break-Out Room.

Class: EnxRoom

Method: - (void)disconnect

Delegate Methods:

  • -room:didDisconnectedBreakoutRoom – Acknowledgment to the user when successfully disconnected from the Break-Out Room.
  • -room:didUserDisconnectedFromBreakoutRoom – Notification to everyone in the Break-Out Room when a user gets disconnected from the 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 the users in a Break-Out Room get disconnected, the Break-Out Room is automatically destroyed and the creator of the Room is notified with the following Callback.:

Delegate Methods:

  • -room:didDestroyedBreakoutRoom – Notification to the owner when Break-Out 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

The EnxRoom.setAudioOnlyMode() method allows you to switch to an audio-only call where you can neither receive anybody’s video nor publish your video. You can use this method as a toggle to switch between audio-only and audio-video call. This doesn’t affect others video Streams in the Room.

Class: EnxRoom

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

Parameter:

AudioOnly – BOOL. Set to true to switch to audio-only call and false to switch to audio-video call.

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

Error Codes / Exceptions

CodeError Description
5051Repeated setAudioOnlyMode() call made while a previous Audio-only request is in process.
5052Repeated setAudioOnlyMode() call made while Audio-Only mode already active.
5053Repeated setAudioOnlyMode() call made while Audio-Video mode already active.
5054Repeated setAudioOnlyMode() call made while a previous Audio-Video request is in process.

Handle Audio Device Updates

The notification on any addition or modification in the Audio Devices such as earphones or headphones connected to the Mobile device is provided through the following Callbacks:

Delegate Method:

- (void)didNotifyDeviceUpdate:(NSString*)updates; – Acknowledgment to the user when a switch to alternate media devices is made at run-time.

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

Handle Application Switch from Foreground to Background

The following methods are used to switch the RTC application to the background and vice versa. The methods allow you to configure whether to continue streaming or pause after the switch.

Moving Application to Background

Class: EnxRoom

Method:

- (void)stopVideoTracksOnApplicationBackground:(BOOL)flag

Parameter:

flag – BOOL. Set to true to stop publishing Local Video Stream on moving the application to the background.

 // To stop Video Track when application goes to Background 
[room stopVideoTracksOnApplicationBackground:true];   

Moving Application to Foreground

Class: EnxRoom

Method:

- (void)startVideoTracksOnApplicationForeground:(BOOL)flag;

Parameter:

flag – BOOL. Set to true to start publishing Local Video Stream on moving the application to the foreground.

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

Make Outbound PSTN/SIP Call

The EnxRoom.makeOutboundCall() method allows you to initiate an Outbound Call to PSTN Number or SIP URI while being in the session, thus 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 can be either a PSTN Number or a SIP URI to dial out.
  • callerId– Calling Line Identification Number to be added as the originator of the Call. In the 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: Notification to the call initiator when Dial out call is initiated.
  • -room:didDialStateEvents: Notification to the call initiator about the status of the dial-out process as received from Gateway. The JSON Response returns status codes as: initiated, calling, connecting, connected, and 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 / Exceptions:

CodeDescription
1141Dial out request already in process.
1142CLI doesn’t match with the configured phone number.
5095Invalid Phone Number.

Share Log with EnableX to audit

The EnxRoom.postClientLogs() method is used to share Console Log with EnableX Tech Team for audit. The method sends 200KB of the most recent Console Log to EnableX. To start posting Console Logs to EnableX, you need to first enable Console logging using EnxLogger.

Class: EnxRoom

Method: - (void)postClientLogs;

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


[room postclientLogs]; // Post log to EnableX

Error Codes / Exceptions

CodeDescription
5056Log File upload already in process.
5083Unable to upload an empty log file.

Explore iOS SDK