Método IPrintOemUI2::D ocumentEvent (prcomoem.h)

Artigo
03/14/2023

O IPrintOemUI2::DocumentEvent método permite que um plug-in de interface do usuário substitua a implementação padrão do módulo de interface do usuário do driver principal da DDI DrvDocumentEvent .

Sintaxe

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

Parâmetros

hPrinter

Identificador de impressora fornecido pelo chamador.

hdc

Identificador de contexto do dispositivo fornecido pelo chamador, gerado por uma chamada CreateDC . Isso será zero se iEsc for DOCUMENTEVENT_CREATEDCPRE.

iEsc

Código de escape fornecido pelo chamador que identifica o evento a ser tratado. Esse parâmetro pode ser uma das seguintes constantes inteiros:

Código de escape	Significado
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.

pvIn

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

iEsc Constante	pvIn Conteúdo
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 de 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 uma estrutura DEVMODEW fornecida pelo chamador de ResetDC (descrito na documentação do SDK do Microsoft Windows).
DOCUMENTEVENT_STARTDOCPOST	pvIn aponta para um LONG que especifica o identificador de trabalho de impressão retornado por StartDoc (descrito na documentação do SDK do Windows).
DOCUMENTEVENT_STARTDOCPRE ou DOCUMENTEVENT_STARTDOC	pvIn contém o endereço de um ponteiro para uma estrutura DOCINFO fornecida pelo chamador de StartDoc (ambos descritos na documentação do SDK do Windows).
DOCUMENTEVENT_STARTPAGE	Não usado.

cbOut

Se iEsc for DOCUMENTEVENT_ESCAPE:

Valor fornecido pela função que é usado como o parâmetro cbOutput para 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.

pvOut

Ponteiro fornecido pela função para um buffer de saída, cujo uso depende do valor fornecido para iEsc, da seguinte maneira. CreateDC, ExtEscape e ResetDC são descritos na documentação do SDK do Windows.

iEsc Constante	pvOut Conteúdo
DOCUMENTEVENT_CREATEDCPRE	Ponteiro para uma estrutura DEVMODEW fornecida pelo driver, que o GDI usa em vez da fornecida pelo chamador CreateDC . (Se NULL, a GDI usará a estrutura fornecida pelo chamador.)
DOCUMENTEVENT_ESCAPE	Ponteiro de buffer usado como o parâmetro lpszOutData para 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 ResetDC . (Se NULL, a GDI usará a estrutura fornecida pelo chamador.)
Todos os outros valores iEsc	Não usado.

piResult

Ponteiro para um local de memória que recebe um dos seguintes valores:

Valor Retornado	Definiçã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. Consulte também a seção Comentários para obter mais informações.
DOCUMENTEVENT_UNSUPPORTED	O driver não dá suporte ao código de escape identificado pelo iEsc.

Retornar valor

Esse método deve retornar um dos valores a seguir. Consulte a seção Comentários para obter mais informações.

Código de retorno	Descrição
S_OK	O plug-in da interface do usuário implementa esse método.
E_NOTIMPL	O plug-in da interface do usuário não implementa esse método.

Comentários

O método de um plug-in de interface do IPrintOemUI2::DocumentEvent usuário executa os mesmos tipos de operações que a DDI DrvDocumentEvent exportada por DLLs da interface da impressora do modo de usuário. Para obter informações sobre eventos de documento e como eles devem ser processados, consulte a descrição da DDI DrvDocumentEvent .

Se você fornecer um plug-in de interface do usuário, a DDI DrvDocumentEvent do driver de impressora chamará o IPrintOemUI2::DocumentEvent método . A DDI DrvDocumentEvent executa seu próprio processamento para o evento especificado e, em seguida, chama o IPrintOemUI2::DocumentEvent método para lidar com o processamento adicional do evento.

Quando esse método é chamado com um valor do parâmetro iEsc de DOCUMENTEVENT_QUERYFILTER e retorna com *piResult == DOCUMENTEVENT_SUCCESS, o spooler pode interpretar esse valor de duas maneiras, dependendo se determinados membros da estrutura DOCEVENT_FILTER alteraram valores. Para obter mais informações, consulte a seção Comentários para DrvDocumentEvent.

Quando o evento DOCUMENTEVENT_QUERYFILTER é acionado, o driver principal chama plug-ins na ordem em que foram instalados, até que um deles retorne S_OK ou até que todos os plug-ins tenham sido chamados e nenhum deles retorne S_OK. Dessa forma, no máximo um plug-in tem permissão para lidar com o evento DOCUMENTEVENT_QUERYFILTER e o filtro especificado é aplicado a todos os plug-ins na cadeia de plug-ins.

Para um gravador de plug-in que está implementando a interface IPrintOemUI2 , mas não precisa dar suporte IPrintOemUI2::DocumentEvent ao método , esse método deve retornar E_NOTIMPL para todos os valores de iEsc. Se você precisar implementar esse método, ele deverá retornar S_OK para todos os valores de iEsc. Isso sinaliza ao driver principal que esse método lidou com o evento relevante. O driver principal usa o valor que esse método coloca em piResult como o valor retornado para a DDI DrvDocumentEvent .