DrvPrinterEvent-Funktion (winddiui.h)

Artikel
02/27/2024

Die DrvPrinterEvent-Funktion einer Druckerschnittstellen-DLL wird vom Druckspooler aufgerufen, wenn druckerspezifische Ereignisse verarbeitet werden, die möglicherweise eine Aktion des Druckertreibers erfordern.

Syntax

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

Parameter

[in] pPrinterName

Vom Aufrufer bereitgestellter Zeiger auf eine MIT NULL endende Druckernamenzeichenfolge. Das Zeichenfolgenformat kann \Machine\PrinterName sein, um einen Remotedrucker anzugeben, oder PrinterName , um einen lokalen Drucker anzugeben.

DriverEvent

Vom Aufrufer bereitgestellter Ereigniscode, der das Ereignis identifiziert. Die folgenden Ereigniscodes sind definiert:

Ereigniscode	Definition
PRINTER_EVENT_ADD_CONNECTION	Der Spooler hat gerade die Verarbeitung eines Aufrufs seiner AddPrinterConnection-Funktion abgeschlossen, die es einem Clientbenutzer ermöglicht, eine Verbindung mit einem zuvor erstellten Remotedrucker herzustellen.
PRINTER_EVENT_ATTRIBUTES_CHANGED	Die Attributbits für einen Drucker wurden geändert. Als Reaktion auf den Aufruf einer Anwendung an die SetPrinter-Funktion ruft der Spooler die DrvPrinterEvent-Funktion des Druckertreibers auf und übergibt den Ereigniscode im Aufruf. Wenn dieser Ereigniscode verwendet wird, verweist der lParam-Parameter auf eine PRINTER_EVENT_ATTRIBUTES_INFO-Struktur , die die alten und neuen Attribute beschreibt.
PRINTER_EVENT_CACHE_DELETE	Der Spooler löscht den Dateicache des Clients.
PRINTER_EVENT_CACHE_REFRESH	Der Spooler aktualisiert die zwischengespeicherten Dateien des Clients.
PRINTER_EVENT_CONFIGURATION_CHANGE	Reserviert.
PRINTER_EVENT_CONFIGURATION_UPDATE	Die Druckerkonfiguration wurde geändert. Wenn dieser Ereigniscode verwendet wird, verweist der lParam-Parameter auf eine Unicode-Zeichenfolge, die eine Benachrichtigung enthält, die gemäß dem Bidi-Benachrichtigungsschema formatiert ist.
PRINTER_EVENT_DELETE_CONNECTION	Der Spooler hat gerade die Verarbeitung eines Aufrufs seiner DeletePrinterConnection-Funktion abgeschlossen, die es einem Clientbenutzer ermöglicht, eine Druckerverbindung zu entfernen.
PRINTER_EVENT_DELETE	Der Spooler hat gerade die Verarbeitung eines Aufrufs seiner DeletePrinter-Funktion abgeschlossen, die es einem Administrator ermöglicht, einen Drucker instance zu löschen.
PRINTER_EVENT_INITIALIZE	Der Spooler hat gerade die Verarbeitung eines Aufrufs seiner AddPrinter-Funktion abgeschlossen, die es einem Administrator ermöglicht, einen Drucker auf einem Server verfügbar zu machen, oder seine SetPrinter-Funktion , die es einem Administrator ermöglicht, den Zustand eines Druckers zu ändern. In einer clientseitigen Renderingverbindung hat der Clientcomputer gerade den GUID-Drucker hinzugefügt. Das PRINTER_EVENT_INITIALIZE-Ereignis gibt einen NULL lParam-Parameterwert für DrvPrinterEvent-Aufrufe unter Windows Vista und früheren Versionen an. Für Windows 7 und höhere Versionen ist der lParam-Parameter ein Benutzertokenhandle. Die Drucktreiber können das zurückgegebene Tokenhandle verwenden, um Benutzerdaten abzufragen oder die Identität des Benutzers zu annehmen.

Flags

Vom Aufrufer bereitgestelltes Bitflag, das wie folgt definiert ist:

Wert	Definition
PRINTER_EVENT_FLAG_NO_UI	Wenn festgelegt, darf die Funktion keine Benutzeroberfläche anzeigen. Während der Installation eines Druckprozessors, Druckermonitors oder Druckertreibers ist eine Benutzeroberfläche nur durch die Verwendung der VendorSetup-Direktive zulässig. Weitere Informationen finden Sie unter Drucker-INF-Dateieinträge und benutzerdefinierte Druckereinrichtungsvorgänge .

Achtung

Die VendorSetup-Direktive ist veraltet und sollte nicht von neuen v3- oder v4-Treibern verwendet werden, die Sie entwickeln. Diese Informationen zu VendorSetup dienen nur zur Referenz oder zur Wartung vorhandener v3-Treiber, die diese INF-Direktive bereits verwenden.

lParam

Wird nur verwendet, wenn der DriverEvent-Parameter auf PRINTER_EVENT_ATTRIBUTES_CHANGED festgelegt ist. In diesem Fall enthält lParam die Adresse einer PRINTER_EVENT_ATTRIBUTES_INFO-Struktur. (Siehe die vorherige Beschreibung des DriverEvent-Parameters .) Für alle anderen Werte des DriverEvent-Parameters ist der lParam-ParameterNULL.

Rückgabewert

Wenn der Vorgang erfolgreich ist, sollte die Funktion TRUE zurückgeben. Andernfalls sollte false zurückgegeben werden. Derzeit wird der Rückgabewert der Funktion jedoch nur überprüft, wenn der Spooler während der Verarbeitung der AddPrinter-FunktionDrvPrinterEvent aufgerufen hat, wobei DriverEvent auf PRINTER_EVENT_INITIALIZE festgelegt ist. Wenn DrvPrinterEvent in diesem Fall FALSE zurückgibt, erstellt der Spooler den Drucker nicht und führt stattdessen dazu , dass AddPrinter fehlschlägt.

Hinweise

Alle Druckerschnittstellen-DLLs müssen eine DrvPrinterEvent-Funktion bereitstellen, und die Funktion muss den PRINTER_EVENT_INITIALIZE Ereigniscode unterstützen. Die Unterstützung für alle anderen Ereigniscodes ist optional.

Registrierungseinstellungen, die beim Behandeln eines PRINTER_EVENT_INITIALIZE-Ereignisses gespeichert werden, sollten unter dem HKEY_LOCAL_MACHINE Schlüssel gespeichert werden, indem SetPrinterData aufgerufen wird. Für die ereigniscodes PRINTER_EVENT_INITIALIZE und PRINTER_EVENT_DELETE überprüft der Spooler, ob der Aufrufer über Administratorrechte verfügt, und ruft DrvPrinterEvent auf, während er die Identität des Aufrufers angibt.

Wenn Sie bei der Behandlung eines PRINTER_EVENT_ADD_CONNECTION-Ereignisses Einstellungen in der Registrierung speichern müssen, sollte die Druckerschnittstellen-DLL diese dagegen unter dem HKEY_CURRENT_USER Schlüssel schreiben, sodass sie auf Benutzerbasis gespeichert werden. Wenn sich dann ein Benutzer mit einem Roamingprofil bei einem anderen System anmeldet, folgt die Verbindung dem Benutzer. Die DrvPrinterEvent-Funktion wird nur aufgerufen, wenn der Benutzer die Verbindung zum ersten Mal herstellt, und nicht, wenn sich der Benutzer anschließend mit dem Roamingprofil bei anderen Systemen anmeldet.

Für die PRINTER_EVENT_ADD_CONNECTION und PRINTER_EVENT_DELETE_CONNECTION Ereigniscodes ist der Ausführungskontext der DrvPrinterEvent-Funktion die aufrufende Anwendung (normalerweise der Druckordner), und die Funktion kann eine Benutzeroberfläche anzeigen. Bei allen anderen Ereigniscodes ist der Ausführungskontext der Druckspooler, und eine Benutzeroberfläche kann nicht angezeigt werden.

Ein Beispiel für einen Treiber, der möglicherweise eine Benutzeroberfläche anzeigt, wenn eine Verbindung hergestellt wird, ist ein FAX-Treiber, der den Benutzer zur Eingabe des Namens und der Telefonnummer des Benutzers (FAX-Absender) auffordern und die Informationen speichern kann, bis die Verbindung gelöscht wird.

Ein Beispiel für den Dateityp, der in einem Clientcache gespeichert werden kann, ist eine große Schriftartmetrikdatei, die zu viele Informationen enthält, um in die Registrierung geschrieben zu werden. Wenn der Ereigniscode der DrvPrinterEvent-Funktion PRINTER_EVENT_CACHE_REFRESH ist, kann die Druckerschnittstellen-DLL die Datei vom Server neu laden, um sicherzustellen, dass der Cache auf dem neuesten Stand ist.

Anforderungen

Anforderung	Wert
Zielplattform	Desktop
Kopfzeile	winddiui.h (einschließlich Winddiui.h)