SetPrinterDataEx-Funktion

Artikel
06/13/2023

Die SetPrinterDataEx-Funktion legt die Konfigurationsdaten für einen Drucker oder Druckserver 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 Druckserver, für den die Funktion Konfigurationsdaten festlegt. Verwenden Sie die Funktion OpenPrinter, OpenPrinter2 oder AddPrinter , um einen Druckerhandle abzurufen.

pKeyName [in]

Ein Zeiger auf eine NULL-endende Zeichenfolge, die den Schlüssel angibt, der den festzulegenden Wert enthält. Wenn der angegebene Schlüssel oder unterschlüssel nicht vorhanden ist, erstellt die Funktion sie.

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

Wert	Bedeutung
SPLDS_DRIVER_KEY	Druckertreiber verwenden diesen Schlüssel zum Speichern von Treibereigenschaften.
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. Druckerobjektnummern.

Werte, die unter dem SPLDS_USER_KEY Schlüssel gespeichert sind, werden nur dann im Verzeichnisdienst veröffentlicht, wenn im Schema eine entsprechende Eigenschaft 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_7auf DSPRINT_UPDATE.

Sie können andere Schlüssel angeben, um Nicht-DS-Konfigurationsdaten zu speichern. Verwenden Sie den umgekehrten Schrägstrich ( \ ) als Trennzeichen, um einen Pfad mit einem oder mehreren Unterschlüsseln anzugeben.

Wenn hPrinter ein Handle für einen Drucker ist und pKeyNameNULL oder eine leere Zeichenfolge ist, gibt SetPrinterDataExERROR_INVALID_PARAMETER zurück.

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 Level = 2.

pValueName [in]

Ein Zeiger auf eine NULL-endende Zeichenfolge, die die festzulegenden Daten identifiziert.

Für Drucker 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.

Geben Sie [in] ein.

Ein Code, der den Typ der Daten angibt, auf die der pData-Parameter verweist. Eine Liste der möglichen Typcodes finden Sie unter Registrierungswerttypen.

Wenn pKeyName einen der vordefinierten Verzeichnisdienstschlüssel angibt, muss TypeREG_SZ, REG_MULTI_SZ, REG_DWORD oder REG_BINARY sein. 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.

Bemerkungen

Hinweis

Dies ist eine blockierende oder synchrone Funktion, die möglicherweise nicht sofort zurückgegeben wird. Wie schnell diese Funktion zurückgibt, hängt von Laufzeitfaktoren wie Netzwerk-status, Druckserverkonfiguration und Druckertreiberimplementierungsfaktoren 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 führen, dass die Anwendung nicht mehr reagiert.

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

Das Aufrufen von SetPrinterDataEx mit dem pKeyName-Parameter , 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	In Windows Server 2003 und höher nicht unterstützt
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 server so festgelegt ist, dass Popupfenster für alle Aufträge wiederholt werden, oder 0, wenn der Server popupfenster nicht für alle Aufträge wiederholt. In Windows Server 2003 und höher nicht unterstützt
SPLREG_SCHEDULER_THREAD_PRIORITY
SPLREG_SCHEDULER_THREAD_PRIORITY_DEFAULT
SPLREG_WEBSHAREMGMT	Windows Server 2003 und höher

Die Übergabe eines der folgenden vordefinierten Werte als pValueName legt das Druckverhalten des Pools fest, 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 mit SPLREG_RESTART_JOB_ON_POOL_ENABLED verwendet.
SPLREG_RESTART_JOB_ON_POOL_ENABLED	Ein Wert ungleich null in pData gibt an, dass SPLREG_RESTART_JOB_ON_POOL_ERROR aktiviert ist.

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

HKLM\SYSTEM\CurrentControlSet\Control\Print\Monitors\<MonitorName>\Ports

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

Portmonitoreinstellung	Datentyp	Bedeutung
StatusUpdateEnabled	REG_DWORD	Wenn ein wert ungleicher Wert ist, kann der Portmonitor den Spooler mit dem Port status aktualisieren.
StatusUpdateInterval	REG_DWORD	Gibt das Intervall in Minuten an, wenn der Portmonitor den Spooler mit dem Port status 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 sein. Der Portmonitor, der SNMP unterstützt, ist standard TCP/IP-Portmonitor.

In Windows 7 und höheren Versionen 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 nicht in der Registrierung vorhanden ist, aktiviert das clientseitige Standardrendering von Druckaufträgen. Der Wert 1 deaktiviert das clientseitige Rendering von Druckaufträgen.
ForceClientSideRendering	REG_DWORD	Der Wert 0 oder wenn dieser Wert nicht in der Registrierung vorhanden ist, führt dazu, dass die Druckaufträge auf dem Client gerendert werden. Wenn ein Druckauftrag nicht auf dem Client gerendert werden kann, wird er auf dem Server gerendert. Wenn ein Druckauftrag nicht auf dem Server gerendert werden kann, tritt ein Fehler auf. Der Wert 1 rendert Druckaufträge auf dem Client. Wenn ein Druckauftrag nicht auf dem Client 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 (einschließlich 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

Freigeben über