winspool.h


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:

ValorSignificado
PRINTER_ENUM_LOCAL La función ignora el parámetro Name, y enumera las impresoras instaladas localmente.
Windows 95: La función también enumera las impresoras de red, ya que son manejadas por el proveedor de impresión local.
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 tengan el atributo de compartidas. No puede ser usado de forma aislada; usar una operación OR para combinarla con otro tipo PRINTER_ENUM.
PRINTER_ENUM_DEFAULT Sólo Windows 95: La impresora devuelve información sobre la impresora por defecto.
PRINTER_ENUM_CONNECTIONS Sólo Windows NT: La función enumera la lista de impresoras con las que el usuario se ha conectado previamente.
PRINTER_ENUM_NETWORK Sólo Windows NT: La función enumera impresoras de red en el dominio del ordenador. Este valor sólo es válido si Level vale 1.
PRINTER_ENUM_REMOTE Sólo Windows NT: La función enumera impresoras de red y servidores de impresión en el dominio del ordenador. Este valor sólo es válido si Level vale 1.

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.

Parámetro FlagsParámetro NameResultado
PRINTER_ENUM_LOCALIgnorado. Todas las impresoras locales.
Windows 95: también se enumeran las impresoras de red, ya que están instaladas localmente.
PRINTER_ENUM_NAME"Proveedor de impresión"Todos los nombres de dominio.
PRINTER_ENUM_NAMEWindows NT sólo:
"Proveedor de impresión!Dominio"
Todas las impresoras y servidores de impresión en el dominio del ordenador.
PRINTER_ENUM_NAMEWindows NT sólo:
"Proveedor de impresión!!\\Maquina"
Todas las impresoras compartidas en \\Maquina.
PRINTER_ENUM_NAMEWindows NT: Una cadena vacía, ""
Windows 95: El nombre de la máquina local o del proveedor de impresión local.
Todas las impresoras locales.
Windows 95: También se enumeran las impresoras de red ya que están instaladas localmente.
PRINTER_ENUM_NAMENULLTodos los proveedores de impresión del dominio del ordenador
Sólo Windows NT:
PRINTER_ENUM_CONNECTIONS
Ignorado.Todas las impresoras conectadas remotamente.
Sólo Windows NT:
PRINTER_ENUM_NETWORK
Ignorado.Todas las impresoras en el dominio del ordenador.
Sólo Windows NT:
PRINTER_ENUM_REMOTE
Una cadena vacía, ""Todas las impresoras y servirodes de impresión en el dominio del ordenador.
Sólo Windows NT:
PRINTER_ENUM_REMOTE
"Proveedor de impresión"Lo mismo que PRINTER_ENUM_NAME.
Sólo Windows NT:
PRINTER_ENUM_REMOTE
"Proveedor de impresión!Dominio" Todas las impresoras y servidores de impresión en el dominio del ordenador, independientemente del dominio especificado.