IPrintOemUI::D eviceCapabilities-Methode (prcomoem.h)
Die IPrintOemUI::DeviceCapabilities -Methode ermöglicht es einem Benutzeroberfläche-Plug-In, benutzerdefinierte Gerätefunktionen anzugeben.
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 Griff 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 Von der Methode zurückgegebenen Informationen angibt. Eine Liste der Flags finden Sie in der Beschreibung der DrvDeviceCapabilities-Funktion .
pOutput
Vom Aufrufer bereitgestellter Zeiger auf einen Puffer, um die angeforderten Informationen zu empfangen. Der Typ der zurückgegebenen Informationen hängt von dem von wCapability angegebenen Flag ab.
pPublicDM
Vom Aufrufer bereitgestellter Zeiger auf eine überprüfte DEVMODEW-Struktur .
pOEMDM
Vom Aufrufer bereitgestellter Zeiger auf die privaten DEVMODEW-Strukturmitglieder des Benutzeroberflächen-Plug-Ins.
dwOld
Vom Aufrufer bereitgestellter Rückgabewert aus der DrvDeviceCapabilities-Funktion des Druckertreibers oder aus einem anderen Benutzerschnittstellen-Plug-In. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
dwResult
Ein Rückgabewert, der von dem von wCapability angegebenen Flag abhängig ist. Weitere Informationen finden Sie in der Beschreibung der DrvDeviceCapabilities-Funktion und im abschnitt "Hinweise".
Rückgabewert
Die -Methode muss einen der folgenden Werte zurückgeben.
| Rückgabecode | BESCHREIBUNG |
|---|---|
|
Der Vorgang wurde erfolgreich ausgeführt. |
|
Das Plug-In beabsichtigt, den Puffer zu verwenden, auf den der pOutput-Parameter für eigene Zwecke 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. |
Hinweise
Die Methode eines Benutzeroberflächen-Plug-Ins IPrintOemUI::DeviceCapabilities führt dieselben Arten von Vorgängen aus wie die DrvDeviceCapabilities-Funktion , die von Benutzermodus-Druckerschnittstellen-DLLs exportiert wird. Die -Methode gibt die vom Drucker bereitgestellten Funktionen an.
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 von seiner DrvDeviceCapabilities-Funktion aus auf.
Wenn die IPrintOemUI::DeviceCapabilities Methode die angepasste Unterstützung für eine Funktion angibt (durch Festlegen entsprechender Bits als Reaktion auf ein empfangenes DC_FIELDS Flag), muss benutzerdefinierter Code die Funktion vollständig unterstützen. Die vollständige Unterstützung umfasst in der Regel das Zurückgeben von Informationen zur Funktion als Reaktion auf Aufrufe der -Methode sowie das IPrintOemUI::DeviceCapabilities Bereitstellen von geeignetem Benutzermodus- oder Kernelmoduscode zum Implementieren 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 Methode eines Plug-Ins IPrintOemUI::DeviceCapabilities aufgerufen wird, ist sein dwOld-Eingabewert der Rückgabewert der methode des zuvor aufgerufenen Plug-Ins IPrintOemUI::DeviceCapabilities . Für das erste Plug-In namens enthält dwOld den Rückgabewert der DrvDeviceCapabilities-Funktion des Druckertreibers. Ebenso enthält der Puffer, auf den pOutput verweist, bei der Eingabe alle Inhalte, die von einer zuvor aufgerufenen IPrintOemUI::DeviceCapabilities Methode oder DrvDeviceCapabilities-Funktion dort platziert werden.
Damit mehrere Benutzeroberflächen-Plug-Ins miteinander zusammenarbeiten können, muss jede IPrintOemUI::DeviceCapabilities Methode den folgenden Regeln entsprechen:
-
Wenn ein Benutzeroberflächen-Plug-In keine angegebene Funktion unterstützt, sollte seine
IPrintOemUI::DeviceCapabilitiesMethode nur den Inhalt des dwOld-Parameters in dwResult zurückgeben. -
Wenn ein Benutzeroberflächen-Plug-In die Funktion unterstützt, sollte seine
IPrintOemUI::DeviceCapabilitiesMethode dwOld und den Inhalt des Puffers ignorieren, auf den pOutput verweist. Es sollte einen Rückgabewert und Pufferinhalte bereitstellen, die geeignet sind, um anzugeben, dass die angegebene Funktion unterstützt wird. Wenn die Methode einen Fehler erkennt, sollte sie GDI_ERROR in dwResult zurückgeben. -
Wenn ein Benutzeroberflächen-Plug-In die Funktionsinformationen ändern soll, die im Puffer empfangen werden, auf den pOutput verweist, sollte seine
IPrintOemUI::DeviceCapabilitiesMethode den Pufferinhalt ändern und einen entsprechenden Rückgabewert in dwResult zurückgeben. Wenn wCapability z. B. DC_FIELDS ist, sollte die -Methode die Bits, die sie mit den Bits festlegen muss, die in dwOld festgelegt werden müssen, und gibt das Ergebnis des OR-Vorgangs in dwResult zurück. - Die obigen Regeln sollten auch dann befolgt werden, wenn der empfangene Inhalt von dwOld GDI_ERROR ist.
IPrintOemUI::DeviceCapabilities Methoden auf, gibt auch DC_FIELDS an und gibt die Union aller festgelegten Bits an den Aufrufer zurück.
Der S_DEVCAP_OUTPUT_FULL_REPLACEMENT Rückgabewert ist neu in Windows Vista und gilt für Unidrv- und Pscript5-Benutzeroberfläche-Plug-Ins. Ein Plug-In sollte den S_DEVCAP_OUTPUT_FULL_REPLACEMENT Rückgabewert nur verwenden, wenn es eine vollständige Kontrolle darüber erfordert, was im 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 Parameter pPublicDM und pOEMDM verwiesen wird) dem Benutzeroberfläche-Plug-In anzeigt, dass es Gerätefunktionsdaten melden soll, die sich von den in der GPD- oder PPD-Datei angegebenen Daten unterscheiden. Beispielsweise erfordert eine DEVMODEW-Struktur, die den Fotodruck angibt, möglicherweise einen anderen Satz von Papiertypen als die, die in der GPD- oder PPD-Datei angegeben sind. In einer solchen Situation sollte das Plug-In unabhängig von den Werten der Parameter pOutput und dwOld S_DEVCAP_OUTPUT_FULL_REPLACEMENT zurückgeben und den dwResult-Parameter auf die Anzahl der Zu meldenden Papiertypen festlegen. Wenn pOutput nicht NULL ist, sollte das Plug-In auch den Puffer füllen, auf den pOutput mit dem gewünschten Satz von 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 eines von ihnen S_DEVCAP_OUTPUT_FULL_REPLACEMENT zurückgibt, interpretiert der Unidrv- oder Pscript5-Kerntreiber diesen Rückgabewert so, dass die Plug-Ins vollständige Ersatzausgabedaten bereitstellen möchten. Daher platziert der Kerntreiber keine Daten in den pOutput-Puffer , bevor er die Plug-Ins aufruft. (Der Kerntreiber ruft die Plug-Ins in derselben Reihenfolge auf, die für ihre 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 Kerntreiber Unidrv und Pscript5 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 Benutzeroberfläche-Plug-Ins finden Sie unter Anpassen der Druckertreiber von Microsoft.
Anforderungen
| Anforderung | Wert |
|---|---|
| Zielplattform | Desktop |
| Kopfzeile | prcomoem.h (einschließlich Prcomoem.h) |