Método IPrintOemPrintTicketProvider::BindPrinter (prcomoem.h)

Artigo
08/07/2023

O método IPrintOemPrintTicketProvider::BindPrinter permite que o driver principal associe um conjunto de URIs (identificadores de recursos uniformes) de namespace privado a um dispositivo. Esse método também permite que o plug-in armazene informações em cache (como o identificador da impressora) que podem ser usadas posteriormente.

Sintaxe

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

Parâmetros

[in] hPrinter

O identificador de impressão do spooler, que é fornecido pela Unidrv. O provedor não deve fechar esse identificador a qualquer momento, pois o cliente do provedor é responsável por gerenciar o tempo de vida desse identificador. O provedor pode armazenar em cache o identificador de impressão; todas as chamadas futuras nesse objeto são relativas à impressora associada a esse identificador.

[in] version

O número de versão principal do esquema de impressão. O Windows Vista dá suporte apenas à versão 1.

[out] pOptions

Um ponteiro para uma variável que recebe um dos seguintes valores enumerados:

OEMPT_DEFAULT

O sistema coloca uma codificação binária (um objeto binário grande [BLOB]) da estrutura DEVMODEW privada no tíquete de impressão em uma conversão de um DEVMODEW em um tíquete de impressão.

OEMPT_NOSNAPSHOT

O sistema não colocará uma codificação binária (um BLOB) da estrutura DEVMODEW privada no tíquete de impressão em uma conversão de DEVMODEW em um tíquete de impressão. Use esse valor se todos os membros de DEVMODEW públicos e privados estiverem totalmente representados no tíquete de impressão.

O objeto OEM que está sendo chamado deve definir o valor apontado por esse parâmetro.

[out] cNamespaces

Um ponteiro para uma variável que recebe o número de URIs de namespace privado que são usadas no plug-in. Esse número representa a contagem de cadeias de caracteres na matriz apontada por *ppNamespaces.

[out] ppNamespaces

Um ponteiro para uma variável que recebe o endereço do primeiro elemento de uma matriz BSTR. O plug-in preenche cada posição da matriz com um URI de namespace. Para obter mais informações sobre esse parâmetro, consulte a seção Comentários a seguir.

Retornar valor

IPrintOemPrintTicketProvider::BindPrinter deve retornar um dos seguintes valores.

Código de retorno	Descrição
S_OK	A operação foi realizada com êxito.
E_VERSION_NOT_SUPPORTED	O plug-in não dá suporte à versão do esquema de impressão especificada no parâmetro de versão .

Comentários

O plug-in é responsável por alocar memória para a matriz apontada pelo parâmetro ppNamespaces e pelas cadeias de caracteres de URI do namespace. A matriz deve ser alocada usando a função CoTaskMemAlloc ; as cadeias de caracteres de namespace devem ser alocadas usando a função SysAllocString . Ambas as funções são descritas na documentação do SDK do Microsoft Windows. A matriz apontada pelo parâmetro ppNamespaces não é necessária para conter os namespaces das palavras-chave do esquema de impressão ou da Estrutura de Esquema de Impressão.

A associação a um dispositivo permite que o provedor armazene em cache determinados objetos e identificadores necessários para futuros serviços de recursos de impressão ou tíquete de impressão nesse dispositivo. Por exemplo, o identificador da impressora no hPrinter pode ser armazenado em cache. IPrintOemPrintTicketProvider::BindPrinter tem a garantia de ser chamado apenas uma vez.

Um objeto IPrintOemPrintTicketProvider não precisa ser capaz de associar mais de uma vez. O gerenciador de tíquetes de impressão sempre usa diferentes instâncias de objeto IPrintOemPrintTicketProvider para associação a dispositivos diferentes. Todos os recursos adquiridos em uma chamada bem-sucedida para IPrintOemPrintTicketProvider::BindPrinter devem ser liberados quando a contagem de referência de um objeto IPrintOemPrintTicketProvider for zero. (Observe que o provedor não deve fechar o identificador que foi passado para a chamada para BindPrinter). O gerenciador de tíquetes de impressão poderá criar vários provedores para o mesmo dispositivo, em versões diferentes, se houver suporte para várias versões.