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 {Object} jquery jQuery properties
 22  * @property {String} jquery:version jQuery version
 23  * @property {Object|null} plugin Plugin properties
 24  * @property {String} plugin:version Plugin version
 25  * @property {Object} states cwic states
 26  * @property {String} states:system Current system state (e.g. "eReady")
 27  * @property {Object} capabilities Capabilities
 28  * @property {Boolean} capabilities:video Support for video calls
 29  * @property {Object} upgrade Advice about possible upgrade
 30  * @property {String} upgrade:javascript Can be 'mandatory' or 'recommended' depending on plugin version (undefined if not relevant)
 31  * @property {String} upgrade:plugin Can be 'mandatory' or 'recommended' depending on javascript version (undefined if not relevant)
 32  */
 33 /**
 34  * @name device
 35  * @namespace
 36  * @property {String} name
 37  * @property {String} description
 38  * @property {String} model
 39  * @property {String} modelDescription
 40  * @property {Boolean} isSoftPhone true if the device is a software phone
 41  * @property {Boolean} isDeskPhone true if the device is a hardware (desk) phone
 42  * @property {String[]} lineDNs Array of line DNs associated with this device (may be initially blank until connected to the device)
 43  * @property {String} serviceState One of <ul><li>"eUnknown"</li><li>"eInService"</li><li>"eOutOfService"</li></ul>
 44  * @property {Number} [inService] Numeric representation of serviceState
 45  * @property {Number} [serviceCause] Numeric code to represent cause for current service state
 46  * @property {Boolean} [isPrivate] Privacy state
 47  * @property {Boolean} [isDND] DND state
 48  * @property {Number} [DNDType] DND type
 49  * @property {line[]} [lines] Lines associated with the device (may be initially blank until connected to the device)
 50  * @property {Boolean} exists The device exists and can be used
 51  */
 52 
 53 /**
 54  * @name line
 55  * @namespace
 56  *
 57  * @property {linecapability[]} capabilities List of capabilities, not yet implemented
 58  * @property {String} directoryNumber DN of the line as represented in the directory
 59  * @property {String} externalNumber Externally reachable DN of the line
 60  * @property {String} name
 61  * @property {String} label
 62  * @property {Boolean} exists true if the line exists
 63  * @property {Boolean} registered true if the line is currently registered
 64  */
 65 
 66 /**
 67  * @name call
 68  * @namespace
 69  * @property {Number} id
 70  * @property {Number} callId Same as id
 71  * @property {Boolean} exists true if the call exists
 72  * @property {Boolean} audioMuted Audio is muted
 73  * @property {Boolean} videoMuted Video is muted
 74  * @property {} callState one of <ul><li>"OffHook" - receiver lifted in CTI control mode, or preparing to make a call in either mode.</li><li>"OnHook" - call is ended or about to go OffHook. If !capabilities.canOriginateCall, then call is ended.</li><li>"Ringout" - remote party is ringing.</li><li>"Ringin" - incoming call.</li><li>"Proceed" - if already on a call in CTI mode and there's an incoming call it may be in "Proceed" state.</li><li>"Connected" - call is connected.</li><li>"Hold" - call is held.</li><li>"RemHold" - call is held on a shared-line device.</li><li>"Resume" - n/a.</li><li>"Busy" - remote line busy.</li><li>"Reorder" - call failed.</li><li>"Conference"</li><li>"Dialing" - dialing number.</li><li>"RemInUse" - call on a shared-line device.</li><li>"HoldRevert"</li><li>"Whisper"</li><li>"Parked"</li><li>"ParkRevert"</li><li>"ParkRetrieved"</li><li>"Preservation" - call is in preservation mode.</li><li>"WaitingForDigits"</li><li>"Spoof_Ringout"</li></ul>
 75  * @property {Number} numericState - Numeric representation of callState - subject to change, do not use
 76  * @property {String} callType One of <ul><li>"None"</li><li>"Incoming"</li><li>"Outgoing"</li><li>"Forwarded"</li></ul>
 77  * @property {String} calledPartyDirectoryNumber The translated directory number of the called party
 78  * @property {String} calledPartyNumber The number of the called party
 79  * @property {String} calledPartyName The name of the called party
 80  * @property {String} callingPartyDirectoryNumber The translated directory number of the calling party
 81  * @property {String} callingPartyNumber The number of the calling party
 82  * @property {String} callingPartyName The name of the calling party
 83  * @property {Number} lineId Not yet implemented
 84  * @property {String} mediaState Not implemented
 85  * @property {String} videoDirection One of <ul><li>"Inactive"</li><li>"SendRecv"</li><li>"SendOnly"</li><li>"RecvOnly"</li></ul>
 86  * @property {Boolean} isConference true if the call is a conference call
 87  * @property {Number} maxParticipants Maximum number of participants on a conference call.  This parameter is not set if the call is not a conference
 88  * @property {callcapability[]} capabilities A map with capability name as key and true as value.  They indicate operations you can perform on the call and should be used to control enabling/disabling/state/access to parts of the UI. Important capabilities are:
 89  * <ul>
 90  * <li>canAnswerCall - call can be answered</li>
 91  * <li>canHold - call can be Held</li>
 92  * <li>canResume - call can be Resumed</li>
 93  * <li>canEndCall - call can be Ended</li>
 94  * <li>canSendDigit - can send a DTMF digit to the call</li>
 95  * <li>canDirectTransfer - can tranfer call</li>
 96  * <li>canJoinAcrossLine - can join this call with another call on the same line with this capability also set</li>
 97  * <li>canImmediateDivert - can iDivert (e.g. to voicemail)</li>
 98  * <li>canUpdateVideoCapability - can update the videoDirection on the call. See {@link $.fn.cwic-updateConversation} examples.</li>
 99  * <li>canMuteAudio - can mute audio on the call</li>
100  * <li>canUnmuteAudio - can unmute audio on the call</li>
101  * <li>canMuteVideo - can mute video on the call</li>
102  * <li>canUnmuteVideo - can unmute video on the call</li>
103  * </ul>
104  * @property {participant[]} participants All other participants on the call
105  * @property {participant[]} localParticipant Local participant (your line info)
106  */
107 
108 /**
109  * @name participant
110  * @namespace
111  * @property {} name
112  * @property {} [number] Untranslated number for other participant
113  * @property {} [translatedNumber] Number translated using available CUCM dial rules - only available on other participant in this release
114  * @property {} [directoryNumber] Local line number as represented in CUCM directory
115  * @property {} [externalNumber] Local line number as reachable from an external number (CUCM external representation)
116  */
117 
118 /**
119  * @name registration
120  * @namespace
121  * @property {Boolean} authenticate The original authenticate argument passed to registerPhone
122  * @property {String} user The CUCM end user name
123  * @property {String} mode One of <ul><li>"SoftPhone"</li><li>"DeskPhone"</li></ul>
124  * @property {Boolean} useCcmcip
125  * @property {device{}} devices Map keyed by device name of all devices available to authenticated user
126  * @property {device} device The selected device
127  * @property {line} line The selected line
128  * @property {String|Object} password Cleartext password or encrypted password Object
129  * @property {String} [password.encrpyted] Encrypted password
130  * @property {String} [password.cipher] Cipher used to encrypt password
131  * @property {String|Array|Object} cucm Original cucm parameter
132  * @property {String|Array} [cucm.ccmcip] ccmcip addresses to attempt connection with
133  * @property {String|Array} [cucm.tftp] tftp addresses to attempt connection with
134  * @property {Object} successfulCucm
135  * @property {String} [successfulCucm.cti] Address of successful cti connection
136  * @property {String} [successfulCucm.tftp] Address of  successful tftp connection
137  * Object representing CUCM registration.  Many properties are set in the initial call to {@link $.fn.cwic-registerPhone}
138  */
139 
140 // EVENTS
141 
142 /**
143  * A conversation has just started.Note the conversation may not be connected yet, for example it is in the Alerting state.The conversation container is passed as an extra event data.
144  * @name $.fn.cwic#conversationStart
145  * @event
146  * @param event
147  * @param {call} conversation
148  * @param {DomNode} container
149  */
150 /**
151  * One or more properties of a conversation have changed, e.g. state, participant.
152  * @name $.fn.cwic#conversationUpdate
153  * @event
154  * @param event
155  * @param {call} conversation
156  * @param {jQueryNodeArray} container
157  */
158 /**
159  * 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).
160  * @name $.fn.cwic#conversationEnd
161  * @event
162  * @param event
163  * @param {call} conversation
164  */
165 /**
166  * A new conversation is being received, but is not started yet.  The newly created conversation container is passed as an extra event data.<br>
167  * The application is responsible for attaching the container to the DOM, and managing the container lifetime.<br>
168  * In the case the new conversation is accepted by calling startConversation, a conversationStart event is triggered afterwards.<br>
169  * @name $.fn.cwic#conversationIncoming
170  * @event
171  * @param event
172  * @param {call} conversation
173  * @param {jQueryNodeArray} container
174  */
175 /**
176  * Called when the phone changes state.
177  * @name $.fn.cwic#system
178  * @event
179  * @param {Object} event
180  * @param {Object} event.phone
181  * @param {String} event.phone.status One of <ul><li>"eIdle"</li><li>"eFetchingDeviceConfig"</li><li>"eRegistering"</li><li>"eReady"</li><li>"eRecoveryPending"</li><li>"eAwaitingIpAddress"</li><li>"eConnectedButNoDeviceReady"</li><li>"eConnectionTerminated*"</li></ul>
182  * @param {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
183  * @param {registration} event.phone.registration An updated copy of the registration object passed to {@link $.fn.cwic-registerPhone}
184  * <br>*eConnectionTerminated is received when a client elsewhere has logged in using the forceRgistration parameter. When this message is received the client should log the user out of the phone using unregisterPhone.
185  */
186 /**
187  * @name $.fn.cwic#error
188  * @event
189  * @param event
190  */
191 
192