FaxSendDocumentA function (winfax.h)
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 |
|---|---|
|
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. |
|
The FaxHandle parameter specifies a remote connection, but the CallHandle member of the FAX_JOB_PARAM structure is not NULL. |
|
Access is denied. FAX_JOB_SUBMIT access is required. |
|
The fax server cannot locate the file specified by the FileName or the CoverpageInfo parameter. |
|
The fax server cannot process the file specified by the FileName or the CoverpageInfo parameter. |
|
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 that 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 is 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 |
See also
Fax Service Client API Functions