Freigeben über


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
S_OK
Der Vorgang wurde erfolgreich ausgeführt.
S_DEVCAP_OUTPUT_FULL_REPLACEMENT
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.
E_FAIL
Fehler beim Vorgang.
E_NOTIMPL
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::DeviceCapabilities Methode nur den Inhalt des dwOld-Parameters in dwResult zurückgeben.
  • Wenn ein Benutzeroberflächen-Plug-In die Funktion unterstützt, sollte seine IPrintOemUI::DeviceCapabilities Methode 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::DeviceCapabilities Methode 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.
Wenn die DrvDeviceCapabilities-Funktion des Treibers mit dem DC_FIELDS-Flags aufgerufen wird, ruft die Funktion alle 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)

Weitere Informationen

DrvDeviceCapabilities

IPrintOemUI