Función EnumPrinters
La función EnumPrinters enumera impresoras disponibles, servidores de impresión, dominios o proveedores de impresión.
Sintaxis
BOOL EnumPrinters(
_In_ DWORD Flags,
_In_ LPTSTR Name,
_In_ DWORD Level,
_Out_ LPBYTE pPrinterEnum,
_In_ DWORD cbBuf,
_Out_ LPDWORD pcbNeeded,
_Out_ LPDWORD pcReturned
);
Parámetros
-
Marcas [in]
-
Tipos de objetos de impresión que la función debe enumerar. Este valor puede ser uno o varios de los valores siguientes.
Valor Significado - PRINTER_ENUM_LOCAL
Si no se pasa también la marca PRINTER_ENUM_NAME, la función omite el parámetro Name y enumera las impresoras instaladas localmente. Si también se pasa PRINTER_ENUM_NAME, la función enumera las impresoras locales en Name. - PRINTER_ENUM_NAME
La función enumera la impresora identificada por Name. Puede ser un servidor, un dominio o un proveedor de impresión. Si Name es NULL, la función enumera los proveedores de impresión disponibles. - PRINTER_ENUM_SHARED
La función enumera las impresoras que tienen el atributo compartido. No se puede utilizar de forma aislada; use una operación OR para combinar con otro tipo de PRINTER_ENUM. - PRINTER_ENUM_CONNECTIONS
La función enumera la lista de impresoras a las que el usuario ha realizado conexiones anteriores. - PRINTER_ENUM_NETWORK
La función enumera las impresoras de red en el dominio del equipo. Este valor solo es válido si Level es 1. - PRINTER_ENUM_REMOTE
La función enumera impresoras de red y servidores de impresión en el dominio del equipo. Este valor solo es válido si Level es 1. - PRINTER_ENUM_CATEGORY_3D
La función enumera solo impresoras 3D. - PRINTER_ENUM_CATEGORY_ALL
La función enumera todos los dispositivos de impresión, incluidas las impresoras 3D. Si Level es 4, solo puede usar las constantes PRINTER_ENUM_CONNECTIONS y PRINTER_ENUM_LOCAL.
Nota
Los dispositivos de impresión 3D no se enumeran de forma predeterminada. Debe incluir tanto PRINTER_ENUM_CATEGORY_3D como PRINTER_ENUM_LOCAL para enumerar solo impresoras 3D. Para incluir impresoras 3D, junto con todas las demás impresoras locales, use PRINTER_ENUM_CATEGORY_ALL y PRINTER_ENUM_LOCAL.
-
Nombre [in]
-
Si Level es 1, Flags contiene PRINTER_ENUM_NAME y Name no es NULL, Name es un puntero a una cadena terminada en null que especifica el nombre del objeto que se va a enumerar. Esta cadena puede ser el nombre de un servidor, un dominio o un proveedor de impresión.
Si Level es 1, Flags contiene PRINTER_ENUM_NAME y Name es NULL, la función enumera los proveedores de impresión disponibles.
Si Level es 1, Flags contiene PRINTER_ENUM_REMOTE y Name es NULL, la función enumera las impresoras en el dominio del usuario.
Si Level es 2 o 5, Name es un puntero a una cadena terminada en null que especifica el nombre de un servidor cuyas impresoras se van a enumerar. Si esta cadena es NULL, la función enumera las impresoras instaladas en el equipo local.
Si Level es 4, Name debe ser NULL. La función siempre consulta en el equipo local.
Cuando Name es NULL, establezca Marcas en PRINTER_ENUM_LOCAL | PRINTER_ENUM_CONNECTIONS enumera las impresoras instaladas en el equipo local. Estas impresoras incluyen las que están físicamente conectadas al equipo local, así como impresoras remotas a las que tiene una conexión de red.
Cuando Name no es NULL, establezca Marcas en PRINTER_ENUM_LOCAL | PRINTER_ENUM_NAME enumera las impresoras locales instaladas en el nombre del servidor.
-
Nivel [in]
-
Tipo de estructuras de datos a las que apunta pPrinterEnum. Los valores válidos son 1, 2, 4 y 5, que corresponden al PRINTER_INFO_1, PRINTER_INFO_2 , PRINTER_INFO_4 y PRINTER_INFO_5 estructuras de datos.
Este valor puede ser 1, 2, 4 o 5.
-
pPrinterEnum [out]
-
Puntero a un búfer que recibe una matriz de estructuras de PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_4 o PRINTER_INFO_5 . Cada estructura contiene datos que describen un objeto de impresión disponible.
Si Level es 1, la matriz contiene estructuras PRINTER_INFO_1 . Si Level es 2, la matriz contiene estructuras PRINTER_INFO_2 . Si Level es 4, la matriz contiene estructuras PRINTER_INFO_4 . Si Level es 5, la matriz contiene estructuras PRINTER_INFO_5 .
El búfer debe ser lo suficientemente grande como para recibir la matriz de estructuras de datos y cualquier cadena u otros datos a los que apunten los miembros de la estructura. Si el búfer es demasiado pequeño, el parámetro pcbNeeded devuelve el tamaño de búfer necesario.
-
cbBuf [in]
-
Tamaño, en bytes, del búfer al que apunta pPrinterEnum.
-
pcbNeeded [ out]
-
Puntero a un valor que recibe el número de bytes copiados si la función se realiza correctamente o el número de bytes necesarios si cbBuf es demasiado pequeño.
-
pcReturned [out]
-
Puntero a un valor que recibe el número de PRINTER_INFO_1, PRINTER_INFO_2 , PRINTER_INFO_4 o estructuras PRINTER_INFO_5 que devuelve la función en la matriz a la que apunta pPrinterEnum .
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto es un valor distinto de cero.
Si la función no se realiza correctamente, el valor devuelto es cero.
Comentarios
No llame a este método en DllMain.
Nota
Se trata de una función de bloqueo o sincrónica que podría no devolverse inmediatamente. La rapidez con la que devuelve esta función depende de factores en tiempo de ejecución, como el estado de red, la configuración del servidor de impresión y los factores de implementación del controlador de impresora que son difíciles de predecir al escribir una aplicación. Llamar a esta función desde un subproceso que administra la interacción con la interfaz de usuario podría hacer que la aplicación parezca que no responde.
Si EnumPrinters devuelve una estructura PRINTER_INFO_1 en la que se especifica PRINTER_ENUM_CONTAINER, esto indica que hay una jerarquía de objetos de impresora. Una aplicación puede enumerar la jerarquía llamando de nuevo a EnumPrinters, estableciendo Name en el valor del miembro pName de la estructura PRINTER_INFO_1.
La función EnumPrinters no recupera información de seguridad. Si PRINTER_INFO_2 estructuras se devuelven en la matriz a la que apunta pPrinterEnum, sus miembros pSecurityDescriptor se establecerán en NULL.
Para obtener información sobre la impresora predeterminada, llame a GetDefaultPrinter.
La estructura de PRINTER_INFO_4 proporciona una manera sencilla y extremadamente rápida de recuperar los nombres de las impresoras instaladas en un equipo local, así como las conexiones remotas que ha establecido un usuario. Cuando se llama a EnumPrinters con una estructura de datos PRINTER_INFO_4 , esa función consulta el Registro para obtener la información especificada y, a continuación, devuelve inmediatamente. Esto difiere del comportamiento de EnumPrinters cuando se llama con otros niveles de estructuras de datos de PRINTER_INFO_* . En concreto, cuando se llama a EnumPrinters con una estructura de datos de nivel 2 (PRINTER_INFO_2), realiza una llamada a OpenPrinter en cada conexión remota. Si una conexión remota está inactiva o el servidor remoto ya no existe, o la impresora remota ya no existe, la función debe esperar a que RPC agote el tiempo de espera y, por consiguiente, produzca un error en la llamada a OpenPrinter . Esto puede tardar unos minutos. Pasar una estructura de PRINTER_INFO_4 permite a una aplicación recuperar un mínimo de información necesaria; si se desea obtener información más detallada, se puede realizar una llamada posterior al nivel 2 de EnumPrinters .
Windows Vista: Los datos de la impresora devueltos por EnumPrinters se recuperan de una memoria caché local cuando el valor de Level es 4.
En la tabla siguiente se muestra la salida de EnumPrinters para varios valores flags cuando el parámetro Level está establecido en 1.
En la columna Parámetro nombre de la tabla, debe sustituir un nombre adecuado para el proveedor de impresión, el dominio y la máquina. Por ejemplo, para "Proveedor de impresión", puede usar el nombre del proveedor de impresión de red o el nombre del proveedor de impresión local. Para recuperar los nombres del proveedor de impresión, llame a EnumPrinters con El nombre establecido en NULL.
| Parámetro Flags | Parámetro Name | Resultado |
|---|---|---|
| PRINTER_ENUM_LOCAL (y no PRINTER_ENUM_NAME) | Se omite el parámetro Name . |
Todas las impresoras locales. |
| PRINTER_ENUM_NAME | "Proveedor de impresión" |
Todos los nombres de dominio |
| PRINTER_ENUM_NAME | "Proveedor de impresión! Dominio" |
Todas las impresoras y los servidores de impresión del dominio del equipo |
| PRINTER_ENUM_NAME | "Proveedor de impresión!! \\Machine" |
Todas las impresoras compartidas en \\Machine |
| PRINTER_ENUM_NAME | Una cadena vacía, "" |
Todas las impresoras locales. |
| PRINTER_ENUM_NAME |
NULL |
Todos los proveedores de impresión del dominio del equipo |
| PRINTER_ENUM_CONNECTIONS | Se omite el parámetro Name . |
Todas las impresoras remotas conectadas |
| PRINTER_ENUM_NETWORK | Se omite el parámetro Name . |
Todas las impresoras del dominio del equipo |
| PRINTER_ENUM_REMOTE | Una cadena vacía, "" |
Todas las impresoras y los servidores de impresión del dominio del equipo |
| PRINTER_ENUM_REMOTE | "Proveedor de impresión" |
Igual que PRINTER_ENUM_NAME |
| PRINTER_ENUM_REMOTE | "Proveedor de impresión! Dominio" |
Todas las impresoras y los servidores de impresión en el dominio del equipo, independientemente del dominio especificado. |
| PRINTER_ENUM_CATEGORY_3D | Se omite el parámetro Name . |
Solo se enumeran las impresoras 3D. |
| PRINTER_ENUM_CATEGORY_ALL | Se omite el parámetro Name . |
Las impresoras 3D se enumeran, junto con todas las demás impresoras. |
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible |
Windows 2000 Professional [solo aplicaciones de escritorio] |
| Servidor mínimo compatible |
Windows 2000 Server [solo aplicaciones de escritorio] |
| Encabezado |
|
| Biblioteca |
|
| Archivo DLL |
|
| Nombres Unicode y ANSI |
EnumPrintersW (Unicode) y EnumPrintersA (ANSI) |