FaxSendDocumentForBroadcast

A fax client application calls the FaxSendDocumentForBroadcast function to queue several fax jobs that will transmit the same outgoing fax transmission to several recipients. 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.

BOOL WINAPI FaxSendDocumentForBroadcast(
  HANDLE FaxHandle,  // handle to the fax server
  LPCTSTR FileName,  // fax document file name
  LPDWORD FaxJobId,  // fax job identifier
  PFAX_RECIPIENT_CALLBACK FaxRecipientCallback, 
                     // pointer to fax recipient callback function
  LPVOID Context     // pointer to context information
);

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

FaxJobId

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

FaxRecipientCallback

[in] 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.

Context

[in] 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 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.

Remarks

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

1. The function queues the master document for transmission to multiple fax transmission recipients.
2. 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.
3. The function queues a fax transmission job for the first recipient using the master document.
4. 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.

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, FaxSendDocument, FAX_RECIPIENT_CALLBACK, FaxConnectFaxServer