Função DrvDocumentEvent (winddiui.h)

  • Artigo

A função DrvDocumentEvent de uma interface de impressora DLL pode lidar com determinados eventos associados à impressão de um documento.

Sintaxe

int DrvDocumentEvent(
        HANDLE hPrinter,
        HDC    hdc,
        int    iEsc,
        ULONG  cbIn,
  [in]  PVOID  pvIn,
        ULONG  cbOut,
  [out] PVOID  pvOut
);

Parâmetros

hPrinter

Identificador de impressora fornecido pelo chamador.

hdc

Identificador de contexto de dispositivo fornecido pelo chamador, gerado por um CreateDC Isso será zero se iEsc estiver definido como DOCUMENTEVENT_CREATEDCPRE. Para obter restrições de impressão de um aplicativo de 32 bits em uma versão de 64 bits do Windows, consulte a seção Comentários abaixo.

iEsc

Código de escape fornecido pelo chamador que identifica o evento a ser manipulado.

Para obter restrições de impressão de um aplicativo de 32 bits em uma versão de 64 bits do Windows, consulte a seção Comentários abaixo.

Esse parâmetro pode ser uma das seguintes constantes de inteiro:

Constante iEsc Evento
DOCUMENTEVENT_ABORTDOC A GDI está prestes a processar uma chamada para sua função AbortDoc .
DOCUMENTEVENT_CREATEDCPOST A GDI acabou de processar uma chamada para sua função CreateDC ou CreateIC . Esse código de escape não deve ser usado, a menos que tenha havido uma chamada anterior para DrvDocumentEvent com iEsc definido como DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_CREATEDCPRE A GDI está prestes a processar uma chamada para sua função CreateDC ou CreateIC .
DOCUMENTEVENT_DELETEDC A GDI está prestes a processar uma chamada para sua função DeleteDC .
DOCUMENTEVENT_ENDDOCPOST A GDI acabou de processar uma chamada para sua função EndDoc .
DOCUMENTEVENT_ENDDOCPRE ou DOCUMENTEVENT_ENDDOC A GDI está prestes a processar uma chamada para sua função EndDoc .
DOCUMENTEVENT_ENDPAGE A GDI está prestes a processar uma chamada para sua função EndPage .
DOCUMENTEVENT_ESCAPE A GDI está prestes a processar uma chamada para sua função ExtEscape .
DOCUMENTEVENT_QUERYFILTER O evento DOCUMENTEVENT_QUERYFILTER representa uma oportunidade para o spooler consultar o driver para obter uma lista dos eventos DOCUMENTEVENT_XXX aos quais o driver responderá. Esse evento é emitido pouco antes de uma chamada para DrvDocumentEvent que passa o evento DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_RESETDCPOST A GDI acabou de processar uma chamada para sua função ResetDC . Esse código de escape não deve ser usado, a menos que tenha havido uma chamada anterior para DrvDocumentEvent com iEsc definido como DOCUMENTEVENT_RESETDCPRE.
DOCUMENTEVENT_RESETDCPRE A GDI está prestes a processar uma chamada para sua função ResetDC .
DOCUMENTEVENT_STARTDOCPOST A GDI acabou de processar uma chamada para sua função StartDoc .
DOCUMENTEVENT_STARTDOCPRE ou DOCUMENTEVENT_STARTDOC A GDI está prestes a processar uma chamada para sua função StartDoc .
DOCUMENTEVENT_STARTPAGE A GDI está prestes a processar uma chamada para sua função StartPage .

cbIn

Tamanho fornecido pelo chamador, em bytes, do buffer apontado por pvIn.

[in] pvIn

Ponteiro fornecido pelo chamador, cujo uso depende do valor fornecido para iEsc, da seguinte maneira:

Constante iEsc Conteúdo de pvIn
DOCUMENTEVENT_ABORTDOC Não usado.
DOCUMENTEVENT_CREATEDCPOST pvIn contém o endereço de um ponteiro para a estrutura DEVMODEW especificada no parâmetro pvOut em uma chamada anterior para essa função, para a qual o parâmetro iEsc foi definido como DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_CREATEDCPRE pvIn aponta para uma estrutura DOCEVENT_CREATEDCPRE .
DOCUMENTEVENT_DELETEDC Não usado.
DOCUMENTEVENT_ENDDOCPOST Não usado.
DOCUMENTEVENT_ENDDOCPRE ou DOCUMENTEVENT_ENDDOC Não usado.
DOCUMENTEVENT_ENDPAGE Não usado.
DOCUMENTEVENT_ESCAPE pvIn aponta para uma estrutura de DOCEVENT_ESCAPE .
DOCUMENTEVENT_QUERYFILTER O mesmo que para DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_RESETDCPOST pvIn contém o endereço de um ponteiro para a estrutura DEVMODEW especificada no parâmetro pvOut em uma chamada anterior para essa função, para a qual o parâmetro iEsc foi definido como DOCUMENTEVENT_RESETDCPRE.
DOCUMENTEVENT_RESETDCPRE pvIn contém o endereço de um ponteiro para a estrutura DEVMODEW fornecida pelo chamador da função ResetDC .
DOCUMENTEVENT_STARTDOCPOST pvIn aponta para um LONG que especifica o identificador de trabalho de impressão retornado pela função StartDoc .
DOCUMENTEVENT_STARTDOCPRE ou DOCUMENTEVENT_STARTDOC pvIn contém o endereço de um ponteiro para uma estrutura DOCINFO fornecida pelo chamador da função StartDoc .
DOCUMENTEVENT_STARTPAGE Não usado.

cbOut

Se iEsc for DOCUMENTEVENT_ESCAPE

Valor fornecido pela função que é usado como o parâmetro cbOutput para a função ExtEscape .

Se iEsc for DOCUMENTEVENT_QUERYFILTER

Tamanho fornecido pelo chamador, em bytes, do ponteiro do buffer para por pvOut.

Para todos os outros valores iEsc

Não usado.

[out] pvOut

Ponteiro fornecido pela função para um buffer de saída, cujo uso depende do valor fornecido para iEsc, da seguinte maneira:

Constante iEsc Conteúdo de pvOut
DOCUMENTEVENT_CREATEDCPRE Ponteiro para uma estrutura DEVMODEW fornecida pelo driver, que a GDI usa em vez da fornecida pelo chamador CreateDC . (Se FOR NULL, a GDI usará a estrutura fornecida pelo chamador.)
DOCUMENTEVENT_ESCAPE Ponteiro de buffer usado como o parâmetro lpszOutData para a função ExtEscape .
DOCUMENTEVENT_QUERYFILTER Ponteiro fornecido pelo chamador para buffer que contém uma estrutura DOCEVENT_FILTER .
DOCUMENTEVENT_RESETDCPRE Ponteiro para uma estrutura DEVMODEW fornecida pelo driver, que o GDI usa em vez da fornecida pelo chamador da função ResetDC . (Se FOR NULL, a GDI usará a estrutura fornecida pelo chamador.)
Todos os outros valores iEsc Não usado.

Retornar valor

O valor retornado da função depende do escape fornecido para iEsc. Para alguns códigos de escape, o valor retornado não é usado (consulte a segunda lista de valores). Se a função fornecer um valor retornado, ela deverá ser uma das seguintes:

Código de retorno Descrição
DOCUMENTEVENT_FAILURE O driver dá suporte ao código de escape identificado pelo iEsc, mas ocorreu uma falha.
DOCUMENTEVENT_SUCCESS O driver lidou com êxito com o código de escape identificado pelo iEsc.
DOCUMENTEVENT_UNSUPPORTED O driver não dá suporte ao código de escape identificado pelo iEsc.

Comentários

Opcionalmente, uma DLL de interface de impressora pode fornecer uma função DrvDocumentEvent para executar pré-processamento ou pós-processamento de chamadas GDI associadas à renderização de um documento. As chamadas para a função DrvDocumentEvent são feitas do cliente GDI no modo de usuário, quando um aplicativo faz chamadas para o cliente GDI.

Para um valor iEsc de DOCUMENTEVENT_QUERYFILTER, o spooler pode interpretar um valor DOCUMENTEVENT_SUCCESS retornado por DrvDocumentEvent de duas maneiras, dependendo se o driver modificou determinados membros da estrutura DOCEVENT_FILTER . (O parâmetro pvOut aponta para essa estrutura.) Quando o spooler aloca memória para uma estrutura desse tipo, ele inicializa dois membros dessa estrutura, cElementsReturned e cElementsNeeded, para valores conhecidos. Depois que DrvDocumentEvent retorna, o spooler determina se os valores desses membros foram alterados e usa essas informações para interpretar o valor retornado drvDocumentEvent . A tabela a seguir resume essa situação.

Retornar valor Status de cElementsReturned, cElementsNeeded Significado
DOCUMENTEVENT_SUCCESS O driver não fez nenhuma alteração em nenhum dos membros. O spooler interpreta esse valor retornado como equivalente a DOCUMENTEVENT_UNSUPPORTED. O spooler não consegue recuperar o filtro de evento do driver, portanto, ele persiste na chamada de DrvDocumentEvent para todos os eventos.
DOCUMENTEVENT_SUCCESS O driver escreveu para um ou ambos os membros. O spooler aceita esse valor retornado sem interpretação. Se o driver tiver escrito em apenas um dos cElementsNeeded e cElementsReturned, o spooler considerará que o membro inalterado tem um valor igual a zero. O spooler filtra todos os eventos listados no membro aDocEventCall do DOCEVENT_FILTER.
DOCUMENTEVENT_UNSUPPORTED Não aplicável O driver não dá suporte a DOCUMENTEVENT_QUERYFILTER. O spooler não consegue recuperar o filtro de evento do driver, portanto, ele persiste na chamada de DrvDocumentEvent para todos os eventos.
DOCUMENTEVENT_FAILURE Não aplicável O driver dá suporte a DOCUMENTEVENT_QUERYFILTER, mas encontrou um erro interno. O spooler não consegue recuperar o filtro de evento do driver, portanto, ele persiste na chamada de DrvDocumentEvent para todos os eventos.

Se o nome do código de escape não tiver sufixo ou for sufixo com PRE, o cliente GDI chamará DrvDocumentEvent pouco antes de chamar o mecanismo de renderização GDI no modo kernel. Se o nome do código de escape for sufixo com POST, o cliente GDI chamará DrvDocumentEvent logo após o mecanismo de renderização GDI do modo kernel retornar.

Se o código de escape fornecido no parâmetro iEsc for DOCUMENTEVENT_CREATEDCPRE, as seguintes regras se aplicarão:

  • Se o trabalho estiver sendo enviado diretamente para a impressora sem spooling, pvIn --> pszDevice apontará para o nome da impressora. (Consulte a estrutura DOCEVENT_CREATEDCPRE para obter mais informações.)

  • Se o trabalho estiver sendo spool, pvIn --> pszDevice apontará para o nome da porta da impressora.

A função DrvDocumentEvent é executada no contexto do chamador de modo de usuário da função de cliente GDI. Quando o spool em EMF está desabilitado, a função pode exibir uma interface do usuário. Por exemplo, a função DrvDocumentEvent para um driver fax pode exibir uma caixa de diálogo para o usuário antes que a função StartDoc da GDI seja processada.

As seguintes restrições se aplicam ao executar um aplicativo de 32 bits em uma versão de 64 bits do Windows:

  • A única função GDI que DrvDocumentEvent deve chamar é ExtEscape, e somente escapes privados devem ser usados.

  • Chamadas drvDocumentEvent para outras funções GDI podem produzir um comportamento indefinido.

Requisitos

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

Confira também

DOCEVENT_CREATEDCPRE

DOCEVENT_ESCAPE

DOCEVENT_FILTER