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.

LevelStructure
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 RightSecurity 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 valueMeaning
DSPRINT_PUBLISHThe printer is published. The pszObjectGUID member contains the GUID of the directory services print queue object associated with the printer.
DSPRINT_UNPUBLISHThe printer is not published.
DSPRINT_PENDINGIndicates 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

 

 

Community Additions

ADD
Show:
© 2014 Microsoft