Funzione DrvDocumentEvent (winddiui.h)

  • Articolo

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)

Vedi anche

DOCEVENT_CREATEDCPRE

DOCEVENT_ESCAPE

DOCEVENT_FILTER