FaxStartPrintJobA function (winfax.h)

Article
02/09/2023

A fax client application calls the FaxStartPrintJob function to start printing an outbound fax transmission on the specified fax printer.

Syntax

WINFAXAPI BOOL FaxStartPrintJobA(
  [in]  LPCSTR                PrinterName,
  [in]  const FAX_PRINT_INFOA *PrintInfo,
  [out] LPDWORD               FaxJobId,
  [out] PFAX_CONTEXT_INFOA    FaxContextInfo
);

Parameters

[in] PrinterName

Type: LPCTSTR

Pointer to a constant null-terminated character string that contains the name of a fax printer. The string can specify one of the following:

A local printer, such as, "printername"
A network printer, such as "\\machinename\printername"
NULL to specify the local fax printer

[in] PrintInfo

Type: const FAX_PRINT_INFO*

Pointer to a FAX_PRINT_INFO structure that contains the information necessary for the fax server to print the fax transmission. The structure includes, among other items, the recipient's fax number, sender and recipient data, an optional billing code, and delivery report information. For more information, see the following Remarks section.

[out] FaxJobId

Type: LPDWORD

Pointer to a DWORD variable to receive the print spooler's unique ID for the fax print job. (This is not the same as the fax queue's ID for the job and it cannot be used as a parameter in any fax API that takes a fax ID parameter.) This parameter is required.

[out] FaxContextInfo

Type: PFAX_CONTEXT_INFO

Pointer to a FAX_CONTEXT_INFO structure to receive a handle to a printer device context. When the fax client application calls the FaxPrintCoverPage function, it must pass this value in that function's FaxContextInfo parameter. For more information, see Device Contexts and the Printing and Print Spooler Reference.

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 both of the PrintInfo or FaxContextInfo parameters are NULL.
ERROR_INVALID_PARAMETER	The RecipientNumber member of the FAX_PRINT_INFO structure is NULL; or the OutputFileName member is NULL and the RecipientNumber member is not specified.
ERROR_INVALID_PRINTER_NAME	The PrinterName parameter specifies a printer that is not a fax printer, or there is no fax printer installed.
ERROR_NOT_ENOUGH_MEMORY	An error occurred during memory allocation.
ERROR_SPL_NO_STARTDOC	FaxStartPrintJob was not called first, hence there was no StartDoc call.

Remarks

The function returns a handle to a device context. The handle is used by the FaxPrintCoverPage function, and by the AbortDoc, EndDoc, DeleteDC, StartPage, EndPage and other Win32 Windows Graphics Device Interface (GDI) functions.

Note The application must also call the AbortDoc function or the EndDoc function to complete the print job, and call the DeleteDC function to deallocate the handle to the printer device context. For more information, see Printing a Fax to a Device Context.

A fax client application should not call the CreateDC GDI function to create the fax printer device context; nor should it call the StartPage printing function to start a fax print job. Instead, the application should call the FaxStartPrintJob function. This is because FaxStartPrintJob modifies information in the DEVMODE structure specific to the fax printer of interest.

The change prevents the display of the Fax Send Wizard that collects information from the user. The fax server uses the data in the FAX_PRINT_INFO structure pointed to by the PrintInfo parameter to print the fax transmission. This structure contains data the Fax Send Wizard would have collected, had the wizard been displayed.

A fax client application must call the FaxStartPrintJob function before calling the FaxPrintCoverPage function to print a cover page with a fax job.

Note

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