Метод IPrintTicketProvider2::BindPrinter (prdrvcom.h)

Статья
08/07/2023

Метод IPrintTicketProvider2::BindPrinter привязывает принтер или очередь печати к определенной версии схемы билета печати, что позволяет основному драйверу связать набор универсальных кодов ресурса (URI) частного пространства имен с устройством.

Синтаксис

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
);

Параметры

[in] hPrinter

Дескриптор печати очереди, который предоставляется основным драйвером. Поставщик не должен закрывать этот дескриптор в любое время, так как клиент поставщика отвечает за управление временем существования этого дескриптора. Поставщик может кэшировать дескриптор печати; все будущие вызовы относятся к принтеру, связанному с этим дескриптором.

[in] version

Основной номер версии билета печати или схемы билета печати, которую диспетчер билетов печати запрашивает у поставщика подключаемых модулей OEM. Windows Vista поддерживает только версию 1. Поставщик должен завершиться ошибкой при любой попытке привязки к версии, которую он не поддерживает или не распознает.

[out] pOptions

Указатель на переменную, которая получает одно из следующих перечисленных значений:

PTSHIM_DEFAULT

Система помещает двоичную кодировку (большой двоичный объект — большой двоичный объект) частной части структуры DEVMODEW в билет печати при преобразовании DEVMODEW в билет печати.
PTSHIM_NOSNAPSHOT

Система не будет помещать двоичную кодировку (BLOB) частной части структуры DEVMODEW в билет печати при преобразовании DEVMODEW в билет печати. Используйте это значение, если все открытые и частные члены DEVMODEW полностью представлены в билете печати.

[out] pDevModeFlags

Указатель на переменную типа DWORD, которая получает набор битовых флагов, указывающих, какие общедоступные члены DEVMODEW не должны обрабатываться оболочкой билета печати при преобразованиях DEVMODEW в печать или print ticket-to-DEVMODEW. Битовый флаг, который присутствует в этом параметре, указывает, что принтер не поддерживает связанный член DEVMODEW или что поставщик обрабатывает эту характеристику DEVMODEW. Например, если DM_MEDIATYPE задано в *pDevModeFlags, принтер не поддерживает несколько типов носителей или поставщик отвечает за поддержку нескольких типов мультимедиа. (Все DM_XXX битовые флаги определены в wingdi.h и описаны в Microsoft Windows SDK.) По умолчанию оболочка билета печати обрабатывает все члены, представленные в элементе dmFlags структуры DEVMODEW по умолчанию.

[out] cNamespaces

Указатель на переменную, получающую количество URI частного пространства имен, используемых в подключаемом модуле. Это число представляет количество строк в массиве, на который указывает ppNamespaces.

[out] ppNamespaces

Указатель на переменную, получающую адрес первого элемента массива BSTR. Подключаемый модуль заполняет каждую позицию массива универсальным кодом ресурса (URI) пространства имен. Дополнительные сведения об этом параметре см. в следующем разделе Примечаний.

Возвращаемое значение

IPrintTicketProvider2::BindPrinter должен возвращать одно из следующих значений:

Код возврата	Описание
S_OK	Операция успешно выполнена.
E_VERSION_NOT_SUPPORTED	Подключаемый модуль не поддерживает версию схемы печати, указанную в параметре version .

Привязка к устройству позволяет поставщику кэшировать определенные объекты и обрабатывать, которые потребуются ему для будущих служб печати билетов или возможностей устройства на этом устройстве. Например, дескриптор принтера в параметре hPrinter можно кэшировать. Метод IPrintTicketProvider2::BindPrinter гарантированно вызывается только один раз.

Драйвер отвечает за выделение памяти для массива, на который указывает параметр ppNamespaces, и для строк URI пространства имен. Массив должен быть выделен с помощью функции CoTaskMemAlloc ; строки пространства имен должны выделяться с помощью функции SysAllocString . Обе функции описаны в документации windows SDK. Массив, на который указывает параметр ppNamespaces, не обязательно должен содержать пространства имен для ключевых слов схемы печати или платформы схемы печати.

Объект IPrintTicketProvider2 не обязательно должен иметь возможность привязывать несколько раз. Диспетчер билетов печати всегда использует разные экземпляры объектов IPrintTicketProvider2 для привязки к разным устройствам. Все ресурсы, полученные в результате успешного вызова IPrintTicketProvider2::BindPrinter , должны быть освобождены, если количество ссылок объекта IPrintTicketProvider2 равно нулю. Обратите внимание, что поставщик не должен закрывать дескриптор, переданный в вызов BindPrinter. Диспетчер билетов печати может создать несколько поставщиков для одного устройства в разных версиях, если поддерживается несколько версий.