FAX_ROUTE

The FAX_ROUTE structure contains information about a received fax document. The fax service passes the structure to a fax routing method in a call to the FaxRouteMethod function.

typedef struct _FAX_ROUTE {
  DWORD     SizeOfStruct;   //structure size, in bytes
  DWORD     JobId;          //fax job identifier
  DWORDLONG ElapsedTime;    //elapsed time for the fax job, in UTC
  DWORDLONG ReceiveTime;    //starting time for the fax job, in UTC
  DWORD     PageCount;      //number of fax pages received
  LPCWSTR   Csid;           //called station identifier
  LPCWSTR   Tsid;           //transmitting station identifier
  LPCWSTR   CallerId;       //pointer to calling device identifier
  LPCWSTR   RoutingInfo;    //pointer to routing string for fax
  LPCWSTR   ReceiverName;   //pointer to receiver name
  LPCWSTR   ReceiverNumber; //pointer to receiving fax number
  LPCWSTR   DeviceName;     //pointer to device name
  DWORD     DeviceId;       //line identifier of the receiving device
  LPBYTE    RoutingInfoData; 
                            //array with additional routing data
  DWORD     RoutingInfoDataSize; 
                            //size of routing data array
} FAX_ROUTE, *PFAX_ROUTE; 

Members

SizeOfStruct

Specifies, in bytes, the size of the FAX_ROUTE structure. Before calling the FaxRouteMethod function, the fax service sets this member to sizeof(FAX_ROUTE).

JobId

Specifies a unique number that identifies the fax job that received the fax document. For more information about fax jobs, see Fax Job Overview.

ElapsedTime

Specifies a 64-bit unsigned integer that is the elapsed time, in Coordinated Universal Time (UTC), for the fax job that received the fax document. This parameter represents the total time that elapses between the beginning of fax reception and the end of fax reception.

ReceiveTime

Specifies a 64-bit unsigned integer that is the starting time, in Coordinated Universal Time (UTC), for the fax job that received the fax document.

PageCount

Specifies the number of pages in the received fax document.

Csid

Pointer to a constant null-terminated Unicode character string that specifies the called station identifier of the local fax device that received the fax document. This identifier is usually a telephone number.

Tsid

Pointer to a constant null-terminated Unicode character string that specifies the transmitting station identifier of the remote fax device that sent the fax document. This identifier is usually a telephone number.

CallerId

Pointer to a constant null-terminated Unicode character string that identifies the calling device that sent the fax document. This string may include the telephone number of the calling device.

RoutingInfo

Pointer to a constant null-terminated Unicode character string that specifies the routing string for the received fax document. The string must be of the form:

Canonical-Phone-Number[|Additional-Routing-Info]

where Canonical-Phone-Number is defined in Canonical Addresses in the TAPI documentation; and the format of Additional-Routing-Info is defined according to the recommendation of the standards body of the International Telecommunication Union (ITU) from Study Group 8 (SG8). This is currently known as "T.Routing."

For more information, see Dialable Addresses and Canonical Addresses in the TAPI documentation.

ReceiverName

Pointer to a constant null-terminated Unicode character string that specifies the name of the person who received the fax document.

ReceiverNumber

Pointer to a constant null-terminated Unicode character string that specifies the telephone number of the fax device that received the fax document.

DeviceName

Pointer to a constant null-terminated Unicode character string that specifies the name of the device that received the fax document.

DeviceId

Specifies the permanent line identifier for the receiving fax device.

RoutingInfoData

Pointer to a buffer that contains additional routing data defined by the routing extension. For more information, see the following Remarks section.

RoutingInfoDataSize

Specifies the size, in bytes, of the array pointed to by the RoutingInfoData member.

Remarks

A fax routing method can call the FaxRouteModifyRoutingData callback function to change the routing information for a subsequent routing method. The function does this by modifying the RoutingInfoData member of the FAX_ROUTE structure that applies to the subsequent method. This allows a fax routing extension to retrieve user-defined routing data and to provide additional callback information to a different routing method. When the subsequent routing method executes, it processes the received fax transmission using the modified routing data. For more information, see FaxRouteModifyRoutingData.

The fax routing method can use the FileTimeToLocalFileTime function to convert from UTC to local time, and then use the FileTimeToSystemTime function to convert the local time to a SYSTEMTIME structure. SYSTEMTIME contains individual members for month, day, year, weekday, hour, minute, second, and millisecond.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in faxroute.h.

See Also

Fax Routing Extension Application Programming Interface Overview, Fax Routing Extension Structures, FaxRouteModifyRoutingData, FaxRouteMethod, FileTimeToLocalFileTime, FileTimeToSystemTime, SYSTEMTIME