IPrintTicketProvider2::BindPrinter-Methode (prdrvcom.h)

Artikel
02/07/2025

Die IPrintTicketProvider2::BindPrinter-Methode bindet einen Drucker oder eine Druckwarteschlange an eine bestimmte Version des Druckticketschemas, wodurch der Haupttreiber eine Reihe privater Namespace-UNIFORM-Ressourcenbezeichner (URIs) einem Gerät zuordnen kann.

Syntax

HRESULT BindPrinter(
  [in]  IN HANDLE     hPrinter,
  [in]  IN INT        version,
  [out] OUT PSHIMOPTS pOptions,
  [out] OUT DWORD     *pDevModeFlags,
  [out] OUT INT       *cNamespaces,
  [out] OUT BSTR      **ppNamespaces
);

Parameter

[in] hPrinter

Der Druckziehpunkt des Spoolers, der vom Kerntreiber bereitgestellt wird. Der Anbieter sollte dieses Handle nicht jederzeit schließen, da der Client des Anbieters für die Verwaltung der Lebensdauer dieses Handles verantwortlich ist. Der Anbieter kann den Druckhandle zwischenspeichern; alle zukünftigen Aufrufe beziehen sich auf den Drucker, der diesem Handle zugeordnet ist.

[in] version

Die Hauptversionsnummer des Druckticket- oder Druckticketschemas, das der Druckticket-Manager anfordert, den OEM-Plug-In-Anbieter zu unterstützen. Windows Vista unterstützt nur Version 1. Der Anbieter sollte keinen Versuch ausführen, eine Bindung an eine Version zu erstellen, die nicht unterstützt oder erkannt wird.

[out] pOptions

Ein Zeiger auf eine Variable, die einen der folgenden Aufzählungswerte empfängt:

PTSHIM_DEFAULT

Das System platziert eine binäre Codierung (ein BLOB - binär großes Objekt) des privaten Teils der DEVMODEW- Struktur in das Druckticket in einer Konvertierung eines DEVMODEW- in ein Druckticket.
PTSHIM_NOSNAPSHOT

Das System platziert keine binäre Codierung (ein BLOB) des privaten Teils der DEVMODEW- Struktur in das Druckticket in einer Konvertierung eines DEVMODEW- in ein Druckticket. Verwenden Sie diesen Wert, wenn alle öffentlichen und privaten DEVMODEW- Mitglieder vollständig im Druckticket dargestellt werden.

[out] pDevModeFlags

Ein Zeiger auf eine DWORD-Typvariable, die eine Reihe von Bitkennzeichnungen empfängt, die angeben, welche öffentlichen DEVMODEW--Member nicht vom Druckticket-Shim in DEVMODEW-to-Print-Ticket oder print ticket-to-DEVMODEW-Konvertierungen verarbeitet werden sollen. Ein Bitkennzeichen, das in diesem Parameter vorhanden ist, gibt an, dass der Drucker das zugeordnete DEVMODEW-Element nicht unterstützt oder dass der Anbieter dieses DEVMODEW-Merkmal behandelt. Wenn z. B. DM_MEDIATYPE in *pDevModeFlags festgelegt ist, unterstützt der Drucker nicht mehrere Medientypen, oder der Anbieter ist für die Unterstützung mehrerer Medientypen verantwortlich. (Alle DM_XXX Bitkennzeichnungen werden in wingdi.h definiert und im Microsoft Windows SDK beschrieben.) Standardmäßig verarbeitet der Druckticket-Shim alle Elemente, die im dmFlags- Mitglied der standardmäßigen DEVMODEW--Struktur dargestellt werden.

[out] cNamespaces

Ein Zeiger auf eine Variable, die die Anzahl der privaten Namespace-URIs empfängt, die im Plug-In verwendet werden. Diese Zahl stellt die Anzahl der Zeichenfolgen im Array dar, auf die durch ppNamespacesverwiesen wird.

[out] ppNamespaces

Ein Zeiger auf eine Variable, die die Adresse des ersten Elements eines BSTR-Arrays empfängt. Das Plug-In füllt jede Arrayposition mit einem Namespace-URI aus. Weitere Informationen zu diesem Parameter finden Sie im folgenden Abschnitt "Hinweise".

Rückgabewert

IPrintTicketProvider2::BindPrinter sollte einen der folgenden Werte zurückgeben:

Rückgabecode	Beschreibung
S_OK	Der Vorgang war erfolgreich.
E_VERSION_NOT_SUPPORTED	Das Plug-In unterstützt nicht die Version des Druckschemas, das in der Version Parameter angegeben ist.

Bemerkungen

Die Bindung an ein Gerät ermöglicht es dem Anbieter, bestimmte Objekte zwischenzuspeichern und Handles zu behandeln, die für zukünftige Druckticket- oder Gerätefunktionendienste auf diesem Gerät erforderlich sind. Beispielsweise kann das Druckerhandle im hPrinter-Parameter zwischengespeichert werden. Die IPrintTicketProvider2::BindPrinter-Methode wird garantiert nur einmal aufgerufen.

Der Treiber ist für das Zuordnen des Speichers für das Array verantwortlich, auf das durch den Parameter "ppNamespaces" und für die Namespace-URI-Zeichenfolgen verwiesen wird. Das Array sollte mithilfe der CoTaskMemAlloc-Funktion zugewiesen werden; Die Namespacezeichenfolgen sollten mithilfe der SysAllocString--Funktion zugewiesen werden. Beide Funktionen werden in der Windows SDK-Dokumentation beschrieben. Das Array, auf das der PpNamespaces-Parameter verweist, ist nicht erforderlich, um die Namespaces für die Druckschemastichwörter oder das Print Schema Framework zu enthalten.

Ein IPrintTicketProvider2--Objekt muss nicht mehr als einmal gebunden werden können. Der Druckticket-Manager verwendet immer unterschiedliche IPrintTicketProvider2 Objektinstanzen zum Binden an verschiedene Geräte. Alle Ressourcen, die in einem erfolgreichen Aufruf von IPrintTicketProvider2::BindPrinter abgerufen werden, sollten freigegeben werden, wenn die Referenzanzahl eines IPrintTicketProvider2- Objekts null ist. Beachten Sie, dass der Anbieter das Handle, das an den Aufruf von BindPrinterübergeben wurde, nicht schließen sollte. Der Druckticket-Manager erstellt möglicherweise mehrere Anbieter für dasselbe Gerät in unterschiedlichen Versionen, wenn mehrere Versionen unterstützt werden.