DrvConvertDevMode-Funktion (winddiui.h)

Artikel
08/08/2023

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 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 bei der Eingabe eine gültige DEVMODEW-Struktur, die die Zieltreiberversion angibt.

[in, out] pcbNeeded

Vom Aufrufer bereitgestellter Zeiger auf die Größe des Puffers, auf den pdmOut verweist, in Bytes. Bei der Ausgabe sollte die DLL der Druckerschnittstelle 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 bereitgestelltes Bitflag, das den Typ des auszuführenden Vorgangs angibt. Dies kann eines der folgenden Flags sein:

CDM_CONVERT

Die Funktion sollte den Inhalt der DEVMODEW-Eingabestruktur (auf die von pdmIn verwiesen wird) in eine neue DEVMODEW-Struktur konvertieren und das Ergebnis in der DEVMODEW-Struktur platzieren, auf die von pdmOut verwiesen wird. Der anfängliche Inhalt der empfangenen DEVMODEW-Ausgabestruktur (auf die von pdmOut verwiesen wird) sollte verwendet werden, um die Ausgabeversion zu bestimmen.

CDM_CONVERT351

Die Funktion sollte den Inhalt der DEVMODEW-Eingabestruktur konvertieren (auf die von pdmIn verwiesen wird), eine DEVMODEW-Ausgabestruktur erstellen, die mit Windows NT 3.51 kompatibel ist, und das Ergebnis in der DEVMODEW-Struktur platzieren, auf die von pdmOut verwiesen 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 ihrer DEVMODEW-Standardstruktur in den Puffer kopieren, auf den von pdmOut verwiesen wird.

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.

Hinweise

In einer Client-/Serverumgebung führt ein Client möglicherweise eine Version des Betriebssystems oder Druckertreibers aus, während der Server (Spooler) eine andere ausgeführt wird. Dies bedeutet, dass die DEVMODEW-Strukturdefinition eines Druckers zwischen Client und Server inkonsistent ist. Die DrvConvertDevMode-Funktion muss Konvertierungen von einer Version der DEVMODEW-Struktur des Druckers in eine andere durchführen können.

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

Der Druckername, auf den pPrinterName verweist, kann als Eingabeargument für die OpenPrinter-Funktion (in der Microsoft Windows SDK Dokumentation beschrieben) verwendet werden, die aufgerufen werden kann, um gespeicherte Standardwerte abzurufen, wenn das CDM_DRIVER_DEFAULT-Flag empfangen wird. Beachten Sie, dass die Zeichenfolge des Druckernamens vor einem Aufruf von OpenPrinter in keiner Weise geändert werden darf. Darüber hinaus muss sich ein Aufruf von OpenPrinter im selben Thread befinden, der zum Aufrufen von DrvConvertDevMode verwendet 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 devMODEW-Ausgabegröße, die von pcbNeeded angegeben wird, zu klein ist, sollte der Treiber den von pcbNeeded angegebenen Größenwert mit der erforderlichen Puffergröße überschreiben, SetLastError(ERROR_INSUFFICIENT_BUFFER) aufrufen und FALSE zurü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 legt. Wenn der letzte Fehler nicht auf diesen Wert festgelegt ist, geht der Spooler von einem allgemeinen Fehler aus.

Anforderungen

Anforderung	Wert
Zielplattform	Desktop
Kopfzeile	winddiui.h (include Winddiui.h)

Freigeben über