Função DocumentEvent

Artigo
05/12/2022
7 minutos para o fim da leitura

A função DocumentEvent é um manipulador de eventos para eventos associados à impressão de um documento.

Sintaxe

HRESULT DocumentEvent(
  _In_  HANDLE hPrinter,
  _In_  HDC    hdc,
        INT    iEsc,
        ULONG  cbIn,
  _In_  PVOID  pvIn,
        ULONG  cbOut,
  _Out_ PVOID  pvOut
);

Parâmetros

hPrinter [in]

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

hdc [in]

Um identificador de contexto do dispositivo gerado por uma chamada de CreateDC. Isso será zero se o 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 Comentários.

iEsc

Um código de escape que identifica o evento a ser manipulado. Esse parâmetro pode ser uma das seguintes constantes inteiros.

Constante	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 ao DocumentEvent com o 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 XXX DOCUMENTEVENT_ aos quais o driver responderá. Esse evento é emitido pouco antes de uma chamada ao DocumentEvent 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 ao DocumentEvent com o 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

O tamanho, em bytes, do buffer apontado por pvIn.

pvIn [in]

Um ponteiro para um buffer. O que o buffer contém depende do valor do iEsc, conforme mostrado na tabela a seguir.

Constante	Conteúdo do pvin
DOCUMENTEVENT_ABORTDOC	Não usado.
DOCUMENTEVENT_CREATEDCPOST	pvIn contém o endereço de um ponteiro para a estrutura DEVMODE 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 que está documentada no Windows Driver Development Kit.
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 DOCEVENT_ESCAPE que está documentada no Windows Driver Development Kit.
DOCUMENTEVENT_QUERYFILTER	O mesmo que para DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_RESETDCPOST	pvIn contém o endereço de um ponteiro para a estrutura DEVMODE 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 DEVMODE fornecida pelo chamador de ResetDC.
DOCUMENTEVENT_STARTDOCPOST	pvIn aponta para um LONG que especifica o identificador de trabalho de impressão retornado pelo StartDoc.
DOCUMENTEVENT_STARTDOCPRE ou DOCUMENTEVENT_STARTDOC	pvIn contém o endereço de um ponteiro para uma estrutura DOCINFO fornecida pelo chamador do StartDoc.
DOCUMENTEVENT_STARTPAGE	Não usado.

*cbOut*

Valor	Significado
IDOCUMENTEVENT_QUERYFILTER	O tamanho, em bytes, do ponteiro do buffer para por pvOut.
DOCUMENTEVENT_ESCAPE	Um valor que é usado como o parâmetro cbOutput para ExtEscape.
Para todos os outros valores	O iEsc não é usado.

pvOut [out]

Um ponteiro para um buffer. O conteúdo do buffer depende do valor fornecido para iEsc, conforme mostrado na tabela a seguir.

Constante	Conteúdo de pvOut
DOCUMENTEVENT_CREATEDCPRE	Um ponteiro para uma estrutura DEVMODE fornecida pelo driver, que o GDI usa em vez da fornecida pelo chamador CreateDC . (Se NULL, o GDI usará a estrutura fornecida pelo chamador.)
DOCUMENTEVENT_ESCAPE	Um ponteiro para um buffer usado como o parâmetro lpszOutData para ExtEscape.
DOCUMENTEVENT_QUERYFILTER	Um ponteiro para o buffer que contém uma estrutura DOCEVENT_FILTER que está documentada no Windows Driver Development Kit.
DOCUMENTEVENT_RESETDCPRE	Um ponteiro para uma estrutura DEVMODE fornecida pelo driver, que o GDI usa em vez da fornecida pelo chamador ResetDC . (Se NULL, o GDI usará a estrutura fornecida pelo chamador.)

Retornar valor

O valor retornado da função depende da escape fornecida para iEsc. Para alguns códigos de escape, o valor retornado não é usado (veja abaixo). Se a função fornecer um valor retornado, ela deverá ser uma das seguintes.

Valor Retornado	Significado
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.

A lista a seguir indica quais códigos de escape que exigem um valor retornado e quais não, e explica o significado dos códigos de retorno DOCUMENTEVENT_SUCCESS, DOCUMENTEVENT_FAILURE e DOCUMENTEVENT_UNSUPPORTED.

Valor Retornado	Significado
DOCUMENTEVENT_ABORTDOC	O valor retornado não é usado e não deve ser lido.
DOCUMENTEVENT_CREATEDCPOST	O valor retornado não é usado e não deve ser lido.
DOCUMENTEVENT_CREATEDCPRE	DOCUMENTEVENT_FAILURE - O GDI não cria o contexto do dispositivo ou o contexto de informações e fornece um valor de retorno de 0 para CreateDC ou CreateIC.
DOCUMENTEVENT_DELETEDC	O valor retornado não é usado e não deve ser lido.
DOCUMENTEVENT_ENDDOCPOST	O valor retornado não é usado e não deve ser lido.
DOCUMENTEVENT_ENDDOCPRE ou DOCUMENTEVENT_ENDDOC	O valor retornado não é usado e não deve ser lido.
DOCUMENTEVENT_ENDPAGE	O valor retornado não é usado e não deve ser lido.
DOCUMENTEVENT_ESCAPE	O valor retornado não é usado e não deve ser lido.
DOCUMENTEVENT_QUERYFILTER	Consulte Observações.
DOCUMENTEVENT_RESETDCPOST	O valor retornado não é usado e não deve ser lido.
DOCUMENTEVENT_RESETDCPRE	DOCUMENTEVENT_FAILURE - O GDI não redefine o contexto do dispositivo e fornece um valor de retorno de 0 para ResetDC.
DOCUMENTEVENT_STARTDOCPOST	DOCUMENTEVENT_FAILURE - O GDI chama AbortDoc para interromper o documento e fornece um valor retornado de SP_ERROR para StartDoc.
DOCUMENTEVENT_STARTDOCPRE ou DOCUMENTEVENT_STARTDOC	DOCUMENTEVENT_FAILURE - O GDI não inicia o documento e fornece um valor retornado de SP_ERROR para StartDoc.
DOCUMENTEVENT_STARTPAGE	DOCUMENTEVENT_FAILURE - O GDI não inicia a página e fornece um valor de retorno de SP_ERROR para StartPage.

Comentários

Para um valor iEsc de DOCUMENTEVENT_QUERYFILTER, o spooler pode interpretar um valor DOCUMENTEVENT_SUCCESS retornado pelo DocumentEvent de duas maneiras, dependendo se o driver modificou determinados membros da estrutura DOCEVENT_FILTER (que está documentado no Windows Driver Development Kit). (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 DocumentEvent retorna, o spooler determina se os valores desses membros foram alterados e usa essas informações para interpretar o valor retornado do DocumentEvent . A tabela a seguir resume essa situação.

Valor Retornado	Status de cElementsReturned e 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 do DocumentEvent para todos os eventos.
DOCUMENTEVENT_SUCCESS	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 zero. O spooler filtra todos os eventos listados no membro aDocEventCall do DOCEVENT_FILTER (que está documentado no Windows Driver Development Kit).
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 do DocumentEvent 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 do DocumentEvent para todos os eventos.

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. (Para obter mais informações, consulte a documentação da estrutura DOCEVENT_CREATEDCPRE no Windows Driver Development Kit.)
Se o trabalho estiver sendo iniciado, pvIn-pszDevice> apontará para o nome da porta da impressora.

Observação

As restrições a seguir se aplicam ao executar um aplicativo de 32 bits em uma versão de 64 bits do Windows. A única função GDI que DocumentEvent deve chamar é ExtEscape, e somente escapes privados devem ser usados. As chamadas do DocumentEvent para outras funções GDI podem produzir um comportamento indefinido.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Cabeçalho	Winspool.h (inclua Windows.h)
Nomes Unicode e ANSI	DocumentEventW (Unicode) e DocumentEventA (ANSI)

Confira também

Impressão
Funções da API do Spooler de impressão
Windows Driver Development Kit