diff --git a/process/IncomingCallExecutor_lib/process.js b/process/IncomingCallExecutor_lib/process.js
index 307f4e456b1fb0fbb1d493dc15db8b9c86acdce5..6ba61f39cb5e73c4ea40f77e830cc0e2c5119da6 100644
--- a/process/IncomingCallExecutor_lib/process.js
+++ b/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);