Compartilhar via


Função DeviceCapabilitiesA (wingdi.h)

A função DeviceCapabilities recupera os recursos de um driver de impressora.

Sintaxe

int DeviceCapabilitiesA(
  [in]  LPCSTR         pDevice,
  [in]  LPCSTR         pPort,
  [in]  WORD           fwCapability,
  [out] LPSTR          pOutput,
  [in]  const DEVMODEA *pDevMode
);

Parâmetros

[in] pDevice

Um ponteiro para uma cadeia de caracteres terminada em nulo que contém o nome da impressora. Observe que esse é o nome da impressora, não do driver da impressora.

[in] pPort

Um ponteiro para uma cadeia de caracteres terminada em nulo que contém o nome da porta à qual o dispositivo está conectado, como LPT1.

[in] fwCapability

Os recursos a serem consultados. Esse parâmetro pode usar um dos valores a seguir.

Valor Significado
DC_BINNAMES
Recupera os nomes dos compartimentos de papel da impressora. O buffer pOutput recebe uma matriz de buffers de cadeia de caracteres. Cada buffer de cadeia de caracteres tem 24 caracteres e contém o nome de uma lixeira de papel. O valor retornado indica o número de entradas na matriz. As cadeias de caracteres de nome são terminadas em nulo, a menos que o nome seja de 24 caracteres. Se pOutput for NULL, o valor retornado será o número de entradas de compartimento necessárias.
DC_BINS
Recupera uma lista de compartimentos de papel disponíveis. O buffer pOutput recebe uma matriz de valores WORD que indicam as fontes de papel disponíveis para a impressora. O valor retornado indica o número de entradas na matriz. Para obter uma lista dos possíveis valores de matriz, consulte a descrição do membro dmDefaultSource da estrutura DEVMODE . Se pOutput for NULL, o valor retornado indicará o número necessário de entradas na matriz.
DC_COLLATE
Se a impressora der suporte à agrupamento, o valor retornado será 1; caso contrário, o valor retornado será zero. O parâmetro pOutput não é usado.
DC_COLORDEVICE
Se a impressora der suporte à impressão de cores, o valor retornado será 1; caso contrário, o valor retornado será zero. O parâmetro pOutput não é usado.
DC_COPIES
Retorna o número de cópias que o dispositivo pode imprimir.
DC_DRIVER
Retorna o número de versão do driver de impressora.
DC_DUPLEX
Se a impressora der suporte à impressão duplex, o valor retornado será 1; caso contrário, o valor retornado será zero. O parâmetro pOutput não é usado.
DC_ENUMRESOLUTIONS
Recupera uma lista das resoluções compatíveis com a impressora. O buffer pOutput recebe uma matriz de valores LONG . Para cada resolução com suporte, a matriz contém um par de valores LONG que especificam as dimensões x e y da resolução, em pontos por polegada. O valor retornado indica o número de resoluções com suporte. Se pOutput for NULL, o valor retornado indicará o número de resoluções com suporte.
DC_EXTRA
Retorna o número de bytes necessários para a parte específica do dispositivo da estrutura DEVMODE para o driver de impressora.
DC_FIELDS
Retorna o membro dmFields da estrutura DEVMODE do driver de impressora. O membro dmFields indica quais membros na parte independente do dispositivo da estrutura têm suporte do driver de impressora.
DC_FILEDEPENDENCIES
Recupera os nomes de todos os arquivos adicionais que precisam ser carregados quando um driver é instalado. O buffer pOutput recebe uma matriz de buffers de cadeia de caracteres. Cada buffer de cadeia de caracteres tem 64 caracteres e contém o nome de um arquivo. O valor retornado indica o número de entradas na matriz. As cadeias de caracteres de nome são terminadas em nulo, a menos que o nome seja de 64 caracteres. Se pOutput for NULL, o valor retornado será o número de arquivos.
DC_MAXEXTENT
Retorna o tamanho máximo do papel que os membros dmPaperLength e dmPaperWidth da estrutura DEVMODE do driver de impressora podem especificar. O LOWORD do valor retornado contém o valor máximo de dmPaperWidth e HIWORD contém o valor máximo de dmPaperLength .
DC_MEDIAREADY
Recupera os nomes dos formulários de papel que estão disponíveis para uso no momento. O buffer pOutput recebe uma matriz de buffers de cadeia de caracteres. Cada buffer de cadeia de caracteres tem 64 caracteres e contém o nome de um formulário de papel. O valor retornado indica o número de entradas na matriz. As cadeias de caracteres de nome são terminadas em nulo, a menos que o nome seja de 64 caracteres. Se pOutput for NULL, o valor retornado será o número de formulários de papel.
DC_MEDIATYPENAMES
Recupera os nomes dos tipos de mídia com suporte. O buffer pOutput recebe uma matriz de buffers de cadeia de caracteres. Cada buffer de cadeia de caracteres tem 64 caracteres e contém o nome de um tipo de mídia com suporte. O valor retornado indica o número de entradas na matriz. As cadeias de caracteres são terminadas em nulo, a menos que o nome seja de 64 caracteres. Se pOutput for NULL, o valor retornado será o número de nomes de tipo de mídia necessários.
DC_MEDIATYPES
Recupera uma lista de tipos de mídia com suporte. O buffer pOutput recebe uma matriz de valores DWORD que indicam os tipos de mídia com suporte. O valor retornado indica o número de entradas na matriz. Para obter uma lista de possíveis valores de matriz, consulte a descrição do membro dmMediaType da estrutura DEVMODE . Se pOutput for NULL, o valor retornado indicará o número necessário de entradas na matriz.
DC_MINEXTENT
Retorna o tamanho mínimo do papel que os membros dmPaperLength e dmPaperWidth da estrutura DEVMODE do driver de impressora podem especificar. O LOWORD do valor retornado contém o valor mínimo dmPaperWidth e o HIWORD contém o valor mínimo de dmPaperLength .
DC_ORIENTATION
Retorna a relação entre as orientações retrato e paisagem de um dispositivo, em termos do número de graus em que a orientação retrato é girada no sentido anti-horário para produzir orientação paisagem. O valor de retorno pode ser um dos seguintes:
0
Sem orientação paisagem.
90
Retrato gira 90 graus para produzir paisagem.
270
Retrato gira 270 graus para produzir paisagem.
DC_NUP
Recupera uma matriz de inteiros que indicam a capacidade da impressora de imprimir várias páginas de documento por página impressa. O buffer pOutput recebe uma matriz de valores DWORD . Cada valor representa um número com suporte de páginas de documento por página impressa. O valor retornado indica o número de entradas na matriz. Se pOutput for NULL, o valor retornado indicará o número necessário de entradas na matriz.
DC_PAPERNAMES
Recupera uma lista de nomes de papel com suporte (por exemplo, Carta ou Legal). O buffer pOutput recebe uma matriz de buffers de cadeia de caracteres. Cada buffer de cadeia de caracteres tem 64 caracteres e contém o nome de um formulário de papel. O valor retornado indica o número de entradas na matriz. As cadeias de caracteres de nome são terminadas em nulo, a menos que o nome seja de 64 caracteres. Se pOutput for NULL, o valor retornado será o número de formulários de papel.
DC_PAPERS
Recupera uma lista de tamanhos de papel com suporte. O buffer pOutput recebe uma matriz de valores WORD que indicam os tamanhos de papel disponíveis para a impressora. O valor retornado indica o número de entradas na matriz. Para obter uma lista dos possíveis valores de matriz, consulte a descrição do membro dmPaperSize da estrutura DEVMODE . Se pOutput for NULL, o valor retornado indicará o número necessário de entradas na matriz.
DC_PAPERSIZE
Recupera as dimensões, em décimos de milímetro, de cada tamanho de papel com suporte. O buffer pOutput recebe uma matriz de estruturas POINT . Cada estrutura contém a largura (dimensão x) e o comprimento (dimensão y) de um tamanho de papel como se o papel estivesse na orientação DMORIENT_PORTRAIT . O valor retornado indica o número de entradas na matriz.
DC_PERSONALITY
Recupera uma lista de idiomas de descrição da impressora compatíveis com a impressora. O buffer pOutput recebe uma matriz de buffers de cadeia de caracteres. Cada buffer tem 32 caracteres e contém o nome de um idioma de descrição da impressora. O valor retornado indica o número de entradas na matriz. As cadeias de caracteres de nome são terminadas em nulo, a menos que o nome seja de 32 caracteres. Se pOutput for NULL, o valor retornado indicará o número necessário de entradas de matriz.
DC_PRINTERMEM
O valor retornado é a quantidade de memória da impressora disponível, em quilobytes. O parâmetro pOutput não é usado.
DC_PRINTRATE
O valor retornado indica a taxa de impressão da impressora. O valor retornado para DC_PRINTRATEUNIT indica as unidades do valor DC_PRINTRATE . O parâmetro pOutput não é usado.
DC_PRINTRATEPPM
O valor retornado indica a taxa de impressão da impressora, em páginas por minuto. O parâmetro pOutput não é usado.
DC_PRINTRATEUNIT
O valor retornado é um dos valores a seguir que indicam as unidades de taxa de impressão para o valor retornado para o sinalizador DC_PRINTRATE . O parâmetro pOutput não é usado.
PRINTRATEUNIT_CPS
Caracteres por segundo.
PRINTRATEUNIT_IPM
Polegadas por minuto.
PRINTRATEUNIT_LPM
Linhas por minuto.
PRINTRATEUNIT_PPM
Páginas por minuto.
DC_SIZE
Retorna o membro dmSize da estrutura DEVMODE do driver de impressora.
DC_STAPLE
Se a impressora der suporte a stapling, o valor retornado será um valor diferente de zero; caso contrário, o valor retornado será zero. O parâmetro pOutput não é usado.
DC_TRUETYPE
Recupera as habilidades do driver para usar fontes TrueType. Para DC_TRUETYPE, o parâmetro pOutput deve ser NULL. O valor retornado pode ser um ou mais dos seguintes:
DCTT_BITMAP
O dispositivo pode imprimir fontes TrueType como gráficos.
DCTT_DOWNLOAD
O dispositivo pode baixar fontes TrueType.
DCTT_SUBDEV
O dispositivo pode substituir fontes de dispositivo por fontes TrueType.
DC_VERSION
Retorna a versão de especificação à qual o driver de impressora está em conformidade.

[out] pOutput

Um ponteiro para uma matriz. O formato da matriz depende da configuração do parâmetro fwCapability . Consulte cada funcionalidade acima para descobrir o que será retornado se pOutput for NULL.

[in] pDevMode

Um ponteiro para uma estrutura DEVMODE . Se esse parâmetro for NULL, DeviceCapabilities recuperará os valores de inicialização padrão atuais para o driver de impressora especificado. Caso contrário, a função recuperará os valores contidos na estrutura para a qual pDevMode aponta.

Retornar valor

Se a função for bem-sucedida, o valor retornado dependerá da configuração do parâmetro fwCapability . Um valor retornado de zero geralmente indica que, embora a função tenha sido concluída com êxito, houve algum tipo de falha, como uma funcionalidade sem suporte. Para obter mais detalhes, confira as descrições dos valores de fwCapability .

Se a função retornar -1, isso pode significar que a funcionalidade não tem suporte ou que houve uma falha geral da função.

Comentários

Nota Essa é uma função de bloqueio ou síncrona e pode não retornar imediatamente. A rapidez com que essa função retorna depende de fatores de tempo de execução, como status de rede, configuração do servidor de impressão e implementação de driver de impressora, fatores difíceis de prever ao escrever um aplicativo. Chamar essa função de um thread que gerencia a interação com a interface do usuário pode fazer com que o aplicativo pareça não responder.
 
A estrutura DEVMODE apontada pelo parâmetro pDevMode pode ser obtida chamando a função DocumentProperties .

Se um driver de impressora der suporte a recursos de dispositivo personalizados, o driver deverá chamar a função SetPrinterData para cada funcionalidade personalizada. A função SetPrinterData adiciona os dados de impressora apropriados ao sistema de impressão, o que permite que aplicativos de 32 bits acessem os recursos personalizados em instalações do Windows de 64 bits.

Para cada funcionalidade personalizada, primeiro você deve adicionar dados de impressora que descrevam o tipo da funcionalidade. Para fazer isso, ao chamar SetPrinterData, defina a cadeia de caracteres pValueName como CustomDeviceCapabilityType_Xxx, em que "Xxx" é a representação hexadecimal da funcionalidade. Por exemplo, você pode ter "CustomDeviceCapabilityType_1234". Os dados do Registro definidos devem ser do tipo REG_DWORD e você deve definir seu valor como um dos seguintes:

  • 0, se a funcionalidade personalizada for um DWORD
  • 1, se a funcionalidade personalizada for um buffer de bytes
  • 2, se a funcionalidade personalizada for uma matriz de itens
Se a funcionalidade personalizada for uma matriz de itens, você deverá chamar SetPinterData uma segunda vez para fornecer informações sobre o tamanho de um item na matriz. Para fazer isso, quando você chama SetPinterData, a cadeia de caracteres pValueName que você fornece deve ser "CustomDeviceCapabilitySize_Xxx" em que Xxx é a representação hexadecimal da funcionalidade. Por exemplo, você pode ter "CustomDeviceCapabilitySize_1234". Os dados do Registro definidos devem ser do tipo REG_DWORD e você deve definir seu valor para o tamanho em bytes de um item na matriz.

Observação

O cabeçalho wingdi.h define DeviceCapabilities como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho wingdi.h (inclua Windows.h)
Biblioteca WinSpool.lib
DLL WinSpool.drv

Confira também

DEVMODE

DOCINFO

Documentproperties

Getdevicecaps

GetProcAddress

LoadLibrary

PONTO

Funções da API do Spooler de impressão

Impressão

Startdoc