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 |
|
| Bibliothek |
|
| DLL |
|
| Unicode- und ANSI-Name |
SetPrinterDataExW (Unicode) und SetPrinterDataExA (ANSI) |