Navigation:  Customizing CopiaFacts > Using Dynamic Link Libraries > The Call Control DLL

The call control DLL is specified using the letter C instead of a DLL number on the definition in the configuration file:

$load_DLL M1 C callctrl.dll

It must have the entry points FFCallNotify and FFCallClose described below, and may have additional entry points as described above for general-purpose use. To select the call-control DLL for general-purpose use, specify 'C' when selecting the active DLL:

$set_var DLL_SELECT C

The following entry points may be provided:

FFDLLinit

The FFDLLinit entry point can be defined in the Call Control DLL to give this DLL direct access to CopiaFacts system and user variables, in the same way as for other user-written DLLs. The value returned by this function consists of a set of bit-flags which may be significant for various hardware environments. Currently the only values recognized are:

Dialogic PRI and Dialogic Diva: If a value of 1 is returned, then no alerting message will be sent back to the network before the call control FFCallNotify or FFCallNotifyEx function is called. The default is to send a message (which normally causes the caller to hear ring tone).  This return value is ignored for other hardware environments.

Dialogic Robbed-Bit: If a value of 2 is returned, the FFCallNotifyEx2 function will be called immediately after the in-band DNIS/ANI code has been parsed.  This allows the parsing to be overridden if required, or the CSID to be set.   This return value is ignored for other hardware environments.

FFCallNotify and FFCallNotifyEx

These entry points are called only when a call has been offered on a Dialogic PRI-ISDN line, or on a Dialogic Diva PRI or BRI line.

The FFCallNotify entry point is passed the following arguments:

If an entry point named FFCallNotifyEx is provided in the DLL, it is called instead of FFCallNotify.  FFCallNotifyEx has an additional parameter:

Your function should save what data you need to process the call, and use the provided data to determine whether to accept it. You may change the values passed as ANI and DNIS, and your modified values will then be used in normal ANI and DNIS processing of an accepted call. You may also replace the telephony channel name with a null-terminated string which you wish to use as the fax CSID for the incoming call.  If you change the redirecting number the changed value will be available in the REDIR_NUMBER system variable.

If you return a negative integer greater than -128 from the function, its absolute value will be used as the cause value with which CopiaFacts rejects the call. You can find the most common cause values by subtracting 6000 from each of the 6000-block items in FF7.SMR; for example return -21 for 'call rejected'.

A special return value of -999 causes the call to be ignored, not rejected. This is only possible if you returned 1 from your FFDLLinit function (see DLL Startup) to suppress the Alert message before your FFCallNotify entry point is called.

For Dialogic Diva digital boards only, you may return special negative codes from FFCallNotifyEx to redirect the call to another destination, if this capability is available from the connected switch. See the details below.

If you return a zero from FFCallNotify, the call is processed normally. If you return a positive value, it is used as a 'handle' for the remainder of the phone call. Typically, you will return a pointer to a data structure you have set up to process the call. This handle value is passed to any general-purpose function calls to any DLL you call during the phone call, in place of the 'call number' parameter.

Note that the use of the line configuration option "Load Default User on DID user not found" forces all calls to be answered, whatever their DNIS value is found to be, so no call is made to the call control DLL in these cases. You must therefore disable this option (to do so, right-click the Type field in the DID box on each Lines page in the FFHWL configuration program) in order to use these Call Control DLL entry points.

FFCallNotifyEx2

This entry point is called immediately after processing the Fixed Format DNIS/ANI, and only when FFDllInit has returned a  value of 2.

The entry point is passed the following arguments:

Your function should save what data you need to process the call, and use the provided data to determine whether to accept it. You may change the values passed as ANI and DNIS, and your modified values will then be used in normal ANI and DNIS processing of an accepted call. You may also replace the telephony channel name with a null-terminated string which you wish to use as the fax CSID for the incoming call. To reject the call, set a value of "-1" (without the quotes) in the DNIS string.

If you return a zero from FFCallNotify, the call is processed normally. If you return a positive value, it is used as a 'handle' for the remainder of the phone call. Typically, you will return a pointer to a data structure you have set up to process the call. This handle value is passed to any general-purpose function calls to any DLL you call during the phone call, in place of the 'call number' parameter.

FFCheckOB

If an entry point named FFCheckOB is provided in the DLL, it is called when an FS file is found to be ready for processing. The entry point is called with the following parameters:

The function is called immediately before each FS file is loaded. This immediately follows the writing of the ACTIVE file to protect the FS file from being processed by other nodes.  It is very important to return quickly from this DLL call, and in particular you must avoid opening and reading the FS file, let alone altering or deleting it.  If you need to obtain data from the FS file, you should consider using an infobox pre-process operation instead of providing this Call Control DLL function.

The integer value you return from your DLL is used as follows:

FFCallClose

The FFCallClose entry point is only called at the end of the phone call when a positive value has been returned from FFCallNotify. It is passed the a single argument which is this positive value, and allows your application to clean up at the end of the call.

Dialogic Diva Call Redirection

You may return a special code between -1000 and -1047 or between -2000 and -2047 from the FFCallNotifyEx function to indicate that the call is to be blind-transferred instead of being processed by CopiaFacts. The DivaTransferOptions value to be used is formed by negating the code returned from the DLL call and using the value modulo 1000. The value you place in the redirecting number field is used as the required destination.  For certain types of transfer you will need to have returned 1 from your FFDLLinit function (see DLL Startup) to suppress the Alert message before your FFCallNotifyEx entry point is called.

For more information on the use of this feature, consult the Diva documentation or contact Copia support.

If the transfer is successfully completed, the incoming call is closed and logged and no further processing is done.  If the transfer fails, the call proceeds normally if the code is in the 2000 range, with the Diva result value available in the system variable TR_RESULT to indicate the cause of the failure.  If the code is in the 1000 range then when the redirection fails the call is rejected with cause code 1.

 

---

Topic url: http://www.copia.com/support/refmanual/index.html?thecallcontroldll.htm