1 /**
  2  * @fileOverview supplementaldocs.js
  3  * documentation of implicit objects/events that don't fit inline
  4  */
  5 //
  6 // Extra documentation for cwic.js that can't be inlined
  7 // Put into a separate file to prevent clutter in cwic.js
  8 
  9 // OBJECTS
 10 
 11 // using virtual namespace for documentation purposes
 12 // useful for objects that can are re-used and need to be cross-referenced
 13 // also jsdoc support documenting nested anonymous virtual objects as return objects
 14 
 15 /**
 16  * Object returned from about method
 17  * @name aboutObject
 18  * @namespace
 19  * @property {Object} javascript JavaScript properties
 20  * @property {String} javascript:version JavaScript version
 21  * @property {String} javascript:system_release Since: 2.1.1 <br>
 22  * JavaScript system release information.
 23  * @property {Object} jquery jQuery properties
 24  * @property {String} jquery:version jQuery version
 25  * @property {Object|null} channel Since: 3.1.0 <br> Properties of channel extension to add-on.  Null if add-on is loaded directly (NPAPI or ActiveX plug-in).
 26  * @property {String} channel:cwicExtId ID of the browser extension, if applicable.
 27  * @property {String} channel:objectId ID of html element that was appended to the web page.  If present, this element is used and required by the channel extension.
 28  * @property {String} channel:version CWIC version of the Cisco Chrome extension channel.
 29  * @property {String} channel:system_release System release information for the channel.
 30  * @property {Object|null} plugin Cisco Web Communicator add-on properties.  Null if add-on could not be loaded.
 31  * @property {Object} plugin:version Version details for the loaded add-on.
 32  * @property {String} plugin:version:plugin CWIC version of the add-on.
 33  * @property {String} plugin:version:system_release Since: 2.1.1 <br>
 34  * System release information for the add-on.
 35  * @property {Object} states cwic states
 36  * @property {String} states:system Current system state (e.g. "eReady")
 37  * @property {Object} states:device Currently registered device if any
 38  * @property {Object} capabilities Capabilities
 39  * @property {Boolean} capabilities:video Support for video calls.
 40  * @property {Boolean} capabilities:videoPluginObject Since: 3.1.0 <br>
 41  * Support for video plug-in objects in the browser, see {@link $.fn.cwic-createVideoWindow}.
 42  * If <tt>false</tt>, video can only be shown in an external video window.
 43  * @property {Boolean} capabilities:delayedUserAuth Since: 3.0.1 <br>
 44  * Support for delayed user authorization dialog.
 45  * @property {Boolean} capabilities:certValidation Since: 3.0.4 <br>
 46  * Support for certificate validation.  If <tt>true</tt>, certificate validation will be used unless explicitly disabled by 
 47  * calling {@link $.fn.cwic-disableCertValidation}.  If <tt>false</tt>, certificate validation will not be available.
 48  * @property {Boolean} capabilities:externalWindowDocking Since: 3.1.2 <br>
 49  * Support for external video window docking, see {@link $.fn.cwic-dock} and {@link $.fn.cwic-undock}.
 50  * @property {Object} upgrade Advice about possible upgrade.
 51  * @property {String} upgrade:javascript Relevant if add-on version is later than the cwic.js JavaScript. Can be one of<ul>
 52  * <li>"mandatory" The add-on and cwic.js versions are not compatible.</li>
 53  * <li>"recommended" The add-on may have features or bug fixes that require upgrade to cwic.js.</li>
 54  * <li>undefined if not relevant.</li></ul>
 55  * @property {String} upgrade:plugin Relevant if the cwic.js JavaScript version is later than the add-on. Can be one of<ul>
 56  * <li>"mandatory" The add-on and cwic.js versions are not compatible.</li>
 57  * <li>"recommended" The add-on may not provide all features or bug fixes available.</li>
 58  * <li>"unknown" Unable to determine version of the add-on.</li>
 59  * <li>undefined if not relevant.</li></ul>
 60  */
 61 /**
 62  * @name device
 63  * @namespace
 64  * @property {String} name
 65  * @property {String} description
 66  * @property {String} modelDescription
 67  * @property {Boolean} isSoftPhone <tt>true</tt> if the device is a software phone
 68  * @property {Boolean} isDeskPhone <tt>true</tt> if the device is a hardware (desk) phone
 69  * @property {String[]} lineDNs Array of line DNs associated with this device (may be blank until connected to the device)
 70  * @property {String} serviceState One of <ul>
 71  * <li>"eUnknown"</li>
 72  * <li>"eInService"</li>
 73  * <li>"eOutOfService"</li></ul>
 74  * @property {Number} [inService] Numeric representation of serviceState
 75  * @property {Number} [serviceCause] Numeric code to represent cause for current service state
 76  * @property {Boolean} [isPrivate] Privacy state
 77  * @property {Boolean} [isDND] DND state
 78  * @property {Number} [DNDType] DND type
 79  * @property {Boolean} exists The device exists and can be used
 80  */
 81 
 82 /**
 83  * @name line
 84  * @namespace
 85  *
 86  * @property {linecapability[]} capabilities List of capabilities, not yet implemented
 87  * @property {String} directoryNumber DN of the line as represented in the directory
 88  * @property {String} name
 89  * @property {Boolean} exists <tt>true</tt> if the line exists
 90  */
 91 
 92 /**
 93  * @name call
 94  * @namespace
 95  * @property {Number} callId Unique identifier of the call.
 96  * @property {Boolean} exists <tt>true</tt> if the call exists.
 97  * @property {Boolean} audioMuted Audio is muted.
 98  * @property {Boolean} videoMuted Video is muted.
 99  * @property {String} callState Current state of the call.  May be one of the following:<ul>
100  * <li>"OffHook" - receiver lifted in CTI control mode, or preparing to make a call in either mode.</li>
101  * <li>"OnHook" - call is ended or about to go OffHook. If !capabilities.canOriginateCall, then call is ended.</li>
102  * <li>"Ringout" - remote party is ringing.</li>
103  * <li>"Ringin" - incoming call.</li>
104  * <li>"Proceed" - if already on a call in CTI mode and there's an incoming call it may be in "Proceed" state.</li>
105  * <li>"Connected" - call is connected.</li>
106  * <li>"Hold" - call is held.</li>
107  * <li>"RemHold" - call is held on a shared-line device.</li>
108  * <li>"Resume" - n/a.</li>
109  * <li>"Busy" - remote line busy.</li>
110  * <li>"Reorder" - call failed.</li>
111  * <li>"Conference"</li>
112  * <li>"Dialing" - dialing number.</li>
113  * <li>"RemInUse" - call on a shared-line device.</li>
114  * <li>"HoldRevert"</li>
115  * <li>"Whisper"</li>
116  * <li>"Parked"</li>
117  * <li>"ParkRevert"</li>
118  * <li>"ParkRetrieved"</li>
119  * <li>"Preservation" - call is in preservation mode.</li>
120  * <li>"WaitingForDigits"</li
121  * ><li>"Spoof_Ringout"</li></ul>
122  * @property {Number} numericState Numeric representation of callState - subject to change, do not use.
123  * @property {String} callType One of the following: <ul><li>"Placed"</li><li>"Received"</li><li>"Missed"</li>
124  * @property {Date} start The <tt>new Date()</tt> when the conversationStart.cwic event was fired for the call.
125  * @property {String} videoDirection One of the following: <ul><li>"Inactive"</li><li>"SendRecv"</li><li>"SendOnly"</li><li>"RecvOnly"</li></ul>
126  * @property {Object} videoResolution Contains video resolution width and height values (in pixels). Included in the Call object any time the resolution changes.
127  * @property {Boolean} isConference <tt>true</tt> if the call is a conference call.
128  * @property {callcapability[]} capabilities A map that has capability name as the key and <tt>true</tt> as the value. 
129  * Call capabilities indicate operations you can perform on the call, and they should be used to control enabling/disabling/state/access to parts of the UI. Important capabilities are:
130  * <ul>
131  * <li>canOriginateCall - can create new call</li>
132  * <li>canAnswerCall - call can be answered</li>
133  * <li>canHold - call can be Held</li>
134  * <li>canResume - call can be Resumed</li>
135  * <li>canEndCall - call can be Ended</li>
136  * <li>canSendDigit - can send a DTMF digit to the call</li>
137  * <li>canDirectTransfer - can tranfer call</li>
138  * <li>canJoinAcrossLine - can join this call with another call on the same line with this capability also set</li>
139  * <li>canImmediateDivert - can iDivert (e.g. to voicemail)</li>
140  * <li>canUpdateVideoCapability - can update the videoDirection on the call. See {@link $.fn.cwic-updateConversation} examples.</li>
141  * <li>canMuteAudio - can mute audio on the call</li>
142  * <li>canUnmuteAudio - can unmute audio on the call</li>
143  * <li>canMuteVideo - can mute video on the call</li>
144  * <li>canUnmuteVideo - can unmute video on the call</li>
145  * </ul>
146  * @property {participant[]} participants Array of all remote participants on the call.
147  * @property {participant} participant Remote participant (first entry in participants list).
148  * @property {participant} localParticipant Local participant (your line info).
149  */
150 
151 /**
152  * @name participant
153  * @namespace
154  * @property {} name
155  * @property {} [number] Untranslated number for other participant
156  * @property {} [translatedNumber] Number for other participant as translated using available Cisco Unified Communications Manager dial rules
157  * @property {} [directoryNumber] Local line number as represented in Cisco Unified Communications Manager directory
158  */
159 
160 /**
161  * @name registration
162  * @namespace
163  * @property {String} user The Cisco Unified Communications Manager end user name
164  * @property {String} mode One of <ul><li>"SoftPhone"</li><li>"DeskPhone"</li></ul>
165  * @property {device{}} devices Map keyed by device name of all devices available to authenticated user
166  * @property {device} device The selected device
167  * @property {line} line The selected line
168  * @property {String|Object} password Cleartext password or encrypted password Object
169  * @property {String} [password.encrpyted] Encrypted password
170  * @property {String} [password.cipher] Cipher used to encrypt password
171  * @property {String|Object} passphrase Alias for password
172  * @property {String|Array|Object} cucm Original cucm parameter
173  * @property {String|Array} [cucm.ccmcip] ccmcip addresses to attempt connection with
174  * @property {String|Array} [cucm.tftp] tftp addresses to attempt connection with
175  * @property {Object} successfulCucm
176  * @property {String} [successfulCucm.cti] Address of successful cti connection
177  * @property {String} [successfulCucm.tftp] Address of  successful tftp connection
178  * Object representing Cisco Unified Communications Manager registration.  Many properties are set in the initial call to {@link $.fn.cwic-registerPhone}
179  */
180 
181 // EVENTS
182 
183 /**
184  * A conversation has just started. Note the conversation may not be connected yet, for example it is in the Alerting state.
185  * The conversation container is passed as an extra event data.
186  * @name $.fn.cwic#conversationStart
187  * @event
188  * @param {Object} event
189  * @param {call} conversation
190  * @param {DomNode} container
191  */
192 /**
193  * One or more properties of a conversation have changed, such as state or participants.
194  * @name $.fn.cwic#conversationUpdate
195  * @event
196  * @param {Object} event
197  * @param {call} conversation
198  * @param {jQueryNodeArray} container
199  */
200 /**
201  * A conversation has ended.  The conversation was terminated by the local user, all participants left the conversation, or an error occurred (media failure for example).
202  * @name $.fn.cwic#conversationEnd
203  * @event
204  * @param {Object} event
205  * @param {call} conversation
206  */
207 /**
208  * A new conversation is being received, but has not yet started.  The newly created conversation container is passed as an extra event data.<br>
209  * The application is responsible for attaching the container to the DOM and for managing the container lifetime.<br>
210  * In the case the new conversation is accepted by calling startConversation, a conversationStart event is triggered afterwards.<br>
211  * @name $.fn.cwic#conversationIncoming
212  * @event
213  * @param {Object} event
214  * @param {call} conversation
215  * @param {jQueryNodeArray} container
216  */
217 /**
218  * Called when the phone changes state.
219  * @name $.fn.cwic#system
220  * @event
221  * @param {Object} event
222  * @param {Object} event.phone
223  * @param {String} event.phone.status One of <ul>
224  * <li>"eConnectionTerminated"</li>
225  * <li>"eIdle"</li>
226  * <li>"eRegistering"</li>
227  * <li>"eReady"</li></ul>
228  * @param {Boolean} event.phone.ready <tt>true</tt> if phone is ready (status "eReady"), <tt>false</tt> if it is logged out or in the process of registering or recovering
229  * @param {registration} event.phone.registration An updated copy of the registration object passed to {@link $.fn.cwic-registerPhone}
230  */
231 /**
232  * @name $.fn.cwic#error
233  * @event
234  * @param {Object|$.fn.cwic-errorMapEntry} event An arbitrary error event or pre-defined cwic error object.
235  * @param {Object} event.code 
236  * @param {String} [event.message] 
237  * @param {String[]} [event.details] An array of additional information.
238  */
239 /**
240  * A change to the list of local multimedia devices has occurred.
241  * The application should use {@link $.fn.cwic-getMultimediaDevices} to acquire the updated list of devices. 
242  * @name $.fn.cwic#mmDeviceChange
243  * @since 3.0.0
244  * @event
245  * @param {Object} event
246  */
247 /**
248  * A property has changed on the external video window created by {@link $.fn.cwic-showPreviewInExternalWindow} or {@link $.fn.cwic-showCallInExternalWindow}.
249  * @name $.fn.cwic#externalWindowEvent
250  * @since 3.1.0
251  * @event
252  * @param {Object} event
253  * @param {Object} event.externalWindowState
254  * @param {Number} event.externalWindowState.callId The {@link call#callId} of a call associated with the external video window. -1 if no call is associated.
255  *  See also {@link $.fn.cwic-showCallInExternalWindow}.
256  * @param {Boolean} event.externalWindowState.showing When <tt>true</tt>, the external video window is displayed, possibly minimized or behind other windows.
257  *  See also {@link $.fn.cwic-hideExternalWindow}.
258  * @param {Boolean} event.externalWindowState.selfViewPip When <tt>true</tt>, the external video window will display a picture-in-picture preview (self-view).
259  *  Note the picture-in-picture preview will not be visible if preview is also in the full window.  See also {@link $.fn.cwic-setExternalWindowShowSelfViewPip}.
260  * @param {Boolean} event.externalWindowState.alwaysOnTop When <tt>true</tt>, the external video window will be set to always display on top of other windows.
261  *  See also {@link $.fn.cwic-setExternalWindowAlwaysOnTop}.
262  * @param {Boolean} event.externalWindowState.preview When <tt>true</tt>, the external video window is showing preview (self-view) in the full window.
263  *  See also {@link $.fn.cwic-showPreviewInExternalWindow}. 
264  * @param {Boolean} event.externalWindowState.docking When <tt>true</tt>, the external video window will be in docked state.
265  *  See also {@link $.fn.cwic-dock}.
266  * @param {String} event.externalWindowState.title The text used for the external video window's title bar.
267  *  See also {@link $.fn.cwic-setExternalWindowTitle}
268  */
269  
270 /**
271  * A call transfer is in progress. It signals that an ongoing call transfer can be completed or canceled.
272  * The application should implement this event to attach "completeTransfer" handler, if the higher level API does not fit specific needs. 
273  * <b>Important note:</b> This event could be triggered multiple times for one call transfer. (be careful not to create memory leaks with event handlers)
274  * @name $.fn.cwic#callTransferInProgress
275  * @since 4.0.0
276  * @event
277  * @param {Object} event
278  * @param {Function} event.completeTransfer Function to be called to complete ongoing call transfer       
279  */
280  
281  /**
282  * An invalid certificate detected.
283  * @name $.fn.cwic#invalidCertificate
284  * @since 4.0.0
285  * @event
286  * @param {Object} event
287  * @param {Function} event.respond(fingerprint,accept) Function to be called to reject or accept advertised invalid certificate.
288  * @param {Object} event.info Additional info about advertised invalid certificate   
289  * @param {String} event.info.certFingerprint Certificate fingerprint
290  * @param {String} event.info.certSubjectCN Certificate Subject Common Name
291  * @param {String} event.info.referenceId 
292  * @param {Array} event.info.invalidReasons Array of invalid reasons
293  * @param {String} event.info.subjectCertificateData 
294  * @param {String} event.info.intermediateCACertificateData 
295  * @param {Boolean} event.info.allowUserToAccept If true, certificate can be accepted with repond function
296  */
297 
298 /**
299  * Signals when authentication with Identity Provider is required during the SSO process. 
300  * @name $.fn.cwic#ssoNavigateTo
301  * @since 4.0.0
302  * @event
303  * @param {Object} event
304  * @param {String} event.url URL to navigate to from popup/iFrame to continue with SSO process.      
305  */
306  
307  /**
308  * Ringtone changed
309  * @name $.fn.cwic#ringtoneChange
310  * @since 4.0.0
311  * @event
312  * @param {Object} event
313  * @param {String} event.ringtone New ringtone name      
314  */
315  
316  /**
317  * List of ringtones is available
318  * @name $.fn.cwic#ringtonesListAvailable
319  * @since 4.0.0
320  * @event
321  * @param {Object} event
322  * @param {Array} event.ringtones List of available ringtones     
323  */
324  
325 /**
326  * Signals weather the multimedia capability is enabled or not. Multimedia services are enabled only in authenticated state.
327  * @name $.fn.cwic#multimediaCapabilities
328  * @since 4.0.0
329  * @event
330  * @param {Object} event
331  * @param {Boolean} event.multimediaCapability    
332  */