Funzione DrvDocumentEvent (winddiui.h)
La funzione DrvDocumentEvent di una DLL dell'interfaccia della stampante può gestire determinati eventi associati alla stampa di un documento.
Sintassi
int DrvDocumentEvent(
HANDLE hPrinter,
HDC hdc,
int iEsc,
ULONG cbIn,
[in] PVOID pvIn,
ULONG cbOut,
[out] PVOID pvOut
);
Parametri
hPrinter
Handle stampante fornito dal chiamante.
hdc
Handle del contesto del dispositivo fornito dal chiamante, generato da un oggetto CreateDC Questo è zero se iEsc è impostato su DOCUMENTEVENT_CREATEDCPRE. Per restrizioni sulla stampa da un'applicazione a 32 bit in una versione a 64 bit di Windows, vedere la sezione Osservazioni di seguito.
iEsc
Codice di escape fornito dal chiamante che identifica l'evento da gestire.
Per restrizioni sulla stampa da un'applicazione a 32 bit in una versione a 64 bit di Windows, vedere la sezione Osservazioni di seguito.
Questo parametro può essere una delle costanti integer seguenti:
| Costante iEsc | Evento |
|---|---|
| DOCUMENTEVENT_ABORTDOC | GDI sta per elaborare una chiamata alla 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 impostata su DOCUMENTEVENT_CREATEDCPRE. |
| DOCUMENTEVENT_CREATEDCPRE | GDI sta per elaborare una chiamata alla funzione CreateDC o CreateIC . |
| DOCUMENTEVENT_DELETEDC | GDI sta per elaborare una chiamata alla funzione DeleteDC . |
| DOCUMENTEVENT_ENDDOCPOST | GDI ha appena elaborato una chiamata alla sua funzione EndDoc . |
| DOCUMENTEVENT_ENDDOCPRE o DOCUMENTEVENT_ENDDOC | GDI sta per elaborare una chiamata alla sua funzione EndDoc . |
| DOCUMENTEVENT_ENDPAGE | GDI sta per elaborare una chiamata alla funzione EndPage . |
| DOCUMENTEVENT_ESCAPE | GDI sta per elaborare una chiamata alla funzione ExtEscape . |
| DOCUMENTEVENT_QUERYFILTER | L'evento DOCUMENTEVENT_QUERYFILTER rappresenta un'opportunità per lo spooler di eseguire query sul driver per un elenco degli eventi DOCUMENTEVENT_ XXX a cui risponderà il driver. Questo evento viene rilasciato appena prima di una chiamata a DrvDocumentEvent che passa l'evento DOCUMENTEVENT_CREATEDCPRE. |
| DOCUMENTEVENT_RESETDCPOST | GDI ha appena elaborato una chiamata alla funzione ResetDC . Questo codice di escape non deve essere usato a meno che non sia stata eseguita una chiamata precedente a DrvDocumentEvent con iEsc impostata su DOCUMENTEVENT_RESETDCPRE. |
| DOCUMENTEVENT_RESETDCPRE | GDI sta per elaborare una chiamata alla relativa funzione ResetDC . |
| DOCUMENTEVENT_STARTDOCPOST | GDI ha appena elaborato una chiamata alla funzione StartDoc . |
| DOCUMENTEVENT_STARTDOCPRE o DOCUMENTEVENT_STARTDOC | GDI sta per elaborare una chiamata alla funzione StartDoc . |
| DOCUMENTEVENT_STARTPAGE | GDI sta per elaborare una chiamata alla funzione StartPage . |
cbIn
Dimensioni fornite dal chiamante, in byte, del buffer a cui punta pvIn.
[in] pvIn
Puntatore fornito dal chiamante, l'uso del quale dipende dal valore fornito per iEsc, come indicato di seguito:
| Costante iEsc | contenuto pvIn |
|---|---|
| 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 o 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 alla struttura DEVMODEW fornita dal chiamante della funzione ResetDC . |
| DOCUMENTEVENT_STARTDOCPOST | pvIn punta a long che specifica l'identificatore del processo di stampa restituito dalla funzione StartDoc . |
| DOCUMENTEVENT_STARTDOCPRE o DOCUMENTEVENT_STARTDOC | pvIn contiene l'indirizzo di un puntatore a una struttura DOCINFO fornita dal chiamante della funzione StartDoc . |
| DOCUMENTEVENT_STARTPAGE | Non usato. |
cbOut
Se iEsc è DOCUMENTEVENT_ESCAPE
Valore fornito dalla funzione utilizzato come parametro cbOutput per la funzione ExtEscape .
Se iEsc è DOCUMENTEVENT_QUERYFILTER
Dimensioni fornite dal chiamante, in byte, del puntatore del buffer a da pvOut.
Per tutti gli altri valori iEsc
Non usato.
[out] pvOut
Puntatore fornito dalla funzione a un buffer di output, l'uso del quale dipende dal valore fornito per iEsc, come indicato di seguito:
| Costante iEsc | contenuto pvOut |
|---|---|
| DOCUMENTEVENT_CREATEDCPRE | Puntatore a una struttura DEVMODEW fornita dal driver, che GDI usa anziché quella fornita dal chiamante CreateDC . Se NULL, GDI usa la struttura fornita dal chiamante. |
| DOCUMENTEVENT_ESCAPE | Puntatore del buffer usato come parametro lpszOutData per la funzione ExtEscape . |
| DOCUMENTEVENT_QUERYFILTER | Puntatore fornito dal chiamante per il buffer contenente una struttura di DOCEVENT_FILTER . |
| DOCUMENTEVENT_RESETDCPRE | Puntatore a una struttura DEVMODEW fornita dal driver, che GDI usa anziché quella fornita dal chiamante della funzione ResetDC . Se NULL, GDI usa la struttura fornita dal chiamante. |
| Tutti gli altri valori di iEsc | Non usato. |
Valore restituito
Il valore restituito della funzione dipende dall'escape fornito per iEsc. Per alcuni codici di escape, il valore restituito non viene usato (vedere il secondo elenco di valori). Se la funzione fornisce un valore restituito, deve essere una delle seguenti:
| Codice restituito | Descrizione |
|---|---|
| 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. |
| DOCUMENTEVENT_UNSUPPORTED | Il driver non supporta il codice di escape identificato da iEsc. |
Commenti
Una DLL dell'interfaccia della stampante può fornire facoltativamente una funzione DrvDocumentEvent per eseguire pre-elaborazione o post-elaborazione delle chiamate GDI associate al rendering di un documento. Le chiamate alla funzione DrvDocumentEvent vengono eseguite dal client GDI in modalità utente, quando un'applicazione effettua chiamate al client GDI.
Per un valore iEsc di DOCUMENTEVENT_QUERYFILTER, il spooler può interpretare un valore DOCUMENTEVENT_SUCCESS restituito da DrvDocumentEvent in due modi, a seconda che il driver abbia modificato determinati membri della struttura DOCEVENT_FILTER . Il parametro pvOut punta a questa struttura. Quando lo spooler alloca la memoria per una struttura di questo tipo, inizializza due membri di questa struttura, cElementsReturned e cElementsNeeded, ai valori noti. Dopo che DrvDocumentEvent restituisce, lo spooler determina se i valori di questi membri sono stati modificati e utilizza tali informazioni per interpretare il valore restituito DrvDocumentEvent . La tabella seguente riepiloga questa situazione.
| Valore restituito | Stato di cElementsReturned, cElementsNeeded | Significato |
|---|---|---|
| DOCUMENTEVENT_SUCCESS | Il driver non ha apportato alcuna modifica a entrambi i membri. | Il spooler interpreta questo valore restituito come equivalente a DOCUMENTEVENT_UNSUPPORTED. Il spooler non è in grado di recuperare il filtro evento dal driver, quindi persiste nella chiamata di DrvDocumentEvent per tutti gli eventi. |
| DOCUMENTEVENT_SUCCESS | Driver ha scritto uno o entrambi i membri. | Il spooler accetta questo valore restituito senza interpretazione. Se il driver ha scritto solo in uno di cElementsNeeded e cElementsReturned, lo spooler considera il membro invariato in modo che abbia un valore pari a zero. Lo spooler filtra tutti gli eventi elencati nel membro aDocEventCall di DOCEVENT_FILTER. |
| DOCUMENTEVENT_UNSUPPORTED | Non applicabile | Il driver non supporta DOCUMENTEVENT_QUERYFILTER. Il spooler non è in grado di recuperare il filtro evento dal driver, quindi persiste nella chiamata di DrvDocumentEvent per tutti gli eventi. |
| DOCUMENTEVENT_FAILURE | Non applicabile | Il driver supporta DOCUMENTEVENT_QUERYFILTER, ma ha rilevato un errore interno. Il spooler non è in grado di recuperare il filtro evento dal driver, quindi persiste nella chiamata di DrvDocumentEvent per tutti gli eventi. |
Se il nome del codice di escape non ha suffisso o è suffisso con PRE, il client GDI chiama DrvDocumentEvent appena prima di chiamare il motore di rendering GDI in modalità kernel. Se il nome del codice di escape è suffisso con POST, il client GDI chiama DrvDocumentEvent subito dopo che il motore di rendering GDI in modalità kernel restituisce.
Se il codice di escape fornito nel parametro iEsc è DOCUMENTEVENT_CREATEDCPRE, si applicano le regole seguenti:
Se il processo viene inviato direttamente alla stampante senza spooling, pvIn --> pszDevice punta al nome della stampante. Per altre informazioni, vedere la struttura DOCEVENT_CREATEDCPRE .
Se il processo viene eseguito ilpooling, pvIn --> pszDevice punta al nome della porta della stampante.
La funzione DrvDocumentEvent viene eseguita nel contesto del chiamante in modalità utente della funzione client GDI. Quando lo spooling EMF è disabilitato, la funzione può visualizzare un'interfaccia utente. Ad esempio, la funzione DrvDocumentEvent per un driver FAX potrebbe visualizzare una finestra di dialogo all'utente prima dell'elaborazione della funzione StartDoc di GDI.
Le restrizioni seguenti si applicano quando si esegue un'applicazione a 32 bit in una versione a 64 bit di Windows:
L'unica funzione GDI che DrvDocumentEvent deve chiamare è ExtEscape e deve essere usata solo le escape private.
Le chiamate DrvDocumentEvent ad altre funzioni GDI possono produrre un comportamento non definito.
Requisiti
| Requisito | Valore |
|---|---|
| Piattaforma di destinazione | Desktop |
| Intestazione | winddiui.h (include Winddiui.h) |