SetPrinterDataEx-Funktion

Die SetPrinterDataEx-Funktion legt die Konfigurationsdaten für einen Drucker oder Druckerserver fest. Die Funktion speichert die Konfigurationsdaten unter dem Registrierungsschlüssel des Druckers.

Syntax

DWORD SetPrinterDataEx(
  _In_ HANDLE  hPrinter,
  _In_ LPCTSTR pKeyName,
  _In_ LPCTSTR pValueName,
  _In_ DWORD   Type,
  _In_ LPBYTE  pData,
  _In_ DWORD   cbData
);

Parameter

hPrinter [ In]

Ein Handle für den Drucker oder Druckerserver, für den die Funktion Konfigurationsdaten fest legt. Verwenden Sie die OpenPrinter-, OpenPrinter2-oder AddPrinter-Funktion, um ein Druckerhand handle abzurufen.

pKeyName [ In]

Ein Zeiger auf eine auf NULL beendete Zeichenfolge, die den Schlüssel angibt, der den festgelegten Wert enthält. Wenn der angegebene Schlüssel oder die angegebenen Unterschlüssel nicht vorhanden sind, erstellt die Funktion sie.

Um Konfigurationsdaten zu speichern, die im Verzeichnisdienst (DS) veröffentlicht werden können, geben Sie einen der folgenden vordefinierten Registrierungsschlüssel an.

Wert Bedeutung
SPLDS_DRIVER_KEY
Druckertreiber verwenden diesen Schlüssel, um Treibereigenschaften zu speichern.
SPLDS_SPOOLER_KEY
Reserviert. Wird nur vom Druckspooler zum Speichern interner Spoolereigenschaften verwendet.
SPLDS_USER_KEY
Anwendungen verwenden diesen Schlüssel zum Speichern von Druckereigenschaften, z. B. Drucker-Ressourcennummern.

Werte, die unter dem SPLDS_USER_KEY gespeichert werden, werden im Verzeichnisdienst nur veröffentlicht, wenn eine entsprechende Eigenschaft im Schema vorhanden ist. Ein Domänenadministrator muss die Eigenschaft erstellen, wenn sie noch nicht vorhanden ist. Um eine benutzerdefinierte Eigenschaft zu veröffentlichen, nachdem Sie SetPrinterDataEx zum Hinzufügen oder Ändern eines Werts verwendet haben, rufen Sie SetPrinter mit Level = 7 und mit dem dwAction-Member von PRINTER_INFO_7 auf DSPRINT_UPDATE.

Sie können andere Schlüssel angeben, um Nicht-DS-Konfigurationsdaten zu speichern. Verwenden Sie den schrägen Schrägstrich () als Trennzeichen, um einen Pfad anzugeben, der einen oder \ mehrere Unterschlüssel hat.

Wenn hPrinter ein Handle für einen Drucker und pKeyName NULL oder eine leere Zeichenfolge ist, gibt SetPrinterDataEx ERROR_INVALID_PARAMETER.

Wenn hPrinter ein Handle für einen Druckserver ist, wird pKeyName ignoriert.

Verwenden Sie nicht SPLDS_SPOOLER_KEY. Um die Eigenschaften des Spoolerdruckers zu ändern, verwenden Sie SetPrinter mit Ebene = 2.

pValueName [ In]

Ein Zeiger auf eine mit NULL beendete Zeichenfolge, die die zu setzenden Daten identifiziert.

Bei Druckern gibt diese Zeichenfolge den Namen eines Werts unter dem Schlüssel pKeyName an.

Bei Druckservern ist diese Zeichenfolge eine der vordefinierten Zeichenfolgen, die im folgenden Abschnitt "Hinweise" aufgeführt sind.

Typ [ In]

Ein Code, der den Datentyp angibt, auf den der pData-Parameter zeigt. Eine Liste der möglichen Typcodes finden Sie unter Registrierungswerttypen.

Wenn pKeyName einen der vordefinierten Verzeichnisdienstschlüssel angibt, muss Type REG_SZ , REG_MULTI_SZ, REG_DWORD oder REG_BINARY. Wenn REG_BINARY verwendet wird, muss cbData gleich 1 sein, und der Verzeichnisdienst behandelt die Daten als booleschen Wert.

pData [ In]

Ein Zeiger auf einen Puffer, der die Druckerkonfigurationsdaten enthält.

cbData [ In]

Die Größe des Arrays in Bytes.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS.

Wenn die Funktion fehlschlägt, ist der Rückgabewert ein Fehlerwert.

Hinweise

Hinweis

Dies ist eine blockierende oder synchrone Funktion, die möglicherweise nicht sofort zurückkehrt. Wie schnell diese Funktion zurückgegeben wird, hängt von Laufzeitfaktoren wie Netzwerkstatus, Druckerserverkonfiguration und Implementierungsfaktoren des Druckertreibers ab, die beim Schreiben einer Anwendung schwer vorherzusagen sind. Das Aufrufen dieser Funktion aus einem Thread, der die Interaktion mit der Benutzeroberfläche verwaltet, könnte dazu kommen, dass die Anwendung nicht reagiert.

Rufen Sie die GetPrinterDataEx-Funktion auf, um vorhandene Konfigurationsdaten für einen Drucker oder Druckspooler abzurufen.

Das Aufrufen von SetPrinterDataEx mit dem Parameter pKeyName, der auf "PrinterDriverData" festgelegt ist, entspricht dem Aufrufen der SetPrinterData-Funktion.

Wenn hPrinter ein Handle für einen Druckserver ist, kann pValueName einen der folgenden vordefinierten Werte angeben.

Wert Kommentare
SPLREG_ALLOW_USER_MANAGEFORMS Windows XP mit Service Pack 2 (SP2) und höher
Windows Server 2003 mit Service Pack 1 (SP1) und höher
SPLREG_BEEP_ENABLED
SPLREG_DEFAULT_SPOOL_DIRECTORY
SPLREG_EVENT_LOG
SPLREG_NET_POPUP Nicht unterstützt in Windows Server 2003 und höher
SPLREG_PORT_THREAD_PRIORITY_DEFAULT
SPLREG_PORT_THREAD_PRIORITY
SPLREG_PRINT_DRIVER_ISOLATION_GROUPS Windows 7 und höher
SPLREG_PRINT_DRIVER_ISOLATION_TIME_BEFORE_RECYCLE Windows 7 und höher
SPLREG_PRINT_DRIVER_ISOLATION_MAX_OBJECTS_BEFORE_RECYCLE Windows 7 und höher
SPLREG_PRINT_DRIVER_ISOLATION_IDLE_TIMEOUT Windows 7 und höher
SPLREG_PRINT_DRIVER_ISOLATION_EXECUTION_POLICY Windows 7 und höher
SPLREG_PRINT_DRIVER_ISOLATION_OVERRIDE_POLICY Windows 7 und höher
SPLREG_RETRY_POPUP Bei erfolgreicher Rückgabe enthält pData 1, wenn der Server so festgelegt ist, dass popupfenster für alle Aufträge erneut ausgeführt werden, oder 0, wenn der Server nicht für alle Aufträge popupfenstert.
Nicht unterstützt in Windows Server 2003 und höher
SPLREG_SCHEDULER_THREAD_PRIORITY
SPLREG_SCHEDULER_THREAD_PRIORITY_DEFAULT
SPLREG_WEBSHAREMGMT Windows Server 2003 und höher

Durch die Übergabe eines der folgenden vordefinierten Werte als pValueName wird das Druckverhalten des Pools festgelegt, wenn ein Fehler auftritt.

Wert Kommentare
SPLREG_RESTART_JOB_ON_POOL_ERROR Der Wert von pData gibt die Zeit in Sekunden an, zu der ein Auftrag an einem anderen Port neu gestartet wird, nachdem ein Fehler aufgetreten ist. Diese Einstellung wird zusammen mit SPLREG_RESTART_JOB_ON_POOL_ENABLED.
SPLREG_RESTART_JOB_ON_POOL_ENABLED Ein Wert ungleich 0 (null) in pData gibt an, dass SPLREG_RESTART_JOB_ON_POOL_ERROR aktiviert ist.

Die in der SPLREG_RESTART_JOB_ON_POOL_ERROR ist eine Mindestzeit. Die tatsächliche Zeit kann je nach den folgenden Portüberwachungseinstellungen, bei denen es sich um Registrierungswerte unter diesem Registrierungsschlüssel handelt, länger dauern:

HKLM \ SYSTEM \ CurrentControlSet-SteuerelementDruckmonitore \ \ \ \ < MonitorName-Ports > \

Rufen Sie die RegSetValueEx-Funktion auf, um diese Werte zu festlegen.

Portüberwachungseinstellung Datentyp Bedeutung
StatusUpdateEnabled REG_DWORD Wenn ein Wert ungleich 0 (null) ist, kann der Portmonitor den Spooler mit dem Portstatus aktualisieren.
StatusUpdateInterval REG_DWORD Gibt das Intervall in Minuten an, in dem der Portmonitor den Spooler mit dem Portstatus aktualisiert.

Um sicherzustellen, dass der Spooler Aufträge an den nächsten verfügbaren Drucker im Pool umleitet (wenn der Druckauftrag nicht innerhalb der festgelegten Zeit gedruckt wird), muss der Portmonitor SNMP unterstützen, und die Netzwerkports im Pool müssen als "SNMP-Status aktiviert" konfiguriert werden. Der Portmonitor, der SNMP unterstützt, ist der STANDARD-TCP/IP-Portmonitor.

In Windows 7 und höher von Windows werden Druckaufträge, die an einen Druckserver gesendet werden, standardmäßig auf dem Client gerendert. Das clientseitige Rendering von Druckaufträgen kann konfiguriert werden, indem pKeyName auf "PrinterDriverData" und pValueName auf den Einstellungswert in der folgenden Tabelle festgelegt wird.

Einstellung Datentyp Beschreibung
EMFDespoolingSetting REG_DWORD Der Wert 0 oder , wenn dieser Wert in der Registrierung nicht vorhanden ist, aktiviert das clientseitige Standardrendering von Druckaufträgen.
Der Wert 1 deaktiviert das clientseitige Rendern von Druckaufträgen.
ForceClientSideRendering REG_DWORD Der Wert 0 oder , wenn dieser Wert nicht in der Registrierung vorhanden ist, bewirkt, dass die Druckaufträge auf dem Client gerendert werden. Wenn ein Druckauftrag auf dem Client nicht gerendert werden kann, wird er auf dem Server gerendert. Wenn ein Druckauftrag auf dem Server nicht gerendert werden kann, tritt ein Fehler auf.
Der Wert 1 rendert Druckaufträge auf dem Client. Wenn ein Druckauftrag auf dem Client nicht gerendert werden kann, tritt ein Fehler auf.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client)
Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)
Windows 2000 Server [nur Desktop-Apps]
Header
Winspool.h (include Windows.h)
Bibliothek
Winspool.lib
DLL
Winspool.drv
Unicode- und ANSI-Name
SetPrinterDataExW (Unicode) und SetPrinterDataExA (ANSI)

Siehe auch

Drucken

Druckspooler-API-Funktionen

GetPrinterDataEx

OpenPrinter

SetPrinter

PRINTER_INFO_7