Export (0) Print
Expand All

FaxSendDocument function

Applies to: desktop apps only

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

Syntax

BOOL WINAPI FaxSendDocument(
  __in      HANDLE FaxHandle,
  __in      LPCTSTR FileName,
  __in      PFAX_JOB_PARAM JobParams,
  __in_opt  const FAX_COVERPAGE_INFO *CoverpageInfo,
  __out     LPDWORD FaxJobId
);

Parameters

FaxHandle [in]

Type: HANDLE

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

FileName [in]

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.

JobParams [in]

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.

CoverpageInfo [in, optional]

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.

FaxJobId [out]

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 codeDescription
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.

Requirements

Minimum supported client

Windows 2000 Professional

Minimum supported server

Windows 2000 Server

Header

Winfax.h

Library

WinFax.lib

Unicode and ANSI names

FaxSendDocumentW (Unicode) and FaxSendDocumentA (ANSI)

See also

Fax Service Client API for Windows 2000
Fax Service Client API Functions
FaxConnectFaxServer
FaxCompleteJobParams
FaxSendDocumentForBroadcast
FAX_COVERPAGE_INFO
FAX_JOB_PARAM

 

 

Build date: 5/5/2012

Community Additions

ADD
Show:
© 2014 Microsoft