IPrintOemUI::D eviceCapabilities-Methode (prcomoem.h)
Mit der IPrintOemUI::DeviceCapabilities-Methode kann ein Benutzeroberflächen-Plug-In benutzerdefinierte Gerätefunktionen angeben.
Syntax
HRESULT DeviceCapabilities(
POEMUIOBJ poemuiobj,
HANDLE hPrinter,
PWSTR pDeviceName,
WORD wCapability,
PVOID pOutput,
PDEVMODE pPublicDM,
PVOID pOEMDM,
DWORD dwOld,
DWORD *dwResult
);
Parameter
poemuiobj
Vom Aufrufer bereitgestellter Zeiger auf eine OEMUIOBJ--Struktur.
hPrinter
Vom Anrufer bereitgestellter Handle für das Druckergerät.
pDeviceName
Vom Aufrufer bereitgestellter Zeiger auf eine Zeichenfolge, die den Gerätenamen darstellt.
wCapability
Vom Aufrufer bereitgestelltes Flag, das den Typ der Informationen angibt, die die Methode zurückgeben soll. Eine Liste der Flags finden Sie in der Beschreibung der funktion DrvDeviceCapabilities.
pOutput
Vom Aufrufer bereitgestellter Zeiger auf einen Puffer, um die angeforderten Informationen zu empfangen. Der Typ der zurückgegebenen Informationen hängt von dem kennzeichen ab, das von wCapabilityangegeben wird.
pPublicDM
Vom Aufrufer bereitgestellter Zeiger auf eine validierte DEVMODEW--Struktur.
pOEMDM
Vom Aufrufer bereitgestellter Zeiger auf die privaten DEVMODEW-Strukturmber des Benutzeroberflächen-Plug-Ins.
dwOld
Vom Aufrufer bereitgestellter Rückgabewert aus dem DrvDeviceCapabilities Funktion des Druckertreibers oder von einem anderen Benutzeroberflächen-Plug-In. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
dwResult
Ein Rückgabewert, der von dem von wCapabilityangegebenen Flag abhängig ist. Weitere Informationen finden Sie in der Beschreibung der funktion DrvDeviceCapabilities und im folgenden Abschnitt "Hinweise".
Rückgabewert
Die Methode muss einen der folgenden Werte zurückgeben.
| Rückgabecode | Beschreibung |
|---|---|
|
Der Vorgang war erfolgreich. |
|
Das Plug-In beabsichtigt, den Puffer zu verwenden, auf den der pOutput Parameter zu eigenen Zwecken verweist. Dieser Rückgabewert wird in prcomoem.h definiert. Weitere Informationen dazu, wann dieser Rückgabewert verwendet werden soll, finden Sie im folgenden Abschnitt "Hinweise". |
|
Fehler beim Vorgang. |
|
Die Methode ist nicht implementiert. |
Bemerkungen
Die IPrintOemUI::DeviceCapabilities-Methode eines Plug-Ins für die Benutzeroberfläche führt dieselben Arten von Vorgängen wie die DrvDeviceCapabilities-Funktion aus, die von DLLs der Benutzeroberfläche exportiert wird. Die Methode gibt funktionen an, die vom Drucker bereitgestellt werden.
Sie können die IPrintOemUI::DeviceCapabilities-Methode verwenden, um die Unidrv-Unterstützung für eine Funktion zu verhindern oder eine Funktion hinzuzufügen, die der Druckertreiber nicht bereitstellt. Der Treiber ruft IPrintOemUI::DeviceCapabilities innerhalb seiner DrvDeviceCapabilities-Funktion auf.
Wenn die IPrintOemUI::DeviceCapabilities-Methode eine angepasste Unterstützung für eine Funktion angibt (indem geeignete Bits als Reaktion auf ein empfangenes DC_FIELDS Flag festgelegt werden), muss benutzerdefinierter Code die Funktion vollständig unterstützen. Die vollständige Unterstützung umfasst in der Regel das Zurückgeben von Informationen über die Funktion als Reaktion auf Aufrufe der IPrintOemUI::DeviceCapabilities-Methode sowie die Bereitstellung geeigneter Benutzermodus- oder Kernelmoduscode zur Implementierung der Funktion.
Wenn IPrintOemUI::DeviceCapabilities Methoden von mehreren Benutzeroberflächen-Plug-Ins exportiert werden, werden die Methoden in der Reihenfolge aufgerufen, in der die Plug-Ins für die Installation angegeben werden. Jedes Mal, wenn die IPrintOemUI::DeviceCapabilities-Methode eines Plug-Ins aufgerufen wird, ist sein dwOld Eingabewert der Rückgabewert der zuvor aufgerufenen IPrintOemUI::DeviceCapabilities-Methode des Plug-Ins. Für das erste aufgerufene Plug-In enthält dwOld den Rückgabewert der DrvDeviceCapabilities-Funktion des Druckertreibers. Ebenso enthält der puffer, auf den pOutput verweist, alle inhalte, die dort durch eine zuvor aufgerufene IPrintOemUI::DeviceCapabilities-Methode oder DrvDeviceCapabilities-Funktion platziert wurden.
Damit mehrere Benutzeroberflächen-Plug-Ins miteinander arbeiten können, muss jede IPrintOemUI::DeviceCapabilities Methode den folgenden Regeln entsprechen:
-
Wenn ein Benutzeroberflächen-Plug-In keine angegebene Funktion unterstützt, sollte die
IPrintOemUI::DeviceCapabilities-Methode nur den Inhalt des dwOld--Parameters in dwResult-zurückgeben. -
Wenn ein Benutzeroberflächen-Plug-In die Funktion unterstützt, sollte die
IPrintOemUI::DeviceCapabilities-Methode dwOld und den Inhalt des Puffers ignorieren, auf den pOutputverweist. Es sollte einen Rückgabewert und einen Pufferinhalt bereitstellen, der geeignet ist, um anzugeben, dass er die angegebene Funktion unterstützt. Wenn die Methode einen Fehler erkennt, sollte sie GDI_ERROR in dwResult-zurückgeben. -
Wenn Sie möchten, dass ein Benutzeroberflächen-Plug-In die im Puffer empfangenen Funktionen ändern kann, auf die von pOutput-verwiesen wird, sollte die
IPrintOemUI::DeviceCapabilities-Methode den Pufferinhalt ändern und einen entsprechenden Rückgabewert in dwResultzurückgeben. Wenn z. B. wCapability DC_FIELDS ist, sollte die Methode ODER die Bits sein, die sie mit den Bits festlegen muss, die in dwOldfestgelegt sind, und das Ergebnis des OR-Vorgangs in dwResultzurückgeben. - Die vorstehenden Regeln sollten eingehalten werden, auch wenn der empfangene Inhalt von dwOld GDI_ERROR ist.
IPrintOemUI::DeviceCapabilities Methoden auf, gibt auch DC_FIELDS an und gibt die Vereinigung aller festgelegten Bits an den Aufrufer zurück.
Der S_DEVCAP_OUTPUT_FULL_REPLACEMENT Rückgabewert ist neu in Windows Vista und gilt sowohl für Unidrv- als auch Pscript5-Benutzeroberflächen-Plug-Ins. Ein Plug-In sollte den S_DEVCAP_OUTPUT_FULL_REPLACEMENT Rückgabewert nur verwenden, wenn er die vollständige Kontrolle darüber benötigt, was in dem Puffer platziert wird, auf den der pOutput Parameter verweist. Weder der Unidrv noch der Pscript5-Kerntreiber platzieren Daten im pOutput- Puffer, wenn das Plug-In S_DEVCAP_OUTPUT_FULL_REPLACEMENT zurückgibt. Ein Plug-In muss diesen Wert möglicherweise zurückgeben, wenn eine Einstellung in der DEVMODEW--Struktur (auf die durch die pPublicDM- und pOEMDM Parameter) verwiesen wird, dem Benutzeroberflächen-Plug-In angibt, dass es Gerätefunktionsdaten melden soll, die sich von der in der GPD- oder PPD-Datei angegebenen unterscheiden. Eine DEVMODEW-Struktur, die den Fotodruck angibt, erfordert möglicherweise einen anderen Satz von Papiertypen als diejenigen, die in der GPD- oder PPD-Datei angegeben sind. In einer solchen Situation und unabhängig von den Werten der pOutput und dwOld Parameter sollte das Plug-In S_DEVCAP_OUTPUT_FULL_REPLACEMENT zurückgeben und den dwResult Parameter auf die Anzahl der Papiertypen festlegen, die sie melden möchten. Wenn pOutput- nicht NULL-ist, sollte das Plug-In auch den Puffer ausfüllen, auf den pOutput- mit den gewünschten Papiertypen verweist, und dwResult- auf die Anzahl der Papiertypen festlegen, die das Plug-In melden möchte.
Wenn mehrere Benutzeroberflächen-Plug-Ins gleichzeitig aktiv sind und einer von ihnen S_DEVCAP_OUTPUT_FULL_REPLACEMENT zurückgibt, interpretiert der Unidrv- oder Pscript5-Kerntreiber diesen Rückgabewert, um zu bedeuten, dass die Plug-Ins vollständige Ersatzausgabedaten bereitstellen möchten. Daher platziert der Kerntreiber keine Daten in den pOutput- Puffer, bevor die Plug-Ins aufgerufen werden. (Der Kerntreiber ruft die Plug-Ins in derselben Reihenfolge auf, die für die Installation angegeben wurde.)
In Situationen, in denen die Werte, die der Kerntreiber im pOutput- Puffer platziert, nicht ersetzt werden müssen, sollte das Plug-In S_OK zurückgeben. Die Unidrv- und Pscript5-Kerntreiber erkennen den S_DEVCAP_OUTPUT_FULL_REPLACEMENT Rückgabewert nur für Gerätefunktionen, die den pOutput- Puffer verwenden, d. h., wenn der wCapability Parameter auf eines der folgenden Flags festgelegt ist:
DC_PAPERNAMES
DC_PAPERS
DC_PAPERSIZE
DC_BINNAMES
DC_BINS
DC_NUP
DC_PERSONALITY
DC_MEDIAREADY
DC_MEDIATYPENAMES
DC_MEDIATYPES
DC_ENUMRESOLUTIONS
Weitere Informationen zum Erstellen und Installieren von Plug-Ins für die Benutzeroberfläche finden Sie unter Anpassen der Druckertreiber von Microsoft.
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform- | Desktop |
| Header- | prcomoem.h (einschließlich Prcomoem.h) |