FaxSendDocumentA function (winfax.h)

Article
02/09/2023

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

Syntax

WINFAXAPI BOOL FaxSendDocumentA(
  [in]           HANDLE                    FaxHandle,
  [in]           LPCSTR                    FileName,
  [in]           PFAX_JOB_PARAMA           JobParams,
  [in, optional] const FAX_COVERPAGE_INFOA *CoverpageInfo,
  [out]          LPDWORD                   FaxJobId
);

Parameters

[in] FaxHandle

Type: HANDLE

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

[in] FileName

Type: LPCTSTR

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 file name. The file must be a properly registered file type, and the fax server must be able to access the file.

[in] JobParams

Type: PFAX_JOB_PARAM

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.

[in, optional] CoverpageInfo

Type: const FAX_COVERPAGE_INFO*

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.

[out] FaxJobId

Type: LPDWORD

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

Return value

Type: BOOL

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.

Return code	Description
ERROR_INVALID_PARAMETER	One or all of the FaxHandle, JobParams, or FileName parameters are NULL; the call handle specified by the CallHandle member of the FAX_JOB_PARAM structure is invalid (should be NULL), or the RecipientNumber member in the FAX_JOB_PARAM structure is NULL.
ERROR_INVALID_FUNCTION	The FaxHandle parameter specifies a remote connection, but the CallHandle member of the FAX_JOB_PARAM structure is not NULL.
ERROR_ACCESS_DENIED	Access is denied. FAX_JOB_SUBMIT access is required.
ERROR_FILE_NOT_FOUND	The fax server cannot locate the file specified by the FileName or the CoverpageInfo parameter.
ERROR_INVALID_DATA	The fax server cannot process the file specified by the FileName or the CoverpageInfo parameter.
ERROR_NOT_SUPPORTED	An attempt was made to hand off a voice call to send a fax, using the CallHandle member of the FAX_JOB_PARAM structure. This functionality is not supported.

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.

For FaxSendDocument to succeed, there must be a remote fax printer installed on the fax server.

To send a fax document efficiently to multiple recipients, an application should call the FaxSendDocument function multiple times. The FaxSendDocumentForBroadcast function is supported for backward compatibility.

When you send a document from an application, links in the document may cause a dialog to appear, requesting information. If you do not handle the information request within several minutes, FaxSendDocument will fail and return an error.

Note

The winfax.h header defines FaxSendDocument as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	winfax.h
Library	WinFax.lib