SetPrinter-Funktion
Die SetPrinter-Funktion legt die Daten für einen angegebenen Drucker fest oder legt den Zustand des angegebenen Druckers fest, indem der Druck angehalten, der Druck fortgesetzt oder alle Druckaufträge entfernt werden.
Syntax
BOOL SetPrinter(
_In_ HANDLE hPrinter,
_In_ DWORD Level,
_In_ LPBYTE pPrinter,
_In_ DWORD Command
);
Parameter
-
hPrinter [in]
-
Ein Handle für den Drucker. Verwenden Sie die Funktion OpenPrinter, OpenPrinter2 oder AddPrinter , um einen Druckerhandle abzurufen.
-
Ebene [in]
-
Der Datentyp, den die Funktion in dem Puffer speichert, auf den pPrinter verweist. Wenn der Command-Parameter nicht gleich 0 ist, muss der Level-Parameter 0 sein.
Dieser Wert kann 0, 2, 3, 4, 5, 6, 7, 8 oder 9 sein.
-
pPrinter [in]
-
Ein Zeiger auf einen Puffer, der daten enthält, die für den Drucker festgelegt werden sollen, oder Informationen für den durch den Command-Parameter angegebenen Befehl enthält. Der Typ der Daten im Puffer wird durch den Wert von Level bestimmt.
Ebene Struktur - 0
Wenn der Command-ParameterPRINTER_CONTROL_SET_STATUS ist, muss pPrinter einen DWORD-Wert enthalten, der den neuen Drucker angibt, status festgelegt werden soll. Eine Liste der möglichen status Werte finden Sie im Statuselement der PRINTER_INFO_2-Struktur. Beachten Sie, dass PRINTER_STATUS_PAUSED und PRINTER_STATUS_PENDING_DELETION status festzulegenden Werte nicht gültig sind.
Wenn Level 0 ist, der Command-Parameter aber nicht PRINTER_CONTROL_SET_STATUS ist, muss pPrinterNULL sein.- 2
Eine PRINTER_INFO_2 Struktur mit detaillierten Informationen zum Drucker. - 3
Eine PRINTER_INFO_3 Struktur, die die Sicherheitsinformationen des Druckers enthält. - 4
Eine PRINTER_INFO_4 Struktur, die minimale Druckerinformationen enthält, einschließlich des Druckernamens, des Namens des Servers und der Angabe, ob der Drucker remote oder lokal ist. - 5
Eine PRINTER_INFO_5 Struktur, die Druckerinformationen wie Druckerattribute und Timeouteinstellungen enthält. - 6
Eine PRINTER_INFO_6 Struktur, die den status Wert eines Druckers angibt. - 7
Eine PRINTER_INFO_7-Struktur . Das dwAction-Element dieser Struktur gibt an, ob SetPrinter die Druckerdaten im Verzeichnisdienst veröffentlichen, aufheben, erneut veröffentlichen oder aktualisieren soll. - 8
Eine PRINTER_INFO_8 Struktur, die die globalen Standarddruckereinstellungen angibt. - 9
Eine PRINTER_INFO_9 Struktur, die die Standardeinstellungen des Druckers pro Benutzer angibt. -
Befehl [in]
-
Die auszuführende Aktion.
Wenn der Level-Parameter nichtzero ist, legen Sie den Wert dieses Parameters auf 0 fest. In diesem Fall behält der Drucker seinen aktuellen Zustand bei, und die Funktion konfiguriert die Druckerdaten neu, wie in den Parametern Level und pPrinter angegeben.
Wenn der Parameter Level 0 ist, legen Sie den Wert dieses Parameters auf einen der folgenden Werte fest.
Wert Bedeutung - PRINTER_CONTROL_PAUSE
Halten Sie den Drucker an. - PRINTER_CONTROL_PURGE
Löschen Sie alle Druckaufträge im Drucker. - PRINTER_CONTROL_RESUME
Fortsetzen eines angehaltenen Druckers. - PRINTER_CONTROL_SET_STATUS
Legen Sie den Drucker status fest.
Legen Sie den pPrinter-Parameter auf einen Zeiger auf einen DWORD-Wert fest, der den neuen Drucker status angibt.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Nichtzero-Wert.
Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null.
Wenn Level 7 ist und die Veröffentlichungsaktion fehlgeschlagen ist, gibt SetPrinterERROR_IO_PENDING zurück und versucht, die Aktion im Hintergrund abzuschließen. Wenn Level 7 ist und die Aktualisierungsaktion fehlgeschlagen ist, gibt SetPrinterERROR_FILE_NOT_FOUND zurück.
Bemerkungen
Hinweis
Dies ist eine blockierende oder synchrone Funktion und wird möglicherweise nicht sofort zurückgegeben. 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. Wenn Sie diese Funktion über einen Thread aufrufen, der die Interaktion mit der Benutzeroberfläche verwaltet, kann die Anwendung nicht reagieren.
Sie können setPrinter nicht verwenden, um den Standarddrucker zu ändern.
Um die aktuellen Druckereinstellungen zu ändern, rufen Sie die GetPrinter-Funktion auf, um die aktuellen Einstellungen in einer PRINTER_INFO_2-Struktur abzurufen, ändern Sie die Elemente dieser Struktur nach Bedarf, und rufen Sie dann SetPrinter auf.
Die SetPrinter-Funktion ignoriert die Elemente pServerName, AveragePPM, Status und cJobs einer PRINTER_INFO_2-Struktur .
Durch das Anhalten eines Druckers wird die Planung aller Druckaufträge für diesen Drucker ausgesetzt, mit Ausnahme des einen Druckauftrags, der gerade gedruckt wird. Druckaufträge können an einen angehaltenen Drucker übermittelt werden, aber es werden keine Aufträge für den Druck auf diesem Drucker geplant, bis der Druck fortgesetzt wird. Wenn ein Drucker deaktiviert ist, werden alle Druckaufträge für diesen Drucker mit Ausnahme des aktuellen Druckauftrags gelöscht.
Wenn Sie SetPrinter verwenden, um die DEVMODE-Standardstruktur für einen Drucker zu ändern (globales Festlegen der Druckerstandardeinstellungen), müssen Sie zuerst die DocumentProperties-Funktion aufrufen, um die DEVMODE-Struktur zu überprüfen.
Für die PRINTER_INFO_2 - und PRINTER_INFO_3-Strukturen , die einen Zeiger auf einen Sicherheitsdeskriptor enthalten, kann die Funktion nur die Komponenten des Sicherheitsdeskriptors festlegen, zu deren Änderung der Aufrufer berechtigt ist. Zum Festlegen bestimmter Sicherheitsbeschreibungskomponenten müssen Sie die erforderlichen Zugriffsrechte angeben, wenn Sie die OpenPrinter - oder OpenPrinter2-Funktion aufrufen, um ein Handle für den Drucker abzurufen. In der folgenden Tabelle sind die Zugriffsrechte aufgeführt, die zum Ändern der verschiedenen Sicherheitsbeschreibungskomponenten erforderlich sind.
| Zugriffsberechtigung | Sicherheitsdeskriptorkomponente |
|---|---|
| WRITE_OWNER | Besitzer Primäre Gruppe |
| WRITE_DAC | Diskretionäre Zugriffssteuerungsliste (DACL) |
| ACCESS_SYSTEM_SECURITY | Systemzugriffssteuerungsliste (SACL) |
Wenn die Sicherheitsbeschreibung eine Komponente enthält, die der Aufrufer nicht über das Zugriffsrecht zum Ändern verfügt, schlägt SetPrinter fehl. Die Komponenten eines Sicherheitsdeskriptors, die Sie nicht ändern möchten, sollten NULL sein oder nicht vorhanden sein. Wenn Sie den Sicherheitsdeskriptor nicht ändern möchten und SetPrinter mit einer PRINTER_INFO_2-Struktur aufrufen, legen Sie das pSecurityDescriptor-Element dieser Struktur auf NULL fest.
Die Internet Connection Firewall (ICF) blockiert standardmäßig Druckerports, aber eine Ausnahme für die Datei- und Druckfreigabe kann aktiviert werden. Wenn SetPrinter von einem Computeradministrator aufgerufen wird, wird die Ausnahme aktiviert. Wenn sie von einem Nichtadministrator aufgerufen wird und die Ausnahme noch nicht aktiviert wurde, schlägt der Aufruf fehl.
Sie können Die Ebene 7 mit der PRINTER_INFO_7-Struktur verwenden, um Verzeichnisdienstdaten für den Drucker zu veröffentlichen, aufzuheben oder zu aktualisieren. Die Verzeichnisdienstdaten für einen Drucker enthalten alle Daten, die unter den SPLDS_*-Schlüsseln gespeichert sind, indem die SetPrinterDataEx-Funktion für den Drucker aufgerufen wird. Legen Sie vor dem Aufrufen von SetPrinter das pszObjectGUID-Member von PRINTER_INFO_7 auf NULL fest, und legen Sie den dwAction-Member auf einen der folgenden Werte fest.
| Wert | BESCHREIBUNG |
|---|---|
|
DSPRINT_PUBLISH |
Veröffentlicht die Verzeichnisdienstdaten. |
|
DSPRINT_REPUBLISH |
Die Verzeichnisdienstdaten für den Drucker werden nicht veröffentlicht und dann erneut veröffentlicht, wobei alle Eigenschaften im veröffentlichten Drucker aktualisiert werden. Die erneute Veröffentlichung ändert auch die GUID des veröffentlichten Druckers. Verwenden Sie diesen Wert, wenn Sie vermuten, dass die veröffentlichten Daten des Druckers beschädigt wurden. |
|
DSPRINT_UNPUBLISH |
Hebt die Veröffentlichung der Verzeichnisdienstdaten auf. |
|
DSPRINT_UPDATE |
Updates die Verzeichnisdienstdaten. Dies ist identisch mit DSPRINT_PUBLISH, mit der Ausnahme, dass SetPrinter mit ERROR_FILE_NOT_FOUND fehlschlägt, wenn der Drucker noch nicht veröffentlicht wurde. Verwenden Sie DSPRINT_UPDATE , um veröffentlichte Eigenschaften zu aktualisieren, aber nicht die Veröffentlichung zu erzwingen. Druckertreiber sollten immer DSPRINT_UPDATE anstelle von DSPRINT_PUBLISH verwenden. |
DSPRINT_PENDING ist kein gültiger dwAction-Wert für SetPrinter.
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 |
SetPrinterW (Unicode) und SetPrinterA (ANSI) |