Método IPrintTicketProvider::BindPrinter (prdrvcom.h)

Artigo
08/07/2023

O método IPrintTicketProvider::BindPrinter associa uma impressora ou fila de impressão a uma versão específica do esquema de tíquete de impressão, o que permite que o driver principal associe um conjunto de URIs (identificadores de recursos uniformes) de namespace privado a um dispositivo.

Sintaxe

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

Parâmetros

[in] hPrinter

A alça de impressão do spooler, que é fornecida pelo driver principal. O provedor não deve fechar esse identificador a qualquer momento porque 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 são relativas à impressora associada a esse identificador.

[in] version

O número de versão principal do tíquete de impressão ou esquema de tíquete de impressão que o gerenciador de tíquetes de impressão solicita ao provedor de plug-in OEM para dar suporte. O Windows Vista dá suporte apenas à versão 1. O provedor deve falhar em qualquer tentativa de associação a uma versão que não dá suporte ou reconhece.

[out] pOptions

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

PTSHIM_DEFAULT

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

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

[out] pDevModeFlags

Um ponteiro para uma variável do tipo DWORD que recebe um conjunto de sinalizadores de bits que indicam quais membros DEVMODEW públicos não devem ser processados pelo shim do tíquete de impressão em conversões de tíquete de impressão ou tíquete de impressão para DEVMODEW. Um sinalizador de bits presente nesse parâmetro indica que a impressora não dá suporte ao membro DEVMODEW associado ou que o provedor manipula essa característica de DEVMODEW. Por exemplo, se DM_MEDIATYPE for definido em *pDevModeFlags, a impressora não oferecerá suporte a vários tipos de mídia ou o provedor será responsável por dar suporte a vários tipos de mídia. (Todos os sinalizadores de bits DM_XXX são definidos em wingdi.h e descritos no SDK do Microsoft Windows.) Por padrão, o shim do tíquete de impressão manipula todos os membros representados no membro dmFlags da estrutura DEVMODEW padrão.

[out] cNamespaces

Um ponteiro para uma variável que recebe o número de URIs de namespace privado que são usados 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 de 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

IPrintTicketProvider::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 especificado no parâmetro version .

Comentários

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 tíquete de impressão ou dispositivo nesse dispositivo. Por exemplo, o identificador da impressora no parâmetro hPrinter pode ser armazenado em cache. O método IPrintTicketProvider::BindPrinter tem a garantia de ser chamado apenas uma vez.

O driver é responsável por alocar memória para a matriz que é 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 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.

Um objeto IPrintTicketProvider 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 IPrintTicketProvider para associação a dispositivos diferentes. Todos os recursos adquiridos em uma chamada bem-sucedida para IPrintTicketProvider::BindPrinter devem ser liberados quando a contagem de referência de um objeto IPrintTicketProvider 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.