DrvPrinterEvent-Funktion (winddiui.h)

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

Syntax

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

Parameter

[in] pPrinterName

Vom Aufrufer bereitgestellter Zeiger auf eine MIT NULL beendete 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 an seine AddPrinterConnection--Funktion abgeschlossen, wodurch ein Clientbenutzer eine Verbindung mit einem zuvor erstellten Remotedrucker herstellen kann.
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 Pooler den 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 die 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 an seine DeletePrinterConnection--Funktion abgeschlossen, wodurch ein Clientbenutzer eine Druckerverbindung entfernen kann.
PRINTER_EVENT_DELETE	Der Spooler hat gerade die Verarbeitung eines Aufrufs seiner DeletePrinter--Funktion abgeschlossen, wodurch ein Administrator eine Druckerinstanz löschen kann.
PRINTER_EVENT_INITIALIZE	Der Spooler hat gerade die Verarbeitung eines Aufrufs an seine AddPrinter--Funktion abgeschlossen, wodurch ein Administrator einen Drucker auf einem Server verfügbar machen kann, oder seine SetPrinter--Funktion, mit der ein Administrator den Zustand eines Druckers ändern kann. In einer clientseitigen Renderingverbindung hat der Clientcomputer soeben den GUID-Drucker hinzugefügt. Das PRINTER_EVENT_INITIALIZE-Ereignis gibt einen NULL lParam-Parameterwert für DrvPrinterEvent- Aufrufe von 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 den Benutzer zu imitieren.

Flags

Vom Aufrufer bereitgestelltes Bit-Flag, das wie folgt definiert ist:

Wert	Definition
PRINTER_EVENT_FLAG_NO_UI	Wenn festgelegt, darf die Funktion keine Benutzeroberfläche anzeigen. Bei der Installation eines Druckprozessors, eines Druckmonitors oder eines Druckertreibers ist die einzige Möglichkeit, wie eine Benutzeroberfläche zulässig ist, durch die Verwendung der VendorSetup Richtlinie. Weitere Informationen finden Sie unter Drucker-INF-Dateieinträge und Benutzerdefinierte Druckereinrichtungsvorgänge.

Vorsicht

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

lParam

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

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 DrvPrinterEvent- während der Verarbeitung der AddPrinter--Funktion 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.

Bemerkungen

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, dass der Aufrufer über Administratorrechte verfügt und DrvPrinterEvent- aufruft, während der Identität des Aufrufers.

Wenn Sie beim Behandeln eines PRINTER_EVENT_ADD_CONNECTION Ereignisses Einstellungen in der Registrierung speichern müssen, sollte die Druckerschnittstellen-DLL diese unter dem HKEY_CURRENT_USER-Schlüssel schreiben, sodass sie pro Benutzer 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 erstellt, und nicht, wenn sich der Benutzer anschließend mithilfe des Roamingprofils bei anderen Systemen anmeldet.

Für die ereigniscodes PRINTER_EVENT_ADD_CONNECTION und PRINTER_EVENT_DELETE_CONNECTION 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 eine Benutzeroberfläche anzeigen kann, wenn eine Verbindung hergestellt wird, ist ein FAXtreiber, der den Benutzer zur Eingabe des Namens und der Telefonnummer des Benutzers (FAX-Absender) auffordert und die Informationen speichert, bis die Verbindung gelöscht wird.

Ein Beispiel für den Dateityp, der in einem Clientcache gespeichert werden kann, ist eine große Datei mit Schriftartmetriken, die zu viele Informationen enthält, die in die Registrierung geschrieben werden müssen. 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
Header-	winddiui.h (include Winddiui.h)