IPrintTicketProvider2::BindPrinter-Methode (prdrvcom.h)

Artikel
02/26/2024

Die IPrintTicketProvider2::BindPrinter-Methode bindet einen Drucker oder eine Druckwarteschlange an eine bestimmte Version des Druckticketschemas, sodass der Kerntreiber einem Gerät eine Reihe von URIs (Uniform Resource Identifiers) für private Namespaces 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 Druckhandle des Spoolers, der vom Kerntreiber bereitgestellt wird. Der Anbieter sollte dieses Handle zu keinem Zeitpunkt schließen, da der Client des Anbieters für die Verwaltung der Lebensdauer dieses Handles verantwortlich ist. Der Anbieter kann das 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 vom Druckticket-Manager vom OEM-Plug-In-Anbieter unterstützt werden soll. Windows Vista unterstützt nur Version 1. Der Anbieter sollte bei jedem Versuch, eine Bindung an eine Version zu erstellen, fehlschlagen, die er nicht unterstützt oder erkennt.

[out] pOptions

Ein Zeiger auf eine Variable, die einen der folgenden aufgezählten Werte empfängt:

PTSHIM_DEFAULT

Das System platziert eine binäre Codierung (ein BLOB - binäres großes Objekt) des privaten Teils der DEVMODEW-Struktur in das Druckticket, um eine DEVMODEW-Datei in ein Druckticket zu konvertieren.
PTSHIM_NOSNAPSHOT

Das System platziert keine binäre Codierung (ein BLOB) des privaten Teils der DEVMODEW-Struktur in das Druckticket, wenn eine DEVMODEW in ein Druckticket konvertiert wird. Verwenden Sie diesen Wert, wenn alle öffentlichen und privaten DEVMODEW-Member vollständig im Druckticket dargestellt sind.

[out] pDevModeFlags

Ein Zeiger auf eine variable Typ vom Typ DWORD, die eine Reihe von Bitflags empfängt, die angeben, welche öffentlichen DEVMODEW-Member nicht vom Shim des Drucktickets in DEVMODEW-zum-Drucken-Ticket oder von Ticket-zu-DEVMODEW-Konvertierungen verarbeitet werden sollen. Ein Bitflag, das in diesem Parameter vorhanden ist, gibt entweder an, dass der Drucker das zugeordnete DEVMODEW-Element nicht unterstützt oder dass der Anbieter diese DEVMODEW-Eigenschaft verarbeitet. Wenn beispielsweise DM_MEDIATYPE in *pDevModeFlags festgelegt ist, unterstützt der Drucker mehrere Medientypen nicht, oder der Anbieter ist für die Unterstützung mehrerer Medientypen verantwortlich. (Alle DM_XXX Bitflags sind in wingdi.h definiert und im Microsoft Windows SDK beschrieben.) Standardmäßig behandelt der Druckticket-Shim alle Member, die im dmFlags-Member der DEVMODEW-Standardstruktur 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 das von ppNamespaces verwiesen 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 wurde erfolgreich ausgeführt.
E_VERSION_NOT_SUPPORTED	Das Plug-In unterstützt nicht die Version des Druckschemas, die im Versionsparameter angegeben ist.

Hinweise

Durch die Bindung an ein Gerät kann der Anbieter bestimmte Objekte und Handles zwischenspeichern, die er für zukünftige Druckticket- oder Gerätefunktionsdienste auf diesem Gerät benötigt. Beispielsweise kann das Druckerhandle im hPrinter-Parameter zwischengespeichert werden. Die IPrintTicketProvider2::BindPrinter-Methode wird garantiert nur einmal aufgerufen.

Der Treiber ist für die Zuweisung von Arbeitsspeicher für das Array verantwortlich, auf das vom parameter ppNamespaces und für die Namespace-URI-Zeichenfolgen verwiesen wird. Das Array sollte mithilfe der Funktion CoTaskMemAlloc zugeordnet werden. Die Namespacezeichenfolgen sollten mithilfe der SysAllocString-Funktion zugeordnet werden. Beide Funktionen werden in der Windows SDK-Dokumentation beschrieben. Das Array, auf das vom ppNamespaces-Parameter verwiesen wird, muss nicht die Namespaces für die Print Schema Keywords oder das Print Schema Framework enthalten.

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