Função DrvDocumentEvent (winddiui.h)
Uma função drvDocumentEvent de de interface de impressora 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 umCreateDCIsso é 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 tratado.
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 inteiros:
| constante de iEsc | Acontecimento |
|---|---|
| DOCUMENTEVENT_ABORTDOC | A GDI está prestes a processar uma chamada para sua funçãoAbortDoc. |
| 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çãoEndDoc. |
| DOCUMENTEVENT_ENDPAGE | A GDI está prestes a processar uma chamada para sua funçãoEndPage. |
| DOCUMENTEVENT_ESCAPE | A GDI está prestes a processar uma chamada para sua funçãoextEscape. |
| DOCUMENTEVENT_QUERYFILTER | O evento DOCUMENTEVENT_QUERYFILTER representa uma oportunidade para o spooler consultar o driver para obter uma lista dos eventos deXXX DOCUMENTEVENT_ 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çãoresetDC. 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 deResetDC. |
| DOCUMENTEVENT_STARTDOCPOST | A GDI acabou de processar uma chamada para sua função deStartDoc. |
| DOCUMENTEVENT_STARTDOCPRE ou DOCUMENTEVENT_STARTDOC | A GDI está prestes a processar uma chamada para sua função deStartDoc. |
| 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, do qual o uso depende do valor fornecido para iEsc, da seguinte maneira:
| constante de iEsc | conteúdo de pvIn |
|---|---|
| DOCUMENTEVENT_ABORTDOC | Não usado. |
| DOCUMENTEVENT_CREATEDCPOST | pvIn contém o endereço de um ponteiro para a estrutura deDEVMODEWespecificada 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 dedeDEVMODEW 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 deDEVMODEWfornecida pelo chamador da funçãoresetDC. |
| DOCUMENTEVENT_STARTDOCPOST | pvIn aponta para um LONG que especifica o identificador de trabalho de impressão retornado pela funçãoStartDoc. |
| DOCUMENTEVENT_STARTDOCPRE ou DOCUMENTEVENT_STARTDOC | pvIn contém o endereço de um ponteiro para uma estrutura dedo DOCINFOfornecida pelo chamador da função StartDoc. |
| DOCUMENTEVENT_STARTPAGE | Não usado. |
cbOut
Se o iEsc for DOCUMENTEVENT_ESCAPE
Valor fornecido pela função que é usado como o parâmetro cbOutput para a funçãoextEscape.
Se o iEsc for DOCUMENTEVENT_QUERYFILTER
Tamanho fornecido pelo chamador, em bytes, do ponteiro do buffer para pvOut.
Para todos os outros valores iEsc
Não usado.
[out] pvOut
Ponteiro fornecido por função para um buffer de saída, do qual o uso depende do valor fornecido para iEsc, da seguinte maneira:
| constante de iEsc | conteúdo de pvOut |
|---|---|
| DOCUMENTEVENT_CREATEDCPRE | Ponteiro para uma estrutura DEVMODEW fornecida pelo driver, que a GDI usa em vez daquela 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 a funçãoextEscape. |
| DOCUMENTEVENT_QUERYFILTER | Ponteiro fornecido pelo chamador para o buffer que contém uma estrutura de DOCEVENT_FILTER. |
| DOCUMENTEVENT_RESETDCPRE | Ponteiro para uma estrutura DEVMODEW fornecida pelo driver, que a GDI usa em vez daquela fornecida pelo chamador de função ResetDC. (Se NULL, a GDI usará a estrutura fornecida pelo chamador.) |
| Todos os outros valores de iEsc | Não usado. |
Valor de retorno
O valor retornado da função depende da escape fornecida 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 por iEsc, mas ocorreu uma falha. |
| DOCUMENTEVENT_SUCCESS | O driver lidou com êxito com o código de escape identificado por iEsc. |
| DOCUMENTEVENT_UNSUPPORTED | O driver não dá suporte ao código de escape identificado pelo iEsc. |
Observações
Uma de DLL da interface da impressora pode, opcionalmente, fornecer uma função DrvDocumentEvent para executar o pré-processamento ou o 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 DrvDocumentEvent valor retornado. A tabela a seguir resume essa situação.
| Valor de retorno | 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 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 cElementsNeededed 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. |
| 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 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 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 no modo kernel retornar.
Se o código de escape fornecido no parâmetro iEsc for DOCUMENTEVENT_CREATEDCPRE, as seguintes regras se aplicam:
Se o trabalho estiver sendo enviado diretamente para a impressora sem spooling, pvIn --> pszDevice aponta para o nome da impressora. (Consulte a estrutura DOCEVENT_CREATEDCPRE para obter mais informações.)
Se o trabalho estiver sendo spooled, pvIn --> pszDevice aponta para o nome da porta da impressora.
A função DrvDocumentEvent é executada no contexto do chamador do modo de usuário da função de cliente GDI. Quando o spooling do EMF está desabilitado, a função pode exibir uma interface do usuário. Por exemplo, a função DrvDocumentEvent para um driver de 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 apenas escapes privados devem ser usados.
DrvDocumentEvent chamadas para outras funções GDI podem produzir um comportamento indefinido.
Requisitos
| Requisito | Valor |
|---|---|
| da Plataforma de Destino | Área de trabalho |
| cabeçalho | winddiui.h (inclua Winddiui.h) |