FaxStartPrintJob

A fax client application calls the FaxStartPrintJob function to start printing an outbound fax transmission on the specified fax printer. The function returns a handle to a device context that is required to call the FaxPrintCoverPage function.

BOOL WINAPI FaxStartPrintJob(
  LPCTSTR PrinterName,        // printer for fax job
  CONST FAX_PRINT_INFO *PrintInfo, 
                              // print job information structure
  LPDWORD FaxJobId,           // fax job identifier
  PFAX_CONTEXT_INFO FaxContextInfo 
                              // pointer to device context structure
);

Parameters

PrinterName

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

PrintInfo

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

FaxJobId

[out] Pointer to a DWORD variable to receive a unique number that identifies the fax print job. This parameter is required.

FaxContextInfo

[out] 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 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

A fax client application should not call the CreateDC graphics device interface (GDI) function to create the fax printer device context; nor should it call the StartDoc 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.

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.

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, FaxPrintCoverPage, DEVMODE, AbortDoc, EndDoc, DeleteDC, FAX_PRINT_INFO, FAX_CONTEXT_INFO