FAX_RECIPIENT_CALLBACK

The FAX_RECIPIENT_CALLBACK function is an application-defined or library-defined callback function that the FaxSendDocumentForBroadcast function calls to retrieve user-specific information for the transmission. FaxSendDocumentForBroadcast calls FAX_RECIPIENT_CALLBACK multiple times, once for each designated fax recipient.

The PFAX_RECIPIENT_CALLBACK data type is a pointer to a FAX_RECIPIENT_CALLBACK function.

BOOL CALLBACK FAX_RECIPIENT_CALLBACK(
  HANDLE FaxHandle,          //handle to the fax server
  DWORD RecipientNumber,     //index indicating current fax recipient
  LPVOID Context,            //pointer to context information
  PFAX_JOB_PARAM JobParams,  //pointer to job information structure
  PFAX_COVERPAGE_INFO CoverpageInfo OPTIONAL 
                             //pointer to local cover page structure
);

Parameters

FaxHandle

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

RecipientNumber

[in] Specifies a DWORD variable that indicates the number of times the FaxSendDocumentForBroadcast function has called the FAX_RECIPIENT_CALLBACK function. Each function call corresponds to one designated fax recipient, and the index is relative to 1.

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.

JobParams

[in/out] Pointer to a FAX_JOB_PARAM structure that contains the information necessary for the fax server to send the fax transmission to the designated recipient. The structure includes, among other items, the recipient's fax number, sender and recipient data, an optional billing code, and job scheduling information. The fax server queues the fax transmission according to the details specified by the FAX_JOB_PARAM structure.

CoverpageInfo

[in/out] Pointer to a FAX_COVERPAGE_INFO structure that contains cover page data to display on the cover page of the fax document for the designated recipient. This parameter must be NULL if a cover page is not required.

Return Values

The function returns a value of nonzero to indicate that the FaxSendDocumentForBroadcast function should queue an outbound fax transmission, using the data pointed to by the JobParams and CoverpageInfo parameters.

The function returns a value of zero to indicate that there are no more fax transmission jobs to queue, and calls to FAX_RECIPIENT_CALLBACK should be terminated. To get extended error information, call GetLastError.

Remarks

Call the FaxCompleteJobParams function before calling the FAX_RECIPIENT_CALLBACK function. FaxCompleteJobParams is a utility function that fills multiple members in the FAX_COVERPAGE_INFO and FAX_JOB_PARAM structures, with information such as the sender's name, fax number, and optional billing code information.

A fax client application must specify the FAX_RECIPIENT_CALLBACK function by passing its address when it calls the FaxSendDocumentForBroadcast function.

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.
  Unicode: Declared as Unicode and ANSI prototypes.

See Also

Fax Service Client Application Programming Interface Overview, Fax Service Client API Functions, FaxSendDocumentForBroadcast, FAX_COVERPAGE_INFO, FAX_JOB_PARAM, FaxConnectFaxServer