Share via

Função DocumentEvent

  • Artigo

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 de dispositivo que é gerado por uma chamada de CreateDC. Isso será zero se iEsc estiver definido como DOCUMENTEVENT_CREATEDCPRE. Para obter restrições à impressão a partir de um aplicativo de 32 bits em uma versão de 64 bits do Windows, consulte Observações.

iEsc

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

Constante Evento
DOCUMENTEVENT_ABORTDOC
 A GDI está prestes a processar uma chamada para a respectiva função AbortDoc.
DOCUMENTEVENT_CREATEDCPOST
 A GDI acaba de processar uma chamada para a respectiva função CreateDC ou CreateIC.
Esse código de escape não deve ser usado, a menos que tenha havido uma chamada anterior para DocumentEvent com iEsc definido como DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_CREATEDCPRE
 A GDI está prestes a processar uma chamada para a respectiva função CreateDC ou CreateIC.
DOCUMENTEVENT_DELETEDC
 A GDI está prestes a processar uma chamada para a respectiva função DeleteDC.
DOCUMENTEVENT_ENDDOCPOST
 A GDI acaba de processar uma chamada para a respectiva função EndDoc.
DOCUMENTEVENT_ENDDOCPRE ou DOCUMENTEVENT_ENDDOC
 A GDI está prestes a processar uma chamada para a respectiva função EndDoc.
DOCUMENTEVENT_ENDPAGE
 A GDI está prestes a processar uma chamada para a respectiva função EndPage.
DOCUMENTEVENT_ESCAPE
 A GDI está prestes a processar uma chamada para a respectiva 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 imediatamente antes de uma chamada para DocumentEvent que passa o evento DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_RESETDCPOST
 A GDI acaba de processar uma chamada para a respectiva função ResetDC.
Esse código de escape não deve ser usado, a menos que tenha havido uma chamada anterior para DocumentEvent com iEsc definido como DOCUMENTEVENT_RESETDCPRE.
DOCUMENTEVENT_RESETDCPRE
 A GDI está prestes a processar uma chamada para a respectiva função ResetDC.
DOCUMENTEVENT_STARTDOCPOST
 A GDI acaba de processar uma chamada para a respectiva função StartDoc.
DOCUMENTEVENT_STARTDOCPRE ou DOCUMENTEVENT_STARTDOC
 A GDI está prestes a processar uma chamada para a respectiva função StartDoc.
DOCUMENTEVENT_STARTPAGE
 A GDI está prestes a processar uma chamada para a respectiva 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 de iEsc, conforme mostrado na tabela a seguir.

Constante Conteúdo de 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 por StartDoc.
DOCUMENTEVENT_STARTDOCPRE ou DOCUMENTEVENT_STARTDOC
 pvIn contém o endereço de um ponteiro para a estrutura DOCINFO fornecida pelo chamador de StartDoc.
DOCUMENTEVENT_STARTPAGE
 Não usado.

cbOut

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

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 a GDI usa em vez daquela fornecida pelo chamador CreateDC. (Se é NULL, a GDI usa a estrutura fornecida pelo chamador.)
DOCUMENTEVENT_ESCAPE
 Um ponteiro para um buffer que é usado como o parâmetro lpszOutData para ExtEscape.
DOCUMENTEVENT_QUERYFILTER
 Um ponteiro para 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 a GDI usa em vez daquela fornecida pelo chamador ResetDC. (Se é NULL, a GDI usa a estrutura fornecida pelo chamador.)

Valor retornado

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

Valor de retorno Significado
DOCUMENTEVENT_FAILURE O driver dá suporte ao código de escape identificado por iEsc, mas ocorreu uma falha.
DOCUMENTEVENT_SUCCESS O driver manipulou com êxito o código de escape identificado por iEsc.
DOCUMENTEVENT_UNSUPPORTED O driver não dá suporte ao código de escape identificado por iEsc.

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

Valor de retorno Significado
DOCUMENTEVENT_ABORTDOC O valor de retorno não é usado e não deve ser lido.
DOCUMENTEVENT_CREATEDCPOST O valor de retorno não é usado e não deve ser lido.
DOCUMENTEVENT_CREATEDCPRE DOCUMENTEVENT_FAILURE – GDI não cria o contexto do dispositivo ou contexto de informações e fornece um valor de retorno de 0 para CreateDC ou CreateIC.
DOCUMENTEVENT_DELETEDC O valor de retorno não é usado e não deve ser lido.
DOCUMENTEVENT_ENDDOCPOST O valor de retorno não é usado e não deve ser lido.
DOCUMENTEVENT_ENDDOCPRE ou DOCUMENTEVENT_ENDDOC O valor de retorno não é usado e não deve ser lido.
DOCUMENTEVENT_ENDPAGE O valor de retorno não é usado e não deve ser lido.
DOCUMENTEVENT_ESCAPE O valor de retorno não é usado e não deve ser lido.
DOCUMENTEVENT_QUERYFILTER Consulte Observações.
DOCUMENTEVENT_RESETDCPOST O valor de retorno não é usado e não deve ser lido.
DOCUMENTEVENT_RESETDCPRE DOCUMENTEVENT_FAILURE – GDI não redefine o contexto do dispositivo e fornece um valor de retorno de 0 para ResetDC.
DOCUMENTEVENT_STARTDOCPOST DOCUMENTEVENT_FAILURE – GDI chama AbortDoc para parar o documento e, em seguida, fornece um valor de retorno de SP_ERROR para StartDoc.
DOCUMENTEVENT_STARTDOCPRE ou DOCUMENTEVENT_STARTDOC DOCUMENTEVENT_FAILURE – GDI não inicia o documento e fornece um valor de retorno de SP_ERROR para StartDoc.
DOCUMENTEVENT_STARTPAGE DOCUMENTEVENT_FAILURE – 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 por DocumentEvent de duas maneiras, dependendo se o driver modificou ou não determinados membros da estrutura DOCEVENT_FILTER (que está documentada 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 de retorno DocumentEvent. A tabela a seguir resume essa situação.

Valor de retorno 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 de retorno como equivalente a DOCUMENTEVENT_UNSUPPORTED. O spooler não consegue recuperar o filtro de eventos do driver, portanto, ele persiste em chamar DocumentEvent para todos os eventos.
DOCUMENTEVENT_SUCCESS
 O sriver escreveu para um ou ambos os membros.
 O spooler aceita esse valor de retorno sem interpretação. Se o driver escreveu em apenas um de cElementsNeeded e cElementsReturned, o spooler considera o membro inalterado como tendo 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 eventos do driver, portanto, ele persiste em chamar 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 eventos do driver, portanto, ele persiste em chamar DocumentEvent para todos os eventos.

Se o código de escape fornecido no parâmetro iEsc é DOCUMENTEVENT_CREATEDCPRE, as seguintes regras serão aplicadas:

  • Se o trabalho estiver sendo enviado diretamente para a impressora sem spooling, pvIn->pszDevice aponta para o nome da impressora. (Para obter mais informações, consulte a documentação da estrutura DOCEVENT_CREATEDCPRE no Kit de Desenvolvimento de Driver do Windows.)
  • Se o trabalho estiver em spool, pvIn-pszDevice> aponta 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. Chamadas DocumentEvent para outras funções GDI podem produzir 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 (inclui Windows.h)
Nomes Unicode e ANSI
 DocumentEventW (Unicode) e DocumentEventA (ANSI)

Confira também