PFAX_RECIPIENT_CALLBACKA callback function (winfax.h)

Article
07/27/2022

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.

Syntax

PFAX_RECIPIENT_CALLBACKA PfaxRecipientCallbacka;

BOOL PfaxRecipientCallbacka(
  [in]                HANDLE FaxHandle,
  [in]                DWORD RecipientNumber,
  [in]                LPVOID Context,
  [in, out]           PFAX_JOB_PARAMA JobParams,
  [in, out, optional] PFAX_COVERPAGE_INFOA CoverpageInfo
)
{...}

Parameters

[in] FaxHandle

Type: HANDLE

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

[in] RecipientNumber

Type: DWORD

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.

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

[in, out] JobParams

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

[in, out, optional] CoverpageInfo

Type: PFAX_COVERPAGE_INFO

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 value

Type: BOOL

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

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.

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.

Note

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