A call control DLL can be used to filter incoming calls and adjust the processing before the call is answered.  The most common use is to select processing options and possibly a FAX CSID (answerback) differently for each incoming DID (DNIS) number.  For a system supporting thousands, or even hundreds, of DID numbers the call control DLL eliminates the need to create and maintain separate USR and MBX files for each one.

Copia can provide the following Call Control DLLs:

A ready-to-use DLL controlled by a list of accepted DIDs.  This DLL requires a list of valid DID numbers, usually written from a customer database or application.  The list is checked every minute and re-loaded if it has been changed.  On each line, following the DNIS value, you can place parameters separated by vertical bar (|) characters. These parameters are either placed in variables PARM01, PARM02, etc. or can be used to set any variable using the syntax varname=value. The DNIS passed to the DLL can be changed to any specific or default DNIS value using the text file parameters, as can the CSID.  This enables many different DID numbers to be processed using either a single USR/MBX pair or a small number of different pairs for different types of input.

A basic C-code sample DLL.  This DLL should be able to be compiled using any C or C++ compiler which can produce Windows standard DLLs.  It shows how tio initialize the DLL so as to be able to get and set CopiaFacts variables, and how to process the passed and returned parameters and variables.  In the middle is a gap where your own database look-up could be inserted to get data based on the DNIS and ANI passed in.  If you do not need to do a database lookup, you could also use this as an example, for example, simply to reformat the incoming DNIS if it comes in with a different format on changing telephony providers.

A simple C-code sample DLL.  This DLL checks the time of the incoming call and returns a code to ignore it during normal office hours.  Outside office hours the call will be answered normally, and the lines are configured for voice-mail.  An external file allows the decision to be overridden.  The use of a Call Control DLL, which is called before the call is answered, stops CopiaFacts from answering the shared lines.

If you have any similar (or different) applications for which a Call Control DLL is the easiest and most efficient solution, please contact Copia Support for advice.

Specifying a 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 incoming call has been detected.  If you specify the use of this call on an analog line, the parameters may be empty.

The FFCallNotify entry point is passed the following arguments:

An integer containing the CopiaFacts line number assigned to process the call

A null-terminated string containing a description of the telephony channel on which the call was offered (e.g. 'dtiB1T1')

A null-terminated string containing the ANI (caller number)

A null-terminated string containing the DNIS (called number)

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

A null-terminated string containing the redirecting number if the call has been forwarded

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 modify the passed values, you must limit the DNIS and ANI values to 64 bytes and the channel and redirect items to 32 bytes, in both cases including the terminating null byte.

If you return a negative integer 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 CF8.SMR; for example return -21 for 'call rejected'.  Negative values from 1 to 127 will be used for ISDN calls; negative valid SIP codes in the 100, 200, 300, 400, 500 and 600 ranges are used for SIP calls.  Adding -10000 to a (negative) SIP rejection code causes the rejection not to be logged in the DBF log.

A special return value of -999 causes an ISDN 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.  In addition, values of -203 to -208 can be used to specify the documented DivaRejectReason values of 3 to 8.

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 return values outside the specified ranges should not be used and the result if you do so is undefined.

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 for each set of lines in the CFHWL 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:

An integer containing the CopiaFacts line number assigned to process the call

A null-terminated string containing a description of the telephony channel on which the call was offered (e.g. 'dtiB1T1')

A null-terminated string containing the ANI (caller number)

A null-terminated string containing the DNIS (called number)

A null-terminated string containing the original incoming DNIS string

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 FFCallNotifyEx2, 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:

A null-terminated UTF-8 string containing the full pathname of the FS file

A value of type time_t representing the date/time of the FS file.

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:

0Continue to process the FS file normally.  Note that suitable resources may not exist to process it, and that this will not  be checked until after your DLL returns.
1Continue to process this FS file but force it to fail (with an outcome code of 89).  Note that the outcome code may be changed from 89 if an error is detected when the FS file has been loaded.
2Ignore the FS file and continue scanning.
3Ignore this FS file and stop scanning (for this pass only) in the TOSEND folder in which it resides.  Scanning will continue in the next TOSEND folder.

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.