Metodo IPrintOemUI2::D ocumentEvent (prcomoem.h)

Articolo
03/14/2023

Il IPrintOemUI2::DocumentEvent metodo consente a un plug-in dell'interfaccia utente di sostituire l'implementazione predefinita del modulo di interfaccia utente del driver principale di DrvDocumentEvent DDI.

Sintassi

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

Parametri

hPrinter

Handle stampante fornito dal chiamante.

hdc

Handle del contesto di dispositivo fornito dal chiamante generato da una chiamata CreateDC . Questo è zero se iEsc è DOCUMENTEVENT_CREATEDCPRE.

iEsc

Codice di escape fornito dal chiamante che identifica l'evento da gestire. Questo parametro può essere una delle costanti integer seguenti:

Codice di escape	Significato
DOCUMENTEVENT_ABORTDOC	GDI sta per elaborare una chiamata alla relativa funzione AbortDoc .
DOCUMENTEVENT_CREATEDCPOST	GDI ha appena elaborato una chiamata alla relativa funzione CreateDC o CreateIC . Questo codice di escape non deve essere usato a meno che non sia stata eseguita una chiamata precedente a DrvDocumentEvent con iEsc impostato su DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_CREATEDCPRE	GDI sta per elaborare una chiamata alla relativa funzione CreateDC o CreateIC .
DOCUMENTEVENT_DELETEDC	GDI sta per elaborare una chiamata alla relativa funzione DeleteDC .
DOCUMENTEVENT_ENDDOCPOST	GDI ha appena elaborato una chiamata alla relativa funzione EndDoc .
DOCUMENTEVENT_ENDDOCPRE oppure DOCUMENTEVENT_ENDDOC	GDI sta per elaborare una chiamata alla relativa funzione EndDoc .
DOCUMENTEVENT_ENDPAGE	GDI sta per elaborare una chiamata alla relativa funzione EndPage .
DOCUMENTEVENT_ESCAPE	GDI sta per elaborare una chiamata alla relativa funzione ExtEscape .
DOCUMENTEVENT_QUERYFILTER	L'evento DOCUMENTEVENT_QUERYFILTER rappresenta un'opportunità per lo spooler di eseguire una query sul driver per un elenco degli eventi DOCUMENTEVENT_XXX a cui risponderà il driver. Questo evento viene generato poco prima di una chiamata a DrvDocumentEvent che passa l'evento DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_RESETDCPOST	GDI ha appena elaborato una chiamata alla relativa funzione ResetDC . Questo codice di escape non deve essere usato a meno che non sia stata eseguita una chiamata precedente a DrvDocumentEvent con iEsc impostato su DOCUMENTEVENT_RESETDCPRE.
DOCUMENTEVENT_RESETDCPRE	GDI sta per elaborare una chiamata alla relativa funzione ResetDC .
DOCUMENTEVENT_STARTDOCPOST	GDI ha appena elaborato una chiamata alla relativa funzione StartDoc .
DOCUMENTEVENT_STARTDOCPRE oppure DOCUMENTEVENT_STARTDOC	GDI sta per elaborare una chiamata alla relativa funzione StartDoc .
DOCUMENTEVENT_STARTPAGE	GDI sta per elaborare una chiamata alla relativa funzione StartPage .

cbIn

Dimensione fornita dal chiamante, in byte, del buffer a cui punta pvIn.

pvIn

Puntatore fornito dal chiamante, l'uso del quale dipende dal valore fornito per iEsc, come indicato di seguito:

iEsc Costante	pvIn Contenuto
DOCUMENTEVENT_ABORTDOC	Non usato.
DOCUMENTEVENT_CREATEDCPOST	pvIn contiene l'indirizzo di un puntatore alla struttura DEVMODEW specificata nel parametro pvOut in una chiamata precedente a questa funzione, per cui il parametro iEsc è stato impostato su DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_CREATEDCPRE	pvIn punta a una struttura DOCEVENT_CREATEDCPRE .
DOCUMENTEVENT_DELETEDC	Non usato.
DOCUMENTEVENT_ENDDOCPOST	Non usato.
DOCUMENTEVENT_ENDDOCPRE oppure DOCUMENTEVENT_ENDDOC	Non usato.
DOCUMENTEVENT_ENDPAGE	Non usato.
DOCUMENTEVENT_ESCAPE	pvIn punta a una struttura DOCEVENT_ESCAPE .
DOCUMENTEVENT_QUERYFILTER	Uguale a per DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_RESETDCPOST	pvIn contiene l'indirizzo di un puntatore alla struttura DEVMODEW specificata nel parametro pvOut in una chiamata precedente a questa funzione, per cui il parametro iEsc è stato impostato su DOCUMENTEVENT_RESETDCPRE.
DOCUMENTEVENT_RESETDCPRE	pvIn contiene l'indirizzo di un puntatore a una struttura DEVMODEW fornita dal chiamante di ResetDC (descritta nella documentazione Microsoft Windows SDK).
DOCUMENTEVENT_STARTDOCPOST	pvIn punta a un valore LONG che specifica l'identificatore del processo di stampa restituito da StartDoc (descritto nella documentazione di Windows SDK).
DOCUMENTEVENT_STARTDOCPRE oppure DOCUMENTEVENT_STARTDOC	pvIn contiene l'indirizzo di un puntatore a una struttura DOCINFO fornita dal chiamante di StartDoc (entrambi descritti nella documentazione di Windows SDK).
DOCUMENTEVENT_STARTPAGE	Non usato.

cbOut

Se iEsc è DOCUMENTEVENT_ESCAPE:

Valore fornito dalla funzione usato come parametro cbOutput per ExtEscape.

Se iEsc è DOCUMENTEVENT_QUERYFILTER:

Dimensioni fornite dal chiamante, in byte, del puntatore del buffer a da pvOut.

Per tutti gli altri valori di iEsc:

Non usato.

pvOut

Puntatore fornito dalla funzione a un buffer di output, che dipende dal valore fornito per iEsc, come indicato di seguito. CreateDC, ExtEscape e ResetDC sono descritti nella documentazione di Windows SDK.

iEsc Costante	pvOut Contenuto
DOCUMENTEVENT_CREATEDCPRE	Puntatore a una struttura DEVMODEW fornita dal driver, che GDI usa anziché quella fornita dal chiamante CreateDC . Se NULL, GDI utilizza la struttura fornita dal chiamante.
DOCUMENTEVENT_ESCAPE	Puntatore al buffer usato come parametro lpszOutData per ExtEscape.
DOCUMENTEVENT_QUERYFILTER	Puntatore fornito dal chiamante al buffer contenente una struttura DOCEVENT_FILTER .
DOCUMENTEVENT_RESETDCPRE	Puntatore a una struttura DEVMODEW fornita dal driver, che GDI usa anziché quella fornita dal chiamante ResetDC . Se NULL, GDI utilizza la struttura fornita dal chiamante.
Tutti gli altri valori di iEsc	Non usato.

piResult

Puntatore a una posizione di memoria che riceve uno dei valori seguenti:

Valore restituito	Definizione
DOCUMENTEVENT_FAILURE	Il driver supporta il codice di escape identificato da iEsc, ma si è verificato un errore.
DOCUMENTEVENT_SUCCESS	Il driver ha gestito correttamente il codice di escape identificato da iEsc. Per altre informazioni, vedere anche la sezione Osservazioni.
DOCUMENTEVENT_UNSUPPORTED	Il driver non supporta il codice di escape identificato da iEsc.

Valore restituito

Questo metodo deve restituire uno dei valori seguenti. Per altre informazioni, vedere la sezione Osservazioni.

Codice restituito	Descrizione
S_OK	Il plug-in dell'interfaccia utente implementa questo metodo.
E_NOTIMPL	Il plug-in dell'interfaccia utente non implementa questo metodo.

Commenti

Il metodo del plug-in di IPrintOemUI2::DocumentEvent un'interfaccia utente esegue gli stessi tipi di operazioni dell'DDI DrvDocumentEvent esportato dalle DLL dell'interfaccia della stampante in modalità utente. Per informazioni sugli eventi del documento e su come devono essere elaborati, vedere la descrizione dell'DDI drvDocumentEvent .

Se si specifica un plug-in dell'interfaccia utente, il DDI drvDocumentEvent del driver della stampante chiama il IPrintOemUI2::DocumentEvent metodo . DrvDocumentEvent DDI esegue la propria elaborazione per l'evento specificato e quindi chiama il IPrintOemUI2::DocumentEvent metodo per gestire l'elaborazione aggiuntiva dell'evento.

Quando questo metodo viene chiamato con un valore del parametro iEsc di DOCUMENTEVENT_QUERYFILTER e restituisce con *piResult == DOCUMENTEVENT_SUCCESS, lo spooler può interpretare questo valore in uno dei due modi, a seconda che determinati membri della struttura DOCEVENT_FILTER modificano i valori. Per altre informazioni, vedere la sezione Osservazioni per DrvDocumentEvent.

Quando viene generato l'evento DOCUMENTEVENT_QUERYFILTER, il driver principale chiama i plug-in nell'ordine in cui sono stati installati, fino a quando uno di essi non restituisce S_OK o fino a quando tutti i plug-in non sono stati chiamati e nessuno di essi ha restituito S_OK. In questo modo, al massimo un plug-in può gestire l'evento DOCUMENTEVENT_QUERYFILTER e il filtro specificato viene applicato a tutti i plug-in nella catena di plug-in.

Per un writer plug-in che implementa l'interfaccia IPrintOemUI2 , ma non è necessario supportare il IPrintOemUI2::DocumentEvent metodo , questo metodo deve restituire E_NOTIMPL per tutti i valori di iEsc. Se è necessario implementare questo metodo, deve restituire S_OK per tutti i valori di iEsc. Segnala al driver principale che questo metodo ha gestito l'evento pertinente. Il driver principale usa il valore che questo metodo inserisce in piResult come valore restituito per l'DDI DrvDocumentEvent .