Freigeben über


SetPrinterDataEx-Funktion

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