Compartilhar via

Método IPrintOemUI::D eviceCapabilities (prcomoem.h)

  • Artigo

O IPrintOemUI::DeviceCapabilities método permite que um plug-in de interface do usuário especifique recursos de dispositivo personalizados.

Sintaxe

HRESULT DeviceCapabilities(
  POEMUIOBJ poemuiobj,
  HANDLE    hPrinter,
  PWSTR     pDeviceName,
  WORD      wCapability,
  PVOID     pOutput,
  PDEVMODE  pPublicDM,
  PVOID     pOEMDM,
  DWORD     dwOld,
  DWORD     *dwResult
);

Parâmetros

poemuiobj

Ponteiro fornecido pelo chamador para uma estrutura OEMUIOBJ .

hPrinter

Identificador fornecido pelo chamador para o dispositivo de impressora.

pDeviceName

Ponteiro fornecido pelo chamador para uma cadeia de caracteres que representa o nome do dispositivo.

wCapability

Sinalizador fornecido pelo chamador indicando o tipo de informação que o método deve retornar. Para obter uma lista de sinalizadores, consulte a descrição da função DrvDeviceCapabilities .

pOutput

Ponteiro fornecido pelo chamador para um buffer para receber as informações solicitadas. O tipo de informação retornada depende do sinalizador especificado por wCapability.

pPublicDM

Ponteiro fornecido pelo chamador para uma estrutura DEVMODEW validada.

pOEMDM

Ponteiro fornecido pelo chamador para os membros da estrutura DEVMODEW privada do plug-in de interface do usuário.

dwOld

Valor retornado fornecido pelo chamador da função DrvDeviceCapabilities do driver de impressora ou de outro plug-in de interface do usuário. Para obter mais informações, consulte a seção Comentários a seguir.

dwResult

Um valor retornado que depende do sinalizador especificado por wCapability. Para obter mais informações, consulte a descrição da função DrvDeviceCapabilities e a seção Comentários a seguir.

Retornar valor

O método deve retornar um dos valores a seguir.

Código de retorno Descrição
S_OK
 A operação foi realizada com êxito.
S_DEVCAP_OUTPUT_FULL_REPLACEMENT
 O plug-in pretende usar o buffer apontado pelo parâmetro pOutput para suas próprias finalidades. Esse valor retornado é definido em prcomoem.h. Para obter mais informações sobre quando usar esse valor retornado, consulte a seção Comentários a seguir.
E_FAIL
 Falha na operação.
E_NOTIMPL
 O método não está implementado.

Comentários

O método de um plug-in de interface do IPrintOemUI::DeviceCapabilities usuário executa os mesmos tipos de operações que a função DrvDeviceCapabilities exportada por DLLs da interface da impressora do modo de usuário. O método especifica os recursos fornecidos pela impressora.

Você pode usar o IPrintOemUI::DeviceCapabilities método para preempção de suporte Unidrv para uma funcionalidade ou para adicionar uma funcionalidade que o driver de impressora não fornece. O driver chama IPrintOemUI::DeviceCapabilities de dentro de sua função DrvDeviceCapabilities .

Se o IPrintOemUI::DeviceCapabilities método indicar suporte personalizado para uma funcionalidade (definindo os bits apropriados em resposta a um sinalizador de DC_FIELDS recebido), o código personalizado deverá dar suporte total à funcionalidade. O suporte completo normalmente inclui o retorno de informações sobre a funcionalidade em resposta a chamadas para o IPrintOemUI::DeviceCapabilities método, além de fornecer o código apropriado do modo de usuário ou do modo kernel para implementar a funcionalidade.

Se IPrintOemUI::DeviceCapabilities os métodos forem exportados por vários plug-ins de interface do usuário, os métodos serão chamados na ordem em que os plug-ins são especificados para instalação. Sempre que o método de IPrintOemUI::DeviceCapabilities um plug-in é chamado, seu valor de entrada dwOld é o valor retornado do método do IPrintOemUI::DeviceCapabilities plug-in chamado anteriormente. Para o primeiro plug-in chamado, dwOld contém o valor retornado da função DrvDeviceCapabilities do driver de impressora. Da mesma forma, o buffer apontado por pOutput contém, na entrada, qualquer conteúdo colocado lá por um método chamado IPrintOemUI::DeviceCapabilities anteriormente ou função DrvDeviceCapabilities .

Para que vários plug-ins de interface do usuário funcionem entre si, cada IPrintOemUI::DeviceCapabilities método deve obedecer às seguintes regras:

  • Se um plug-in de interface do usuário não der suporte a uma funcionalidade especificada, seu IPrintOemUI::DeviceCapabilities método deverá retornar apenas o conteúdo do parâmetro dwOld no dwResult.
  • Se um plug-in de interface do usuário der suporte à funcionalidade, seu IPrintOemUI::DeviceCapabilities método deverá ignorar dwOld e o conteúdo do buffer apontado por pOutput. Ele deve fornecer um valor retornado e um conteúdo de buffer apropriado para indicar que ele dá suporte à funcionalidade especificada. Se o método detectar um erro, ele deverá retornar GDI_ERROR no dwResult.
  • Se você quiser que um plug-in de interface do usuário modifique as informações de recursos recebidas no buffer apontado por pOutput, seu IPrintOemUI::DeviceCapabilities método deverá modificar o conteúdo do buffer e retornar um valor retornado apropriado no dwResult. Por exemplo, se wCapability for DC_FIELDS, o método deverá OU os bits necessários para definir com os bits definidos em dwOld e retornar o resultado da operação OR no dwResult.
  • As regras anteriores devem ser seguidas mesmo se o conteúdo recebido de dwOld for GDI_ERROR.
Quando a função DrvDeviceCapabilities do driver é chamada com o sinalizador DC_FIELDS definido, a função chama todos os IPrintOemUI::DeviceCapabilities métodos, especificando também DC_FIELDS e retorna a união de todos os bits definidos para o chamador.

O valor retornado S_DEVCAP_OUTPUT_FULL_REPLACEMENT é novo no Windows Vista e se aplica a plug-ins de interface do usuário Unidrv e Pscript5. Um plug-in deve usar o valor retornado S_DEVCAP_OUTPUT_FULL_REPLACEMENT somente se exigir controle completo sobre o que é colocado no buffer apontado pelo parâmetro pOutput . Nem o Unidrv nem o driver de núcleo Pscript5 colocarão dados no buffer pOutput quando o plug-in retornar S_DEVCAP_OUTPUT_FULL_REPLACEMENT. Um plug-in pode precisar retornar esse valor quando uma configuração na estrutura DEVMODEW (que é apontada pelos parâmetros pPublicDM e pOEMDM ) indica ao plug-in da interface do usuário que deve relatar dados de funcionalidade do dispositivo diferentes daquele especificado no arquivo GPD ou PPD. Por exemplo, uma estrutura DEVMODEW que especifica a impressão de fotos pode exigir um conjunto diferente de tipos de papel do que aqueles especificados no arquivo GPD ou PPD. Nessa situação e independentemente dos valores dos parâmetros pOutput e dwOld , o plug-in deve retornar S_DEVCAP_OUTPUT_FULL_REPLACEMENT e deve definir o parâmetro dwResult para o número de tipos de papel que pretende relatar. Se pOutput não for NULL, o plug-in também deverá preencher o buffer apontado por pOutput com o conjunto desejado de tipos de papel e deve definir dwResult como o número de tipos de papel que o plug-in pretende relatar.

Quando vários plug-ins de interface do usuário estão ativos ao mesmo tempo e um deles retorna S_DEVCAP_OUTPUT_FULL_REPLACEMENT, o driver principal Unidrv ou Pscript5 interpreta esse valor retornado para significar que os plug-ins pretendem fornecer dados de saída de substituição completa. Como resultado, o driver principal não coloca nenhum dado no buffer pOutput antes de chamar os plug-ins. (O driver principal chama os plug-ins na mesma ordem especificada para sua instalação.)

Em situações em que os valores que o driver principal coloca no buffer pOutput não precisam ser substituídos, o plug-in deve retornar S_OK. Os drivers principais Unidrv e Pscript5 reconhecem a S_DEVCAP_OUTPUT_FULL_REPLACEMENT valor retornado somente para recursos de dispositivo que usam o buffer pOutput , em outras palavras, quando o parâmetro wCapability é definido como um dos seguintes sinalizadores:

DC_PAPERNAMES

DC_PAPERS

DC_PAPERSIZE

DC_BINNAMES

DC_BINS

DC_NUP

DC_PERSONALITY

DC_MEDIAREADY

DC_MEDIATYPENAMES

DC_MEDIATYPES

DC_ENUMRESOLUTIONS

Para obter mais informações sobre como criar e instalar plug-ins de interface do usuário, consulte Personalizando drivers de impressora da Microsoft.

Requisitos

Requisito Valor
Plataforma de Destino Área de Trabalho
Cabeçalho prcomoem.h (inclua Prcomoem.h)

Confira também

DrvDeviceCapabilities

IPrintOemUI