Namespace $.fn.cwic

Namespace Summary

Constructor Attributes	Constructor Name and Description
	$.fn.cwic CWIC is a jQuery plug-in to access the Cisco Web Communicator Audio and Video media require the Cisco Web Communicator add-on to be installed Fields overview Methods overview All cwic methods are called in the following manner $('#selector').cwic('method',parameters) Events overview All events are part of the cwic namespace.

Method Summary

Method Attributes	Method Name and Description
<inner>	about() Versions, states and capabilities.
<inner>	addPreviewWindow(args) Assign a video window object to preview (self-view).
<inner>	cancelSSO() Cancels ongoing Single Sign On procedure if internal 'canCancelSingleSignOn' capability is enabled.
<inner>	createVideoWindow(settings) Creates an object that can be passed to startConversation, addPreviewWindow, or updateConversation('addRemoteVideoWindow').
<inner>	dock(args) Docks an external video window created by $.fn.cwic-showPreviewInExternalWindow or $.fn.cwic-showCallInExternalWindow.
<inner>	endConversation(iDivert, id) Ends a conversation.
<inner>	getExternalWindowState() Triggers an $.fn.cwic#event:externalWindowEvent to be sent to the application with the current state of the external window.
<inner>	getMultimediaDevices() Gets a list of objects describing the multimedia devices installed on a system.
<inner>	getMultimediaDeviceVolume(device, callback(volume)) Gets the current volume value for particular device.
<inner>	getUserAuthStatus() Gets the current user authorization status.
<inner>	hideExternalWindow() Hides an external video window created by $.fn.cwic-showPreviewInExternalWindow or $.fn.cwic-showCallInExternalWindow.
<inner>	init(options) Wait for the document to be ready, and try to load the Cisco Web Communicator add-on.
<inner>	manualSignIn() Alias for $.fn.cwic-registerPhone
<inner>	registerPhone(args) Register phone to CUCM (SIP register).
<inner>	removePreviewWindow(args) Remove a video window object from preview (self-view)
<inner>	resetData() Clears cached user and system data.
<inner>	sendDTMF(digit, id) Sends digit (String) as Dual-Tone Multi-Frequency (DTMF)
<inner>	setCaptureDevice(clientCaptureID:) Sets the video capture device used by the Cisco Web Communicator.
<inner>	setExternalWindowAlwaysOnTop(isAlwaysOnTop) Controls whether external video windows created by $.fn.cwic-showPreviewInExternalWindow or $.fn.cwic-showCallInExternalWindow are shown always on top (default) or not.
<inner>	setExternalWindowShowControls(showControls) Controls whether a overlaid controls are shown in external video window created by $.fn.cwic-showCallInExternalWindow or $.fn.cwic-showPreviewInExternalWindow.
<inner>	setExternalWindowShowSelfViewPip(showPipSelfView) Controls whether a picture-in-picture preview (self-view) is shown when $.fn.cwic-showCallInExternalWindow is used to put a call in external video window.
<inner>	setExternalWindowTitle(title) Sets the window title used in external video windows created by $.fn.cwic-showPreviewInExternalWindow or $.fn.cwic-showCallInExternalWindow.
<inner>	setMicrophoneVolume() Sets microphone volume.
<inner>	setPlayoutDevice(clientPlayoutID:) Sets the audio playout device used by the Cisco Web Communicator.
<inner>	setPlayRingerOnAllDevices() Sets all capable devices as ringers.
<inner>	setRecordingDevice(clientRecordingID:) Sets the audio recording device used by the Cisco Web Communicator.
<inner>	setRingerDevice(clientRingerID:) Sets the ringer device used by the Cisco Web Communicator.
<inner>	setRingerVolume() Sets ringer volume.
<inner>	setRingtone(ringtone) Sets ringtone.
<inner>	setSpeakerVolume() Sets speaker volume.
<inner>	showCallInExternalWindow(id) Shows the call in an external video window.
<inner>	showPreviewInExternalWindow() Shows preview (self-view) in an external video window.
<inner>	showUserAuthorization(denied, force) Shows the user authorization dialog.
<inner>	shutdown() Shuts down the API Unregisters the phone Unbinds all cwic events handlers Clears all cwic data Releases the Cisco Web Communicator add-on instance
<inner>	signOut(args) Signs out a registered device from CUCM: Ends any active call.
<inner>	startConversation(conversation) Start a conversation with a participant.
<inner>	startDiscovery(args) Initiates service discovery based sign-in.
<inner>	switchPhoneMode(options) Switch mode on a session that is already authorized.
<inner>	undock() Undocks an external video window previously docked by $.fn.cwic-dock Example use:
<inner>	unregisterPhone(args) Unregisters a phone from CUCM: Ends any active call if this is the last instance or forceLogout is set to true.
<inner>	updateConversation(update, id) Updates an existing conversation.

Event Summary

Event Attributes	Event Name and Description
	callTransferInProgress(event) A call transfer is in progress.
	conversationEnd(event, conversation) A conversation has ended.
	conversationIncoming(event, conversation, container) A new conversation is being received, but has not yet started.
	conversationStart(event, conversation, container) A conversation has just started.
	conversationUpdate(event, conversation, container) One or more properties of a conversation have changed, such as state or participants.
	error(event)
	externalWindowEvent(event) A property has changed on the external video window created by $.fn.cwic-showPreviewInExternalWindow or $.fn.cwic-showCallInExternalWindow.
	invalidCertificate(event) An invalid certificate detected.
	mmDeviceChange(event) A change to the list of local multimedia devices has occurred.
	multimediaCapabilities(event) Signals weather the multimedia capability is enabled or not.
	ringtoneChange(event) Ringtone changed
	ringtonesListAvailable(event) List of ringtones is available
	ssoNavigateTo(event) Signals when authentication with Identity Provider is required during the SSO process.
	system(event) Called when the phone changes state.

Parameters:

{String} method

The name of the method to call

{Variable} arguments

trailing arguments are passed to the specific call see methods below

Returns:

{aboutObject}

---

Parameters:

{Object} args

arguments object

{DOMWindow} args.window Optional

DOM Window that contains the plug-in Object defaults to current window

{String|Object} args.previewWindow

ID or DOM element of preview window

{Function} args.error Optional

Called when arguments object is malformed, i.e. args.previewWindow ID or DOM element is non-existent or malformed

---

---

Parameters:

{Object} settings Optional

Settings to use when creating the video render object

{String} settings.id Optional, Default: generated

The DOM ID of the element to be created

{Function} settings.success Optional

Called when the object is loaded and ready for use plug-in ID is passed as a parameter

{String} settings.onload Optional

Not recommended for video windows created in the same window as the main phone plug-in.
Mandatory in popup windows or iframes. The string must be the name of a function in the global scope, and the function must call parent or opener window._cwic_onPopupVideoPluginLoaded. This function will be called in the onload handler of the video object.
Single parameter is the videoplugin object that must be passed to the parent handler.

---

Parameters:

{Object} args Optional

Information about target element for video overlay

{DOMWindow} args.window

Window object in which the target element is located

{DOMElement} args.element

Target element for video overlay

Since:

3.1.2

---

Parameters:

{boolean} iDivert

If true, redirects the call to voice mail. See UCM documentation on the Immediate Divert (iDivert) feature for details. The call can be iDiverted only if call#capabilities contains 'canImmediateDivert',

{String|Object} id

A conversation identifier (String) or an Object containing an id property.

---

Since:

3.1.0

---

Since:

3.0.0

Returns:

a list of objects describing the multimedia devices with the following properties:

• deviceID: unique device ID
• deviceName: {string} human readable device name
• vendorID: {string} unique vendor ID
• productID: {string} vendor product ID
• hardwareID: {string} hardware dependent ID
• canRecord: {boolean} indicates whether this object can be used as an audio recording device
• canPlayout: {boolean} indicates whether this object can be used as an audio playout device
• canCapture: {boolean} indicates whether this object can be used as a video capture device
• canRing: {boolean} indicates whether this object can be used as a ringer device
• isDefault: {boolean} indicates whether this object represents the default device of the type indicated by the canRecord, canPlayout, and canCapture flags
• recordingName: {string} human readable name for the audio recording function of this device
• playoutName: {string} human readable name for the audio playout function of this device
• captureName: {string} human readable name for the video capture function of this device
• recordingID: {string} ID for the audio recording function of this device
• playoutID: {string} ID for the audio playout function of this device
• captureID: {string} ID for the video capture function of this device
• clientRecordingID: {string} the ID to pass to setRecordingDevice to select this device as the audio recording device
• clientPlayoutID: {string} the ID to pass to setPlayoutDevice to select this device as the audio playout device
• clientCaptureID: {string} the ID to pass to setCaptureDevice to select this device as the video capture device
• isSelectedRecordingDevice: {boolean} indicates whether this is the currently selected audio recording device
• isSelectedPlayoutDevice: {boolean} indicates whether this is the currently selected audio playout device
• isSelectedCaptureDevice: {boolean} indicates whether this is the currently selected video capture device

In order to use the list, the client should check the canXXXX fields to determine if a device can be passed as a particular function, then pass the clientXXXID to the correct setXXXXDevice function. Depending on the platform, devices with multiple functions may show up as a single entry with multiple IDs, or multiple times with similar or different IDs.

---

Parameters:

{String} device

Type of device. One of: "Speaker", "Microphone", "Ringer"

{Function} callback(volume)

Callback to be called with volume value

Since:

4.0.0

---

Since:

3.0.1

Returns:

{String} a value indicating the current user authorization status.

• "UserAuthorized" indicates the user has authorized the Cisco Web Communicator add-on and it is ready to use.
• "MustShowAuth" indicates the application must call $.fn.cwic-showUserAuthorization to show the user authorization dialog.
• "UserDenied" indicates the user has denied the application access to the Cisco Web Communicator add-on.
• "UserAuthPending" indicates the dialog box is currently displayed and the user has not yet selected "allow", "deny", or "always allow".
• "Unknown" indicates status cannot be determined because delay authorization feature is not supported by the current Cisco Web Communicator add-on. This case will trigger $.fn.cwic-errorMap.OperationNotSupported as well.

---

Since:

3.1.0

---

Parameters:

{Object} options

Is a set of key/value pairs to configure the phone registration. See $.fn.cwic-settings for options.

---

---

Parameters:

args

A map with:

{String} args.user

The CUCM end user name (required)

{String|Object} args.password

String - clear password. Object - {encrypted: encoded password, cipher:'cucm'}

{String|Object|Array} args.cucm

The list of CUCM(s) to attempt to register with (required).
If String, it will be used as a TFTP, CCMCIP and CTI address.
If Array, a list of String or Object as described above. Three is the maximum number of addresses per server (TFTP, CCMCIP, CTI).

{String[]} args.cucm.tftp Optional

TFTP addresses. Maximum three values.

{String[]} args.cucm.ccmcip Optional

CCMCIP addresses (will use tftp values if not present). Maximum three values.

{String[]} args.cucm.cti Optional

Since: 2.1.1
CTI addresses (will use tftp values if not present). Maximum three values.

{String} args.mode Optional

Register the phone in this mode. Available modes are "SoftPhone" or "DeskPhone". Default of intelligent guess is applied after a device is selected.

{Function} args.devicesAvailable(devices, phoneMode, callback) Optional

Callback called after successful authentication. If this callback is not specified, cwic applies the default device selection algorithm. An array of device objects is passed so the application can select the device.
To complete the device registration, call the callback function that is passed in to devicesAvailable as the third parameter. The callback function is defined in the API, but it must be called by the function that is specified as the devicesAvailable parameter.

{Function} args.error(err) Optional

Callback called if the registration fails. $.fn.cwic-errorMapEntry is passed as parameter.

{Boolean} args.forceRegistration Optional

Specifies whether to forcibly unregister other softphone instances with CUCM. Default is false. See GracefulRegistration doc for more info.

{Function} args.success(registration) Optional

Callback called when registration succeeds. A registration object is passed to the callback: registerPhone examples

---

Parameters:

{Object} args

arguments object

{DOMWindow} args.window Optional

DOM Window that contains the plug-in Object defaults to current window

{String|Object} args.previewWindow

id or DOM element of preview window

{Function} args.error Optional

Called when arguments object is malformed, i.e. args.previewWindow ID or DOM element is non-existent or malformed

---

---

Parameters:

{String} digit

Dual-Tone Multi-Frequency (DTMF) digit to send. Does not trigger any event.

{String|Object} id Optional

a {String} conversation identifier or an {Object} containing an id property

---

Parameters:

{String} clientCaptureID:

clientCaptureID retrieved from getMultimediaDevices()

Since:

3.0.0

---

Parameters:

{Boolean} isAlwaysOnTop

Set to false to remove the always on top property. Set to true to restore default behavior.

Since:

3.1.0

---

Parameters:

{Boolean} showControls

Set to false to turn off the overlaid call controls. Set to true to restore default behavior.

Since:

4.0.0

---

Parameters:

{Boolean} showPipSelfView

Set to false to turn off the picture-in-picture. Set to true to restore default behavior.

Since:

3.1.0

---

Parameters:

{String} title

A string value to be used as the window title for the exernal video window.

Since:

3.1.0

---

Parameters:

{String|Number} args.volume

Volume to set (0 to 100)

{Function} args.success

Success callback

{Function} args.error

Error callback

Since:

4.0.0

---

Parameters:

{String} clientPlayoutID:

clientPlayoutID retrieved from getMultimediaDevices()

Since:

3.0.0

---

Since:

4.0.0

---

Parameters:

{String} clientRecordingID:

clientRecordingID retrieved from getMultimediaDevices()

Since:

3.0.0

---

Parameters:

{String} clientRingerID:

clientRingerID retrieved from getMultimediaDevices()

Since:

4.0.0

---

Parameters:

{String|Number} args.volume

Volume to set (0 to 100)

{Function} args.success

Success callback

{Function} args.error

Error callback

Since:

4.0.0

---

Parameters:

{String} ringtone

ringtone name

Since:

4.0.0

---

Parameters:

{String|Number} args.volume

Volume to set (0 to 100)

{Function} args.success

Success callback

{Function} args.error

Error callback

Since:

4.0.0

---

Parameters:

{String|Object} id Optional

A {String} conversation identifier or an {Object} containing an id property.

Since:

3.1.0

---

Since:

3.1.0

---

Parameters:

{Function} denied

A callback that will be called if the user selects "deny" from the user authorization dialog. If the user selects allow or always allow, the settings.ready callback will be called.

{Boolean} force Optional, Default: false

Since 3.1.0
Set true to force the dialog to display even if the page is currently hidden. Setting this may cause the dialog to appear when the page is not yet accessible to the user.

Since:

3.0.1

---

---

Parameters:

args Optional

Is a set of key/value pairs to configure the phone signOut.

{function} args.complete Optional

Callback called when sign out is successfully completed.

---

Parameters:

{Object|call} conversation

Can be a new object to start a new conversation or an existing call which you wish to answer.

{Number} conversation.id

Unique identifier of the conversation. Required when referencing an exising call.

{participant} conversation.participant

First remote participant of the call.

{String} conversation.participant.recipient

The phone number of the participant. Required when placing a new outbound call. This will be the dialed number for the call.

{String} conversation.participant.name Optional

The participant name.

{String} conversation.participant.photosrc Optional

A suitable value for the src attribute of an <img> element.

{String} conversation.state Optional

Current state of the conversation. Can be OffHook, Ringing, Connected, OnHook, Reorder.

{Date} conversation.start Optional

Start time. Defined on resolution update only.

{Date} conversation.connect Optional

Media connection time. Defined on resolution update only.

{Object} conversation.videoResolution Optional

Resolution of the video conversation, contains width and height properties. Defined on resolution update only.

{String|Object} conversation.container Optional

The HTML element which contains the conversation. Conversation events are triggered on this element. If String, specifies a jQuery selector If Object, specifies a jQuery wrapper of matched elements(s). By default container is $(this), that is the first element of the matched set startConversation is called on.

{String} conversation.subject Optional

The subject of the conversation to start.

{Function} conversation.error(err) Optional

A function to be called if the conversation cannot be started. $.fn.cwic-errorMapEntry is passed as parameter.

{String} conversation.videoDirection Optional

The video media direction: 'Inactive' or undefined (audio only by default), 'SendOnly', 'RecvOnly' or 'SendRecv'.

{Object} conversation.remoteVideoWindow Optional

The video object (must be of mime type application/x-cisco-cwc-videocall).

{DOMWindow} conversation.window Optional

DOM window that contains the remoteVideoWindow (default to this DOM window) required if specifying a video object on another window (popup/iframe).

---

Parameters:

{Object} args

A map with:

{String} args.mode Optional

Register the phone in this mode. Available modes are "SoftPhone" or "DeskPhone". Default of intelligent guess is applied after a device is selected.

{Function} args.devicesAvailable(devices, phoneMode, selectDeviceCb) Optional

Callback called after successful authentication. If this callback is not specified, cwic applies the default device selection algorithm. An array of device objects is passed so the application can select the device.
To complete the device registration, call the selectDeviceCb(phoneMode, deviceName, lineDN) function that is passed in to devicesAvailable as the third parameter. lineDN argument is optional and it is valid only in deskphone mode. It is ignored in softphone mode.

{Boolean} args.forceRegistration Optional

Specifies whether to forcibly unregister other softphone instances with CUCM. Default is false. See GracefulRegistration doc for more info.

{Function} args.success(registration) Optional

Callback called when registration succeeds. A registration object is passed to the callback

{Function} args.error(errorMapEntry) Optional

Callback called if the registration fails.

---

Parameters:

options

{Function} options.progress Optional

A handler called when the mode switch has passed pre-conditions.
If specified, the handler is called when the switchMode operation starts.

{Function} options.success(registration) Optional

A handler called when mode switch complete with registration as a parameter

{Function} options.error(err) Optional

A handler called when the mode switch fails on pre-conditions. $.fn.cwic-errorMapEntry is passed as parameter.

{string} options.mode Optional

The new mode 'SoftPhone'/'DeskPhone'. Defaults to SoftPhone. If you want to change a property on a desk phone, such as the line, you must explicitly set this parameter to 'DeskPhone'.

{string} options.device Optional

Name of the device (e.g. SEP012345678, ECPUSER) to control. If not specified and switching from SoftPhone to DeskPhone mode, it defaults to picking first available. If not specified and switching from DeskPhone to SoftPhone mode, it defaults to output of predictDevice function (see $.fn.cwic-settings.predictDevice). If 'first available' is desired result in this case, output of custom predictDevice function should be empty string ('').

{string} options.line Optional

Phone number of a line valid for the specified device (e.g. '0000'). defaults to picking first available

{Boolean} options.forceRegistration Optional

Specifies whether to forcibly unregister other softphone instances with CUCM. Default is false. See GracefulRegistration doc for more info.

---

Since:

3.1.2

---

Parameters:

args

Is a set of key/value pairs to configure the phone unregistration.

{function} args.complete Optional

Callback called when unregistration is successfully completed.
If specified, the handler is called only in the case where the phone was already registered.

{boolean} args.forceLogout:

If true, end the phone session even if registered in other instances. unregisterPhone examples

---

Parameters:

{String|Object} update

Update a started conversation. update can be:
A String: hold, resume, mute, unmute, muteAudio, muteVideo, unmuteAudio, unmuteVideo.
An Object: contains one or more writable conversation properties to update e.g. videoDirection.
Triggers a conversationUpdate event.

{String|Object} id

A conversation identifier (String) or Object containing an id property

Parameters:

{Object} event

{Function} event.completeTransfer

Function to be called to complete ongoing call transfer

Since:

4.0.0

---

Parameters:

{Object} event

{call} conversation

---

Parameters:

{Object} event

{call} conversation

{jQueryNodeArray} container

---

Parameters:

{Object} event

{call} conversation

{DomNode} container

---

Parameters:

{Object} event

{call} conversation

{jQueryNodeArray} container

---

Parameters:

{Object|$.fn.cwic-errorMapEntry} event

An arbitrary error event or pre-defined cwic error object.

{Object} event.code

{String} event.message Optional

{String[]} event.details Optional

An array of additional information.

---

Parameters:

{Object} event

{Object} event.externalWindowState

{Number} event.externalWindowState.callId

The call#callId of a call associated with the external video window. -1 if no call is associated. See also $.fn.cwic-showCallInExternalWindow.

{Boolean} event.externalWindowState.showing

When true, the external video window is displayed, possibly minimized or behind other windows. See also $.fn.cwic-hideExternalWindow.

{Boolean} event.externalWindowState.selfViewPip

When true, the external video window will display a picture-in-picture preview (self-view). Note the picture-in-picture preview will not be visible if preview is also in the full window. See also $.fn.cwic-setExternalWindowShowSelfViewPip.

{Boolean} event.externalWindowState.alwaysOnTop

When true, the external video window will be set to always display on top of other windows. See also $.fn.cwic-setExternalWindowAlwaysOnTop.

{Boolean} event.externalWindowState.preview

When true, the external video window is showing preview (self-view) in the full window. See also $.fn.cwic-showPreviewInExternalWindow.

{Boolean} event.externalWindowState.docking

When true, the external video window will be in docked state. See also $.fn.cwic-dock.

{String} event.externalWindowState.title

The text used for the external video window's title bar. See also $.fn.cwic-setExternalWindowTitle

Since:

3.1.0

---

Parameters:

{Object} event

{Function} event.respond(fingerprint,accept)

Function to be called to reject or accept advertised invalid certificate.

{Object} event.info

Additional info about advertised invalid certificate

{String} event.info.certFingerprint

Certificate fingerprint

{String} event.info.certSubjectCN

Certificate Subject Common Name

{String} event.info.referenceId

{Array} event.info.invalidReasons

Array of invalid reasons

{String} event.info.subjectCertificateData

{String} event.info.intermediateCACertificateData

{Boolean} event.info.allowUserToAccept

If true, certificate can be accepted with repond function

Since:

4.0.0

---

Parameters:

{Object} event

Since:

3.0.0

---

Parameters:

{Object} event

{Boolean} event.multimediaCapability

Since:

4.0.0

---

Parameters:

{Object} event

{String} event.ringtone

New ringtone name

Since:

4.0.0

---

Parameters:

{Object} event

{Array} event.ringtones

List of available ringtones

Since:

4.0.0

---

Parameters:

{Object} event

{String} event.url

URL to navigate to from popup/iFrame to continue with SSO process.

Since:

4.0.0

---

Parameters:

{Object} event

{Object} event.phone

{String} event.phone.status

One of

• "eConnectionTerminated"
• "eIdle"
• "eRegistering"
• "eReady"

{Boolean} event.phone.ready

true if phone is ready (status "eReady"), false if it is logged out or in the process of registering or recovering

{registration} event.phone.registration

An updated copy of the registration object passed to $.fn.cwic-registerPhone