Función DeviceCapabilitiesA (wingdi.h)

Artículo
03/08/2023

La función DeviceCapabilities recupera las funciones de un controlador de impresora.

Sintaxis

int DeviceCapabilitiesA(
  [in]  LPCSTR         pDevice,
  [in]  LPCSTR         pPort,
  [in]  WORD           fwCapability,
  [out] LPSTR          pOutput,
  [in]  const DEVMODEA *pDevMode
);

Parámetros

[in] pDevice

Puntero a una cadena terminada en null que contiene el nombre de la impresora. Tenga en cuenta que este es el nombre de la impresora, no del controlador de impresora.

[in] pPort

Puntero a una cadena terminada en null que contiene el nombre del puerto al que está conectado el dispositivo, como LPT1.

[in] fwCapability

Funcionalidades que se van a consultar. Este parámetro puede ser uno de los valores siguientes.

Valor	Significado
DC_BINNAMES	Recupera los nombres de las papeleras de la impresora. El búfer pOutput recibe una matriz de búferes de cadena. Cada búfer de cadenas tiene 24 caracteres y contiene el nombre de una papelera. El valor devuelto indica el número de entradas de la matriz. Las cadenas de nombre terminan en null a menos que el nombre tenga 24 caracteres de longitud. Si pOutput es NULL, el valor devuelto es el número de entradas bin necesarias.
DC_BINS	Recupera una lista de papeleras disponibles. El búfer pOutput recibe una matriz de valores WORD que indican los orígenes de papel disponibles para la impresora. El valor devuelto indica el número de entradas de la matriz. Para obtener una lista de los posibles valores de matriz, vea la descripción del miembro dmDefaultSource de la estructura DEVMODE . Si pOutput es NULL, el valor devuelto indica el número necesario de entradas en la matriz.
DC_COLLATE	Si la impresora admite la intercalación, el valor devuelto es 1; de lo contrario, el valor devuelto es cero. No se usa el parámetro pOutput .
DC_COLORDEVICE	Si la impresora admite la impresión en color, el valor devuelto es 1; de lo contrario, el valor devuelto es cero. No se usa el parámetro pOutput .
DC_COPIES	Devuelve el número de copias que el dispositivo puede imprimir.
DC_DRIVER	Devuelve el número de versión del controlador de impresora.
DC_DUPLEX	Si la impresora admite la impresión dúplex, el valor devuelto es 1; de lo contrario, el valor devuelto es cero. No se usa el parámetro pOutput .
DC_ENUMRESOLUTIONS	Recupera una lista de las resoluciones admitidas por la impresora. El búfer de pOutput recibe una matriz de valores LONG . Para cada resolución admitida, la matriz contiene un par de valores LONG que especifican las dimensiones x e y de la resolución, en puntos por pulgada. El valor devuelto indica el número de resoluciones admitidas. Si pOutput es NULL, el valor devuelto indica el número de resoluciones admitidas.
DC_EXTRA	Devuelve el número de bytes necesarios para la parte específica del dispositivo de la estructura DEVMODE para el controlador de impresora.
DC_FIELDS	Devuelve el miembro dmFields de la estructura DEVMODE del controlador de impresora. El miembro dmFields indica qué miembros de la parte independiente del dispositivo de la estructura son compatibles con el controlador de impresora.
DC_FILEDEPENDENCIES	Recupera los nombres de los archivos adicionales que deben cargarse cuando se instala un controlador. El búfer pOutput recibe una matriz de búferes de cadena. Cada búfer de cadenas tiene 64 caracteres y contiene el nombre de un archivo. El valor devuelto indica el número de entradas de la matriz. Las cadenas de nombre terminan en null a menos que el nombre tenga 64 caracteres de longitud. Si pOutput es NULL, el valor devuelto es el número de archivos.
DC_MAXEXTENT	Devuelve el tamaño máximo de papel que pueden especificar los miembros dmPaperLength y dmPaperWidth de la estructura DEVMODE del controlador de impresora. La LOWORD del valor devuelto contiene el valor máximo dmPaperWidth y HIWORD contiene el valor máximo dmPaperLength .
DC_MEDIAREADY	Recupera los nombres de los formularios de papel que están disponibles actualmente para su uso. El búfer pOutput recibe una matriz de búferes de cadena. Cada búfer de cadenas tiene 64 caracteres y contiene el nombre de un formulario de papel. El valor devuelto indica el número de entradas de la matriz. Las cadenas de nombre terminan en null a menos que el nombre tenga 64 caracteres de longitud. Si pOutput es NULL, el valor devuelto es el número de formularios de papel.
DC_MEDIATYPENAMES	Recupera los nombres de los tipos de medios admitidos. El búfer pOutput recibe una matriz de búferes de cadena. Cada búfer de cadenas tiene 64 caracteres de longitud y contiene el nombre de un tipo de medio admitido. El valor devuelto indica el número de entradas de la matriz. Las cadenas terminan en null a menos que el nombre tenga 64 caracteres de longitud. Si pOutput es NULL, el valor devuelto es el número de nombres de tipo multimedia necesarios.
DC_MEDIATYPES	Recupera una lista de tipos de medios admitidos. El búfer pOutput recibe una matriz de valores DWORD que indican los tipos de medios admitidos. El valor devuelto indica el número de entradas de la matriz. Para obtener una lista de posibles valores de matriz, vea la descripción del miembro dmMediaType de la estructura DEVMODE . Si pOutput es NULL, el valor devuelto indica el número necesario de entradas en la matriz.
DC_MINEXTENT	Devuelve el tamaño de papel mínimo que pueden especificar los miembros dmPaperLength y dmPaperWidth de la estructura DEVMODE del controlador de impresora. La LOWORD del valor devuelto contiene el valor mínimo dmPaperWidth y HIWORD contiene el valor dmPaperLength mínimo.
DC_ORIENTATION	Devuelve la relación entre las orientaciones verticales y horizontales de un dispositivo, en términos del número de grados en los que la orientación vertical se gira en sentido contrario a las agujas del reloj para generar orientación horizontal. El valor devuelto puede ser cualquiera de los siguientes: 0 Sin orientación horizontal. 90 Vertical gira 90 grados para producir paisaje. 270 Vertical gira 270 grados para producir paisaje.
DC_NUP	Recupera una matriz de enteros que indican la capacidad de la impresora para imprimir varias páginas de documento por página impresa. El búfer pOutput recibe una matriz de valores DWORD . Cada valor representa un número admitido de páginas de documento por página impresa. El valor devuelto indica el número de entradas de la matriz. Si pOutput es NULL, el valor devuelto indica el número necesario de entradas en la matriz.
DC_PAPERNAMES	Recupera una lista de nombres de papel admitidos (por ejemplo, Carta o Legal). El búfer pOutput recibe una matriz de búferes de cadena. Cada búfer de cadena tiene 64 caracteres y contiene el nombre de un formulario de papel. El valor devuelto indica el número de entradas de la matriz. Las cadenas de nombre terminan en null a menos que el nombre tenga 64 caracteres de longitud. Si pOutput es NULL, el valor devuelto es el número de formularios de papel.
DC_PAPERS	Recupera una lista de tamaños de papel admitidos. El búfer pOutput recibe una matriz de valores WORD que indican los tamaños de papel disponibles para la impresora. El valor devuelto indica el número de entradas de la matriz. Para obtener una lista de los posibles valores de matriz, vea la descripción del miembro dmPaperSize de la estructura DEVMODE . Si pOutput es NULL, el valor devuelto indica el número necesario de entradas en la matriz.
DC_PAPERSIZE	Recupera las dimensiones, en décimo milímetros, de cada tamaño de papel admitido. El búfer pOutput recibe una matriz de estructuras POINT . Cada estructura contiene el ancho (dimensión x) y la longitud (dimensión y) de un tamaño de papel como si el papel estuviera en la orientación DMORIENT_PORTRAIT . El valor devuelto indica el número de entradas de la matriz.
DC_PERSONALITY	Recupera una lista de idiomas de descripción de impresora admitidos por la impresora. El búfer pOutput recibe una matriz de búferes de cadena. Cada búfer tiene 32 caracteres y contiene el nombre de un idioma de descripción de la impresora. El valor devuelto indica el número de entradas de la matriz. Las cadenas de nombre terminan en null a menos que el nombre tenga 32 caracteres de longitud. Si pOutput es NULL, el valor devuelto indica el número necesario de entradas de matriz.
DC_PRINTERMEM	El valor devuelto es la cantidad de memoria de impresora disponible, en kilobytes. No se usa el parámetro pOutput .
DC_PRINTRATE	El valor devuelto indica la velocidad de impresión de la impresora. El valor devuelto para DC_PRINTRATEUNIT indica las unidades del valor de DC_PRINTRATE . No se usa el parámetro pOutput .
DC_PRINTRATEPPM	El valor devuelto indica la velocidad de impresión de la impresora, en páginas por minuto. No se usa el parámetro pOutput .
DC_PRINTRATEUNIT	El valor devuelto es uno de los siguientes valores que indican las unidades de velocidad de impresión para el valor devuelto para la marca DC_PRINTRATE . No se usa el parámetro pOutput . PRINTRATEUNIT_CPS Caracteres por segundo. PRINTRATEUNIT_IPM Pulgadas por minuto. PRINTRATEUNIT_LPM Líneas por minuto. PRINTRATEUNIT_PPM Páginas por minuto.
DC_SIZE	Devuelve el miembro dmSize de la estructura DEVMODE del controlador de impresora.
DC_STAPLE	Si la impresora admite la asociación, el valor devuelto es un valor distinto de cero; de lo contrario, el valor devuelto es cero. No se usa el parámetro pOutput .
DC_TRUETYPE	Recupera las capacidades del controlador para usar fuentes TrueType. Para DC_TRUETYPE, el parámetro pOutput debe ser NULL. El valor devuelto puede ser uno o varios de los siguientes: DCTT_BITMAP El dispositivo puede imprimir fuentes TrueType como gráficos. DCTT_DOWNLOAD El dispositivo puede descargar fuentes TrueType. DCTT_SUBDEV El dispositivo puede sustituir las fuentes del dispositivo por fuentes TrueType.
DC_VERSION	Devuelve la versión de especificación a la que se ajusta el controlador de impresora.

[out] pOutput

Puntero a una matriz. El formato de la matriz depende del valor del parámetro fwCapability . Consulte cada funcionalidad anterior para averiguar qué se devuelve si pOutput es NULL.

[in] pDevMode

Puntero a una estructura DEVMODE . Si este parámetro es NULL, DeviceCapabilities recupera los valores de inicialización predeterminados actuales para el controlador de impresora especificado. De lo contrario, la función recupera los valores contenidos en la estructura a la que apunta pDevMode .

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto depende de la configuración del parámetro fwCapability . Un valor devuelto de cero suele indicar que, mientras la función se completó correctamente, hubo algún tipo de error, como una funcionalidad que no se admite. Para obtener más información, consulte las descripciones de los valores fwCapability .

Si la función devuelve -1, esto puede significar que no se admite la funcionalidad o que se produjo un error de función general.

Comentarios

Nota Se trata de una función de bloqueo o sincrónica que podría no devolverse inmediatamente. La rapidez con la que esta función devuelve depende de factores en tiempo de ejecución, como el estado de red, la configuración del servidor de impresión y la implementación del controlador de impresora, factores 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.

La estructura DEVMODE a la que apunta el parámetro pDevMode se puede obtener llamando a la función DocumentProperties .

Si un controlador de impresora admite funcionalidades de dispositivo personalizadas, el controlador debe llamar a la función SetPrinterData para cada funcionalidad personalizada. La función SetPrinterData agrega los datos de impresora adecuados al sistema de impresión, lo que permite que las aplicaciones de 32 bits accedan a las funcionalidades personalizadas en instalaciones de Windows de 64 bits.

Para cada funcionalidad personalizada, primero debe agregar datos de impresora que describen el tipo de la funcionalidad. Para ello, al llamar a SetPrinterData, establezca la cadena pValueName en CustomDeviceCapabilityType_Xxx, donde "Xxx" es la representación hexadecimal de la funcionalidad. Por ejemplo, podría tener "CustomDeviceCapabilityType_1234". Los datos del Registro que establezca deben ser del tipo REG_DWORD y debe establecer su valor en uno de los siguientes:

0, si la funcionalidad personalizada es DWORD
1, si la funcionalidad personalizada es un búfer de bytes
2, si la funcionalidad personalizada es una matriz de elementos

Si la funcionalidad personalizada es una matriz de elementos, debe llamar a SetPinterData una segunda vez para proporcionar información sobre el tamaño de un elemento de la matriz. Para ello, al llamar a SetPinterData, la cadena pValueName que proporcione debe ser "CustomDeviceCapabilitySize_Xxx" donde Xxx es la representación hexadecimal de la funcionalidad. Por ejemplo, podría tener "CustomDeviceCapabilitySize_1234". Los datos del Registro que establezca deben ser del tipo REG_DWORD y debe establecer su valor en el tamaño en bytes de un elemento de la matriz.

Nota

El encabezado wingdi.h define DeviceCapabilities como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

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]
Plataforma de destino	Windows
Encabezado	wingdi.h (incluye Windows.h)
Library	WinSpool.lib
Archivo DLL	WinSpool.drv