14 Developing WebRTC-enabled iOS Applications
This chapter shows how you can use the Oracle Communications WebRTC Session Controller iOS application programming interface (API) library to develop WebRTC-enabled iOS applications.
About the iOS SDK
The WebRTC Session Controller iOS SDK enables you to integrate your iOS applications with core WebRTC Session Controller functions. You can use the iOS SDK to implement the following features:
Audio calls inbetween an iOS application and any other WebRTC-enabled application, a Session Initialization Protocol (SIP) endpoint, or a Public Switched Telephone Network endpoint using a SIP trunk.
Movie calls inbetween an iOS application and any other WebRTC-enabled application, with suitable movie conferencing support.
Seamless upgrading of an audio call to a movie call and downgrading of a movie call to an audio call.
Support for Interactive connectivity Establishment (ICE) server configuration, including support for Trickle ICE.
Semitransparent session reconnection following network connectivity interruption.
The WebRTC Session Controller iOS SDK is built upon several extra libraries and modules as shown in Figure 14-1.
Figure 14-1 iOS SDK Architecture
The WebRTC iOS cording enables the WebRTC Session Controller iOS SDK access to the native WebRTC library which itself provides WebRTC support. The Socket Rocket WebSocket library enables the WebSocket access required to communicate with WebRTC Session Controller.
For extra information on any of the APIs used in this document, see Oracle WebRTC Session Controller iOS API Reference .
Supported Architectures
The WebRTC Session Controller iOS SDK supports the following architectures:
About the iOS SDK WebRTC Call Workflow
The general workflow for using the WebRTC Session Controller iOS SDK to place a call is:
Authenticate against WebRTC Session Controller using the WSCHttpContext class. You initialize the WSCHttpContext with necessary HTTP headers and optional SSLContextRef in the following manner:
Send an HTTP GET request to the login URI of WebRTC Session Controller
Finish the authentication process based upon your authentication scheme
Proceed with the WebSocket handshake on the established authentication context
Establish a WebRTC Session Controller session using the WSCSession class.
Two protocols must be implemented:
WSCSessionConnectionDelegate : A delegate that reports on the success or failure of the session creation.
WSCSessionObserverDelegate : A delegate that signals on various session state switches, including CLOSED , CONNECTED , FAILED , and others.
Once a session is established, create a WSCCallPackage class which manages WSCCall objects in the WSCSession .
Create a WSCCall using the WSCCallPackage createCall method with a callee ID as its argument, for example, [email protected].
Implement a WSCCallObserver protocol which fastens to the Call to monitor call events such as ACCEPTED , REJECTED , RECEIVED .
Create a fresh WSCCallConfig class to determine the nature of the WebRTC call, whether bisexual or mono-directional audio or movie or both.
Create and configure a fresh RTCPeerConnectionFactory object and commence the WSCCall using the embark method.
When the call is accomplish, terminate the call using the WSCCall object’s end method.
Prerequisites
Before continuing, make sure you accurately review and understand the JavaScript API discussed in the following chapters:
The WebRTC Session Controller iOS SDK is closely aligned in concept and functionality with the JavaScript SDK to ensure a seamless transition.
In addition to an understanding of the WebRTC Session Controller JavaScript API, you are expected to be familiar with:
Objective C and general object oriented programming concepts
General iOS SDK programming concepts including event treating, delegates, and views.
The functionality and use of XCode.
iOS SDK System Requirements
In order to develop applications with the WebRTC Session Controller SDK, you must meeting the following software/hardware requirements:
A installed and fully configured WebRTC Session Controller installation. See the Oracle Communications WebRTC Session Controller Installation Guide .
A Macintosh computer capable of running XCode version Five.1 or later.
An actual iOS hardware device.
While you can test the general flow and function of your iOS WebRTC Session Controller application using the iOS simulator, a physical iOS device such as an iPhone or an iPad is required to fully utilize audio and movie functionality.
About the Examples in This Chapter
The examples and descriptions in this chapter are kept intentionally straightforward in order to illustrate the functionality of the WebRTC Session Controller iOS SDK API without obscuring it with user interface code and other abstractions and indirections. Since it is likely that use cases for production applications will take many forms, the examples assume no pre-existing interface schemas except when absolutely necessary, and then, only with the barest minimum of code. For example, if a particular method requires arguments such as a user name, a code example will display a plain string username such as " [email protected] " being passed to the method. It is assumed that in a production application, you would interface with the iOS device’s contact manager.
Installing the iOS SDK
To install the WebRTC Session Controller iOS SDK, do the following:
The WebRTC Session Controller iOS SDK requires XCode version Five.1 or higher.
iOS version six is the minimum required by the WebRTC Session Controller iOS SDK for utter functionality.
Download and extract the WebRTC Session Controller iOS SDK zip file. There are two subfolders, in the archive, include and lib .
Within the include folder are two folders, wsc and webrtc containing, respectively, the header files for the WebRTC Session Controller iOS SDK, and the WebRTC SDK.
Within the lib folder, are two folders, debug and release , each of which contain wsc and webrtc folders with WebRTC Session Controller iOS SDK, and the WebRTC SDK libraries for either debug or release builds depending upon your state of development.
Import the WebRTC Session Controller iOS SDK .a lib files:
Select your application target in XCode project navigator.
Click Build Settings in top of the editor pane.
Expand Link Binary With Libraries .
Haul the .a lib files from the lib folders of webrtc and wsc_sdk into the expanded panel.
The webrtc folder contains two sets of lib files, one for iOS devices in the ios folder and one for the iOS simulator in the sim folder. Make sure you choose the correct lib files for your target.
In addition, make sure you include either debug or release libraries as suitable for your development target.
Import any other system frameworks you require. The following extra frameworks are recommended:
libicucore.dylib : A unicode support library. For more information see: http://icu-project.org/apiref/icu4c40/ .
libsqlite3.dylib : A framework providing a SQLite interface. For more information, see: https://developer.apple.com/technologies/ios/data-management.html .
Import the header files from include/webrtc and include/wsc by dragging the wsc and webrtc folders directly onto your project in the XCode project navigator.
Click Build Settings in the top of the editor toolbar.
Expand Linking and set -ObjC as Other Linker Flags for both Debug and Release . For more information on setting XCode build settings, see: https://developer.apple.com/library/ios/recipes/xcode_help-project_editor/Articles/EditingBuildSettings.html .
If you are targeting iOS version eight or above, add the libstdc++.6.dylib.a framework to prevent linking errors.
Authenticating with WebRTC Session Controller
You use the WSCHttpContext class to set up an authentication context. The authentication context contains the necessary HTTP headers and SSLContext information, and is used when setting up a wsc.Session.
Initialize a URL Object
You then create a fresh NSURL object using the URL to your WebRTC Session Controller endpoint.
Example 14-1 Initializing a URL Object
Configure Authorization Headers if Required
Configure authorization headers as required by your authentication scheme. The following example uses Basic authentication; OAuth and other authentication schemes will be similarly configured.
Example 14-2 Initializing Basic Authentication Headers
If you are using Guest authentication, no headers are required.
Connect to the URL
With your authentication parameters configured, you can now connect to the WebRTC Session Controller URL using sendSynchronousRequest . or NSURlRequest , and NSURlConnection , in which case the error and response are returned in delegate methods.
Example 14-3 Connecting to the WebRTC Session Controller URL
Configure the SSL Context if Required
If you are using Secure Sockets Layer (SSL), configure the SSL context, using the SSLCreateContext method, depending upon whether the URL connection was successful. For more information on SSLCreateContext , see https://developer.apple.com/library/mac/documentation/Security/Reference/secureTransportRef/index.html#/apple_ref/c/func/SSLCreateContext .
Example 14-4 Configuring the SSLContext
Retrieve the Response Headers from the Request
Depending upon the results of the authentication request, you retrieve the response headers from the URL request and copy the cookies to the httpContext builder.
Example 14-5 Retrieving the Response Headers from the URL Request
Build the HTTP Context
Depending upon the results of the authentication request, you then build the WSCHttpContext using WSCHttpContextBuilder .
Example 14-6 Building the HttpContext
Configure Interactive Connectivity Establishment (ICE)
If you have access to one or more Overwhelm/TURN ICE servers, you can initialize the WSCIceServer class. For details on ICE, see "Managing Interactive Connectivity Establishment Interval."
Example 14-7 Configuring the WSCIceServer Class
Creating a WebRTC Session Controller Session
Once you have configured your authentication method and connected to your WebRTC Session Controller endpoint, you can instantiate a WebRTC Session Controller session object.
Implement the WSCSessionConnectionDelegate Protocol
You must implement the WSCSessionConnectionDelegate protocol to treat the results of your session creation request. The WSCSessionConnectionDelegate protocol has two event handlers:
onSuccess : Triggered upon a successful session creation.
onFailure : Comebacks a failure status code. Triggered when session creation fails.
Example 14-8 Implementing the WSCSessionConnectionDelegate Protocol
Implement the WSCSession Connection Observer Protocol
Create a WSCSessionConnectionObserver protocol to monitor and react to switches in session state.
Example 14-9 Implementing the WSCSessionConnectionObserver Protocol
Build the Session Object and Open the Session Connection
With the connection delegate and connection observer configured, you now build a WebRTC Session Controller session and open a connection with the server.
Example 14-10 Building the Session Object and Opening the Session Connection
In Example 14-10, note that the withPackage method registers a fresh WSCCallPackage with the session that will be instantiated when creating voice or movie calls.
Configure Extra WSCSession Properties
You can configure extra properties when creating a session using the WSCSessionBuilder withProperty method.
Example 14-11 Configuring WSCSession Properties
Adding WebRTC Voice Support to your iOS Application
This section describes how you can add WebRTC voice support to your iOS application.
Initialize the CallPackage Object
When you created your Session, you registered a fresh WSCCallPackage object using the Session object’s withPackage method. You now instantiate that WSCCallPackage .
Example 14-12 Initializing the CallPackage
Use the default PACKAGE_TYPE_CALL call type unless you have defined a custom-built call type.
Place a WebRTC Voice Call from Your iOS Application
Once you have configured your authentication scheme, and created a Session, you can place voice calls from your iOS application.
Add the Audio Capture Device to Your Session
Before continuing, in order to stream audio from your iOS device you initialize a capture session and add an audio capture device.
Example 14-13 Adding an Audio Capture Device to Your Session
Initialize the Call Object
Now, with the WSCCallPackage object created, you then initialize a WSCCall object, passing the callee’s ID as an argument.
Example 14-14 Initializing the Call Object
Configure Trickle ICE
To improve ICE candidate gathering spectacle, you can choose to enable Trickle ICE in your application using the WSCCall object’s setTrickleIceMode method. For more information see "Enabling Trickle ICE to Improve Application Spectacle."
Example 14-15 Configuring Trickle ICE
Create a CallObserverDelegate Protocol
You create a CallObserverDelegate protocol so you can react to the following WSCCall events:
callUpdated : Triggered on incoming and outgoing call update requests.
mediaStateChanged : Triggered on switches to the WSCCall media state.
stateChanged : Triggered on switches to the WSCCall state.
Example 14-16 Creating a CallObserverDelegate Protocol
Register the CallObserverDelegate Protocol with the Call Object
You register the CallObserverDelegate protocol with the WSCCall object.
Example 14-17 Registering a CallObserverDelegate Protocol
Create a WSCCallConfig Object
You create a WSCCallConfig object to determine the type of call you wish to make. The WSCCallConfig constructor takes two parameters, audioMediaDirection and videoMediaDirection . The very first parameter configures an audio call while the 2nd configures a movie call.
The values for audioMediaDirection and videoMediaDirection parameters are:
WSCMediaDirectionNone : No direction; media support disabled.
WSCMediaDirectionRecvOnly : The media stream is receive only.
WSCMediaDirectionSendOnly : The media stream is send only.
WSCMediaDirectionSendRecv : The media stream is bi-directional.
Example 14-18 shows the configuration for a bi-directional, audio-only call.
Example 14-18 Creating an Audio CallConfig Object
Configure the Local MediaStream for Audio
With the WSCCallConfig object created, you then configure the local audio MediaStream using the WebRTC PeerConnectionFactory . For information on the WebRTC SDK API, see http://www.webrtc.org/reference/native-apis .
Example 14-19 Configuring the Local MediaStream for Audio
Embark the Audio Call
Eventually, you embark the audio call using the Call object’s commence method and passing it the WSCCallConfig object and the streamArray .
Example 14-20 Kicking off the Audio Call
Terminating the Audio Call
To terminate the audio call, use the WSCCall object end method:
Receiving a WebRTC Voice Call in Your iOS Application
This section describes configuring your iOS application to receive WebRTC voice calls.
Create a CallPackageObserverDelegate
To be notified of an incoming call, create a CallPackageObserverDelegate and fasten it to your WSCCallPackage .
Example 14-21 Creating a CallPackageObserver Delegate
In Example 14-21, the callArrived event handler processes an incoming call request:
The method registers a CallObserverDelegate for the incoming call. In this case, it uses the same CallObserverDelegate , from the example in "Create a CallObserverDelegate Protocol."
The method then configures the local media stream, in the same manner as "Configure the Local MediaStream for Audio."
The method determines whether to accept or reject the call based upon the value of the answerTheCall boolean using either Call object’s accept or decline methods.
The answerTheCall boolean will most likely be set by a user interface element in your application such as a button or link.
Truss the CallPackage Observer to the CallPackage
With the CallPackage observer created, you tie it to your CallPackage object:
Adding WebRTC Movie Support to your iOS Application
This section describes how you can add WebRTC movie support to your iOS application. While the methods are almost fully identical to adding voice call support to an iOS application, extra prep is required.
Add the Audio and Movie Capture Devices to Your Session
As with an audio call, you initialize the audio capture device as shown in "Add the Audio Capture Device to Your Session." In addition, you initialize the movie capture device and add it to your session.
Example 14-22 Adding the Audio and Movie Capture Devices to Your Session
Configure a View Controller and a View Display Incoming Movie
You add a view object to a view controller to display the incoming movie. In Example 14-23, when the MyWebRTCApplicationViewController view controller is created, its view property is nil, which triggers the loadView method
Example 14-23 Creating a View to Display the Movie Stream
Next you set the view controller as the rootViewController, which adds videoView as a subview of the window, and automatically resizes videoView to be the same size as the window.
Example 14-24 Setting the Root View Controller
Placing a WebRTC Movie Call from Your iOS Application
To place a movie call from your iOS application, finish the coding tasks contained in the following sections:
In addition, finish the coding tasks for an audio call contained in the following sections:
Audio and movie call work flows are identical with the exception of media directions, local media stream configuration, and the extra considerations described earlier in this section.
Create a WSCCallConfig Object
You create a WSCCallConfig object as described in "Create a WSCCallConfig Object," in the audio call section, setting both arguments to WSCMediaDirectionSendRecv .
Example 14-25 Creating an Audio/Movie WSCCallConfig Object
Configure the Local WSCMediaStream for Audio and Movie
With the CallConfig object created, you then configure the local movie and audio MediaStream objects using the WebRTC PeerConnectionFactory . In Example 14-26, the PeerConnectionFactory is used to very first configure a movie stream using optional constraints and mandatory constraints (as defined in the getMandatoryConstraints method), and is then added to the localMediaStream using its addVideoTrack method. Two boolean arguments, hasAudio and hasVideo, enable the calling function to specify whether audio or movie flows are supported in the current call. The audioTrack is added as well and the localMediaStream is returned to the calling function.
For information on the WebRTC PeerConnectionFactory and mandatory and optional constraints, see http://www.webrtc.org/reference/native-apis .
Example 14-26 Configuring the Local MediaStream for Audio and Movie
Tie the Movie Track to the View Controller
Example 14-27 Cording the Movie Track to the View Controller
Begin the Movie Call
Eventually, embark the audio/movie call using the Call object’s commence method and passing it the WSCCallConfig object and the MediaStream stream array.
Example 14-28 Beginning the Movie Call
Terminate the Movie Call
To terminate the movie call, use the WSCCall object’s end method:
Example 14-29 Terminating the Movie Call
Receiving a WebRTC Movie Call in Your iOS Application
Receiving a movie call is identical to receiving an audio call as described here, "Receiving a WebRTC Voice Call in Your iOS Application." The only difference is the configuration of the WSCMediaStream object, as described in "Configure the Local WSCMediaStream for Audio and Movie."
Upgrading and Downgrading Calls
This section describes how you can treat upgrading an audio call to an audio movie call and downgrading a movie call to an audio-only call in your iOS application.
Treat Upgrade and Downgrade Requests from Your Application
To upgrade from a voice call to a movie call as a request from your application, you can tie a user interface element such as a button class containing the WSCCall update logic using the forControlEvents act:
You treat the upgrade or downgrade workflow in the videoUpgrade and videoDowngrade event handlers for each button example.
Example 14-30 Sending Upgrade/Downgrade Requests from Your Application
Treat Incoming Upgrade Requests
You configure the callUpdated method of your CallObserverDelegate class to treat incoming upgrade requests in the case of a WSCCallUpdateEventReceived state switch.
The declineUpgrade boolean must be set by some other part of your application’s user interface.
Example 14-31 Treating an Incoming Upgrade Request
Developing WebRTC-enabled iOS Applications
14 Developing WebRTC-enabled iOS Applications
This chapter shows how you can use the Oracle Communications WebRTC Session Controller iOS application programming interface (API) library to develop WebRTC-enabled iOS applications.
About the iOS SDK
The WebRTC Session Controller iOS SDK enables you to integrate your iOS applications with core WebRTC Session Controller functions. You can use the iOS SDK to implement the following features:
Audio calls inbetween an iOS application and any other WebRTC-enabled application, a Session Initialization Protocol (SIP) endpoint, or a Public Switched Telephone Network endpoint using a SIP trunk.
Movie calls inbetween an iOS application and any other WebRTC-enabled application, with suitable movie conferencing support.
Seamless upgrading of an audio call to a movie call and downgrading of a movie call to an audio call.
Support for Interactive connectivity Establishment (ICE) server configuration, including support for Trickle ICE.
See-through session reconnection following network connectivity interruption.
The WebRTC Session Controller iOS SDK is built upon several extra libraries and modules as shown in Figure 14-1.
Figure 14-1 iOS SDK Architecture
The WebRTC iOS cording enables the WebRTC Session Controller iOS SDK access to the native WebRTC library which itself provides WebRTC support. The Socket Rocket WebSocket library enables the WebSocket access required to communicate with WebRTC Session Controller.
For extra information on any of the APIs used in this document, see Oracle WebRTC Session Controller iOS API Reference .
Supported Architectures
The WebRTC Session Controller iOS SDK supports the following architectures:
About the iOS SDK WebRTC Call Workflow
The general workflow for using the WebRTC Session Controller iOS SDK to place a call is:
Authenticate against WebRTC Session Controller using the WSCHttpContext class. You initialize the WSCHttpContext with necessary HTTP headers and optional SSLContextRef in the following manner:
Send an HTTP GET request to the login URI of WebRTC Session Controller
Accomplish the authentication process based upon your authentication scheme
Proceed with the WebSocket handshake on the established authentication context
Establish a WebRTC Session Controller session using the WSCSession class.
Two protocols must be implemented:
WSCSessionConnectionDelegate : A delegate that reports on the success or failure of the session creation.
WSCSessionObserverDelegate : A delegate that signals on various session state switches, including CLOSED , CONNECTED , FAILED , and others.
Once a session is established, create a WSCCallPackage class which manages WSCCall objects in the WSCSession .
Create a WSCCall using the WSCCallPackage createCall method with a callee ID as its argument, for example, [email protected].
Implement a WSCCallObserver protocol which affixes to the Call to monitor call events such as ACCEPTED , REJECTED , RECEIVED .
Create a fresh WSCCallConfig class to determine the nature of the WebRTC call, whether bisexual or mono-directional audio or movie or both.
Create and configure a fresh RTCPeerConnectionFactory object and commence the WSCCall using the embark method.
When the call is accomplish, terminate the call using the WSCCall object’s end method.
Prerequisites
Before continuing, make sure you accurately review and understand the JavaScript API discussed in the following chapters:
The WebRTC Session Controller iOS SDK is closely aligned in concept and functionality with the JavaScript SDK to ensure a seamless transition.
In addition to an understanding of the WebRTC Session Controller JavaScript API, you are expected to be familiar with:
Objective C and general object oriented programming concepts
General iOS SDK programming concepts including event treating, delegates, and views.
The functionality and use of XCode.
iOS SDK System Requirements
In order to develop applications with the WebRTC Session Controller SDK, you must meeting the following software/hardware requirements:
A installed and fully configured WebRTC Session Controller installation. See the Oracle Communications WebRTC Session Controller Installation Guide .
A Macintosh computer capable of running XCode version Five.1 or later.
An actual iOS hardware device.
While you can test the general flow and function of your iOS WebRTC Session Controller application using the iOS simulator, a physical iOS device such as an iPhone or an iPad is required to fully utilize audio and movie functionality.
About the Examples in This Chapter
The examples and descriptions in this chapter are kept intentionally straightforward in order to illustrate the functionality of the WebRTC Session Controller iOS SDK API without obscuring it with user interface code and other abstractions and indirections. Since it is likely that use cases for production applications will take many forms, the examples assume no pre-existing interface schemas except when absolutely necessary, and then, only with the barest minimum of code. For example, if a particular method requires arguments such as a user name, a code example will demonstrate a plain string username such as " [email protected] " being passed to the method. It is assumed that in a production application, you would interface with the iOS device’s contact manager.
Installing the iOS SDK
To install the WebRTC Session Controller iOS SDK, do the following:
The WebRTC Session Controller iOS SDK requires XCode version Five.1 or higher.
iOS version six is the minimum required by the WebRTC Session Controller iOS SDK for utter functionality.
Download and extract the WebRTC Session Controller iOS SDK zip file. There are two subfolders, in the archive, include and lib .
Within the include folder are two folders, wsc and webrtc containing, respectively, the header files for the WebRTC Session Controller iOS SDK, and the WebRTC SDK.
Within the lib folder, are two folders, debug and release , each of which contain wsc and webrtc folders with WebRTC Session Controller iOS SDK, and the WebRTC SDK libraries for either debug or release builds depending upon your state of development.
Import the WebRTC Session Controller iOS SDK .a lib files:
Select your application target in XCode project navigator.
Click Build Settings in top of the editor pane.
Expand Link Binary With Libraries .
Haul the .a lib files from the lib folders of webrtc and wsc_sdk into the expanded panel.
The webrtc folder contains two sets of lib files, one for iOS devices in the ios folder and one for the iOS simulator in the sim folder. Make sure you choose the correct lib files for your target.
In addition, make sure you include either debug or release libraries as suitable for your development target.
Import any other system frameworks you require. The following extra frameworks are recommended:
libicucore.dylib : A unicode support library. For more information see: http://icu-project.org/apiref/icu4c40/ .
libsqlite3.dylib : A framework providing a SQLite interface. For more information, see: https://developer.apple.com/technologies/ios/data-management.html .
Import the header files from include/webrtc and include/wsc by dragging the wsc and webrtc folders directly onto your project in the XCode project navigator.
Click Build Settings in the top of the editor toolbar.
Expand Linking and set -ObjC as Other Linker Flags for both Debug and Release . For more information on setting XCode build settings, see: https://developer.apple.com/library/ios/recipes/xcode_help-project_editor/Articles/EditingBuildSettings.html .
If you are targeting iOS version eight or above, add the libstdc++.6.dylib.a framework to prevent linking errors.
Authenticating with WebRTC Session Controller
You use the WSCHttpContext class to set up an authentication context. The authentication context contains the necessary HTTP headers and SSLContext information, and is used when setting up a wsc.Session.
Initialize a URL Object
You then create a fresh NSURL object using the URL to your WebRTC Session Controller endpoint.
Example 14-1 Initializing a URL Object
Configure Authorization Headers if Required
Configure authorization headers as required by your authentication scheme. The following example uses Basic authentication; OAuth and other authentication schemes will be similarly configured.
Example 14-2 Initializing Basic Authentication Headers
If you are using Guest authentication, no headers are required.
Connect to the URL
With your authentication parameters configured, you can now connect to the WebRTC Session Controller URL using sendSynchronousRequest . or NSURlRequest , and NSURlConnection , in which case the error and response are returned in delegate methods.
Example 14-3 Connecting to the WebRTC Session Controller URL
Configure the SSL Context if Required
If you are using Secure Sockets Layer (SSL), configure the SSL context, using the SSLCreateContext method, depending upon whether the URL connection was successful. For more information on SSLCreateContext , see https://developer.apple.com/library/mac/documentation/Security/Reference/secureTransportRef/index.html#/apple_ref/c/func/SSLCreateContext .
Example 14-4 Configuring the SSLContext
Retrieve the Response Headers from the Request
Depending upon the results of the authentication request, you retrieve the response headers from the URL request and copy the cookies to the httpContext builder.
Example 14-5 Retrieving the Response Headers from the URL Request
Build the HTTP Context
Depending upon the results of the authentication request, you then build the WSCHttpContext using WSCHttpContextBuilder .
Example 14-6 Building the HttpContext
Configure Interactive Connectivity Establishment (ICE)
If you have access to one or more Overwhelm/TURN ICE servers, you can initialize the WSCIceServer class. For details on ICE, see "Managing Interactive Connectivity Establishment Interval."
Example 14-7 Configuring the WSCIceServer Class
Creating a WebRTC Session Controller Session
Once you have configured your authentication method and connected to your WebRTC Session Controller endpoint, you can instantiate a WebRTC Session Controller session object.
Implement the WSCSessionConnectionDelegate Protocol
You must implement the WSCSessionConnectionDelegate protocol to treat the results of your session creation request. The WSCSessionConnectionDelegate protocol has two event handlers:
onSuccess : Triggered upon a successful session creation.
onFailure : Comes back a failure status code. Triggered when session creation fails.
Example 14-8 Implementing the WSCSessionConnectionDelegate Protocol
Implement the WSCSession Connection Observer Protocol
Create a WSCSessionConnectionObserver protocol to monitor and react to switches in session state.
Example 14-9 Implementing the WSCSessionConnectionObserver Protocol
Build the Session Object and Open the Session Connection
With the connection delegate and connection observer configured, you now build a WebRTC Session Controller session and open a connection with the server.
Example 14-10 Building the Session Object and Opening the Session Connection
In Example 14-10, note that the withPackage method registers a fresh WSCCallPackage with the session that will be instantiated when creating voice or movie calls.
Configure Extra WSCSession Properties
You can configure extra properties when creating a session using the WSCSessionBuilder withProperty method.
Example 14-11 Configuring WSCSession Properties
Adding WebRTC Voice Support to your iOS Application
This section describes how you can add WebRTC voice support to your iOS application.
Initialize the CallPackage Object
When you created your Session, you registered a fresh WSCCallPackage object using the Session object’s withPackage method. You now instantiate that WSCCallPackage .
Example 14-12 Initializing the CallPackage
Use the default PACKAGE_TYPE_CALL call type unless you have defined a custom-made call type.
Place a WebRTC Voice Call from Your iOS Application
Once you have configured your authentication scheme, and created a Session, you can place voice calls from your iOS application.
Add the Audio Capture Device to Your Session
Before continuing, in order to stream audio from your iOS device you initialize a capture session and add an audio capture device.
Example 14-13 Adding an Audio Capture Device to Your Session
Initialize the Call Object
Now, with the WSCCallPackage object created, you then initialize a WSCCall object, passing the callee’s ID as an argument.
Example 14-14 Initializing the Call Object
Configure Trickle ICE
To improve ICE candidate gathering spectacle, you can choose to enable Trickle ICE in your application using the WSCCall object’s setTrickleIceMode method. For more information see "Enabling Trickle ICE to Improve Application Spectacle."
Example 14-15 Configuring Trickle ICE
Create a CallObserverDelegate Protocol
You create a CallObserverDelegate protocol so you can react to the following WSCCall events:
callUpdated : Triggered on incoming and outgoing call update requests.
mediaStateChanged : Triggered on switches to the WSCCall media state.
stateChanged : Triggered on switches to the WSCCall state.
Example 14-16 Creating a CallObserverDelegate Protocol
Register the CallObserverDelegate Protocol with the Call Object
You register the CallObserverDelegate protocol with the WSCCall object.
Example 14-17 Registering a CallObserverDelegate Protocol
Create a WSCCallConfig Object
You create a WSCCallConfig object to determine the type of call you wish to make. The WSCCallConfig constructor takes two parameters, audioMediaDirection and videoMediaDirection . The very first parameter configures an audio call while the 2nd configures a movie call.
The values for audioMediaDirection and videoMediaDirection parameters are:
WSCMediaDirectionNone : No direction; media support disabled.
WSCMediaDirectionRecvOnly : The media stream is receive only.
WSCMediaDirectionSendOnly : The media stream is send only.
WSCMediaDirectionSendRecv : The media stream is bi-directional.
Example 14-18 shows the configuration for a bi-directional, audio-only call.
Example 14-18 Creating an Audio CallConfig Object
Configure the Local MediaStream for Audio
With the WSCCallConfig object created, you then configure the local audio MediaStream using the WebRTC PeerConnectionFactory . For information on the WebRTC SDK API, see http://www.webrtc.org/reference/native-apis .
Example 14-19 Configuring the Local MediaStream for Audio
Begin the Audio Call
Eventually, you embark the audio call using the Call object’s commence method and passing it the WSCCallConfig object and the streamArray .
Example 14-20 Embarking the Audio Call
Terminating the Audio Call
To terminate the audio call, use the WSCCall object end method:
Receiving a WebRTC Voice Call in Your iOS Application
This section describes configuring your iOS application to receive WebRTC voice calls.
Create a CallPackageObserverDelegate
To be notified of an incoming call, create a CallPackageObserverDelegate and link it to your WSCCallPackage .
Example 14-21 Creating a CallPackageObserver Delegate
In Example 14-21, the callArrived event handler processes an incoming call request:
The method registers a CallObserverDelegate for the incoming call. In this case, it uses the same CallObserverDelegate , from the example in "Create a CallObserverDelegate Protocol."
The method then configures the local media stream, in the same manner as "Configure the Local MediaStream for Audio."
The method determines whether to accept or reject the call based upon the value of the answerTheCall boolean using either Call object’s accept or decline methods.
The answerTheCall boolean will most likely be set by a user interface element in your application such as a button or link.
Truss the CallPackage Observer to the CallPackage
With the CallPackage observer created, you truss it to your CallPackage object:
Adding WebRTC Movie Support to your iOS Application
This section describes how you can add WebRTC movie support to your iOS application. While the methods are almost totally identical to adding voice call support to an iOS application, extra prep is required.
Add the Audio and Movie Capture Devices to Your Session
As with an audio call, you initialize the audio capture device as shown in "Add the Audio Capture Device to Your Session." In addition, you initialize the movie capture device and add it to your session.
Example 14-22 Adding the Audio and Movie Capture Devices to Your Session
Configure a View Controller and a View Display Incoming Movie
You add a view object to a view controller to display the incoming movie. In Example 14-23, when the MyWebRTCApplicationViewController view controller is created, its view property is nil, which triggers the loadView method
Example 14-23 Creating a View to Display the Movie Stream
Next you set the view controller as the rootViewController, which adds videoView as a subview of the window, and automatically resizes videoView to be the same size as the window.
Example 14-24 Setting the Root View Controller
Placing a WebRTC Movie Call from Your iOS Application
To place a movie call from your iOS application, finish the coding tasks contained in the following sections:
In addition, finish the coding tasks for an audio call contained in the following sections:
Audio and movie call work flows are identical with the exception of media directions, local media stream configuration, and the extra considerations described earlier in this section.
Create a WSCCallConfig Object
You create a WSCCallConfig object as described in "Create a WSCCallConfig Object," in the audio call section, setting both arguments to WSCMediaDirectionSendRecv .
Example 14-25 Creating an Audio/Movie WSCCallConfig Object
Configure the Local WSCMediaStream for Audio and Movie
With the CallConfig object created, you then configure the local movie and audio MediaStream objects using the WebRTC PeerConnectionFactory . In Example 14-26, the PeerConnectionFactory is used to very first configure a movie stream using optional constraints and mandatory constraints (as defined in the getMandatoryConstraints method), and is then added to the localMediaStream using its addVideoTrack method. Two boolean arguments, hasAudio and hasVideo, enable the calling function to specify whether audio or movie flows are supported in the current call. The audioTrack is added as well and the localMediaStream is returned to the calling function.
For information on the WebRTC PeerConnectionFactory and mandatory and optional constraints, see http://www.webrtc.org/reference/native-apis .
Example 14-26 Configuring the Local MediaStream for Audio and Movie
Truss the Movie Track to the View Controller
Example 14-27 Strapping the Movie Track to the View Controller
Embark the Movie Call
Ultimately, begin the audio/movie call using the Call object’s begin method and passing it the WSCCallConfig object and the MediaStream stream array.
Example 14-28 Commencing the Movie Call
Terminate the Movie Call
To terminate the movie call, use the WSCCall object’s end method:
Example 14-29 Terminating the Movie Call
Receiving a WebRTC Movie Call in Your iOS Application
Receiving a movie call is identical to receiving an audio call as described here, "Receiving a WebRTC Voice Call in Your iOS Application." The only difference is the configuration of the WSCMediaStream object, as described in "Configure the Local WSCMediaStream for Audio and Movie."
Upgrading and Downgrading Calls
This section describes how you can treat upgrading an audio call to an audio movie call and downgrading a movie call to an audio-only call in your iOS application.
Treat Upgrade and Downgrade Requests from Your Application
To upgrade from a voice call to a movie call as a request from your application, you can truss a user interface element such as a button class containing the WSCCall update logic using the forControlEvents activity:
You treat the upgrade or downgrade workflow in the videoUpgrade and videoDowngrade event handlers for each button example.
Example 14-30 Sending Upgrade/Downgrade Requests from Your Application
Treat Incoming Upgrade Requests
You configure the callUpdated method of your CallObserverDelegate class to treat incoming upgrade requests in the case of a WSCCallUpdateEventReceived state switch.
The declineUpgrade boolean must be set by some other part of your application’s user interface.
Example 14-31 Treating an Incoming Upgrade Request