EnumPrinters

La función EnumPrinters enumera las impresoras, servidores de impresión, dominios o proveedores de impresión disponibles.

Sintaxis

BOOL EnumPrinters(
    DWORD Flags,          // tipos de objetos de impresión a enumerar
    LPTSTR Name,          // nombre de objeto de impresión
    DWORD Level,          // especifica el tipo de estructura de información de impresora
    LPBYTE pPrinterEnum,  // puntero a buffer para recibir las estructuras de información de impresora
    DWORD cbBuf,          // tamaño, en bytes, del array
    LPDWORD pcbNeeded,    // puntero a variable con el número de bytes copiados (o requeridos)
    LPDWORD pcReturned    // puntero a variable con el número de estructuras de información de impresora copiados
   );

Parámetros

flags: especifica los tipos de objetos de impresión que la función debe enumerar. Este valor puede ser una combinación de las siguientes constantes:

Si Level es 4, sólo se pueden usar las constantes PRINTER_ENUM_CONNECTIONS y PRINTER_ENUM_LOCAL.

Name: Si Level es 1, Flags contiene PRINTER_ENUM_NAME, y Name no es NULL, Name apunta a una cadena terminada en cero que especifica el nombre del objeto 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 ó 5, Name apunta a una cadena termianda en cero que especifica el nombre de un servidor cuyas impresoras han de ser enumeradas. Si esta cadena es NULL, la función enumera las impresoras instaladas en la máquina local.

Si Level es 4, Name debe ser NULL. la función siempre consulta en la máquina local.

Cuando Name es NULL, enumera las impresoras que están instaladas en la máquina local. Estas impresoras incluyen tanto aquellas que están físicamente conectadas al ordenador local como las impresoras remotas mediante una consexión de red.

Level: Especifica el tipo de estructura de datos apuntado por pPrinterEnum. Los valores válidos son 1, 2, 4 y 5, que corresponden con las estructuras de datos PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_4 y PRINTER_INFO_5.

Windows 95: el valor puede ser 1, 2 ó 5.

Windows NT: el valor puede ser 1, 2, 4 ó 5.

pPrinterEnum: Puntero a un buffer que recibirá un array de estructuras 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, el array contiene estructuras PRINTER_INFO_1. Si Level es 2, el array contiene estructuras PRINTER_INFO_2. Si Level es 4, el array contiene estructuras PRINTER_INFO_4. Si Level es 5, el array contiene estructuras PRINTER_INFO_5.

Windows 95: El buffer no puede recibir estructuras PRINTER_INFO_4. Sólo puede contener cualquiera de los otros tipos.

cbBuf: Especifica el tamaño, en bytes, del array apuntado por pPrinterEnum.

pcbNeeded: Puntero a una variable que recibirá el número de bytes copiados si la función tiene éxito o el número de bytes requeridos si cbBuf es demasiado pequeño.

pcReturned: puntero a una variable que recibe el nímero de estructuras PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_4 o PRINTER_INFO_5 que la función ha devuelto en el array apuntado por pPrinterEnum.

Valor de retorno

Si la función tiene éxito, el valor de retorno es distinto de cero.

Si la función falla, el valor de retorno es cero. Para obtener información adicional sobre el error, usar la función GetLastError.

Observaciones

Si EnumPrinters devuelve una estructura PRINTER_INFO_1 en la que se especifica PRINTER_ENUM_CONTAINER, eso indica que existe una gerarquía de objetos de impresión. Una aplicación puede enumerar una gerarquía llamando a EnumPrinters otra vez, usando el valor el miembro pName de la estructura PRINTER_INFO_1 para el parámetro Name.

la función EnumPrinters no recupera información de seguridad. Si se devuelven estructuras PRINTER_INFO_2 en el array apuntado por pPrinterEnum, sus miembros pSecurityDescriptor contendrán el valor NULL.

Para obtener información sobre la impresora por defecto, llamar a la función GetProfileString con el valor "windows" para la cadena de nombre de sección y el valor "device" para el nombre de clave. La cadena retornada contiene el nombre de la impresora por defecto, el nombre del fichero del DRV de la impresora y el puerto al que está conectado la impresora.

Windows NT: La estructura PRINTER_INFO_4 proporciona un modo fácil y extremadamente rápido para recuperar los nombres de las impresoras tanto del ordenador local, como de las conexiines remotas que el usuario haya establecido. Cuando EnumPrinters es invocada con una estructura de datos PRINTER_INFO_4, la función consulta el registro para la información especificada, y retorna inmediatamente. Esto difiere del comportamiento de EnumPrinters cuando es llamada con otros niveles de estruturas de datos PRINTER_INFO_*. En particular, cuando EnumPrinters es invocada con nivel 2 (PRINTER_INFO_2) de estructura de datos, realiza una llamada a OpenPrinter para cada conexión remota. Si una conexión remota está caída, o si el servidor remoto ya no existe, o es la impresora remota la que ya no existe, la función debe esperar al time-out del RPC y al consecuente fallo de la llamada a OpenPrinter. Esto puede llevar un tiempo. Pasando una estructura PRINTER_INFO_4 dejamos a la aplicación recuperar un mínimo de la información requerida; si se desea una información más detallada, se puede realizar una segunda llamada a EnumPrinter con el nivel 2.

Windows 95: Para enumerar rápidamente impresoras locales y de red, usar la estructura PRINTER_INFO_5. Esto hace que EnumPrinters consulte el registro en lugar de hacer llamadas remotas, y es similar a usar PRINTER_INFO_4 en Windows NT como se describe en el párrafo anterior.

Ejemplos

La siguiente tabla muestra la salida de EnumPrinters para varios valores de Flags cuando el parámetro Level es 1.

En la columna del parámetro Name de la tabla, se debe sustituir "Proveedor de impresión", "Dominio" y "Máquina" por un nombre apropiado. Por ejemplo, para "Proveedor de impresión", se puede usar el nomre del proveedero de impresion de la red de Windows NT: "Windows NT Remote Printers", o el nomreb del proveedor local de impresión de Windows 95: "Windows 95 Local Print Provider". Para obtener los nombres de proveedores de impresión, llamar a EnumPrinters con el parámetro Name a NULL.