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 sending a fax or audio message. 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 and audio messages, converting fax graphic images to text files, delivering faxes and audio messages 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 or audio file and other important parameters, such as Recipient Number, Sender Fax ID (TSID), Recipient Fax ID (CSID) etc.
The following is an example of the command-line arguments passed to your application when sending a fax:
/@@@Fax
/@@@FileName=C:\WINDOWS\TEMP\7E5371130B5A12C12C_occc\FAX.pdf
/@@@RecipientNumber=19012223344
/@@@DocumentName=invoice07_10_20_003.pdf;Information.txt /@@@PagesTotal=4
/@@@RemoteFaxID=(901) 222-3344 /@@@LocalFaxID=(631) 490-16-10 FAX /@@@FaxHeader=FaxVoip Software, LLC
/@@@SubmissionTime=07.10.2020@01:28:18 /@@@OriginalScheduledTime=07.10.2020@01:28:18
/@@@ScheduledTime=07.10.2020@01:28:18
/@@@StartTime=07.10.2020@01:32:49 /@@@EndTime=07.10.2020@01:36:14 /@@@Duration=00:03:25
/@@@BitRate=14400 /@@@Ecm=0 /@@@FaxMode=T.38 /@@@PagesTransferred=4 /@@@Resolution=204x196 dpi
/@@@JobStatus=Completed /@@@ExtendedStatus=OK /@@@Retries=0
The following is an example of the command-line arguments passed to your application when sending an audio message:
/@@@Audio
/@@@FileName=C:\WINDOWS\TEMP\7E53772E3B8E3A03A0_occc\MESSAGE.wav
/@@@RecipientNumber=19012223344
/@@@DocumentName=Maid with the Flaxen Hair.mp3
/@@@WaveLength=156.1 s /@@@WaveFrequency=8,000 kHz
/@@@SubmissionTime=07.10.2020@01:28:18 /@@@OriginalScheduledTime=07.10.2020@01:28:18
/@@@ScheduledTime=07.10.2020@01:28:18
/@@@StartTime=07.10.2020@01:32:49 /@@@EndTime=07.10.2020@01:35:26 /@@@Duration=00:02:37
/@@@JobStatus=Completed /@@@ExtendedStatus=OK /@@@Retries=0
The command line arguments differ depending on the type of outgoing call (fax or audio message). The command line can contain the following arguments:
Indicates that the outgoing call is a fax call.
Indicates that the outgoing call is an audio call.
The temporary copy of the outgoing fax (TIFF, PDF or SFF file depending on your choice) or audio message (WAV file). 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 sent fax in the following format option (Create temporary copy of the sent audio message option) is unchecked, this argument is missing in the command line. See also in the Custom routing for outgoing faxes and audio messages chapter of this user manual.
The fax or phone number of the recipient.
E-mail address associated with the sender. If the fax or audio message is generated by the Mail to Fax (Mail to Audio) function, this is the sender's e-mail address extracted from the e-mail message.
If the fax is generated by the Mail to Fax function, this is the original name of sender document including file extension. When sending multiple documents, they are comma separated. If the audio message is generated by the Mail to Audio function, this is the name of the original audio file including file extension.
The total number of pages in the outbound fax. The value (-1) is used when no data is available.
The Called Subscriber ID (CSID) received from the fax recipient.
The Transmitting Subscriber ID (TSID) that identifies you as a fax sender, sent to the fax recipient.
The text that is transmitted at the top of each faxed page.
The length of the audio message in seconds.
The sample rate, kHz of the audio file.
The time that the outgoing fax or audio message was submitted for processing. The format of this string is 'mm.dd.yyyy@hh:mm:ss'.
The time that the fax or audio message was originally scheduled for transmission. The format of this string is 'mm.dd.yyyy@hh:mm:ss'.
The time that the fax or audio message was scheduled for transmission for the last time. This may be later than the original scheduled time due to delays, such as a busy number or due to previous unsuccessful retries. The format of this string is 'mm.dd.yyyy@hh:mm:ss'.
The time when the outgoing call or fax (audio message) transmission started. The format of this string is 'mm.dd.yyyy@hh:mm:ss'.
The time when the outgoing call or fax (audio message) transmission ended. The format of this string is 'mm.dd.yyyy@hh:mm:ss'.
The duration of the outgoing call or fax (audio message) transmission. The format of this string is 'hh:mm:ss'.
Fax transmission rate.
Indicates whether Error Correction Mode (ECM) has been used when sending a fax. Can be one of the following values: 1 - with ECM, 0 - without ECM, -1 - no data available, in particular when sending 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.
The number of successfully sent fax pages. The value (-1) is used when no data is available.
Fax resolution (Image quality). Can be one of the following values: 204x196 dpi (Fine), 204x98 dpi (Normal).
Status of the fax or audio message job (in English). Examples: Completed, Retries exceeded.
Operation completion code. Example: OK (in the case of a successful sending of fax or audio message). In the case of a failed sending of fax or audio message contains the error description (in English).
The number of times that the system attempted to transmit an outgoing fax or audio message after the initial transmission attempt failed.
Temporary copy of the sent fax or audio message
If the Create temporary copy of the sent fax in the following format option (Create temporary copy of the sent audio message option) is checked (see in the Custom routing for outgoing faxes and audio messages chapter of this user manual), the Custom Routing Method creates a temporary folder and copies the outgoing fax (TIFF, PDF or SFF file depending on your choice) or audio message (WAV file) 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 or audio file is passed to the custom application via FileName command-line argument, see above.
For example,
/@@@FileName=C:\WINDOWS\TEMP\7E5371130B5A12C12C_occc\FAX.pdf
The path to the fax file (PDF format) is:
C:\WINDOWS\TEMP\7E5371130B5A12C12C_occc\FAX.pdf
The path to the temporary folder is:
C:\Windows\TEMP\7E5371130B5A12C12C_occc\
For example,
/@@@FileName=C:\WINDOWS\TEMP\7E53772E3B8E3A03A0_occc\MESSAGE.wav
The path to the audio file is:
C:\WINDOWS\TEMP\7E53772E3B8E3A03A0_occc\MESSAGE.wav
The path to the temporary folder is:
C:\Windows\TEMP\7E53772E3B8E3A03A0_occc\
The temporary folder in which fax file (FAX.tif, FAX.pdf or FAX.sff) or audio file (MESSAGE.wav) 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 or audio 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 sent fax in the following format option (Create temporary copy of the sent audio message option) is not checked, the Custom Routing Method does not create the copy of the outgoing fax or audio message.
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.