Windows Dev Center

FaxStartPrintJob function

Applies to: desktop apps only

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

Syntax

BOOL WINAPI FaxStartPrintJob(
  __in   LPCTSTR PrinterName,
  __in   const FAX_PRINT_INFO *PrintInfo,
  __out  LPDWORD FaxJobId,
  __out  PFAX_CONTEXT_INFO FaxContextInfo
);

Parameters

PrinterName [in]

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

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.

FaxJobId [out]

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.

FaxContextInfo [out]

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

Requirements

Minimum supported client

Windows 2000 Professional

Minimum supported server

Windows 2000 Server

Header

Winfax.h

Library

WinFax.lib

Unicode and ANSI names

FaxStartPrintJobW (Unicode) and FaxStartPrintJobA (ANSI)

See also

Fax Service Client API for Windows 2000
Fax Service Client API Functions
FaxPrintCoverPage
DEVMODE
AbortDoc
EndDoc
DeleteDC
FAX_PRINT_INFO
FAX_CONTEXT_INFO

 

 

Build date: 5/5/2012

Community Additions

ADD
Show:
© 2015 Microsoft