Função EnumPrinters
A função EnumPrinters enumera impressoras disponíveis, servidores de impressão, domínios ou provedores de impressão.
Sintaxe
BOOL EnumPrinters(
_In_ DWORD Flags,
_In_ LPTSTR Name,
_In_ DWORD Level,
_Out_ LPBYTE pPrinterEnum,
_In_ DWORD cbBuf,
_Out_ LPDWORD pcbNeeded,
_Out_ LPDWORD pcReturned
);
Parâmetros
-
Sinalizadores [in]
-
Os tipos de objetos de impressão que a função deve enumerar. Esse valor pode ser um ou mais dos valores a seguir.
Valor Significado - PRINTER_ENUM_LOCAL
Se o sinalizador PRINTER_ENUM_NAME também não for passado, a função ignorará o parâmetro Name e enumera as impressoras instaladas localmente. Se PRINTER_ENUM_NAME também for passado, a função enumera as impressoras locais em Nome. - PRINTER_ENUM_NAME
A função enumera a impressora identificada por Name. Isso pode ser um servidor, um domínio ou um provedor de impressão. Se Name for NULL, a função enumera os provedores de impressão disponíveis. - PRINTER_ENUM_SHARED
A função enumera impressoras que têm o atributo compartilhado. Não pode ser usado isoladamente; use uma operação OR para combinar com outro tipo de PRINTER_ENUM. - PRINTER_ENUM_CONNECTIONS
A função enumera a lista de impressoras às quais o usuário fez conexões anteriores. - PRINTER_ENUM_NETWORK
A função enumera impressoras de rede no domínio do computador. Esse valor só será válido se Level for 1. - PRINTER_ENUM_REMOTE
A função enumera impressoras de rede e servidores de impressão no domínio do computador. Esse valor só será válido se Level for 1. - PRINTER_ENUM_CATEGORY_3D
A função enumera apenas impressoras 3D. - PRINTER_ENUM_CATEGORY_ALL
A função enumera todos os dispositivos de impressão, incluindo impressoras 3D. Se Level for 4, você só poderá usar as constantes PRINTER_ENUM_CONNECTIONS e PRINTER_ENUM_LOCAL.
Observação
Os dispositivos de impressão 3D não são enumerados por padrão. Você deve incluir PRINTER_ENUM_CATEGORY_3D e PRINTER_ENUM_LOCAL para enumerar apenas impressoras 3D. Para incluir impressoras 3D, juntamente com todas as outras impressoras locais, use PRINTER_ENUM_CATEGORY_ALL e PRINTER_ENUM_LOCAL.
-
Nome [in]
-
Se Level for 1, Flags conterá PRINTER_ENUM_NAME e Name não for NULL, Name será um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do objeto a ser enumerado. Essa cadeia de caracteres pode ser o nome de um servidor, um domínio ou um provedor de impressão.
Se Level for 1, Flags conterá PRINTER_ENUM_NAME e Nome for NULL, a função enumera os provedores de impressão disponíveis.
Se Level for 1, Flags conterá PRINTER_ENUM_REMOTE e Nome for NULL, a função enumera as impressoras no domínio do usuário.
Se Level for 2 ou 5, Name será um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome de um servidor cujas impressoras devem ser enumeradas. Se essa cadeia de caracteres for NULL, a função enumera as impressoras instaladas no computador local.
Se Level for 4, Name deverá ser NULL. A função sempre consulta no computador local.
Quando Name for NULL, configure Sinalizadores como PRINTER_ENUM_LOCAL | PRINTER_ENUM_CONNECTIONS enumera impressoras instaladas no computador local. Essas impressoras incluem aquelas que estão fisicamente anexadas ao computador local, bem como impressoras remotas às quais ela tem uma conexão de rede.
Quando Name não for NULL, configure Sinalizadores como PRINTER_ENUM_LOCAL | PRINTER_ENUM_NAME enumera as impressoras locais instaladas no Nome do servidor.
-
Nível [in]
-
O tipo de estruturas de dados apontadas por pPrinterEnum. Os valores válidos são 1, 2, 4 e 5, que correspondem às estruturas de dados PRINTER_INFO_1, PRINTER_INFO_2 , PRINTER_INFO_4 e PRINTER_INFO_5 .
Esse valor pode ser 1, 2, 4 ou 5.
-
pPrinterEnum [out]
-
Um ponteiro para um buffer que recebe uma matriz de estruturas de PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_4 ou PRINTER_INFO_5 . Cada estrutura contém dados que descrevem um objeto de impressão disponível.
Se Level for 1, a matriz conterá PRINTER_INFO_1 estruturas. Se Level for 2, a matriz conterá PRINTER_INFO_2 estruturas. Se Level for 4, a matriz conterá PRINTER_INFO_4 estruturas. Se Level for 5, a matriz conterá PRINTER_INFO_5 estruturas.
O buffer deve ser grande o suficiente para receber a matriz de estruturas de dados e quaisquer cadeias de caracteres ou outros dados aos quais os membros da estrutura apontam. Se o buffer for muito pequeno, o parâmetro pcbNeeded retornará o tamanho do buffer necessário.
-
cbBuf [in]
-
O tamanho, em bytes, do buffer apontado por pPrinterEnum.
-
pcbNeeded [out]
-
Um ponteiro para um valor que recebe o número de bytes copiados se a função for bem-sucedida ou o número de bytes necessários se cbBuf for muito pequeno.
-
pcReturned [out]
-
Um ponteiro para um valor que recebe o número de estruturas de PRINTER_INFO_1, PRINTER_INFO_2 , PRINTER_INFO_4 ou PRINTER_INFO_5 que a função retorna na matriz à qual pPrinterEnum aponta.
Valor retornado
Se a função for bem-sucedida, o valor retornado será um valor diferente de zero.
Se a função falhar, o valor retornado será zero.
Comentários
Não chame esse método em DllMain.
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.
Se EnumPrinters retornar uma estrutura PRINTER_INFO_1 na qual PRINTER_ENUM_CONTAINER é especificado, isso indica que há uma hierarquia de objetos de impressora. Um aplicativo pode enumerar a hierarquia chamando EnumPrinters novamente, definindo Nome como o valor do membro pName da estrutura PRINTER_INFO_1.
A função EnumPrinters não recupera informações de segurança. Se PRINTER_INFO_2 estruturas forem retornadas na matriz apontada por pPrinterEnum, seus membros pSecurityDescriptor serão definidos como NULL.
Para obter informações sobre a impressora padrão, chame GetDefaultPrinter.
A estrutura PRINTER_INFO_4 fornece uma maneira fácil e extremamente rápida de recuperar os nomes das impressoras instaladas em um computador local, bem como as conexões remotas estabelecidas por um usuário. Quando EnumPrinters é chamado com uma estrutura de dados PRINTER_INFO_4 , essa função consulta o Registro para obter as informações especificadas e retorna imediatamente. Isso difere do comportamento de EnumPrinters quando chamado com outros níveis de estruturas de dados PRINTER_INFO_* . Em particular, quando EnumPrinters é chamado com uma estrutura de dados de nível 2 (PRINTER_INFO_2), ele executa uma chamada OpenPrinter em cada conexão remota. Se uma conexão remota estiver inativa ou o servidor remoto não existir mais ou a impressora remota não existir mais, a função deverá aguardar o tempo limite do RPC e, consequentemente, falhar na chamada do OpenPrinter . Isso pode levar algum tempo. Passar uma estrutura PRINTER_INFO_4 permite que um aplicativo recupere um mínimo de informações necessárias; se forem desejadas informações mais detalhadas, uma chamada subsequente de nível 2 do EnumPrinters poderá ser feita.
Windows Vista: Os dados da impressora retornados por EnumPrinters são recuperados de um cache local quando o valor de Level é 4.
A tabela a seguir mostra a saída EnumPrinters para vários valores flags quando o parâmetro Level é definido como 1.
Na coluna Parâmetro de nome da tabela, você deve substituir um nome apropriado para Provedor de Impressão, Domínio e Computador. Por exemplo, para "Provedor de Impressão", você pode usar o nome do provedor de impressão de rede ou o nome do provedor de impressão local. Para recuperar nomes de provedor de impressão, chame EnumPrinters com Name definido como NULL.
| Parâmetro Flags | Parâmetro name | Result |
|---|---|---|
| PRINTER_ENUM_LOCAL (e não PRINTER_ENUM_NAME) | O parâmetro Name é ignorado. |
Todas as impressoras locais. |
| PRINTER_ENUM_NAME | "Provedor de Impressão" |
Todos os nomes de domínio |
| PRINTER_ENUM_NAME | "Provedor de Impressão! Domínio" |
Todas as impressoras e servidores de impressão no domínio do computador |
| PRINTER_ENUM_NAME | "Provedor de Impressão!! \\Machine" |
Todas as impressoras compartilhadas em \\Machine |
| PRINTER_ENUM_NAME | Uma cadeia de caracteres vazia, "" |
Todas as impressoras locais. |
| PRINTER_ENUM_NAME |
NULL |
Todos os provedores de impressão no domínio do computador |
| PRINTER_ENUM_CONNECTIONS | O parâmetro Name é ignorado. |
Todas as impressoras remotas conectadas |
| PRINTER_ENUM_NETWORK | O parâmetro Name é ignorado. |
Todas as impressoras no domínio do computador |
| PRINTER_ENUM_REMOTE | Uma cadeia de caracteres vazia, "" |
Todas as impressoras e servidores de impressão no domínio do computador |
| PRINTER_ENUM_REMOTE | "Provedor de Impressão" |
O mesmo que PRINTER_ENUM_NAME |
| PRINTER_ENUM_REMOTE | "Provedor de Impressão! Domínio" |
Todas as impressoras e servidores de impressão no domínio do computador, independentemente do Domínio especificado. |
| PRINTER_ENUM_CATEGORY_3D | O parâmetro Name é ignorado. |
Somente impressoras 3D são enumeradas. |
| PRINTER_ENUM_CATEGORY_ALL | O parâmetro Name é ignorado. |
Impressoras 3D são enumeradas, juntamente com todas as outras impressoras. |
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 |
EnumPrintersW (Unicode) e EnumPrintersA (ANSI) |