added comments in IncomingCallExecutor

process/IncomingCallExecutor_lib/process.js

@@ -36,6 +36,32 @@ import("system.indexsearch");
  * ic.setHandlerDisconnect(disconnectingHandlerFn);
  * ic.execute();
  */
+/**
+ * object for processing cti-calls
+ * Within the constructor, data is collected but not further processed. To perform operations, different methods are provided.
+ *
+ * @class 
+ * @param {Object} pCallData object with all the basic call information, the object needs the following parameters: <ul>
+ * 	<li>action:for example: vars.get("$local.action")                                                                </li>
+ * 	<li>callId:uid of the call, requried, for example: vars.get("$local.callID")                                                                </li>
+ * 	<li>localAddress:the target phone address, for example: vars.get("$local.localAddress")                                                    </li>
+ * 	<li>localId:id of the call target, for example: vars.get("$local.localID")                                                              </li>
+ * 	<li>callAddress:the source phone address, for example: vars.get("$local.callAddress")                                                      </li>
+ * 	<li>isIncomingCall:Boolean:is the call an incoming or outgoing call, for example: vars.getString("$local.callIsIncoming") == "true"                                </li>
+ * 	<li>state:Number:callstate-constant (Ringing, talking, etc.), for example: Number(vars.get("$local.callState"))                                                      </li>
+ * 	<li>privateData:Object: additional telephony data when the tapi does provide it, for example: vars.exists("$local.privateData2") ? vars.get("$local.privateData2") : null         </li>
+ * 	<li>isConnectedCall:Boolean:specifies if the call was redirected ("connected") from somebody else</li>
+ *   </ul>
+ * 
+ * @example 
+ * 
+ * var ic = new IncomingCallExecutor(callData);
+ * //most of the logic happens in the handler-fuctions
+ * ic.setHandlerRinging(ringingHandlerFn);
+ * ic.setHandlerTalking(talkingHandlerFn);
+ * ic.setHandlerDisconnect(disconnectingHandlerFn);
+ * ic.execute();
+ */
 function IncomingCallExecutor(pCallData)
 {
     this.callData = pCallData;
@@ -53,16 +79,34 @@ function IncomingCallExecutor(pCallData)
     this.usersCall = null;
     this.collectDataFromCallInfo();
     
-    //key-value pairs of states-functions
+    //key-value pairs of callstates-functions
     this._handlerFunctions = {};
     
     this.notificationContentId = null;
 }
+
+/**
+ * transform the whole object into string representation, good for debugging and logging purposes
+ * This will list the own properties of the object and it's values. will not resolve functions (so no callback-functions are resolved)
+ * 
+ * @return {String} stringified object-instance
+ */
 IncomingCallExecutor.prototype.toString = function()
 {
     return JSON.stringify(this, null, " ");
 }
 
+/**
+ * method for processing the callData.privateData - if it has been specified
+ * Since the tapi privateData supplies additional informations about the call, additional assumptions can be made for questions like:
+ * "who is the calling number?", "is the call a connected (=redirected) call?", etc.
+ * 
+ * The object will set properties within the callData-member of your object and not return any value.
+ * 
+ * There is no need to call this function your own because it's done in the constructor automatically.
+ * 
+ * @return undefined
+ */
 IncomingCallExecutor.prototype.processPrivateData = function()
 {
     // handling tapi-drivers which support privateData: extending the call information
@@ -84,6 +128,15 @@ IncomingCallExecutor.prototype.processPrivateData = function()
     }
 };
 
+/**
+ * searches for additional information to the given local-phone address and stores them in the following property in the object:
+ * <ul>
+ * <li>contactsLocal</li>
+ * </ul>
+ * 
+ * //TODO: describe what is set there exactly
+ * @return undefined
+ */
 IncomingCallExecutor.prototype.collectDataFromLocalInfo = function()
 {
     this.usersLocal = [];
@@ -104,12 +157,29 @@ IncomingCallExecutor.prototype.collectDataFromLocalInfo = function()
     this.contactsLocal = IncomingCallExecutor._getContactsFromNumber(null, userContactIds);
 };
 
+/**
+ * searches for additional information to the given call-phone address and stores them in the following properties in the object:
+ * <ul>
+ * <li>contactsCall</li>
+ * <li>usersCall</li>
+ * </ul>
+ * 
+ * //TODO: describe what is set there exactly
+ * @return undefined
+ */
 IncomingCallExecutor.prototype.collectDataFromCallInfo = function()
 {
     this.contactsCall = IncomingCallExecutor._getContactsFromNumber(this.callData.callAddress);
     this.usersCall = IncomingCallExecutor._getUsersFromContacts(this.contactsCall);
 };
 
+/**
+ * helper function that will log different callData and collected data to standard-output
+ * The function does not specify any module, importance or else
+ * Needed for live-analytics of problems and errors.
+ * 
+ * @return undefined
+ */
 IncomingCallExecutor.prototype.logData = function()
 {
     logging.log("ctiServerEvents");
@@ -138,27 +208,67 @@ IncomingCallExecutor.prototype.getNotificationBaseConfig = function(pUserName)
                                          
     return notificationConfig;
 };
+/**
+ * sets a callback function for a given call state (for example the state ringing)
+ * 
+ * @param {primitive} pCallState the state for the given function that will be executed whenver the state is reached
+ * @param {Function} pFunction the callback-function that will be executed; this function will get no parameter but has access to all object instance properties
+ * 
+ * @private this function should not be called from outside
+ * 
+ * @return undefined
+ */
 IncomingCallExecutor.prototype._setHandlerFn = function(pCallState, pFunction)
 {
     this._handlerFunctions[pCallState] = pFunction;
 }
 
+/**
+ * Sets a callback function which is called when an in- or outcoming call has has the state ringing/connection-rining. 
+ * In the given function could be done some logging of the call for example.
+ * 
+ * @param pFunction the callback-function that will be executed; this function will get no parameter but has access to all object instance properties
+ * 
+ * @return undefined
+ */
 IncomingCallExecutor.prototype.setHandlerRinging = function(pFunction)
 {
     this._setHandlerFn(cti.CALLSTATE_RINGING, pFunction);
     this._setHandlerFn(cti.CALLSTATE_CONNECTION_RINGING, pFunction);
 }
 
+/**
+ * Sets a callback function which is called when an in- or outcoming call has has the state talking 
+ * In the given function could be done some logging of the call for example.
+ * 
+ * @param pFunction the callback-function that will be executed; this function will get no parameter but has access to all object instance properties
+ * 
+ * @return undefined
+ */
 IncomingCallExecutor.prototype.setHandlerTalking = function(pFunction)
 {
     this._setHandlerFn(cti.CALLSTATE_TALKING, pFunction);
 }
 
+/**
+ * Sets a callback function which is called when an in- or outcoming call has has the state disconnected. 
+ * In the given function could be done some logging of the call for example.
+ * 
+ * @param pFunction the callback-function that will be executed; this function will get no parameter but has access to all object instance properties
+ * 
+ * @return undefined
+ */
 IncomingCallExecutor.prototype.setHandlerDisconnect = function(pFunction)
 {
     this._setHandlerFn(cti.CALLSTATE_DISCONNECTED, pFunction);
 }
 
+/**
+ * After all the data is initialized, collected and so on this method actually calls the correct handler depending on the callstate that is set
+ * If no handler function for that state is defined, nothing is done 
+ * 
+ * @return undefined
+ */
 IncomingCallExecutor.prototype.execute = function()
 {
     var state = this.callData.state;
@@ -171,6 +281,15 @@ IncomingCallExecutor.prototype.execute = function()
     }
 }
 
+/**
+ * helper function that converts a callstate into easy read- and understandable text
+ * 
+ * @param {cti.CALLSATE_***} pCallstate the callstate as number/constant that shall be converted
+ * 
+ * @return {String} descriptive shorttext of the callstate
+ * 
+ * @private
+ */
 IncomingCallExecutor._callstateToText = function(pCallstate)
 {
     var callstateName;
@@ -282,7 +401,7 @@ IncomingCallExecutor._getContactsFromNumber = function(pNumber, pContactIds)
     rows = entities.getRows(config);
     return rows;
     */
-    //load entities does not work here, so use instead a traditional sql-query:
+    //load entities does not work here, so instead use a traditional sql-query:
     var contacts = newSelect("CONTACT.CONTACTID, CONTACT.ORGANISATION_ID, ORGANISATION.NAME, CONTACT.PERSON_ID, CONTACT.ISOLANGUAGE, PERSON.LASTNAME, PERSON.FIRSTNAME")
                         .from("CONTACT")
                         .join("ORGANISATION", "ORGANISATION.ORGANISATIONID = CONTACT.ORGANISATION_ID")
@@ -354,17 +473,37 @@ IncomingCallExecutor.prototype.getLocaleFromUser = function(pUserObject)
         return null;
 };
 
+/**
+ * helper function to format the local address (source phone address)
+ * Will replace special cti-phone elements like the provider (e.g. SIP/203 is changed to 203)
+ * 
+ * @return {String} the formatted local-address or the original replaced number when the nubmber could not be formatted
+ */
 IncomingCallExecutor.prototype.getFormattedLocalAddress = function()
 {
     return IncomingCallExecutor.formatAddress(this.callData.localAddress);
 }
 
-
+/**
+ * helper function to format the call address (target phone address)
+ * Will replace special cti-phone elements like the provider (e.g. SIP/203 is changed to 203)
+ * 
+ * @return {String} the formatted call-address or the original replaced number when the nubmber could not be formatted
+ */
 IncomingCallExecutor.prototype.getFormattedCallAddress = function()
 {
     return IncomingCallExecutor.formatAddress(this.callData.callAddress);
 }
 
+/**
+ * helper function to format a cti-phone address
+ * Will replace special cti-phone elements like the provider (e.g. SIP/203 is changed to 203)
+ * 
+ * @static
+ * @param {String} pAddress the cti phone address that shall be formatted
+ * 
+ * @return {String} the formatted number or the original replaced number when the nubmber could not be formatted
+ */
 IncomingCallExecutor.formatAddress = function (pAddress)
 {
     return cti.formatPhoneNumber(pAddress.replace(/P?J?SIP\//, ""), true, null);