Compartir a través de

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

  • Artículo

El método IPrintOemUI::DeviceCapabilities 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 de OEMUIOBJ de.

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 de 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 del controlador de impresora función DrvDeviceCapabilities o desde otro complemento de interfaz de usuario. Para obtener más información, vea la siguiente sección Comentarios.

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 las siguientes observaciones.

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 se implementa.

Observaciones

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

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

Si el método IPrintOemUI::DeviceCapabilities indica compatibilidad personalizada con 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 método IPrintOemUI::DeviceCapabilities, además de proporcionar el código adecuado en modo de usuario o en modo kernel para implementar la funcionalidad.

Si varios complementos de interfaz de usuario exportan IPrintOemUI::DeviceCapabilities 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 IPrintOemUI::DeviceCapabilities de un complemento, su dwOld valor de entrada es el valor devuelto del método IPrintOemUI::DeviceCapabilities del complemento anteriormente llamado . 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 anteriormente llamado IPrintOemUI::DeviceCapabilities o función drvDeviceCapabilities.

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

  • Si un complemento de interfaz de usuario no admite una funcionalidad especificada, su método IPrintOemUI::DeviceCapabilities solo debe devolver el contenido del parámetro dwOld en dwResult.
  • Si un complemento de interfaz de usuario admite la funcionalidad, su método de IPrintOemUI::DeviceCapabilities 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 método IPrintOemUI::DeviceCapabilities 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 que se establecen en dwOldy devuelven el resultado de la operación OR en dwResult.
  • Se deben seguir las reglas anteriores incluso si se GDI_ERROR el contenido recibido de dwOld.
Cuando se llama a la función DrvDeviceCap abilities del controlador con la marca DC_FIELDS establecida, la función llama a todos los métodos IPrintOemUI::DeviceCapabilities, especificando también DC_FIELDS y devuelve la unión de todos los bits establecidos al autor de la llamada.

El S_DEVCAP_OUTPUT_FULL_REPLACEMENT valor devuelto es nuevo en Windows Vista y se aplica a los complementos de interfaz de usuario Unidrv y Pscript5. Un complemento debe usar el S_DEVCAP_OUTPUT_FULL_REPLACEMENT valor devuelto solo si requiere 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 un valor en la estructura de DEVMODEW (que apunta el pPublicDM y parámetros pOEMDM) indica al complemento de 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 la pOutput y dwOld parámetros, 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 al número de tipos de papel a los que el complemento pretende notificar.

Cuando varios complementos de interfaz de usuario están 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 significar que los complementos pretenden proporcionar datos de salida de reemplazo completos. 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 especificado 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 de S_DEVCAP_OUTPUT_FULL_REPLACEMENT solo para las funcionalidades del dispositivo que usan el pOutput búfer, 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 Personalización de los controladores de impresora de Microsoft.

Requisitos

Requisito Valor
de la plataforma de destino de Escritorio
encabezado de prcomoem.h (include Prcomoem.h)

Consulte también

DrvDeviceCapabilities

IPrintOemUI