Função SetPrinterDataEx
A função SetPrinterDataEx define os dados de configuração de uma impressora ou servidor de impressão. A função armazena os dados de configuração na chave do Registro da impressora.
Sintaxe
DWORD SetPrinterDataEx(
_In_ HANDLE hPrinter,
_In_ LPCTSTR pKeyName,
_In_ LPCTSTR pValueName,
_In_ DWORD Type,
_In_ LPBYTE pData,
_In_ DWORD cbData
);
Parâmetros
-
hPrinter [in]
-
Um identificador para a impressora ou servidor de impressão para o qual a função define 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 definido. Se a chave ou as subchaves especificadas não existirem, a função as criará.
Para armazenar dados de configuração que podem ser publicados no DS (serviço de diretório), especifique uma das chaves predefinidas do Registro a seguir.
Valor Significado - SPLDS_DRIVER_KEY
Os drivers de impressora usam essa chave para armazenar as propriedades do driver. - SPLDS_SPOOLER_KEY
Reservado. Usado apenas pelo spooler de impressão para armazenar propriedades internas do spooler. - SPLDS_USER_KEY
Os aplicativos usam essa chave para armazenar propriedades da impressora, como números de ativos da impressora. Os valores armazenados sob a chave SPLDS_USER_KEY serão publicados no serviço de diretório somente se houver uma propriedade correspondente no esquema. Um administrador de domínio deverá criar a propriedade se ela ainda não existir. Para publicar uma propriedade definida pelo usuário depois de usar SetPrinterDataEx para adicionar ou alterar um valor, chame SetPrinter com Level = 7 e com o membro dwAction de PRINTER_INFO_7 definido como DSPRINT_UPDATE.
Você pode especificar outras chaves para armazenar dados de configuração não DS. 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, SetPrinterDataEx retornará ERROR_INVALID_PARAMETER.
Se hPrinter for um identificador para um servidor de impressão, pKeyName será ignorado.
Não use SPLDS_SPOOLER_KEY. Para alterar as propriedades da impressora spooler, use SetPrinter com Level = 2.
-
pValueName [in]
-
Um ponteiro para uma cadeia de caracteres terminada em nulo que identifica os dados a serem definidos.
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.
-
Digite [in]
-
Um código que indica o tipo de dados apontado pelo parâmetro pData . Para obter uma lista dos códigos de tipo possíveis, consulte Tipos de valor do Registro.
Se pKeyName especificar uma das chaves de serviço de diretório predefinidas, Type deverá ser REG_SZ, REG_MULTI_SZ, REG_DWORD ou REG_BINARY. Se REG_BINARY for usado, cbData deverá ser igual a 1 e o serviço de diretório tratará os dados como um valor booliano.
-
pData [in]
-
Um ponteiro para um buffer que contém os dados de configuração da impressora.
-
cbData [in]
-
O tamanho, em bytes, da matriz.
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.
Para recuperar dados de configuração existentes para uma impressora ou spooler de impressão, chame a função GetPrinterDataEx .
Chamar SetPrinterDataEx com o parâmetro pKeyName definido como "PrinterDriverData" é equivalente a chamar a função SetPrinterData .
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_BEEP_ENABLED | |
| SPLREG_DEFAULT_SPOOL_DIRECTORY | |
| SPLREG_EVENT_LOG | |
| SPLREG_NET_POPUP | Sem suporte no Windows Server 2003 e posterior |
| 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_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 |
Passar um dos seguintes valores predefinidos como pValueName define 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 RegSetValueEx para definir 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. |
Para garantir que o spooler redirecione trabalhos para a próxima impressora disponível no pool (quando o trabalho de impressão não for impresso dentro do tempo definido), o monitor de porta deve dar suporte a SNMP e as portas de rede no pool devem ser configuradas como "SNMP status habilitado". O monitor de porta que dá suporte ao SNMP é o monitor de porta TCP/IP Padrão.
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 renderização do lado do cliente de trabalhos de impressão pode ser configurada definindo pKeyName como "PrinterDriverData" e pValueName para 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 |
SetPrinterDataExW (Unicode) e SetPrinterDataExA (ANSI) |