Função EnumPrinterData
A função EnumPrinterData enumera os dados de configuração de uma impressora especificada.
Para recuperar os dados de configuração em uma única chamada, use a função EnumPrinterDataEx .
Sintaxe
DWORD EnumPrinterData(
_In_ HANDLE hPrinter,
_In_ DWORD dwIndex,
_Out_ LPTSTR pValueName,
_In_ DWORD cbValueName,
_Out_ LPDWORD pcbValueName,
_Out_ LPDWORD pType,
_Out_ LPBYTE pData,
_In_ DWORD cbData,
_Out_ LPDWORD pcbData
);
Parâmetros
-
hPrinter [in]
-
Um identificador para a impressora cujos dados de configuração devem ser obtidos. Use a função OpenPrinter ou AddPrinter para recuperar um identificador de impressora.
-
dwIndex [in]
-
Um valor de índice que especifica o valor de dados de configuração a ser recuperado.
Defina esse parâmetro como zero para a primeira chamada como EnumPrinterData para um identificador de impressora especificado. Em seguida, incremente o parâmetro por um para chamadas subsequentes envolvendo a mesma impressora, até que a função retorne ERROR_NO_MORE_ITEMS. Consulte a seção Comentários a seguir para obter mais informações.
Se você usar a técnica mencionada nas descrições dos parâmetros cbValueName e cbData para obter valores de tamanho de buffer adequados, definindo ambos os parâmetros como zero em uma primeira chamada para EnumPrinterData para um identificador de impressora especificado, o valor de dwIndex não importa para essa chamada. Defina dwIndex como zero na próxima chamada para EnumPrinterData para iniciar o processo de enumeração real.
Os valores de dados de configuração não são ordenados. Novos valores terão um índice arbitrário. Isso significa que a função EnumPrinterData pode retornar valores em qualquer ordem.
-
pValueName [out]
-
Um ponteiro para um buffer que recebe o nome do valor de dados de configuração, incluindo um caractere nulo de terminação.
-
cbValueName [in]
-
O tamanho, em bytes, do buffer apontado por pValueName.
Se você quiser que o sistema operacional forneça um tamanho de buffer adequado, defina esse parâmetro e o parâmetro cbData como zero para a primeira chamada para EnumPrinterData para um identificador de impressora especificado. Quando a função retornar, a variável apontada por pcbValueName conterá um tamanho de buffer grande o suficiente para enumerar com êxito todos os nomes de valor de dados de configuração da impressora.
-
pcbValueName [out]
-
Um ponteiro para uma variável que recebe o número de bytes armazenados no buffer apontado por pValueName.
-
pType [out]
-
Um ponteiro para uma variável que recebe um código que indica o tipo de dados armazenados no valor especificado. Para obter uma lista dos códigos de tipo possíveis, consulte Tipos de valor do Registro. O parâmetro pType poderá ser NULL se o código de tipo não for necessário.
-
pData [out]
-
Um ponteiro para um buffer que recebe o valor de dados de configuração.
Esse parâmetro poderá ser NULL se o valor dos dados de configuração não for necessário.
-
cbData [in]
-
O tamanho, em bytes, do buffer apontado por pData.
Se você quiser que o sistema operacional forneça um tamanho de buffer adequado, defina esse parâmetro e o parâmetro cbValueName como zero para a primeira chamada a EnumPrinterData para um identificador de impressora especificado. Quando a função retornar, a variável apontada por pcbData conterá um tamanho de buffer grande o suficiente para enumerar com êxito todos os nomes de valor de dados de configuração da impressora.
-
pcbData [out]
-
Um ponteiro para uma variável que recebe o número de bytes armazenados no buffer apontado por pData.
Esse parâmetro poderá ser NULL se pData for NULL.
Valor retornado
Se a função obtiver êxito, o valor retornado será ERROR_SUCCESS.
Se a função falhar, o valor retornado será um código de erro do sistema.
A função retorna ERROR_NO_MORE_ITEMS quando não há mais valores de dados de configuração a serem recuperados para um identificador de impressora especificado.
Comentários
Observação
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 fatores de implementação do driver de impressora que são difíceis de prever ao gravar 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.
EnumPrinterData recupera os dados de configuração da impressora definidos pela função SetPrinterData . Os dados de configuração de uma impressora consistem em um conjunto de valores nomeados e tipado. A função EnumPrinterData obtém um desses valores, seu nome e um código de tipo, sempre que você chamá-lo. Chame a função EnumPrinterData várias vezes consecutivas para obter todos os valores de dados de configuração de uma impressora.
Os dados de configuração da impressora são armazenados no registro. Ao enumerar dados de configuração da impressora, você deve evitar chamar funções do Registro que possam alterar esses dados.
Se você quiser que o sistema operacional forneça um tamanho de buffer adequado, primeiro chame EnumPrinterData com os parâmetros cbValueName e cbData definidos como zero, conforme observado anteriormente na seção Parâmetros. O valor de dwIndex não importa para essa chamada. Quando a função retornar, *pcbValueName e *pcbData conterão tamanhos de buffer grandes o suficiente para enumerar todos os valores e nomes de valores de dados de configuração da impressora. Na próxima chamada, aloque o nome do valor e os buffers de dados, defina cbValueName e cbData para os tamanhos em bytes dos buffers alocados e defina dwIndex como zero. Depois disso, continue a chamar a função EnumPrinterData , incrementando dwIndex uma vez, até que a função retorne ERROR_NO_MORE_ITEMS.
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] |
| Cabeçalho |
|
| Biblioteca |
|
| DLL |
|
| Nomes Unicode e ANSI |
EnumPrinterDataW (Unicode) e EnumPrinterDataA (ANSI) |