Função DrvConvertDevMode (winddiui.h)

A função DrvConvertDevMode de uma interface de impressora converte a estrutura DEVMODEW de uma impressora de uma versão para outra.

Sintaxe

BOOL DrvConvertDevMode(
  [in]      LPTSTR   pPrinterName,
  [in]      PDEVMODE pdmIn,
  [out]     PDEVMODE pdmOut,
  [in, out] PLONG    pcbNeeded,
  [in]      DWORD    fMode
);

Parâmetros

[in] pPrinterName

Ponteiro fornecido pelo chamador para uma cadeia de caracteres de nome de impressora. Para obter mais informações sobre esse parâmetro, consulte a seção Comentários a seguir.

[in] pdmIn

Ponteiro fornecido pelo chamador para uma estrutura DEVMODEW de entrada. Se fMode for CDM_DRIVER_DEFAULT, esse ponteiro será NULL.

[out] pdmOut

Ponteiro fornecido pelo chamador para um buffer para receber uma estrutura DEVMODEW de saída. Se fMode for CDM_CONVERT o buffer contiver, na entrada, uma estrutura DEVMODEW válida indicando a versão do driver de destino.

[in, out] pcbNeeded

Ponteiro fornecido pelo chamador para o tamanho, em bytes, do buffer apontado por pdmOut. Na saída, a DLL da interface da impressora deve substituir o valor de tamanho recebido pelo tamanho real da estrutura DEVMODEW convertida. Se o buffer recebido for muito pequeno, a DLL da interface da impressora deverá substituir o valor de tamanho recebido pelo tamanho do buffer necessário.

[in] fMode

Sinalizador de bits fornecido pelo chamador indicando o tipo de operação a ser executada. Esse pode ser um dos seguintes sinalizadores:

CDM_CONVERT

A função deve converter o conteúdo da estrutura DEVMODEW de entrada (apontada por pdmIn) em uma nova estrutura DEVMODEW e colocar o resultado na estrutura DEVMODEW apontada por pdmOut. O conteúdo inicial da estrutura DEVMODEW de saída recebida (apontado por pdmOut) deve ser usado para determinar a versão de saída.

CDM_CONVERT351

A função deve converter o conteúdo da estrutura DEVMODEW de entrada (apontada por pdmIn), criando uma estrutura DEVMODEW de saída compatível com Windows NT 3.51 e colocar o resultado na estrutura DEVMODEW apontada por pdmOut.

Se o driver não der suporte a uma estrutura DEVMODEW para Windows NT 3.51, a função deverá converter o DEVMODEW de entrada para a versão atual.

CDM_DRIVER_DEFAULT

A função deve copiar a versão atual de sua estrutura DEVMODEW padrão para o buffer apontado por pdmOut.

Retornar valor

Se a operação for bem-sucedida, a função deverá retornar TRUE; caso contrário, ele deve chamar SetLastError para definir um código de erro e retornar FALSE.

Comentários

Em um ambiente de cliente/servidor, um cliente pode estar executando uma versão do sistema operacional ou driver de impressora enquanto o servidor (spooler) está executando outra, o que significa que a definição de estrutura DEVMODEW de uma impressora pode ser inconsistente entre o cliente e o servidor. A função DrvConvertDevMode deve ser capaz de executar conversões de uma versão da estrutura DEVMODEW da impressora para outra.

Ao converter de uma versão DEVMODEW para outra, membros DEVMODEW públicos e privados devem ser incluídos.

O nome da impressora apontado por pPrinterName pode ser usado como um argumento de entrada para a função OpenPrinter (descrita na documentação do SDK do Microsoft Windows), que pode ser chamada para obter valores padrão armazenados quando o sinalizador CDM_DRIVER_DEFAULT é recebido. Observe que a cadeia de caracteres de nome da impressora não deve ser modificada de forma alguma antes de uma chamada para OpenPrinter. Além disso, uma chamada para OpenPrinter deve estar no mesmo thread que foi usado para chamar DrvConvertDevMode.

A função deve verificar se pdmIn e pdmOut (se aplicável) apontam para estruturas DEVMODEW válidas. Se não o fizerem, a função deverá chamar SetLastError(ERROR_INVALID_PARAMETER) e retornar FALSE. Se o tamanho DEVMODEW de saída especificado por pcbNeeded for muito pequeno, o driver deverá substituir o valor de tamanho fornecido por pcbNeeded com o tamanho do buffer necessário, chamar SetLastError(ERROR_INSUFFICIENT_BUFFER) e retornar FALSE.

A função DrvConvertDevMode é executada no contexto do spooler e, portanto, não deve exibir uma interface do usuário.

Quando DrvConvertDevMode é chamado com um ponteiro de estrutura NULL DEVMODEW no parâmetro pdmOut para obter o tamanho do buffer, espera-se que o driver defina o último erro como ERROR_INSUFFICIENT_BUFFER. Se o último erro não estiver definido como esse valor, o spooler assumirá um erro geral.

Requisitos

Requisito	Valor
Plataforma de Destino	Área de Trabalho
Cabeçalho	winddiui.h (inclua Winddiui.h)