Função DrvEnablePDEV (winddi.h)

Artigo
08/27/2023

A função DrvEnablePDEV retorna uma descrição das características do dispositivo físico para a GDI.

Sintaxe

DHPDEV DrvEnablePDEV(
  [in]           DEVMODEW *pdm,
  [in]           LPWSTR   pwszLogAddress,
                 ULONG    cPat,
  [in, optional] HSURF    *phsurfPatterns,
                 ULONG    cjCaps,
  [out]          ULONG    *pdevcaps,
                 ULONG    cjDevInfo,
  [out]          DEVINFO  *pdi,
                 HDEV     hdev,
  [in]           LPWSTR   pwszDeviceName,
                 HANDLE   hDriver
);

Parâmetros

[in] pdm

Ponteiro para uma estrutura DEVMODEW que contém dados de driver.

Para um driver que dá suporte ao Windows NT 4.0, DrvEnablePDEV deve retornar o modo padrão do hardware quando o GDI o chamar com os seguintes membros DEVMODEW definidos como zero: dmBitsPerPel, dmPelsWidth, dmPelsHeight e dmDisplayFrequency.

[in] pwszLogAddress

Para drivers de impressora, aponta para a cadeia de caracteres de endereço lógico que é o nome do usuário para o local no qual o driver está gravando. Os exemplos incluem "LPT1" ou "Minha Impressora".

Os drivers de exibição devem ignorar esse parâmetro.

cPat

Para drivers de impressora, especifica o número de alças de superfície no buffer apontado por phsurfPatterns. O driver não pode acessar a memória além do final do buffer.

Os drivers de exibição devem ignorar esse parâmetro.

[in, optional] phsurfPatterns

Os drivers de exibição devem ignorar esse parâmetro.

Para drivers de impressora, aponta para um buffer que o driver preencherá com alças de superfície que representam os padrões de preenchimento padrão. Os seguintes padrões devem ser definidos na ordem:

Padrão	Descrição
HS_HORIZONTAL	Hachura horizontal.
HS_VERTICAL	Escotilha vertical.
HS_FDIAGONAL	Hachura ascendente de 45 graus (da esquerda para a direita).
HS_BDIAGONAL	Hachura descendente de 45 graus (da esquerda para a direita).
HS_CROSS	Hachura cruzada horizontal e vertical.
HS_DIAGCROSS	Trava cruzada de 45 graus.

Nota O número de padrões de hachura padrão que exigem suporte ao driver foi reduzido em uma versão anterior do DDK (Kit de Desenvolvimento de Driver). Consequentemente, HS_DDI_MAX, normalmente usadas por drivers para declarar o tamanho da matriz padrão, foi reduzida.

A GDI chama DrvRealizeBrush com uma dessas superfícies para perceber um pincel com um padrão padrão.

Cada uma dessas superfícies deve ser um bitmap GDI monocromático (1 bit por pixel) para dispositivos de varredura. O driver do dispositivo deve escolher padrões que se parecerão mais com padrões padrão quando gravados na superfície do dispositivo.

A GDI nunca é necessária para usar esses pincéis em rotinas de suporte para um dispositivo vetor. Portanto, as superfícies podem ser superfícies compatíveis com o dispositivo que o DrvRealizeBrush reconhece como padrão.

cjCaps

Especifica o tamanho do buffer apontado por pdevcaps. O driver não deve acessar a memória além do final do buffer.

[out] pdevcaps

Ponteiro para uma estrutura GDIINFO que será usada para descrever as funcionalidades do dispositivo. O GDI inicializa essa estrutura chamando DrvEnablePDEV.

cjDevInfo

Especifica o número de bytes na estrutura DEVINFO apontada por pdi. O driver não deve modificar mais do que esse número de bytes no DEVINFO.

[out] pdi

Ponteiro para a estrutura DEVINFO , que descreve o driver e o dispositivo físico. O driver só deve alterar os membros que ele entende. A GDI preenche essa estrutura com zeros antes de uma chamada para DrvEnablePDEV.

hdev

Identificador fornecido pela GDI para o dispositivo. Esse identificador deve ser usado como entrada para alguns retornos de chamada GDI, como EngGetDriverName.

[in] pwszDeviceName

Ponteiro para uma cadeia de caracteres terminada em nulo que é o nome legível pelo usuário do dispositivo.

hDriver

Manipule para um dispositivo de saída. Para um driver de exibição, esse é o identificador do dispositivo de exibição. Para um driver de impressora, esse parâmetro deve ser usado como um identificador para a impressora em chamadas para o spooler.

Valor retornado

O valor retornado é um identificador para o PDEV que identifica o dispositivo habilitado se a função for bem-sucedida. Ou seja, DrvEnablePDEV retorna um identificador para as informações de instância de dispositivo privadas definidas pelo driver após o êxito. Caso contrário, retornará NULL.

Comentários

Um driver de dispositivo gráfico pode dar suporte a vários dispositivos físicos anexados a endereços lógicos diferentes. Os drivers também devem dar suporte ao uso simultâneo de diferentes superfícies de desenho.

As finalidades de DrvEnablePDEV são as seguintes:

Para informar a GDI sobre as características físicas do dispositivo.
Para criar uma estrutura PDEV privada que descreve a instância do dispositivo atual (com base na estrutura DEVMODE recebida e no nome do dispositivo).

Quando a GDI chama posteriormente outras funções DDI gráficas, ela fornece o identificador retornado por DrvEnablePDEV como entrada (geralmente dentro de uma estrutura SURFOBJ) para que o driver possa identificar a instância do dispositivo.

Um único dispositivo lógico pode gerenciar vários PDEVs que podem ser diferenciados pelo seguinte:

Tipo de hardware – um único driver de dispositivo pode dar suporte a "LaserWhiz", "LaserWhiz II" e "LaserWhiz Super".
Endereço lógico – um único driver de dispositivo pode dar suporte a impressoras anexadas a "LPT1", "COM2", "\SERVER1\PSLAZER" e assim por diante. Um driver de exibição que pode dar suporte a mais de uma exibição VGA simultaneamente pode diferenciá-los de acordo com os números da porta; por exemplo, 0x3CE ou 0x2CE.
Surfaces – um driver de impressora pode processar dois trabalhos de impressão simultaneamente. As duas superfícies representam duas páginas que serão impressas. Da mesma forma, um driver de dispositivo de exibição pode dar suporte a duas áreas de trabalho no mesmo dispositivo.

Ao receber uma chamada para essa função, o driver deve alocar a memória para dar suporte ao PDEV. No entanto, a superfície real não precisa ter suporte até que a GDI chame DrvEnableSurface.

Se uma superfície de dispositivo exigir que um bitmap seja alocado, essas alocações não precisarão ser feitas até que seja necessário. Embora os aplicativos geralmente solicitem informações do dispositivo muito antes de realmente gravar no dispositivo, esperar para alocar recursos, como bitmaps grandes, pode conservar memória.

O GDI inicializa zero o buffer apontado por phsurfPatterns antes de chamar essa função.

DrvEnablePDEV é necessário para drivers gráficos.