Compartir a través de

Método IPrintOemUI::D eviceCapabilities (prcomoem.h)

  • Artículo

El IPrintOemUI::DeviceCapabilities método permite que un complemento de interfaz de usuario especifique funcionalidades de dispositivo personalizadas.

Sintaxis

HRESULT DeviceCapabilities(
  POEMUIOBJ poemuiobj,
  HANDLE    hPrinter,
  PWSTR     pDeviceName,
  WORD      wCapability,
  PVOID     pOutput,
  PDEVMODE  pPublicDM,
  PVOID     pOEMDM,
  DWORD     dwOld,
  DWORD     *dwResult
);

Parámetros

poemuiobj

Puntero proporcionado por el autor de la llamada a una estructura OEMUIOBJ .

hPrinter

Identificador proporcionado por el autor de la llamada al dispositivo de impresora.

pDeviceName

Puntero proporcionado por el autor de la llamada a una cadena que representa el nombre del dispositivo.

wCapability

Marca proporcionada por el autor de la llamada que indica el tipo de información que debe devolver el método. Para obtener una lista de marcas, consulte la descripción de la función DrvDeviceCapabilities .

pOutput

Puntero proporcionado por el autor de la llamada a un búfer para recibir la información solicitada. El tipo de información devuelta depende de la marca especificada por wCapability.

pPublicDM

Puntero proporcionado por el autor de la llamada a una estructura DEVMODEW validada.

pOEMDM

Puntero proporcionado por el autor de la llamada a los miembros privados de la estructura DEVMODEW del complemento de interfaz de usuario.

dwOld

Valor devuelto proporcionado por el autor de la llamada de la función DrvDeviceCapabilities del controlador de impresora o de otro complemento de interfaz de usuario. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

dwResult

Valor devuelto que depende de la marca especificada por wCapability. Para obtener más información, consulte la descripción de la función DrvDeviceCapabilities y la siguiente sección Comentarios.

Valor devuelto

El método debe devolver uno de los valores siguientes.

Código devuelto Descripción
S_OK
 La operación se realizó correctamente.
S_DEVCAP_OUTPUT_FULL_REPLACEMENT
 El complemento pretende usar el búfer al que apunta el parámetro pOutput para sus propios fines. Este valor devuelto se define en prcomoem.h. Para obtener más información sobre cuándo usar este valor devuelto, vea la siguiente sección Comentarios.
E_FAIL
 Error en la operación.
E_NOTIMPL
 El método no está implementado.

Comentarios

El método de IPrintOemUI::DeviceCapabilities un complemento de interfaz de usuario realiza los mismos tipos de operaciones que la función DrvDeviceCapabilities que exporta los archivos DLL de la interfaz de impresora en modo de usuario. El método especifica las funcionalidades proporcionadas por la impresora.

Puede usar el IPrintOemUI::DeviceCapabilities método para reemplazar la compatibilidad con Unidrv para una funcionalidad o para agregar una funcionalidad que el controlador de impresora no proporcione. El controlador llama IPrintOemUI::DeviceCapabilities desde su función DrvDeviceCapabilities .

Si el IPrintOemUI::DeviceCapabilities método indica compatibilidad personalizada para una funcionalidad (estableciendo los bits adecuados en respuesta a una marca de DC_FIELDS recibida), el código personalizado debe admitir completamente la funcionalidad. La compatibilidad completa suele incluir la devolución de información sobre la funcionalidad en respuesta a las llamadas al IPrintOemUI::DeviceCapabilities método, además de proporcionar el código adecuado en modo de usuario o modo kernel para implementar la funcionalidad.

Si IPrintOemUI::DeviceCapabilities varios complementos de interfaz de usuario exportan métodos, se llama a los métodos en el orden en que se especifican los complementos para la instalación. Cada vez que se llama al método de IPrintOemUI::DeviceCapabilities un complemento, su valor de entrada dwOld es el valor devuelto del método del IPrintOemUI::DeviceCapabilities complemento denominado anteriormente. Para el primer complemento llamado, dwOld contiene el valor devuelto de la función DrvDeviceCapabilities del controlador de impresora. Del mismo modo, el búfer al que apunta pOutput contiene, en la entrada, cualquier contenido colocado allí por un método llamado IPrintOemUI::DeviceCapabilities anteriormente o la función DrvDeviceCapabilities .

Para que varios complementos de interfaz de usuario funcionen conjuntamente entre sí, cada IPrintOemUI::DeviceCapabilities método debe obedecer las reglas siguientes:

  • Si un complemento de interfaz de usuario no admite una funcionalidad especificada, su IPrintOemUI::DeviceCapabilities método solo debe devolver el contenido del parámetro dwOld en dwResult.
  • Si un complemento de interfaz de usuario admite la funcionalidad, su IPrintOemUI::DeviceCapabilities método debe omitir dwOld y el contenido del búfer al que apunta pOutput. Debe proporcionar un valor devuelto y un contenido de búfer adecuado para indicar que admite la funcionalidad especificada. Si el método detecta un error, debe devolver GDI_ERROR en dwResult.
  • Si desea que un complemento de interfaz de usuario modifique la información de funcionalidades recibida en el búfer al que apunta pOutput, su IPrintOemUI::DeviceCapabilities método debe modificar el contenido del búfer y devolver un valor devuelto adecuado en dwResult. Por ejemplo, si wCapability es DC_FIELDS, el método debe OR los bits que necesita establecer con los bits establecidos en dwOld y devolver el resultado de la operación OR en dwResult.
  • Las reglas anteriores deben seguirse incluso si el contenido recibido de dwOld es GDI_ERROR.
Cuando se llama a la función DrvDeviceCapabilities del controlador con la marca DC_FIELDS establecida, la función llama a todos los IPrintOemUI::DeviceCapabilities métodos, especificando también DC_FIELDS y devuelve la unión de todos los bits establecidos en el autor de la llamada.

El valor devuelto S_DEVCAP_OUTPUT_FULL_REPLACEMENT es nuevo en Windows Vista y se aplica a los complementos de interfaz de usuario Unidrv y Pscript5. Un complemento debe usar el valor devuelto S_DEVCAP_OUTPUT_FULL_REPLACEMENT solo si requiere un control completo sobre lo que se coloca en el búfer al que apunta el parámetro pOutput . Ni Unidrv ni el controlador principal Pscript5 colocarán datos en el búfer de pOutput cuando el complemento devuelva S_DEVCAP_OUTPUT_FULL_REPLACEMENT. Es posible que un complemento tenga que devolver este valor cuando una configuración de la estructura DEVMODEW (a la que apuntan los parámetros pPublicDM y pOEMDM ) indica al complemento de la interfaz de usuario que debe notificar los datos de funcionalidad del dispositivo que son diferentes de los especificados en el archivo GPD o PPD. Por ejemplo, una estructura DEVMODEW que especifica la impresión fotográfica podría requerir un conjunto diferente de tipos de papel que los especificados en el archivo GPD o PPD. En tal situación, e independientemente de los valores de los parámetros pOutput y dwOld , el complemento debe devolver S_DEVCAP_OUTPUT_FULL_REPLACEMENT y debe establecer el parámetro dwResult en el número de tipos de papel que pretende notificar. Si pOutput no es NULL, el complemento también debe rellenar el búfer al que apunta pOutput con el conjunto deseado de tipos de papel y debe establecer dwResult en el número de tipos de papel que el complemento pretende notificar.

Cuando hay varios complementos de interfaz de usuario activos al mismo tiempo y uno de ellos devuelve S_DEVCAP_OUTPUT_FULL_REPLACEMENT, el controlador principal Unidrv o Pscript5 interpreta este valor devuelto para que los complementos tengan la intención de proporcionar datos completos de salida de reemplazo. Como resultado, el controlador principal no coloca ningún dato en el búfer de pOutput antes de llamar a los complementos. (El controlador principal llama a los complementos en el mismo orden que se especificó para su instalación).

En situaciones en las que no es necesario reemplazar los valores que coloca el controlador principal en el búfer de pOutput , el complemento debe devolver S_OK. Los controladores principales Unidrv y Pscript5 reconocen el valor devuelto S_DEVCAP_OUTPUT_FULL_REPLACEMENT solo para las funcionalidades del dispositivo que usan el búfer pOutput ; es decir, cuando el parámetro wCapability se establece en una de las marcas siguientes:

DC_PAPERNAMES

DC_PAPERS

DC_PAPERSIZE

DC_BINNAMES

DC_BINS

DC_NUP

DC_PERSONALITY

DC_MEDIAREADY

DC_MEDIATYPENAMES

DC_MEDIATYPES

DC_ENUMRESOLUTIONS

Para obtener más información sobre cómo crear e instalar complementos de interfaz de usuario, vea Personalizar los controladores de impresora de Microsoft.

Requisitos

Requisito Value
Plataforma de destino Escritorio
Encabezado prcomoem.h (incluya Prcomoem.h)

Consulte también

DrvDeviceCapabilities

IPrintOemUI