DrvConvertDevMode-Funktion (winddiui.h)

Artikel
02/07/2025

Die DrvConvertDevMode-Funktion einer Druckerschnittstellen-DLL konvertiert die DEVMODEW- Struktur eines Druckers von einer Version in eine andere.

Syntax

BOOL DrvConvertDevMode(
  [in]      LPTSTR   pPrinterName,
  [in]      PDEVMODE pdmIn,
  [out]     PDEVMODE pdmOut,
  [in, out] PLONG    pcbNeeded,
  [in]      DWORD    fMode
);

Parameter

[in] pPrinterName

Vom Aufrufer bereitgestellter Zeiger auf eine Druckernamenzeichenfolge. Weitere Informationen zu diesem Parameter finden Sie im folgenden Abschnitt "Hinweise".

[in] pdmIn

Vom Aufrufer bereitgestellter Zeiger auf eine DEVMODEW-Eingabestruktur. Wenn fMode- CDM_DRIVER_DEFAULT ist, ist dieser Zeiger NULL-.

[out] pdmOut

Vom Aufrufer bereitgestellter Zeiger auf einen Puffer, um eine DEVMODEW-Ausgabestruktur zu empfangen. Wenn fMode- CDM_CONVERT enthält der Puffer eine gültige DEVMODEW-Struktur, die die Zieltreiberversion angibt.

[in, out] pcbNeeded

Vom Aufrufer bereitgestellter Zeiger auf die Größe des Puffers in Bytes, auf den pdmOut-verweist. Bei der Ausgabe sollte die Druckerschnittstellen-DLL den empfangenen Größenwert mit der tatsächlichen Größe der konvertierten DEVMODEW-Struktur überschreiben. Wenn der empfangene Puffer zu klein ist, sollte die Druckerschnittstellen-DLL den empfangenen Größenwert mit der erforderlichen Puffergröße überschreiben.

[in] fMode

Vom Aufrufer bereitgestellte Bitkennzeichnung, die den Typ des auszuführenden Vorgangs angibt. Dies kann eine der folgenden Flags sein:

CDM_CONVERT

Die Funktion sollte den Inhalt der Eingabe-DEVMODEW-Struktur (wie durch pdmIn) in eine neue DEVMODEW-Struktur umwandeln und das Ergebnis in der DEVMODEW-Struktur platzieren, auf die durch pdmOutverwiesen wird. Der anfängliche Inhalt der empfangenen Ausgabe DEVMODEW-Struktur (auf die durch pdmOut) verwiesen wird, sollte verwendet werden, um die Ausgabeversion zu bestimmen.

CDM_CONVERT351

Die Funktion sollte den Inhalt der Eingabe-DEVMODEW-Struktur konvertieren (auf die durch pdmInverwiesen wird), eine DEVMODEW-Ausgabestruktur erstellen, die mit Windows NT 3.51 kompatibel ist, und das Ergebnis in der DEVMODEW-Struktur platzieren, auf die durch pdmOutverwiesen wird.

Wenn der Treiber keine DEVMODEW-Struktur für Windows NT 3.51 unterstützt, sollte die Funktion die Eingabe DEVMODEW in die aktuelle Version konvertieren.

CDM_DRIVER_DEFAULT

Die Funktion sollte die aktuelle Version der standardmäßigen DEVMODEW-Struktur in den Puffer kopieren, auf den pdmOut-verweist.

Rückgabewert

Wenn der Vorgang erfolgreich ist, sollte die Funktion TRUE-zurückgeben; andernfalls sollte SetLastError aufgerufen werden, um einen Fehlercode festzulegen und FALSE-zurückzugeben.

Bemerkungen

In einer Client-/Serverumgebung kann ein Client eine Version des Betriebssystems oder druckertreibers ausführen, während der Server (Spooler) ausgeführt wird, was bedeutet, dass die DEVMODEW-Strukturdefinition eines Druckers zwischen Client und Server inkonsistent ist. Die DrvConvertDevMode Funktion muss in der Lage sein, Konvertierungen von einer Version der DEVMODEW-Struktur des Druckers in eine andere auszuführen.

Beim Konvertieren von einer DEVMODEW-Version in eine andere müssen sowohl öffentliche als auch private DEVMODEW-Member einbezogen werden.

Der Druckername, auf den pPrinterName verweist, kann als Eingabeargument für die OpenPrinter--Funktion verwendet werden (in der Microsoft Windows SDK-Dokumentation beschrieben), die aufgerufen werden kann, um gespeicherte Standardwerte abzurufen, wenn das CDM_DRIVER_DEFAULT Flag empfangen wird. Beachten Sie, dass die Druckernamenzeichenfolge vor einem Aufruf von OpenPrinter-nicht geändert werden darf. Darüber hinaus muss sich ein Aufruf von OpenPrinter- im gleichen Thread befinden, wie zum Aufrufen DrvConvertDevModeverwendet wurde.

Die Funktion sollte überprüfen, ob sowohl pdmIn als auch pdmOut- (falls zutreffend) auf gültige DEVMODEW-Strukturen verweisen. Andernfalls sollte die Funktion SetLastError(ERROR_INVALID_PARAMETER) aufrufen und FALSE-zurückgeben. Wenn die durch pcbNeed- angegebene Ausgabegröße DEVMODEW zu klein ist, sollte der Treiber den von pcbNeededed bereitgestellten Größenwert mit der erforderlichen Puffergröße überschreiben, setLastError(ERROR_INSUFFICIENT_BUFFER) aufrufen und FALSEzurückgeben.

Die DrvConvertDevMode-Funktion wird im Kontext des Spoolers ausgeführt und darf daher keine Benutzeroberfläche anzeigen.

Wenn DrvConvertDevMode mit einem NULL- DEVMODEW-Strukturzeiger im pdmOut Parameter aufgerufen wird, um die Puffergröße abzurufen, wird erwartet, dass der Treiber den letzten Fehler auf ERROR_INSUFFICIENT_BUFFER festgelegt. Wenn der letzte Fehler nicht auf diesen Wert festgelegt ist, geht der Spooler von einem allgemeinen Fehler aus.

Anforderungen

Anforderung	Wert
Zielplattform-	Desktop
Header-	winddiui.h (include Winddiui.h)

Freigeben über