GetPrinter function

The GetPrinter function retrieves information about a specified printer.

Syntax

BOOL GetPrinter(
  _In_  HANDLE  hPrinter,
  _In_  DWORD   Level,
  _Out_ LPBYTE  pPrinter,
  _In_  DWORD   cbBuf,
  _Out_ LPDWORD pcbNeeded
);

Parameters

hPrinter [in]

A handle to the printer for which the function retrieves information. Use the OpenPrinter or AddPrinter function to retrieve a printer handle.

Level [in]

The level or type of structure that the function stores into the buffer pointed to by pPrinter.

This value can be 1, 2, 3, 4, 5, 6, 7, 8 or 9.

pPrinter [out]

A pointer to a buffer that receives a structure containing information about the specified printer. The buffer must be large enough to receive the structure and any strings or other data to which the structure members point. If the buffer is too small, the pcbNeeded parameter returns the required buffer size.

The type of structure is determined by the value of Level.

Level Structure
1
A PRINTER_INFO_1 structure containing general printer information.
2
A PRINTER_INFO_2 structure containing detailed information about the printer.
3
A PRINTER_INFO_3 structure containing the printer's security information.
4
A PRINTER_INFO_4 structure containing minimal printer information, including the name of the printer, the name of the server, and whether the printer is remote or local.
5
A PRINTER_INFO_5 structure containing printer information such as printer attributes and time-out settings.
6
A PRINTER_INFO_6 structure specifying the status value of a printer.
7
A PRINTER_INFO_7 structure that indicates whether the printer is published in the directory service.
8
A PRINTER_INFO_8 structure specifying the global default printer settings.
9
A PRINTER_INFO_9 structure specifying the per-user default printer settings.

cbBuf [in]

The size, in bytes, of the buffer pointed to by pPrinter.

pcbNeeded [out]

A pointer to a variable that the function sets to the size, in bytes, of the printer information. If cbBuf is smaller than this value, GetPrinter fails, and the value represents the required buffer size. If cbBuf is equal to or greater than this value, GetPrinter succeeds, and the value represents the number of bytes stored in the buffer.

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.

The pDevMode member in the PRINTER_INFO_2, PRINTER_INFO_8, and PRINTER_INFO_9 structures can be NULL. When this happens, the printer is unusable until the driver is reinstalled successfully.

For the PRINTER_INFO_2 and PRINTER_INFO_3 structures that contain a pointer to a security descriptor, the function retrieves only those components of the security descriptor that the caller has permission to read. To retrieve particular security descriptor components, you must specify the necessary access rights when you call the OpenPrinter function to retrieve a handle to the printer. The following table shows the access rights required to read the various security descriptor components.

Access Right Security Descriptor Component
READ_CONTROL
Owner
Primary group
Discretionary access-control list (DACL)
ACCESS_SYSTEM_SECURITY
System access-control list (SACL)

If you specify level 7, the dwAction member of PRINTER_INFO_7 returns one of the following values to indicate whether the printer is published in the directory service.

dwAction value Meaning
DSPRINT_PUBLISH The printer is published. The pszObjectGUID member contains the GUID of the directory services print queue object associated with the printer.
DSPRINT_UNPUBLISH The printer is not published.
DSPRINT_PENDING Indicates that the system is attempting to complete a publish or unpublish operation. If a SetPrinter call fails to publish or unpublish a printer, the system makes further attempts to complete the operation in the background.

Starting with Windows Vista, the printer data returned by GetPrinter is retrieved from a local cache when hPrinter refers to a printer hosted by a print server and there is at least one open connection to the print server. In all other configurations, the printer data is queried from the print server.

Requirements

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
GetPrinterW (Unicode) and GetPrinterA (ANSI)

See also

Printing

Print Spooler API Functions

AbortPrinter

AddPrinter

ClosePrinter

DeletePrinter

EnumPrinters

PRINTER_INFO_1

PRINTER_INFO_2

PRINTER_INFO_3

PRINTER_INFO_4

PRINTER_INFO_5

PRINTER_INFO_7

PRINTER_INFO_8

PRINTER_INFO_9

OpenPrinter

SetPrinter