EnumPrinters function

The EnumPrinters function enumerates available printers, print servers, domains, or print providers.

Syntax


BOOL EnumPrinters(
  _In_   DWORD Flags,
  _In_   LPTSTR Name,
  _In_   DWORD Level,
  _Out_  LPBYTE pPrinterEnum,
  _In_   DWORD cbBuf,
  _Out_  LPDWORD pcbNeeded,
  _Out_  LPDWORD pcReturned
);

Parameters

Flags [in]

The types of print objects that the function should enumerate. This value can be one or more of the following values.

ValueMeaning
PRINTER_ENUM_LOCAL

If the PRINTER_ENUM_NAME flag is not also passed, the function ignores the Name parameter, and enumerates the locally installed printers. If PRINTER_ENUM_NAME is also passed, the function enumerates the local printers on Name.

PRINTER_ENUM_NAME

The function enumerates the printer identified by Name. This can be a server, a domain, or a print provider. If Name is NULL, the function enumerates available print providers.

PRINTER_ENUM_SHARED

The function enumerates printers that have the shared attribute. Cannot be used in isolation; use an OR operation to combine with another PRINTER_ENUM type.

PRINTER_ENUM_CONNECTIONS

The function enumerates the list of printers to which the user has made previous connections.

PRINTER_ENUM_NETWORK

The function enumerates network printers in the computer's domain. This value is valid only if Level is 1.

PRINTER_ENUM_REMOTE

The function enumerates network printers and print servers in the computer's domain. This value is valid only if Level is 1.

PRINTER_ENUM_CATEGORY_3D

The function enumerates only 3D printers.

PRINTER_ENUM_CATEGORY_ALL

The function enumerates all print devices, including 3D printers.

 

If Level is 4, you can only use the PRINTER_ENUM_CONNECTIONS and PRINTER_ENUM_LOCAL constants.

Note  3D print devices are not enumerated by default. You must include both PRINTER_ENUM_CATEGORY_3D and PRINTER_ENUM_LOCAL to enumerate only 3D printers. To include 3D printers, along with all other local printers, use PRINTER_ENUM_CATEGORY_ALL and PRINTER_ENUM_LOCAL.

Name [in]

If Level is 1, Flags contains PRINTER_ENUM_NAME, and Name is non-NULL, then Name is a pointer to a null-terminated string that specifies the name of the object to enumerate. This string can be the name of a server, a domain, or a print provider.

If Level is 1, Flags contains PRINTER_ENUM_NAME, and Name is NULL, then the function enumerates the available print providers.

If Level is 1, Flags contains PRINTER_ENUM_REMOTE, and Name is NULL, then the function enumerates the printers in the user's domain.

If Level is 2 or 5,Name is a pointer to a null-terminated string that specifies the name of a server whose printers are to be enumerated. If this string is NULL, then the function enumerates the printers installed on the local computer.

If Level is 4, Name should be NULL. The function always queries on the local computer.

When Name is NULL, setting Flags to PRINTER_ENUM_LOCAL | PRINTER_ENUM_CONNECTIONS enumerates printers that are installed on the local machine. These printers include those that are physically attached to the local machine as well as remote printers to which it has a network connection.

When Name is not NULL, setting Flags to PRINTER_ENUM_LOCAL | PRINTER_ENUM_NAME enumerates the local printers that are installed on the server Name.

Level [in]

The type of data structures pointed to by pPrinterEnum. Valid values are 1, 2, 4, and 5, which correspond to the PRINTER_INFO_1, PRINTER_INFO_2 , PRINTER_INFO_4, and PRINTER_INFO_5 data structures.

This value can be 1, 2, 4, or 5.

pPrinterEnum [out]

A pointer to a buffer that receives an array of PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_4, or PRINTER_INFO_5 structures. Each structure contains data that describes an available print object.

If Level is 1, the array contains PRINTER_INFO_1 structures. If Level is 2, the array contains PRINTER_INFO_2 structures. If Level is 4, the array contains PRINTER_INFO_4 structures. If Level is 5, the array contains PRINTER_INFO_5 structures.

The buffer must be large enough to receive the array of data structures 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.

cbBuf [in]

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

pcbNeeded [out]

A pointer to a value that receives the number of bytes copied if the function succeeds or the number of bytes required if cbBuf is too small.

pcReturned [out]

A pointer to a value that receives the number of PRINTER_INFO_1, PRINTER_INFO_2 , PRINTER_INFO_4, or PRINTER_INFO_5 structures that the function returns in the array to which pPrinterEnum points.

Return value

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

If the function fails, the return value is zero.

Remarks

Do not call this method in DllMain.

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.

If EnumPrinters returns a PRINTER_INFO_1 structure in which PRINTER_ENUM_CONTAINER is specified, this indicates that there is a hierarchy of printer objects. An application can enumerate the hierarchy by calling EnumPrinters again, setting Name to the value of the PRINTER_INFO_1 structure's pName member.

The EnumPrinters function does not retrieve security information. If PRINTER_INFO_2 structures are returned in the array pointed to by pPrinterEnum, their pSecurityDescriptor members will be set to NULL.

To get information about the default printer, call GetDefaultPrinter.

The PRINTER_INFO_4 structure provides an easy and extremely fast way to retrieve the names of the printers installed on a local machine, as well as the remote connections that a user has established. When EnumPrinters is called with a PRINTER_INFO_4 data structure, that function queries the registry for the specified information, then returns immediately. This differs from the behavior of EnumPrinters when called with other levels of PRINTER_INFO_* data structures. In particular, when EnumPrinters is called with a level 2 (PRINTER_INFO_2) data structure, it performs an OpenPrinter call on each remote connection. If a remote connection is down, or the remote server no longer exists, or the remote printer no longer exists, the function must wait for RPC to time out and consequently fail the OpenPrinter call. This can take a while. Passing a PRINTER_INFO_4 structure lets an application retrieve a bare minimum of required information; if more detailed information is desired, a subsequent EnumPrinters level 2 call can be made.

Windows Vista: The printer data returned by EnumPrinters is retrieved from a local cache when the value of Level is 4.

The following table shows the EnumPrinters output for various Flags values when the Level parameter is set to 1.

In the Name parameter column of the table, you should substitute an appropriate name for Print Provider, Domain, and Machine. For example, for "Print Provider," you could use the name of the network print provider or the name of the local print provider. To retrieve print provider names, call EnumPrinters with Name set to NULL.

Flags parameterName parameterResult
PRINTER_ENUM_LOCAL (and not PRINTER_ENUM_NAME)

The Name parameter is ignored.

All local printers.

PRINTER_ENUM_NAME

"Print Provider"

All domain names

PRINTER_ENUM_NAME

"Print Provider!Domain"

All printers and print servers in the computer's domain

PRINTER_ENUM_NAME

"Print Provider!!\\Machine"

All printers shared at \\Machine

PRINTER_ENUM_NAME

An empty string, ""

All local printers.

PRINTER_ENUM_NAME

NULL

All print providers in the computer's domain

PRINTER_ENUM_CONNECTIONS

The Name parameter is ignored.

All connected remote printers

PRINTER_ENUM_NETWORK

The Name parameter is ignored.

All printers in the computer's domain

PRINTER_ENUM_REMOTE

An empty string, ""

All printers and print servers in the computer's domain

PRINTER_ENUM_REMOTE

"Print Provider"

Same as PRINTER_ENUM_NAME

PRINTER_ENUM_REMOTE

"Print Provider!Domain"

All printers and print servers in computer's domain, regardless of Domain specified.

PRINTER_ENUM_CATEGORY_3D

The Name parameter is ignored.

Only 3D printers are enumerated.

PRINTER_ENUM_CATEGORY_ALL

The Name parameter is ignored.

3D printers are enumerated, along with all other printers.

 

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

EnumPrintersW (Unicode) and EnumPrintersA (ANSI)

See also

Printing
Print Spooler API Functions
AddPrinter
DeletePrinter
GetPrinter
PRINTER_INFO_1
PRINTER_INFO_2
PRINTER_INFO_4
PRINTER_INFO_5
SetPrinter

 

 

Community Additions

ADD
Show:
© 2014 Microsoft