Función DrvPrinterEvent (winddiui.h)

El administrador de trabajos de impresión llama a la función DrvPrinterEvent de una interfaz de impresora al procesar eventos específicos de la impresora que podrían requerir la acción del controlador de impresora.

Sintaxis

BOOL DrvPrinterEvent(
  [in] LPWSTR pPrinterName,
       int    DriverEvent,
       DWORD  Flags,
       LPARAM lParam
);

Parámetros

[in] pPrinterName

Puntero proporcionado por el autor de la llamada a una cadena de nombre de impresora terminada en NULL. El formato de cadena puede ser \Machine\PrinterName para especificar una impresora remota o PrinterName para especificar una impresora local.

DriverEvent

Código de evento proporcionado por el autor de la llamada que identifica el evento. Se definen los siguientes códigos de evento:

Código de evento	Definición
PRINTER_EVENT_ADD_CONNECTION	El administrador de colas acaba de procesar una llamada a su función AddPrinterConnection , lo que permite a un usuario cliente conectarse a una impresora remota creada anteriormente.
PRINTER_EVENT_ATTRIBUTES_CHANGED	Los bits de atributo de una impresora han cambiado. En respuesta a la llamada de una aplicación a la función SetPrinter , el administrador de trabajos llama a la función DrvPrinterEvent del controlador de impresora, pasando el código de evento en la llamada. Cuando se usa este código de evento, el parámetro lParam apunta a una estructura de PRINTER_EVENT_ATTRIBUTES_INFO que describe los atributos antiguos y nuevos.
PRINTER_EVENT_CACHE_DELETE	El administrador de colas elimina la memoria caché de archivos del cliente.
PRINTER_EVENT_CACHE_REFRESH	El administrador de trabajos está actualizando los archivos almacenados en caché del cliente.
PRINTER_EVENT_CONFIGURATION_CHANGE	Reservado.
PRINTER_EVENT_CONFIGURATION_UPDATE	La configuración de la impresora ha cambiado. Cuando se usa este código de evento, el parámetro lParam apunta a una cadena Unicode que contiene una notificación con formato según el esquema de notificación bidi.
PRINTER_EVENT_DELETE_CONNECTION	El administrador de colas acaba de terminar de procesar una llamada a su función DeletePrinterConnection , lo que permite a un usuario cliente quitar una conexión de impresora.
PRINTER_EVENT_DELETE	El administrador acaba de procesar una llamada a su función DeletePrinter , lo que permite a un administrador eliminar una instancia de impresora.
PRINTER_EVENT_INITIALIZE	El administrador acaba de terminar de procesar una llamada a su función AddPrinter , lo que permite a un administrador hacer que una impresora esté disponible en un servidor o su función SetPrinter , lo que permite a un administrador modificar el estado de una impresora. En una conexión de representación del lado cliente, el equipo cliente acaba de agregar la impresora GUID. El evento PRINTER_EVENT_INITIALIZE especifica un valor de parámetro lParam NULL para las llamadas a DrvPrinterEvent en Windows Vista y versiones anteriores. Para Windows 7 y versiones posteriores, el parámetro lParam es un identificador de token de usuario. Los controladores de impresión pueden usar el identificador de token devuelto para consultar datos de usuario o suplantar al usuario.

Flags

Marca de bits proporcionada por el autor de la llamada, definida de la siguiente manera:

Value

Definición

PRINTER_EVENT_FLAG_NO_UI

Si se establece, la función no debe mostrar una interfaz de usuario. Durante la instalación de un procesador de impresión, un monitor de impresión o un controlador de impresora, la única manera en que se permite una interfaz de usuario es mediante el uso de la directiva VendorSetup . Consulte Entradas de archivo INF de impresora y Operaciones de configuración de impresora personalizadas para obtener más información.

Precaución

La directiva VendorSetup está en desuso y no debe usarse en ningún nuevo controlador v3 o v4 que desarrolle. Esta información sobre VendorSetup solo se proporciona como referencia o para el mantenimiento de los controladores v3 existentes que ya usan esta directiva INF.

lParam

No se usa a menos que el parámetro DriverEvent esté establecido en PRINTER_EVENT_ATTRIBUTES_CHANGED. En este caso, lParam contiene la dirección de una estructura de PRINTER_EVENT_ATTRIBUTES_INFO. (Vea la descripción anterior del parámetro DriverEvent ). Para todos los demás valores del parámetro DriverEvent , el parámetro lParam es NULL.

Valor devuelto

Si la operación se realiza correctamente, la función debe devolver TRUE; de lo contrario, debe devolver FALSE. Sin embargo, actualmente, la única vez que se comprueba el valor devuelto de la función es cuando el administrador de colas ha llamado a DrvPrinterEvent durante el procesamiento de la función AddPrinter , con DriverEvent establecido en PRINTER_EVENT_INITIALIZE. Si DrvPrinterEvent devuelve FALSE en este caso, el administrador de colas no crea la impresora y, en su lugar, hace que AddPrinter produzca un error.

Comentarios

Todos los archivos DLL de interfaz de impresora deben proporcionar una función DrvPrinterEvent y la función debe admitir el código de evento PRINTER_EVENT_INITIALIZE. La compatibilidad con todos los demás códigos de evento es opcional.

La configuración del Registro almacenada al controlar un evento de PRINTER_EVENT_INITIALIZE debe almacenarse en la clave HKEY_LOCAL_MACHINE mediante una llamada a SetPrinterData. En el caso de los códigos de evento PRINTER_EVENT_INITIALIZE y PRINTER_EVENT_DELETE, el administrador de colas comprueba que el autor de la llamada tiene privilegios administrativos y llama a DrvPrinterEvent mientras suplanta al autor de la llamada.

Por el contrario, si necesita almacenar la configuración en el Registro al controlar un evento de PRINTER_EVENT_ADD_CONNECTION, el archivo DLL de la interfaz de impresora debe escribirlos en la clave HKEY_CURRENT_USER para que se almacenen por usuario. A continuación, si un usuario con un perfil móvil inicia sesión en otro sistema, la conexión sigue al usuario. Solo se llama a la función DrvPrinterEvent cuando el usuario realiza la conexión por primera vez y no cuando el usuario inicia sesión posteriormente en otros sistemas mediante el perfil móvil.

En el caso de los códigos de evento PRINTER_EVENT_ADD_CONNECTION y PRINTER_EVENT_DELETE_CONNECTION, el contexto de ejecución de la función DrvPrinterEvent es la aplicación que realiza la llamada (normalmente la carpeta de impresión) y la función puede mostrar una interfaz de usuario. Para todos los demás códigos de evento, el contexto de ejecución es el administrador de trabajos de impresión y no se puede mostrar una interfaz de usuario.

Un ejemplo de un controlador que podría mostrar una interfaz de usuario cuando se realiza una conexión es un controlador fax, que podría pedir al usuario el nombre y el número de teléfono del usuario (remitente del FAX) y guardar la información hasta que se elimine la conexión.

Un ejemplo del tipo de archivo que se puede almacenar en una memoria caché de cliente es un archivo de métricas de fuente grande que contiene demasiada información que se va a escribir en el registro. Cuando se PRINTER_EVENT_CACHE_REFRESH el código de evento de la función DrvPrinterEvent , el archivo DLL de la interfaz de impresora puede volver a cargar el archivo desde el servidor para asegurarse de que la memoria caché está actualizada.

Requisitos

Requisito	Value
Plataforma de destino	Escritorio
Encabezado	winddiui.h (incluya Winddiui.h)