Utilities

The iOS SDK provides the following methods for managing different aspects of video sessions:

• adjustLayout(): To adjust the video player layout to fit within its parent view.
• makeOutboundCall(): To initiate an outbound call to a PSTN number or a SIP URI while being in a session.
• cancelOutboundCall(): To cancel an ongoing outbound call to a PSTN number or a SIP URI.
• setAudioOnlyMode(): To switch to an audio-only call.
• stopVideoTracksOnApplicationBackground(): To switch the RTC application to the background.
• startVideoTracksOnApplicationForeground(): To switch the RTC application to the foreground.
• postClientLogs(): To share console log with the EnableX technical team for audit.
• clientDiagnostics(): To detect the issues causing the RTC to fail.
• captureScreenShot(): To take a snapshot of a video stream in your application.
• updateConfiguration(): To reconfigure a stream by adding new or updating existing attributes of the stream.

Adjust Layout

You can play the remote streams in the Active Talker list with a custom-defined view by selecting activeviews : view during connect(). You do not need to handle the UI in this case, as the predefined video grid plays all the streams received at the client endpoint. When choosing this option, you can use the adjustLayout() method to adjust the video player layout to fit within its parent view. This method helps when a user rotates the screen or when the view needs to be adjusted to fit correctly.

Class: enxRoom

Method: -(void)adjustLayout

Sample Code

enxRoom.adjustLayout()

Dialing Out to Phone and SIP Endpoint from a Video Room

DIal Out

The EnxRoom.makeOutboundCall() method initiates an outbound call to a PSTN number or a SIP URI during a session, inviting the called participant to join the session on accepting the call.

Class: EnxRoom

Methods

Parameters

Notes:

• options parameters are available from the iOS SDK version 2.1.3 and above
• early_media and silent_join may not be used together

Delegate Methods

Sample Code

[enxRoom makeOutboundCall:"9999999999"  callerId:"8888888888" withDialOptions: dialOptions];	// Make a Call

where var dialOptions = {
"name": "John",
"early_media": false,
"silent_join": true
};
 
-(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 and Exceptions

Cancel Outbound Call

This functionality is available from the iOS SDK version 2.1.3 and above

The EnxRoom.cancelOutboundCall() method allows you to cancel an ongoing outbound call to a PSTN number or SIP URI thus disconnects the participant from the session on passing the number.

Class: EnxRoom

Method: -(void)cancelOutboundCall:(NSString*_Nonnull)number;

Parameter: number: String. A PSTN Number or a SIP URI to disconnect from the session.

Delegate Method: -room:didOutBoundCallCancel:: Notification to the call initiator when the participant gets disconnected.

Sample Code

[enxRoom cancelOutboundCall:"9999999999"];	// Cancel a Call
 
- (void)room:(EnxRoom *_Nullable)room didOutBoundCallCancel:(NSArray *_Nullable)data{
	// Acknowledge that the Call has been cancelled
}

Send DTMF Response

This functionality is available from iOS SDK v2.3.16+ onwards.

The EnxRoom.sendDTMF() method allows send DTMF response to pass through an IVR if dialed out PSTN Call is connected to IVR. This method can be executed repeatedly to pass single digit or multiple digits in a single call.

An outbound PSTN Call must have been answered first to make use of sendDTMF() method to pass DTMF digits on the same PSTN channel.

• Method: (void)sendDTMF:(NSString*_Nonnull)number digits:((NSString*_Nonnull)digits;
• Parameters:
  • options :
    • number : String. It's the same number used with makeOutboundCall() method. It can be either a PSTN Number or a SIP URI to dial out. For Phone Number, use country code without 00 or +.
    • digits : String. Digit(s) to pass on to Voice Service as DTMF digits.
• Delegate Methods:
  • -room:didOutBoundCallSendDtmf : Method call success and failure notifications are given with error codes.

Sample Code

[enxRoom sendDTMF:@“919999988888” digits:@"1"];

- (void)room:(EnxRoom *_Nullable)room didOutBoundCallSendDtmf:(NSArray *_Nullable)data {
	// Acknowledge that the DTMF Sending is successful
}

Error Codes

Audio Only Mode for Video Room

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 calls. It doesn't affect others' video streams in the room.

Class: EnxRoom

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

Parameter: AudioOnly: Boolean. Set it to true to switch to audio-only call.
Set it to false to switch to audio-video call.

Error Codes and Exceptions

Handle Application Switch from Foreground to Background

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

Moving Application to Background

The method switches the RTC application to the background.

Method: -(void)stopVideoTracksOnApplicationBackground:(BOOL)flag

Parameter: flag: Boolean. true - to stop publishing local video stream on moving the application to the background.

Sample Code

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

Moving Application to Foreground

The method switches the RTC application to the foreground.

Method: -(void)startVideoTracksOnApplicationForeground:(BOOL)flag

Parameter: flag: Boolean. true - to start publishing local video stream on moving the application to the foreground.

Sample Code

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

Share Log with EnableX

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 post Console Logs to EnableX, you must first enable Console logging using EnxLogger.

Class: EnxRoom

Method: - (void)postClientLogs;

Sample Code

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


[room postclientLogs]; // Post log to EnableX

Error Codes and Exceptions

Pre-Call Test

• This functionality is available from the iOS SDK version 1.9.6 and above.
• This functionality is compatible with the iOS version 13 and above.

The EnxRtc.clientDiagnostics() method 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:

Notes: Test Groups Camera, Microphone, Bandwidth are not available on SDK version 1.9.6.

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

Class: EnxRtc

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

Parameters:

Delegate Methods

Sample 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

Sample Response at the beginning of the test: -didClientDiagnosisStatus:

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

Sample Code - 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."
        }
      ]
    }
  }
}

Sample 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:

Take Image Snapshot of Video Stream

The (void) captureScreenShot method takes a snapshot of a video stream captures and returns it as a framed image.

Delegate Method: -didCapturedView: Receives an image in a framed view.

Sample Code

//Set delegate
EnxPlayerView.delegate = self;

//Capture Snapshot
[EnxPlayer captureScreenShot];

//Snapshot captured.
-(void)didCapturedView:(UIImage*_Nonnull)snapShot;
// SnapShot is the Image Frame

Update Stream Configuration

This functionality is available in iOS SDK 1.5.6 and later versions.

The EnxStream.updateConfiguration() method is used to reconfigure a stream by adding new or updating existing attributes of the stream. This API applies to both remote and local streams.

Class: EnxStream

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

Parameter: data: JSON Object. New stream configuration options in the Dictionary object.

Sample Code

-(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 and Exceptions