BOOL EnumPrinters(
DWORD dwType, /* printer type or types */
LPTSTR lpszName, /* address of server name */
DWORD dwLevel, /* structure level */
LPBYTE lpbPrinters, /* printer info array */
DWORD cbBuf, /* number of bytes in printer info array */
/* buffer provided by caller */
LPDWORD lpdwNeeded, /* address of variable with count of bytes */
/* copied (or required) */
LPDWORD lpdwReturned /* address of variable with count of job */
/* info. structures copied */
);
Enumerates the available printers on the specified server.
dwType | Specifies the type of printers that the function should enumerate. This value can be any combination of the following constants: | |
PRINTER_ENUM_DEFAULT | Enumerates the default printer. | |
PRINTER_ENUM_LOCAL | Enumerates the locally installed printers. | |
PRINTER_ENUM_FAVORITE | Enumerates a list of favorite printers. This is essentially the list of printers that the user has made previous connections to. | |
PRINTER_ENUM_NAME | Enumerates the printer identified by lpszName. This could be a server lpszName, or a domain lpszName. If lpszName is NULL, available domains (that is, Network Print Providors) will be enumerated. | |
PRINTER_ENUM_REMOTE | Enumerates network printers. | |
PRINTER_ENUM_SHARED | Enumerates printers with the shared attribute. | |
lpszName | Points to a null-terminated string that specifies the name of the server for which to enumerate the printers. If this string is NULL, the local printers are enumerated. | |
dwLevel | Specifies the version of the structure to which lpbPrinters points. This value must be 1 or 2. | |
lpbPrinters | Points to an array of PRINTER_INFO_1 or PRINTER_INFO_2 structures. If dwLevel is 1, the array contains PRINTER_INFO_1 structures; if dwLevel is 2, the array contains PRINTER_INFO_2 structures. | |
cbBuf | Specifies the size, in bytes, of the array to which lpbPrinters points. | |
lpdwNeeded | Points to a value that specifies the number of bytes copied if the function succeeds or the number of bytes required if cbBuf is too small. | |
lpdwReturned | Points to a value that specifies the number of PRINTER_INFO_1 or PRINTER_INFO_2 structures that returned in the array to which the lpbPrinters parameter points. |
Network print providers are only required to support two of the dwType parameter values: PRINTER_ENUM_REMOTE and PRINTER_ENUM_NAME.
There are four possible dispositions for a server name passed to a provider's EnumPrinters function by the PRR:
Cases 1 and 2 indicate that the specified server does not exist on the network. In these cases, the PRR expects providers to return FALSE and to set the last error code to the value ERROR_INVALID_NAME.
Case 3 represents a network error. The provider should return FALSE and call the SetLastError function to an appropriate Win32 error code. Once a network error has been encountered, the PRR will perform no further enumeration.
Case 4 indicates success. The provider should return TRUE.