IPrintOemPrintTicketProvider::BindPrinter-Methode (prcomoem.h)

Artikel
08/07/2023

Die IPrintOemPrintTicketProvider::BindPrinter-Methode ermöglicht es dem Kerntreiber, einem Gerät eine Reihe von privaten Namespace-URIs (Uniform Resource Identifiers) zuzuordnen. Diese Methode ermöglicht es dem Plug-In auch, Informationen (z. B. das Druckerhandle) zwischenzuspeichern, die zu einem späteren Zeitpunkt verwendet werden können.

Syntax

HRESULT BindPrinter(
  [in]  HANDLE     hPrinter,
  [in]  INT        version,
  [out] POEMPTOPTS pOptions,
  [out] INT        *cNamespaces,
  [out] BSTR       **ppNamespaces
);

Parameter

[in] hPrinter

Der Druckhandle des Spoolers, der von Unidrv geliefert wird. Der Anbieter sollte dieses Handle nicht zu einem beliebigen 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 dieses Objekts sind relativ zum Drucker, der diesem Handle zugeordnet ist.

[in] version

Die Hauptversionsnummer des Druckschemas. Windows Vista unterstützt nur Version 1.

[out] pOptions

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

OEMPT_DEFAULT

Das System platziert eine binäre Codierung (ein binäres großes Objekt [BLOB]) der privaten DEVMODEW-Struktur im Druckticket bei einer Konvertierung eines DEVMODEW-Objekts in ein Druckticket.

OEMPT_NOSNAPSHOT

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

Das aufgerufene OEM-Objekt sollte den Wert festlegen, auf den dieser Parameter verweist.

[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 in dem 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. Weitere Informationen zu diesem Parameter finden Sie im abschnitt Hinweise.

Rückgabewert

IPrintOemPrintTicketProvider::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

Das Plug-In 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 Microsoft Windows SDK-Dokumentation beschrieben. Das Array, auf das vom parameter ppNamespaces verwiesen wird, muss nicht die Namespaces für die Print Schema Keywords oder das Print Schema Framework enthalten.

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

Ein IPrintOemPrintTicketProvider-Objekt muss nicht mehr als einmal gebunden werden können. Der Druckticket-Manager verwendet immer unterschiedliche IPrintOemPrintTicketProvider-Objektinstanzen für die Bindung an verschiedene Geräte. Alle Ressourcen, die in einem erfolgreichen Aufruf von IPrintOemPrintTicketProvider::BindPrinter abgerufen werden, sollten freigegeben werden, wenn die Verweisanzahl eines IPrintOemPrintTicketProvider-Objekts 0 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.