FaxSendDocumentForBroadcastA function (winfax.h)
A fax client application calls the FaxSendDocumentForBroadcast function to queue several fax jobs that will transmit the same outgoing fax transmission to several recipients.
WINFAXAPI BOOL FaxSendDocumentForBroadcastA(
[in] HANDLE FaxHandle,
[in] LPCSTR FileName,
[out] LPDWORD FaxJobId,
[in] PFAX_RECIPIENT_CALLBACKA FaxRecipientCallback,
[in] LPVOID Context
Specifies a fax server handle returned by a call to the FaxConnectFaxServer function.
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.
Pointer to a DWORD variable to receive the unique number that identifies the queued job that will send the fax transmission.
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.
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.
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.
|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.
|The fax server cannot locate the file specified by the FileName parameter.
|The fax server cannot render the file specified by the FileName parameter.
|Access is denied. FAX_JOB_SUBMIT access is required.
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.
- 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.
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.
|Minimum supported client
|Windows 2000 Professional [desktop apps only]
|Minimum supported server
|Windows 2000 Server [desktop apps only]