Bolsas de propiedades del controlador de impresora V4

Artículo
03/08/2023

Importante

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 la guía de diseño de aplicaciones de soporte técnico de impresión.

El modelo de controlador de impresión v4 proporciona una serie de bolsas de propiedades que facilitan un flujo de datos de las 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, ser consumidas por el proceso de representación. Todas las bolsas 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.
USB Bidi JavaScript	Los contenedores de propiedades de controlador y cola se pasan a scripts de JavaScript de USB Bidi 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	Todas las bolsas 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 UWP	Todas las bolsas 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 XPS	Los filtros XPS pueden acceder 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. Llame a QueryInterface para obtener un puntero a la interfaz IPrinterPropertyBag al contenedor de propiedades del controlador. Y los filtros XPS pueden acceder 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. Llame 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 usado 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 de 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 predefinan propiedades 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 no se puede modificar en tiempo de ejecución.

El Kit de 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 asociados almacenar la configuración en un contexto local de equipo por usuario. Este contenedor de propiedades es adecuado como mecanismo de almacenamiento para las preferencias del 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, ya que 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 XML DEVMODE 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\um\printerdriverdevmodemap.xsd.pr

esquema xml de asignación de contenedor de propiedades devmode.

La herramienta INFGate valida los archivos XML para la asignación del contenedor de propiedades DEVMODE.

Contenedor de propiedades queue

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 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 con la herramienta de contenedor de propiedades del controlador. Los contenedores de propiedades de cola están disponibles para las impresoras compatibles con los controladores de impresión v4 que realizan una de las siguientes acciones:

Especificar varias bandejas, OR
Especificar opciones instalables en el archivo GPD o PPD, OR
Especifique un contenedor de propiedades de cola en el manifiesto del controlador mediante la directiva QueueProperties.

Los administradores configuran bolsas de propiedades de cola mediante PowerShell. Los siguientes comandos permiten (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 el uso global).
Set-PrinterProperty -inputObject <printerPropertyObject>	Cambia una propiedad de cola de impresión mediante una 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 un dúplex, se exponen en el contenedor de propiedades de la 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 con el mismo cmdlet de 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 de un contenedor de propiedades de cola desde una aplicación de dispositivo para UWP.

Asignaciones de formularios a bandejas

En el caso de 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 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 estándar o *(MS)PrintSchemaKeywordMap), el nombre del formulario seguirá el siguiente formato:

PrintSchema:<Paper Size name>

Por ejemplo: PrintSchema:NorthAmericaLetter
Si 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 de trabajos. Esto es coherente con el índice utilizado cuando el tamaño del papel se especifica en PrintTicket de la siguiente manera:

UserForm<form index>

Por ejemplo: UserForm123
De lo contrario, el nombre del formulario seguirá el formato siguiente, donde el nombre del formulario es el nombre que se especificó en el *PaperSize de GPD o en el *PageSize de PPD.

Config:<name>

Por ejemplo: Config:_8_5x16

Una cadena de ejemplo completa se leería de la siguiente manera:

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 del contenedor de propiedades de cola

En el fragmento de código siguiente se 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 en la carpeta de instalación de WDK: \Include\um\printqueueproperties.xsd.

Esquema xml del contenedor de propiedades de cola.