Método IPrintOemUI::D eviceCapabilities (prcomoem.h)
O método IPrintOemUI::DeviceCapabilities permite que um plug-in de interface do usuário especifique recursos personalizados do dispositivo.
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 de 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 de DEVMODEW validada.
pOEMDM
Ponteiro fornecido pelo chamador para os membros da estrutura DEVMODEW privada do plug-in de interface do usuário.
dwOld
O 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.
Valor de retorno
O método deve retornar um dos valores a seguir.
| Código de retorno | Descrição |
|---|---|
|
A operação foi bem-sucedida. |
|
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. |
|
Falha na operação. |
|
O método não é implementado. |
Observações
O método IPrintOemUI::DeviceCapabilities de um plug-in de interface do usuário executa os mesmos tipos de operações que a função DrvDeviceCapabilities exportada por DLLs da interface da impressora no modo de usuário. O método especifica os recursos fornecidos pela impressora.
Você pode usar o método IPrintOemUI::DeviceCapabilities para prever o 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 método IPrintOemUI::DeviceCapabilities indicar suporte personalizado para uma funcionalidade (definindo bits apropriados em resposta a um sinalizador de DC_FIELDS recebido), o código personalizado deverá dar suporte completo à funcionalidade. O suporte completo normalmente inclui o retorno de informações sobre a funcionalidade em resposta a chamadas para o método IPrintOemUI::DeviceCapabilities, além de fornecer o código apropriado do modo de usuário ou do modo kernel para implementar a funcionalidade.
Se IPrintOemUI::DeviceCapabilities 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 IPrintOemUI::DeviceCapabilities de um plug-in é chamado, seu dwOld valor de entrada é o valor retornado do método de IPrintOemUI::DeviceCapabilities do 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 IPrintOemUI::DeviceCapabilities anteriormente chamado ou função drvDeviceCapabilities.
Para que vários plug-ins de interface do usuário funcionem entre si, cada método IPrintOemUI::DeviceCapabilities deve obedecer às seguintes regras:
-
Se um plug-in de interface do usuário não der suporte a uma funcionalidade especificada, seu método
IPrintOemUI::DeviceCapabilitiesdeverá apenas retornar o conteúdo do parâmetro dwOld em dwResult. -
Se um plug-in de interface do usuário der suporte à funcionalidade, seu método
IPrintOemUI::DeviceCapabilitiesdeverá 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 em 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 método
IPrintOemUI::DeviceCapabilitiesdeverá modificar o conteúdo do buffer e retornar um valor de retorno apropriado em 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 em dwResult. - As regras anteriores devem ser seguidas mesmo se o conteúdo recebido de dwOld for GDI_ERROR.
IPrintOemUI::DeviceCapabilities, 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 precisar de controle completo sobre o que é colocado no buffer apontado pelo parâmetro pOutput. Nem o Unidrv nem o driver principal Pscript5 colocarão dados no buffer de de 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 de de DEVMODEW (que é apontada pelo pPublicDM e parâmetros de pOEMDM) indica ao plug-in da interface do usuário que ele deve relatar dados de funcionalidade do dispositivo diferentes dos especificados 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. Em tal 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 ele 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 com 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 completos. Como resultado, o driver principal não coloca nenhum dado no buffer de 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 o valor de retorno S_DEVCAP_OUTPUT_FULL_REPLACEMENT somente para recursos de dispositivo que usam o buffer de pOutput, ou seja, 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 os drivers de impressora da Microsoft.
Requisitos
| Requisito | Valor |
|---|---|
| da Plataforma de Destino | Área de trabalho |
| cabeçalho | prcomoem.h (inclua Prcomoem.h) |