FaxSendDocumentForBroadcastW function (winfax.h)

Article
02/09/2023

A fax client application calls the FaxSendDocumentForBroadcast function to queue several fax jobs that will transmit the same outgoing fax transmission to several recipients.

Syntax

WINFAXAPI BOOL FaxSendDocumentForBroadcastW(
  [in]  HANDLE                   FaxHandle,
  [in]  LPCWSTR                  FileName,
  [out] LPDWORD                  FaxJobId,
  [in]  PFAX_RECIPIENT_CALLBACKW FaxRecipientCallback,
  [in]  LPVOID                   Context
);

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 to all recipients. 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.

[out] FaxJobId

Type: LPDWORD

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

[in] FaxRecipientCallback

Type: PFAX_RECIPIENT_CALLBACK

Pointer to a FAX_RECIPIENT_CALLBACK function that retrieves user-specific information for each designated recipient of the fax transmission. The FaxSendDocumentForBroadcast function calls the FAX_RECIPIENT_CALLBACK function once for each fax recipient until it returns a value of zero, indicating that all outbound transmissions have been queued.

[in] Context

Type: LPVOID

Pointer to a variable that contains application-specific context information or an application-defined value. FaxSendDocumentForBroadcast passes this data to the FAX_RECIPIENT_CALLBACK function.

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, FileName, FaxRecipientCallback, or FaxJobId parameters are NULL, or the RecipientNumber member in the FAX_JOB_PARAM structure is NULL.
ERROR_FILE_NOT_FOUND	The fax server cannot locate the file specified by the FileName parameter.
ERROR_INVALID_DATA	The fax server cannot render the file specified by the FileName parameter.
ERROR_ACCESS_DENIED	Access is denied. FAX_JOB_SUBMIT access is required.

Remarks

The function calls the FAX_RECIPIENT_CALLBACK function once for each designated fax recipient.

An application should call the FaxSendDocumentForBroadcast function to efficiently send a fax document to multiple recipients, rather than calling FaxSendDocument multiple times. This is because FaxSendDocumentForBroadcast stores the master document only once, using the same file for all outbound transmissions.

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

The FaxSendDocumentForBroadcast function performs the following operations in the order indicated:

The function queues the master document for transmission to multiple fax transmission recipients.
The function calls the user-defined FAX_RECIPIENT_CALLBACK function. If the callback function supplies the required information for the transmission to a fax recipient, it returns a value of nonzero. This value indicates that FaxSendDocumentForBroadcast should use the data to queue an outbound fax.
The function queues a fax transmission job for the first recipient using the master document.
The function calls the FAX_RECIPIENT_CALLBACK function multiple times, until it returns a value of zero. Each time FAX_RECIPIENT_CALLBACK returns nonzero, the FaxSendDocumentForBroadcast function queues an outbound transmission for the next fax recipient. A value of zero indicates that there are no more fax transmission jobs to queue, and calls to FAX_RECIPIENT_CALLBACK should be terminated.

For more information, see Transmitting Faxes.

Note

The winfax.h header defines FaxSendDocumentForBroadcast 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