Custom Application Requirements (Developer's Guide)
The custom routing application, specified by the customer, is started by the Windows Fax Service when executing Custom Routing Method (Fax Voip FSP Routing Extension), 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 (TIFF) and other important parameters, such as CallerID, Called Number (DID), TSID, CSID etc.
The following is an example of the command-line arguments passed to your application:
/@@@TiffFileName=C:\Windows\ServiceProfiles\NetworkService\AppData\Local\Temp\5547_c\FAX.tif
/@@@JobId=5547 /@@@ElapsedTime=00:00:55
/@@@ReceiveTime=07.28.2017@00:42:11 /@@@PageCount=1
/@@@Csid=Fax Voip FSP /@@@Tsid=(901) 222-3344
/@@@CallerId=19012223344 /@@@RoutingInfo=16314901610
/@@@ReceiverName=Fax Voip Line 0 /@@@ReceiverNumber=Fax Voip FSP
/@@@DeviceName=Fax Voip Line 0 /@@@DeviceId=24576
Command line arguments match to the elements of the FAX_ROUTE structure, see below:
The temporary copy of the fax file (TIFF) associated with a received fax document. This file and the temporary folder in which it is located (subfolder in the %temp% folder for Network Service account) should be deleted in custom routing application after applying necessary actions. If the Create temporary copy of the received fax (TIFF file) 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.
Specifies a unique number that identifies the fax job that received the fax document.
Represents the total time that elapses between the beginning of fax reception and the end of fax reception. The format of this string is 'hh:mm:ss'.
The starting time for the fax job that received the fax document. The format of this string is 'mm.dd.yyyy@hh:mm:ss'.
Specifies the number of pages in the received fax document.
Specifies the called station identifier of the local fax device (Local Fax ID) that received the fax document. This identifier is usually a telephone number.
Specifies the transmitting station identifier of the remote fax device (Remote Fax ID) that sent the fax document. This identifier is usually a telephone number.
Identifies the calling device that sent the fax document. This string usually includes the telephone number of the calling device.
Specifies the routing string for the received fax document. Fax Voip FSP stores the Called Number (DID) in this string.
According to MSDN, specifies the name of the person who received the fax document (usually coincides with DeviceName and not used).
According to MSDN, specifies the telephone number of the fax device that received the fax document (usually coincides with Csid - local fax device identifier, and not used).
Specifies the name of the device that received the fax document.
Specifies the permanent line identifier for the receiving fax device.
Temporary copy of the received fax (TIFF file)
If the Create temporary copy of the received fax (TIFF file) option is checked (see in the Custom routing for incoming faxes chapter of this user manual), the Custom Routing Method (Fax Voip FSP Routing Extension) creates a temporary folder and copies the received fax (TIFF file) into this folder. The temporary folder is created in the %temp% folder for the Network Service account. The path to the temporary TIFF file is passed to the custom application via TiffFileName command-line argument, see above.
For example,
/@@@TiffFileName=C:\Windows\ServiceProfiles\NetworkService\AppData\Local\Temp\5547_c\FAX.tif
The path to the TIFF file is:
C:\Windows\ServiceProfiles\NetworkService\AppData\Local\Temp\5547_c\FAX.tif
The path to the temporary folder is:
C:\Windows\ServiceProfiles\NetworkService\AppData\Local\Temp\5547_c\
The temporary folder in which TIFF file (FAX.tif) 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 TIFF 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 (TIFF file) option is not checked, the Custom Routing Method (Fax Voip FSP Routing Extension) does not create the copy of the received fax, but the custom application can still access the received fax by using Fax Service API functions (based on JobId parameter that is also passed via command line).
Running under Network Service account
The custom application is started in the context of the Windows Fax Service using the Network Service account, so the Network Service account must have necessary access to files, folders and other objects with which your application works.
Terminating the application
The Custom Routing Method (Fax Voip FSP Routing Extension) executes the custom routing application in the separated thread by calling the CreateProcess function. The Windows Fax Service 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.