Função GetPrinterDataEx
A função GetPrinterDataEx recupera dados de configuração para a impressora ou servidor de impressão especificado. GetPrinterDataEx pode recuperar valores armazenados pela função SetPrinterData . Além disso, GetPrinterDataEx pode recuperar valores que a função SetPrinterDataEx armazena em uma chave especificada.
Sintaxe
DWORD GetPrinterDataEx(
_In_ HANDLE hPrinter,
_In_ LPCTSTR pKeyName,
_In_ LPCTSTR pValueName,
_Out_ LPDWORD pType,
_Out_ LPBYTE pData,
_In_ DWORD nSize,
_Out_ LPDWORD pcbNeeded
);
Parâmetros
-
hPrinter [in]
-
Um identificador para a impressora ou servidor de impressão para o qual a função recupera dados de configuração. Use a função OpenPrinter, OpenPrinter2 ou AddPrinter para recuperar um identificador de impressora.
-
pKeyName [in]
-
Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica a chave que contém o valor a ser recuperado. Use o caractere de barra invertida ( \ ) como um delimitador para especificar um caminho que tenha uma ou mais subchaves.
Se hPrinter for um identificador para uma impressora e pKeyName for NULL ou uma cadeia de caracteres vazia, GetPrinterDataEx retornará ERROR_INVALID_PARAMETER.
Se hPrinter for um identificador para um servidor de impressão, pKeyName será ignorado.
-
pValueName [in]
-
Um ponteiro para uma cadeia de caracteres terminada em nulo que identifica os dados a serem recuperados.
Para impressoras, essa cadeia de caracteres especifica o nome de um valor sob a chave pKeyName .
Para servidores de impressão, essa cadeia de caracteres é uma das cadeias de caracteres predefinidas listadas na seção Comentários a seguir.
-
pType [out]
-
Um ponteiro para uma variável que recebe o tipo de dados armazenados no valor . A função retorna o tipo especificado na chamada SetPrinterDataEx quando os dados foram armazenados. Esse parâmetro poderá ser NULL se você não precisar das informações. GetPrinterDataEx passa pType como o parâmetro lpdwType de uma chamada de função RegQueryValueEx .
-
pData [out]
-
Um ponteiro para um buffer que recebe os dados de configuração.
-
nSize [in]
-
O tamanho, em bytes, do buffer apontado por pData.
-
pcbNeeded [out]
-
Um ponteiro para uma variável que recebe o tamanho, em bytes, dos dados de configuração. Se o tamanho do buffer especificado por nSize for muito pequeno, a função retornará ERROR_MORE_DATA e pcbNeeded indicará o tamanho do buffer necessário.
Valor retornado
Se a função for bem-sucedida, o valor retornado será ERROR_SUCCESS.
Se a função falhar, o valor retornado será um valor de erro.
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.
GetPrinterDataEx recupera dados de configuração de impressora que foram definidos pelas funções SetPrinterDataEx e SetPrinterData .
Chamar GetPrinterDataEx com o parâmetro pKeyName definido como "PrinterDriverData" é equivalente a chamar a função GetPrinterData .
Se hPrinter for um identificador para um servidor de impressão, pValueName poderá especificar um dos seguintes valores predefinidos.
| Valor | Comentários |
|---|---|
| SPLREG_ALLOW_USER_MANAGEFORMS | Windows XP com Service Pack 2 (SP2) e posterior Windows Server 2003 com Service Pack 1 (SP1) e posterior |
| SPLREG_ARCHITECTURE | |
| SPLREG_BEEP_ENABLED | |
| SPLREG_DEFAULT_SPOOL_DIRECTORY | |
| SPLREG_DNS_MACHINE_NAME | |
| SPLREG_DS_PRESENT | No retorno bem-sucedido, pData conterá 0x0001 se o computador estiver em um domínio DS, caso contrário, 0. |
| SPLREG_DS_PRESENT_FOR_USER | No retorno bem-sucedido, pData conterá 0x0001 se o usuário estiver conectado a um domínio DS, caso contrário, 0. |
| SPLREG_EVENT_LOG | |
| SPLREG_MAJOR_VERSION | |
| SPLREG_MINOR_VERSION | |
| SPLREG_NET_POPUP | Sem suporte no Windows Server 2003 e posterior |
| SPLREG_NET_POPUP_TO_COMPUTER | No retorno bem-sucedido, o pData contém 1 se as notificações de trabalho devem ser enviadas para o computador cliente ou 0 se as notificações de trabalho forem enviadas ao usuário. Sem suporte no Windows Server 2003 e posterior |
| SPLREG_OS_VERSION | Windows XP e posterior |
| SPLREG_OS_VERSIONEX | |
| SPLREG_PORT_THREAD_PRIORITY_DEFAULT | |
| SPLREG_PORT_THREAD_PRIORITY | |
| SPLREG_PRINT_DRIVER_ISOLATION_GROUPS | Windows 7 e posterior |
| SPLREG_PRINT_DRIVER_ISOLATION_TIME_BEFORE_RECYCLE | Windows 7 e posterior |
| SPLREG_PRINT_DRIVER_ISOLATION_MAX_OBJECTS_BEFORE_RECYCLE | Windows 7 e posterior |
| SPLREG_PRINT_DRIVER_ISOLATION_IDLE_TIMEOUT | Windows 7 e posterior |
| SPLREG_PRINT_DRIVER_ISOLATION_EXECUTION_POLICY | Windows 7 e posterior |
| SPLREG_PRINT_DRIVER_ISOLATION_OVERRIDE_POLICY | Windows 7 e posterior |
| SPLREG_REMOTE_FAX | No retorno bem-sucedido, pData conterá 0x0001 se o serviço FAX der suporte a clientes remotos, caso contrário, 0. |
| SPLREG_RETRY_POPUP | No retorno bem-sucedido, o pData conterá 1 se o servidor estiver definido para tentar novamente janelas pop-up para todos os trabalhos ou 0 se o servidor não tentar novamente janelas pop-up para todos os trabalhos. Sem suporte no Windows Server 2003 e posterior |
| SPLREG_SCHEDULER_THREAD_PRIORITY | |
| SPLREG_SCHEDULER_THREAD_PRIORITY_DEFAULT | |
| SPLREG_WEBSHAREMGMT | Windows Server 2003 e posterior |
Os valores a seguir de pValueName indicam o comportamento de impressão do pool quando ocorre um erro.
| Valor | Comentários |
|---|---|
| SPLREG_RESTART_JOB_ON_POOL_ERROR | O valor de pData indica o tempo, em segundos, quando um trabalho é reiniciado em outra porta após ocorrer um erro. Essa configuração é usada com SPLREG_RESTART_JOB_ON_POOL_ENABLED. |
| SPLREG_RESTART_JOB_ON_POOL_ENABLED | Um valor diferente de zero no pData indica que SPLREG_RESTART_JOB_ON_POOL_ERROR está habilitado. |
O tempo especificado em SPLREG_RESTART_JOB_ON_POOL_ERROR é um tempo mínimo. O tempo real pode ser maior, dependendo das seguintes configurações de monitor de porta, que são valores do Registro sob esta chave do Registro:
HKLM\SYSTEM\CurrentControlSet\Control\Print\Monitors\<MonitorName>\Ports
Chame a função RegQueryValueEx para consultar esses valores.
| Configuração do monitor de porta | Tipo de dados | Significado |
|---|---|---|
| StatusUpdateEnabled | REG_DWORD | Se um valor diferente de zero, permite que o monitor de porta atualize o spooler com a porta status. |
| StatusUpdateInterval | REG_DWORD | Especifica o intervalo, em minutos, quando o monitor de porta atualiza o spooler com a porta status. |
Se pKeyName for uma das chaves de DS (Serviço de Diretório) predefinidas (consulte SetPrinter) e pValueName contiver uma vírgula (','), a parte de pValueName antes da vírgula será o nome do valor e a parte de pValueName à direita da vírgula será a propriedade DS OID. Uma subchave chamada OID é criada e um novo valor que consiste no nome do valor e o OID é inserido sob a chave OID. SetPrinterDataEx também adiciona o nome do valor e os dados sob a chave DS.
No Windows 7 e versões posteriores do Windows, os trabalhos de impressão enviados para um servidor de impressão são renderizados no cliente por padrão. A configuração da renderização do lado do cliente para uma impressora pode ser lida definindo pKeyName como "PrinterDriverData" e pValueName como o valor de configuração na tabela a seguir.
| Configuração | Tipo de dados | Descrição |
|---|---|---|
| EMFDespoolingSetting | REG_DWORD | Um valor de 0 ou, se esse valor não estiver presente no Registro, habilitará a renderização padrão do lado do cliente de trabalhos de impressão. Um valor 1 desabilita a renderização do lado do cliente de trabalhos de impressão. |
| ForceClientSideRendering | REG_DWORD | Um valor de 0 ou, se esse valor não estiver presente no registro, fará com que os trabalhos de impressão sejam renderizados no cliente. Se um trabalho de impressão não puder ser renderizado no cliente, ele será renderizado no servidor. Se um trabalho de impressão não puder ser renderizado no servidor, ele falhará. Um valor de 1 renderizará trabalhos de impressão no cliente. Se um trabalho de impressão não puder ser renderizado no cliente, ele falhará. |
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 |
GetPrinterDataExW (Unicode) e GetPrinterDataExA (ANSI) |