AddJob function

Article
01/07/2021

The AddJob function adds a print job to the list of print jobs that can be scheduled by the print spooler. The function retrieves the name of the file you can use to store the job.

Note

In Windows 8 and later operating systems, we do not recommended using AddJob directly because there are cases (such as printing to a queue using File: or PORTPROMPT:) where AddJob will fail. Instead, you are advised to use GDI Print API, XPS Print API, StartDocPrinter, or the appropriate method from the Windows.Graphics.Printing namespace, depending on the print scenario.

If you try to print to a queue using File: or PORTPROMPT:, AddJob will Return the NOT_SUPPORTED error.

Syntax

BOOL AddJob(
  _In_  HANDLE  hPrinter,
  _In_  DWORD   Level,
  _Out_ LPBYTE  pData,
  _In_  DWORD   cbBuf,
  _Out_ LPDWORD pcbNeeded
);

Parameters

hPrinter [in]: A handle that specifies the printer for the print job. This must be a local printer that is configured as a spooled printer. If hPrinter is a handle to a remote printer connection, or if the printer is configured for direct printing, the AddJob function fails. Use the OpenPrinter or AddPrinter function to retrieve a printer handle.
Level [in]: The version of the print job information data structure that the function stores into the buffer pointed to by pData. Set this parameter to one.
pData [out]: A pointer to a buffer that receives an ADDJOB_INFO_1 data structure and a path string.
cbBuf [in]: The size, in bytes, of the buffer pointed to by pData. The buffer needs to be large enough to contain an ADDJOB_INFO_1 structure and a path string.
pcbNeeded [out]: A pointer to a variable that receives the total size, in bytes, of the ADDJOB_INFO_1 data structure plus the path string. If this value is less than or equal to cbBuf and the function succeeds, this is the actual number of bytes written to the buffer pointed to by pData. If this number is greater than cbBuf, the buffer is too small, and you must call the function again with a buffer size at least as large as *pcbNeeded.

Return value

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

Note

This is a blocking or synchronous function and might not return immediately. How quickly this function returns depends on run-time factors such as network status, print server configuration, and printer driver implementation factors that are difficult to predict when writing an application. Calling this function from a thread that manages interaction with the user interface could make the application appear to be unresponsive.

You can call the CreateFile function to open the spool file specified by the Path member of the ADDJOB_INFO_1 structure, and then call the WriteFile function to write print job data to it. After that is done, call the ScheduleJob function to notify the print spooler that the print job can now be scheduled by the spooler for printing.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Header	Winspool.h (include Windows.h)
Library	Winspool.lib
DLL	Winspool.drv
Unicode and ANSI names	AddJobW (Unicode) and AddJobA (ANSI)