Custom Application Requirements (Developer's Guide)
The custom routing application, specified by the customer, is started by the Fax Voip T.38 Console software when executing Custom Routing Method, after receiving a fax. The individual developer is responsible for developing this application, for creating graphical user interface (GUI) to configure the rules and other settings, and for storing the configuration. The application functions can include, but are not limited to: printing faxes, storing faxes, converting fax graphic images to text files, delivering faxes in electronic mail attachments etc.
Below are the general requirements that must be taken into account by the software vendor when writing the custom application.
Command-Line Arguments
The command line passed to an application is predefined and contains all the necessary information. The developer of the custom application can parse the command line in his application to obtain the path to the fax file and other important parameters, such as CallerID, Called Number (DID), Sender Fax ID (TSID), Recipient Fax ID (CSID) etc.
The following is an example of the command-line arguments passed to your application:
/@@@FaxFileName=C:\Windows\TEMP\220120200123192788362_ccc\FAX.pdf
/@@@CallingParty=sip:19012223344@callcentric.com
/@@@CalledParty=sip:16314901610@192.168.11.2:5070
/@@@CallerId=19012223344 /@@@CalledNumber=16314901610
/@@@RemoteFaxID=(901) 222-3344 /@@@LocalFaxID=(631) 490-16-10 FAX
/@@@ElapsedTime=00:01:28 /@@@ReceiveTime=01.14.2020@23:15:34
/@@@EndTime=01.14.2020@23:17:02 /@@@PageCount=3 /@@@BitRate=14400
/@@@Ecm=0 /@@@FaxMode=T.38 /@@@Resolution=204x196 dpi /@@@Status=OK
The command line contains the following arguments:
The temporary copy of the fax file (TIFF, PDF or SFF file depending on your choice) associated with a received fax document. This file and the temporary folder in which it is located (subfolder in the %temp% folder for the current user account or the Local System account) should be deleted in custom routing application after applying necessary actions. If the Create temporary copy of the received fax in the following format option is unchecked, this argument is missing in the command line. See also in the Custom routing for incoming faxes chapter of this user manual.
The full address of the calling party include prefixes (sip:, h323:, isdn: etc...).
The full address of the called party include prefixes (sip:, h323:, isdn: etc...).
The fax number of the caller.
The telephone number of the called party (DID).
The Transmitting Subscriber ID (TSID) received from the fax sender.
The Called Subscriber ID (CSID) that identifies you as a fax recipient, sent to the fax sender.
The duration of the incoming fax call or fax transmission. The format of this string is 'hh:mm:ss'.
The time when fax reception started. The format of this string is 'mm.dd.yyyy@hh:mm:ss'.
The time when fax reception ended. The format of this string is 'mm.dd.yyyy@hh:mm:ss'.
Specifies the number of pages in the received fax document.
Fax transmission rate.
Indicates whether Error Correction Mode (ECM) has been used when receiving a fax. Can be one of the following values: 1 - with ECM, 0 - without ECM, -1 - no data available, when receiving a fax using ISDN-FAX B3:4:SFF protocol.
Fax protocol information. Can be one of the following values: T.38, G711-FAX - audio fax over G.711 codec via VOIP or ISDN CAPI 2.0, ISDN-FAX B3:4:SFF - fax via ISDN CAPI 2.0 line using B3 Protocol 4: T.30 for Group 3 fax, ISDN-FAX B3:5:SFF - fax via ISDN CAPI 2.0 line using B3 Protocol 5: T.30 for Group 3 fax extended.
Fax resolution (Image quality). Can be one of the following values: 204x196 dpi (Fine), 204x98 dpi (Normal).
Operation completion code. Example: OK (in the case of a successful fax reception). In the case of a failed fax reception contains the error description (in English).
Temporary copy of the received fax
If the Create temporary copy of the received fax in the following format option is checked (see in the Custom routing for incoming faxes chapter of this user manual), the Custom Routing Method creates a temporary folder and copies the received fax (TIFF, PDF or SFF file depending on your choice) into this folder. The temporary folder is created in the %temp% folder for the current user account or the Local System account (if Fax Voip T.38 Console is running as a Windows service). The path to the temporary fax file is passed to the custom application via FaxFileName command-line argument, see above.
For example,
/@@@FaxFileName=C:\Windows\TEMP\220120200123192788362_ccc\FAX.pdf
The path to the fax file (PDF format) is:
C:\Windows\TEMP\220120200123192788362_ccc\FAX.pdf
The path to the temporary folder is:
C:\Windows\TEMP\220120200123192788362_ccc\
The temporary folder in which fax file (FAX.tif, FAX.pdf or FAX.sff) is placed can be used by your custom routing application to store temporary files that your application generates.
The custom application is responsible for deleting the temporary fax file and the temporary folder in which this file is located. You must permanently delete the temporary folder in your application after you perform all the necessary actions.
If the Create temporary copy of the received fax in the following format option is not checked, the Custom Routing Method does not create the copy of the received fax.
Running under current user account or Local System account
The custom application is started using the current user account or the Local System account (if Fax Voip T.38 Console is running as a Windows service), so the corresponding account must have necessary access to files, folders and other objects with which your application works.
Terminating the application
The Custom Routing Method executes the custom routing application in the separated thread by calling the CreateProcess function. The Fax Voip T.38 Console does not monitor the application after it is started and does not guarantee its correct completion. The developer of the custom routing application is responsible for the correct automatic termination of the application after execution.