Função DocumentProperties

A função DocumentProperties recupera ou modifica informações de inicialização da impressora ou exibe uma folha de propriedades de configuração de impressora para a impressora especificada.

Sintaxe

LONG DocumentProperties(
  _In_  HWND     hWnd,
  _In_  HANDLE   hPrinter,
  _In_  LPTSTR   pDeviceName,
  _Out_ PDEVMODE pDevModeOutput,
  _In_  PDEVMODE pDevModeInput,
  _In_  DWORD    fMode
);

Parâmetros

hWnd [in]

Um identificador para a janela pai da folha de propriedades de configuração da impressora.

hPrinter [in]

Um identificador para um objeto de impressora. Use a função OpenPrinter ou AddPrinter para recuperar um identificador de impressora.

pDeviceName [in]

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do dispositivo para o qual a folha de propriedades de configuração da impressora é exibida.

pDevModeOutput [out]

Um ponteiro para uma estrutura DEVMODE que recebe os dados de configuração da impressora especificados pelo usuário.

pDevModeInput [in]

Um ponteiro para uma estrutura DEVMODE que o sistema operacional usa para inicializar os controles da folha de propriedades.

Esse parâmetro só será usado se o sinalizador DM_IN_BUFFER estiver definido no parâmetro fMode . Se DM_IN_BUFFER não estiver definido, o sistema operacional usará o DEVMODE padrão da impressora.

fMode [in]

As operações que a função executa. Se esse parâmetro for zero, a função DocumentProperties retornará o número de bytes exigidos pela estrutura de dados DEVMODE do driver de impressora. Caso contrário, use uma ou mais das seguintes constantes para construir um valor para esse parâmetro; no entanto, observe que, para alterar as configurações de impressão, um aplicativo deve especificar pelo menos um valor de entrada e um valor de saída.

Valor	Significado
DM_IN_BUFFER	Valor de entrada. Antes de solicitar, copiar ou atualizar, a função mescla as configurações de impressão atuais do driver de impressora com as configurações na estrutura DEVMODE especificada pelo parâmetro pDevModeInput . A função atualiza a estrutura somente para os membros especificados pelo membro dmFields da estrutura DEVMODE. Esse valor também é definido como DM_MODIFY. Em casos de conflito durante a mesclagem, as configurações na estrutura DEVMODE especificada por pDevModeInput substituem as configurações de impressão atuais do driver de impressora.
DM_IN_PROMPT	Valor de entrada. A função apresenta a folha de propriedades de Instalação de Impressão do driver de impressora e altera as configurações na estrutura de dados DEVMODE da impressora para os valores especificados pelo usuário. Esse valor também é definido como DM_PROMPT.
DM_OUT_BUFFER	Valor de saída. A função grava as configurações de impressão atuais do driver de impressora, incluindo dados privados, na estrutura de dados DEVMODE especificada pelo parâmetro pDevModeOutput . O chamador deve alocar um buffer suficientemente grande para conter as informações. Se o bit DM_OUT_BUFFER conjuntos estiver claro, o parâmetro pDevModeOutput poderá ser NULL. Esse valor também é definido como DM_COPY.

Valor retornado

Se o parâmetro fMode for zero, o valor retornado será o tamanho do buffer necessário para conter os dados de inicialização do driver da impressora. Observe que esse buffer pode ser maior que uma estrutura DEVMODE se o driver da impressora acrescentar dados privados à estrutura.

Se a função exibir a folha de propriedades, o valor retornado será IDOK ou IDCANCEL, dependendo do botão selecionado pelo usuário.

Se a função não exibir a folha de propriedades e for bem-sucedida, o valor retornado será IDOK.

Se a função falhar, o valor retornado será menor que zero.

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.

A cadeia de caracteres apontada pelo parâmetro pDeviceName pode ser obtida chamando a função GetPrinter .

A estrutura DEVMODE realmente usada por um driver de impressora contém a parte independente do dispositivo (conforme definido acima) seguida por uma parte específica do driver que varia de tamanho e conteúdo com cada driver e versão do driver. Devido a essa dependência de driver, é muito importante que os aplicativos consultem o driver pelo tamanho correto da estrutura DEVMODE antes de alocar um buffer para ele.

Para fazer alterações nas configurações de impressão locais para um aplicativo, um aplicativo deve seguir estas etapas:

1. Obtenha o número de bytes necessários para a estrutura DEVMODE completa chamando DocumentProperties e especificando zero no parâmetro fMode .
2. Alocar memória para a estrutura DEVMODE completa.
3. Obtenha as configurações atuais da impressora chamando DocumentProperties. Passe um ponteiro para a estrutura DEVMODE alocada na Etapa 2 como o parâmetro pDevModeOutput e especifique o valor DM_OUT_BUFFER .
4. Modifique os membros apropriados da estrutura DEVMODE retornada e indique quais membros foram alterados definindo os bits correspondentes no membro dmFields do DEVMODE.
5. Chame DocumentProperties e passe a estrutura DEVMODE modificada de volta como os parâmetros pDevModeInput e pDevModeOutput e especifique os valores DM_IN_BUFFER e DM_OUT_BUFFER (que são combinados usando o operador OR). A estrutura DEVMODE retornada pela terceira chamada para DocumentProperties pode ser usada como um argumento em uma chamada para a função CreateDC .

Para criar um identificador para um contexto impressora-dispositivo usando as configurações atuais da impressora, você só precisa chamar DocumentProperties duas vezes, conforme descrito acima. A primeira chamada obtém o tamanho do DEVMODE completo e a segunda chamada inicializa o DEVMODE com as configurações atuais da impressora. Passe o DEVMODE inicializado para CreateDC para obter o identificador para o contexto do dispositivo de impressora.

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	Winspool.h (inclua Windows.h)
Biblioteca	Winspool.lib
DLL	Winspool.drv
Nomes Unicode e ANSI	DocumentPropertiesW (Unicode) e DocumentPropertiesA (ANSI)

Confira também

Impressão

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

AdvancedDocumentProperties

Createdc

DEVMODE

GetPrinter

OpenPrinter