Função DocumentEvent

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