FaxSendDocument

A fax client application calls the FaxSendDocument function to queue a fax job that will transmit an outgoing fax transmission.

BOOL WINAPI FaxSendDocument(
  HANDLE FaxHandle,          // handle to the fax server
  LPCTSTR FileName,          // file with data to transmit
  PFAX_JOB_PARAM JobParams,  // pointer to job information structure
  CONST FAX_COVERPAGE_INFO *CoverpageInfo OPTIONAL, 
                             // pointer to local cover page structure
  LPDWORD FaxJobId           // fax job identifier
);

Parameters

FaxHandle

[in] Specifies a fax server handle returned by a call to the FaxConnectFaxServer function.

FileName

[in] Pointer to a constant null-terminated character string that contains the fully qualified path and name of the file that contains the fax document to transmit. The path can be a UNC path or a path that begins with a drive letter.

This parameter can contain any valid local or remote file name. The file must be a properly registered file type, and the fax server must be able to access the file.

JobParams

[in] Pointer to a FAX_JOB_PARAM structure that contains the information necessary for the fax server to send the fax transmission. The structure includes, among other items, the recipient's fax number, sender and recipient data, an optional billing code, and job scheduling information.

CoverpageInfo

[in] Pointer to a FAX_COVERPAGE_INFO structure that contains personal data to display on the cover page of the fax document. This parameter must be NULL if a cover page is not required.

FaxJobId

[out] Pointer to a DWORD variable to receive a unique number that identifies the queued job that will send the fax transmission.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError can return one of the following errors.

This function can also return a TAPI error code if you specify a CallHandle member to the FAX_JOB_PARAM structure.

Remarks

Call the FaxCompleteJobParams function before calling the FaxSendDocument function. FaxCompleteJobParams is a utility function that fills in multiple members in the FAX_COVERPAGE_INFO and FAX_JOB_PARAM structures, with information such as the sender's name, the fax number, and optional billing code information.

The FaxSendDocument function executes asynchronously, and the function returns immediately. The fax server queues the job to send the fax transmission according to the details specified by the FAX_JOB_PARAM structure.

To send a fax document efficiently to multiple recipients, an application should call the FaxSendDocumentForBroadcast function, rather than calling FaxSendDocument multiple times. For more information, see Transmitting Faxes.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable with BackOffice Small Business Server.
  Header: Declared in Winfax.h.
  Library: Included as a resource in Winfax.dll.
  Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Fax Service Client Application Programming Interface Overview, Fax Service Client API Functions, FaxConnectFaxServer, FaxCompleteJobParams, FaxSendDocumentForBroadcast, FAX_COVERPAGE_INFO, FAX_JOB_PARAM