Platform SDK: Fax Services

FAX_RECEIVE

The FAX_RECEIVE structure contains information about an inbound fax document. This information includes the name of the file that will receive the fax data stream, and the name and telephone number of the receiving device.

typedef struct _FAX_RECEIVE {
    DWORD    SizeOfStruct;    // structure size, in bytes 
    LPWSTR   FileName;        // pointer to file to store data stream
    LPWSTR   ReceiverName;    // pointer to receiver name 
    LPWSTR   ReceiverNumber;  // pointer to receiver number 
    DWORD    Reserved[4];     // must be zero 
} FAX_RECEIVE, *PFAX_RECEIVE; 

Members

SizeOfStruct
Specifies the size, in bytes, of the FAX_RECEIVE structure. Before calling the FaxDevReceive function, the fax service sets this member to sizeof(FAX_RECEIVE). For more information, see the following Remarks section.
FileName
Pointer to a null-terminated Unicode character string that specifies the full path to the file in which the fax service provider must store the data stream of an inbound fax document. The data stream is a Tagged Image File Format, Class F for facsimile (TIFF 6.0 Class F) file. For more information, see Fax Image Format. The fax service creates the file before it calls the FaxDevReceive function. The fax service provider must specify the OPEN_EXISTING flag when opening this file.
ReceiverName
Pointer to a null-terminated Unicode character string that specifies the name of the receiving device. The fax service provider will send the name to the remote sending device after the receiving device receives an inbound fax. For more information, see the following Remarks section.
ReceiverNumber
Pointer to a null-terminated Unicode character string that specifies the telephone number of the receiving device. The fax service provider will send the number to the remote sending device after the receiving device receives an inbound fax. For more information, see the following Remarks section.
Reserved[4]
This member is reserved for future use by Microsoft. It must be set to zero.

Remarks

The fax service provider must set the ReceiverName and ReceiverNumber members in this structure. The fax service allocates the memory for these strings. The size of the memory the service allocates is equal to sizeof(FAX_RECEIVE) + FAXDEVRECEIVE_SIZE. The fax service provider must place the strings in the block of memory that follows the FAX_RECEIVE structure. Note that you must allow for the size of the FileName string that follows immediately after the FAX_RECEIVE structure. The ReceiverName and ReceiverNumber members must point to the location of the strings in the memory block.

The following code sample and diagram illustrate how to fill in the memory that the fax service allocates.

PWSTR ReceiverName;
PWSTR ReceiverNumber;

//
// Routine to retrieve the receiver name 
//   and receiver number here.

//
// Set the receiver name and receiver number data
//  in the FAX_RECEIVE structure; then
//  copy the data to the appropriate offset.
//
FaxReceive->ReceiverNumber = (LPWSTR) ( (LPBYTE)FaxReceive->FileName + sizeof(WCHAR)*(wcslen(FaxReceive->FileName) + 1));
wcscpy(  FaxReceive->ReceiverNumber, ReceiverNumber );

FaxReceive->ReceiverName = (LPWSTR) ( (LPBYTE)FaxReceive->ReceiverNumber+ sizeof(WCHAR)*(wcslen(FaxReceive->ReceiverNumber) + 1));
wcscpy(  FaxReceive->ReceiverName, ReceiverName );

The fax service provider can reformat the ReceiverName and ReceiverNumber members and transmit the reformatted data to the remote sending device as the called subscriber identifier (CSI) to comply with "T.Routing" requirements. For more information, see the RoutingInfo and CSI members of the FAX_DEV_STATUS structure.

Requirements

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

See Also

Fax Service Provider Application Programming Interface Overview, Fax Service Provider Structures, FaxDevReceive, FAX_DEV_STATUS