Contenedores de propiedades del controlador de impresora V4
Importante
La plataforma de impresión moderna es el medio preferido de Windows para comunicarse con impresoras. Se recomienda usar el controlador de clase de bandeja de entrada IPP de Microsoft, junto con aplicaciones de soporte técnico de impresión (PSA), para personalizar la experiencia de impresión en Windows 10 y 11 para el desarrollo de dispositivos de impresora.
Para obtener más información, consulte Plataforma de impresión moderna y la Guía de diseño de aplicaciones para compatibilidad con impresión.
El modelo del controlador de impresión v4 proporciona una serie de contenedores de propiedades que facilitan un flujo de datos de aplicaciones de interfaz de usuario personalizadas al proceso de representación.
Estos contenedores de propiedades permiten crear propiedades personalizadas y definiciones de características en una interfaz de usuario personalizada y, a continuación, consumirlas en el proceso de representación. Todos los contenedores de propiedades se exponen mediante la interfaz IPrinterScriptablePropertyBag en JavaScript o mediante la interfaz IPrinterPropertyBag en otros entornos.
En la tabla siguiente se proporciona información general sobre cómo usar distintos componentes para obtener el objeto de contenedor de propiedades de diferentes partes de un controlador de impresión v4.
| Componente | Descripción |
|---|---|
| Script de restricción de JavaScript | Los contenedores de propiedades de controlador y cola se pasan a scripts de restricción de JavaScript mediante el parámetro scriptContext. Este parámetro es de tipo IPrinterScriptContext y contiene elementos secundarios: DriverProperties: hace referencia al contenedor de propiedades del controlador. QueueProperties: hace referencia al contenedor de propiedades de cola. UserProperties: contenedor de propiedades de usuario. El contenedor de propiedades DEVMODE se pasa a los métodos de conversión DEVMODE <-> PrintTicket como parámetro devModeProperties (que es de tipo IPrinterScriptablePropertyBag). No está disponible en los otros métodos. |
| JavaScript bidi USB | Los contenedores de propiedades de controlador y cola se pasan a scripts JavaScript bidi USB mediante el parámetro scriptContext. Este parámetro es de tipo IPrinterScriptContext y contiene elementos secundarios: DriverProperties: hace referencia al contenedor de propiedades del controlador. QueueProperties: hace referencia al contenedor de propiedades de cola. |
| Aplicación de extensión de impresora | Todos los contenedores de propiedades se pasan como parte del parámetro IPrinterExtensionEventArgs al controlador OnDriverEvent. Todos son de tipo IPrinterPropertyBag. Se especifican como los siguientes: DriverProperties: hace referencia al contenedor de propiedades del controlador. UserProperties: contenedor de propiedades de usuario. PrinterQueue.GetProperties(): hace referencia al contenedor de propiedades de cola. |
| Aplicación de dispositivo para UWP | Todos los contenedores de propiedades se pasan durante la activación mediante el objeto IPrinterExtensionContext. Se especifican como: DriverProperties: hace referencia al contenedor de propiedades del controlador. UserProperties: contenedor de propiedades de usuario. PrinterQueue.GetProperties(): hace referencia al contenedor de propiedades de cola. |
| Filtro de representación de XPS | Los filtros XPS pueden tener acceso al contenedor de propiedades del controlador desde el contenedor de propiedades de canalización de filtro de impresión mediante el nombre de propiedad "DriverPropertyBag" o el valor definido XPS_FP_PROPERTY_BAG desde filterpipeline.h. Esta es la información sobre DriverPropertyBag: Tipo de propiedad: VT_UNKNOWN Descripción: Puntero a una interfaz IUnknown. Llama a QueryInterface para obtener un puntero a la interfaz IPrinterPropertyBag al contenedor de propiedades del controlador. Los filtros XPS pueden tener acceso al contenedor de propiedades de cola desde el contenedor de propiedades de canalización de filtro de impresión mediante el nombre de propiedad "QueuePropertyBag" o el valor definido XPS_FP_QUEUE_PROPERTY_BAG desde filterpipeline.h. Esta es la información sobre QueuePropertyBag: Tipo de propiedad: VT_UNKNOWN Descripción: Puntero a una interfaz IUnknown. Llama a QueryInterface para obtener un puntero a la interfaz IPrinterPropertyBag al contenedor de propiedades de cola. |
En las implementaciones de JavaScript, los contenedores de propiedades se pasan como parámetros. En las aplicaciones de extensión de impresora, los contenedores de propiedades se pasan como miembros del argumento de evento que se usa para iniciar la aplicación.
Los descriptores de acceso del contenedor de propiedades proporcionados por las interfaces COM IPrinterQueue, IPrinterExtensionContext e IPrinterExtensionEventArgs, así como los descriptores de acceso del contenedor de propiedades en las implementaciones de Javascript producirán una excepción si no se especifica o no se encuentra el contenedor de propiedades. Además, la consulta de propiedades individuales en una interfaz IPrinterPropertyBag producirá excepciones si no se encuentra la propiedad. Debe usar una instrucción try catch para evitar bloqueos si una propiedad no está disponible.
Contenedor de propiedades del controlador
El contenedor de propiedades del controlador es un almacén de datos para que los controladores definan propiedades predefinidas o blobs de datos para el uso de solo lectura por parte del controlador. Se puede especificar mediante la directiva "PropertyBag" en el archivo de manifiesto v4 y es posible que no se modifique en tiempo de ejecución.
El Kit para controladores de Windows incluye un proyecto de plantilla para un contenedor de propiedades de controlador. El contenedor de propiedades del controlador es un blob binario compilado. Visual Studio incluye una plantilla para generar un contenedor de propiedades de controlador compilado. El archivo XML generado para esta plantilla no es el contenedor de propiedades, sino que la salida compilada de esta plantilla es el archivo de contenedor de propiedades que se debe especificar en el archivo de manifiesto v4.
Contenedor de propiedades de usuario
El contenedor de propiedades de usuario permite a los partners almacenar la configuración en un contexto local por usuario y equipo. Este contenedor de propiedades es adecuado como un mecanismo de almacenamiento para preferencias de usuario como "No volver a mostrar esto". Los administradores no pueden administrar este contenedor de propiedades y no se sincronizan entre el cliente y el servidor durante el uso compartido de impresoras. El contenedor de propiedades de usuario solo se establece en tiempo de ejecución y solo está disponible para las extensiones de impresora, las aplicaciones de dispositivo para UWP y las restricciones de JavaScript.
Dado que las restricciones de JavaScript también se pueden llamar fuera de un contexto de usuario, durante la agrupación, el contenedor de propiedades de usuario no está disponible en este momento y Windows devolverá HRESULT_FROM_WIN32(ERROR_NOT_FOUND).
Contenedor de propiedades DEVMODE
El contenedor de propiedades DEVMODE se usa para organizar el contenido en la sección privada de la estructura DEVMODE. Durante las llamadas a ConvertPrintTicketToDevMode, se invoca JavaScript para rellenar el contenido del contenedor de propiedades DEVMODE. Durante las llamadas a ConvertDevModeToPrintTicket, se invoca JavaScript para leer la configuración persistente del contenedor de propiedades DEVMODE y almacenarlos de nuevo en PrintTicket.
Este contenedor de propiedades está limitado a menos de 60 KB (la cantidad exacta variará en función del tamaño de las secciones asignadas del DEVMODE), ya que debe serializarse en una estructura DEVMODE para evitar la pérdida de datos en algunos escenarios. El tamaño exacto disponible variará por controlador porque viene determinado por el tamaño de la sección pública del DEVMODE más la sección privada administrada por el módulo de configuración.
El contenedor de propiedades DEVMODE usa un archivo XML para especificar los miembros del contenedor de propiedades y usa las API convertPrintTicketToDevMode y convertDevModeToPrintTicket para controlar las conversiones. El archivo de asignación DEVMODE XML debe especificarse en el manifiesto v4 mediante la directiva DevModeMap.
El siguiente fragmento de código muestra un ejemplo XML de asignación de contenedor de propiedades DEVMODE.
<?xml version="1.0" encoding="utf-8"?>
<Properties xmlns="https://schemas.microsoft.com/windows/2011/08/printing/devmodemap">
<Property Name="FabrikamAccountCode">
<String Length="32"></String>
</Property>
</Properties>
En la captura de pantalla siguiente se muestra el esquema XML de asignación de contenedor de propiedades DEVMODE y se puede encontrar en la siguiente ruta de acceso de la carpeta de instalación de WDK: \Include\mmm\printerdriverdevmodemap.xsd.pr
La herramienta INFGate valida los archivos XML para la asignación del contenedor de propiedades DEVMODE.
Contenedor de propiedades de cola
El contenedor de propiedades de cola almacena las opciones de configuración por cola, incluidas las asignaciones de formulario a bandeja y la configuración de propiedades de impresora, como las opciones instalables. Las propiedades definidas por el controlador y las propiedades de impresora se pueden configurar en PowerShell, mientras que las asignaciones de formulario a bandeja se pueden configurar en la interfaz de usuario de las propiedades de la impresora. Las extensiones de impresora no pueden editar ninguno de los valores de propiedad.
El contenedor de propiedades de cola se crea automáticamente para muchos controladores de impresión v4, pero los controladores también pueden proporcionar propiedades adicionales para configurar mediante un archivo XML. Este archivo XML no se debe compilar mediante la herramienta contenedor de propiedades del controlador. Los contenedores de propiedades de cola están disponibles para impresoras compatibles con los controladores de impresión v4 que realizan cualquiera de las siguientes acciones:
Especificar varias bandejas o
Especificar opciones instalables en el archivo GPD o PPD, o
Especificar un contenedor de propiedades de cola en el manifiesto del controlador mediante la directiva QueueProperties.
Los administradores configuran contenedores de propiedades de cola mediante PowerShell. Los siguientes command-lets (cmdlets) son elementos secundarios de un objeto de impresora, que se pueden obtener mediante el cmdlet Get-Printer.
| Nombre del cmdlet | Descripción |
|---|---|
| Get-PrinterProperty -printerName <printerName> -name <propertyName*> | Recupera una o varias propiedades (-name admite globbing). |
| Set-PrinterProperty -inputObject <printerPropertyObject> | Cambia una propiedad de cola de impresión mediante un printerPropertyObject persistente. |
| Set-PrinterProperty -printerName <printerName> -PropertyName <propertyName> -Value <value> | Cambia la propiedad especificada al valor especificado. |
Opciones instalables
Estas opciones, por ejemplo, el estado de una unidad dúplex, se mostrarán en el contenedor de propiedades de cola como propiedades individuales. Cada propiedad se denominará como se indica a continuación, donde el nombre de la característica se basa en el nombre de la característica del archivo GPD o PPD del controlador:
Config:<feature name>
Por ejemplo: Config:DuplexUnit
El valor de la propiedad es el nombre de palabra clave de la opción seleccionada por el administrador. Por ejemplo, Instalado. Las opciones instalables se pueden editar mediante el mismo cmdlet Set-PrinterProperty que se usa para las propiedades de la cola.
A partir de Windows 8.1, un usuario con derechos de administrador o un usuario que creó una cola de impresión puede cambiar las opciones instalables y las opciones de configuración por cola para un contenedor de propiedades de cola desde una aplicación de dispositivo para UWP.
Asignaciones de formulario a bandeja
Para las impresoras con un controlador de impresión v4 y con más de una bandeja, las asignaciones de "formulario a bandeja" se exponen a través del contenedor de propiedades de cola en la propiedad denominada "FormTrayTable".
Esta propiedad tiene el formato de una cadena terminada en NULL que contiene pares del formato <tray name>, <form name>, donde el nombre del formulario es uno de los siguientes:
Si el tamaño del papel se asigna al esquema de impresión en el archivo GPD o PPD (ya sea mediante las palabras clave *PaperSize/*PageSize o *(MS)PrintSchemaKeywordMap), el nombre del formulario seguirá el siguiente formato:
PrintSchema:<Paper Size name>Por ejemplo:
PrintSchema:NorthAmericaLetterSi el formulario es un formulario definido por el usuario, determinado por la marca FORM_USER, el nombre del formulario será el siguiente. El índice del formulario es el mismo valor que se usa en la base de datos de formularios del administrador. Esto es coherente con el índice utilizado cuando se especifica el tamaño del papel en PrintTicket de la siguiente manera:
UserForm<form index>Por ejemplo:
UserForm123De lo contrario, el nombre del formulario seguirá el siguiente formato, donde el nombre del formulario es el nombre especificado en el *PaperSize de GPD o el *PageSize del PPD.
Config:<name>Por ejemplo:
Config:_8_5x16
Una cadena de ejemplo completa sería así:
Config:Tray1,PrintSchema:NorthAmericaLetter,Config:Tray2,Config:_8_5X16,Config:Manual,UserForm123,\0
Los filtros de representación deben leer la configuración PageMediaSize de PrintTicket entrante y buscar ese valor en los valores de nombre del formulario de FormTrayTable.
Ejemplo XML de contenedor de propiedades de cola
El siguiente fragmento de código muestra la sintaxis XML que se podría usar para tres propiedades, Name1, Name2, Name3 y sus elementos secundarios:
<?xml version="1.0" encoding="utf-8"?>
<Properties xmlns= "https://schemas.microsoft.com/windows/2011/08/printing/queueproperties">
<Property Name="Name1">
<String>String1</String>
</Property>
<Property Name="Name2">
<Int32>3244</Int32>
</Property>
<Property Name="Name3">
<Bool>true</Bool>
</Property>
</Properties>
Esquema XML del contenedor de propiedades de cola
En la captura de pantalla siguiente se muestra el esquema XML del contenedor de propiedades de cola y se puede encontrar en la siguiente ruta de acceso de la carpeta de instalación de WDK: \Include\um\printqueueproperties.xsd.
Temas relacionados
Contenedor de propiedades de canalización de filtro de impresión