Funzione DocumentEvent

La funzione DocumentEvent è un gestore eventi per gli eventi associati alla stampa di un documento.

Sintassi

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

Parametri

hPrinter [in]

Handle per un oggetto stampante. Utilizzare la funzione OpenPrinter o AddPrinter per recuperare un handle della stampante.

hdc [in]

Handle del contesto di dispositivo generato da una chiamata di CreateDC. Questo valore è zero se iEsc è impostato su DOCUMENTEVENT_CREATEDCPRE. Per le restrizioni sulla stampa da un'applicazione a 32 bit in una versione a 64 bit di Windows, vedere Osservazioni.

iEsc

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

Costante Evento
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 DocumentEvent 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 o 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 DocumentEvent 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 DocumentEvent 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 o 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, in byte, del buffer a cui punta pvIn.

pvIn [in]

Puntatore a un buffer. Il contenuto del buffer dipende dal valore di iEsc, come illustrato nella tabella seguente.

Costante Contenuto pvin
DOCUMENTEVENT_ABORTDOC
Non usato.
DOCUMENTEVENT_CREATEDCPOST
pvIn contiene l'indirizzo di un puntatore alla struttura DEVMODE 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 documentata in Windows Driver Development Kit.
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 documentata in Windows Driver Development Kit.
DOCUMENTEVENT_QUERYFILTER
Uguale a per DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_RESETDCPOST
pvIn contiene l'indirizzo di un puntatore alla struttura DEVMODE 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 DEVMODE fornita dal chiamante di ResetDC.
DOCUMENTEVENT_STARTDOCPOST
pvIn punta a un valore LONG che specifica l'identificatore del processo di stampa restituito da StartDoc.
DOCUMENTEVENT_STARTDOCPRE o DOCUMENTEVENT_STARTDOC
pvIn contiene l'indirizzo di un puntatore a una struttura DOCINFO fornita dal chiamante di StartDoc.
DOCUMENTEVENT_STARTPAGE
Non usato.
*cbOut*
Valore Significato
IDOCUMENTEVENT_QUERYFILTER Dimensioni, in byte, del puntatore del buffer a da pvOut.
DOCUMENTEVENT_ESCAPE Valore utilizzato come parametro cbOutput per ExtEscape.
Per tutti gli altri valori iEsc non viene usato.

pvOut [out]

Puntatore a un buffer. Il contenuto del buffer dipende dal valore fornito per iEsc, come illustrato nella tabella seguente.

Costante Contenuto pvOut
DOCUMENTEVENT_CREATEDCPRE
Puntatore a una struttura DEVMODE fornita dal driver, che GDI usa anziché quella fornita dal chiamante CreateDC . Se NULL, GDI usa la struttura fornita dal chiamante.
DOCUMENTEVENT_ESCAPE
Puntatore a un buffer utilizzato come parametro lpszOutData per ExtEscape.
DOCUMENTEVENT_QUERYFILTER
Puntatore al buffer contenente una struttura DOCEVENT_FILTER documentata nel kit di sviluppo driver di Windows.
DOCUMENTEVENT_RESETDCPRE
Puntatore a una struttura DEVMODE fornita dal driver, che GDI usa anziché quella fornita dal chiamante ResetDC . Se NULL, GDI usa la struttura fornita dal chiamante.

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 di seguito). Se la funzione fornisce un valore restituito, deve essere una delle seguenti.

Valore restituito Significato
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.

L'elenco seguente indica i codici di escape che richiedono un valore restituito e che non e spiega il significato del DOCUMENTEVENT_SUCCESS, DOCUMENTEVENT_FAILURE e DOCUMENTEVENT_UNSUPPORTED codici restituiti.

Valore restituito Significato
DOCUMENTEVENT_ABORTDOC Il valore restituito non viene usato e non deve essere letto.
DOCUMENTEVENT_CREATEDCPOST Il valore restituito non viene usato e non deve essere letto.
DOCUMENTEVENT_CREATEDCPRE DOCUMENTEVENT_FAILURE : GDI non crea il contesto del dispositivo o il contesto informativo e fornisce un valore restituito pari a 0 per CreateDC o CreateIC.
DOCUMENTEVENT_DELETEDC Il valore restituito non viene usato e non deve essere letto.
DOCUMENTEVENT_ENDDOCPOST Il valore restituito non viene usato e non deve essere letto.
DOCUMENTEVENT_ENDDOCPRE o DOCUMENTEVENT_ENDDOC Il valore restituito non viene usato e non deve essere letto.
DOCUMENTEVENT_ENDPAGE Il valore restituito non viene usato e non deve essere letto.
DOCUMENTEVENT_ESCAPE Il valore restituito non viene usato e non deve essere letto.
DOCUMENTEVENT_QUERYFILTER Vedere la sezione Osservazioni.
DOCUMENTEVENT_RESETDCPOST Il valore restituito non viene usato e non deve essere letto.
DOCUMENTEVENT_RESETDCPRE DOCUMENTEVENT_FAILURE: GDI non reimposta il contesto del dispositivo e fornisce un valore restituito pari a 0 per ResetDC.
DOCUMENTEVENT_STARTDOCPOST DOCUMENTEVENT_FAILURE : GDI chiama AbortDoc per arrestare il documento e quindi fornisce un valore restituito di SP_ERROR per StartDoc.
DOCUMENTEVENT_STARTDOCPRE o DOCUMENTEVENT_STARTDOC DOCUMENTEVENT_FAILURE : GDI non avvia il documento e fornisce un valore restituito di SP_ERROR per StartDoc.
DOCUMENTEVENT_STARTPAGE DOCUMENTEVENT_FAILURE : GDI non avvia la pagina e fornisce un valore restituito di SP_ERROR per StartPage.

Commenti

Per un valore iEsc di DOCUMENTEVENT_QUERYFILTER, il spooler può interpretare un valore DOCUMENTEVENT_SUCCESS restituito da DocumentEvent in due modi, a seconda che il driver abbia modificato determinati membri della struttura DOCEVENT_FILTER (documentata nel kit di sviluppo driver Windows ). 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 DocumentEvent restituisce, lo spooler determina se i valori di questi membri sono stati modificati e utilizza tali informazioni per interpretare il valore restituito DocumentEvent . La tabella seguente riepiloga questa situazione.

Valore restituito Stato di cElementsReturned e 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 a DocumentEvent 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 (che è documentato nel kit di sviluppo driver Windows ).
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 a DocumentEvent 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 a DocumentEvent per tutti gli eventi.

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 documentazione relativa alla struttura DOCEVENT_CREATEDCPRE nel kit di sviluppo driver Windows.
  • Se il processo viene eseguito ilpooling, pvIn-pszDevice> punta al nome della porta della stampante.

Nota

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 DocumentEvent deve chiamare è ExtEscape e deve essere usata solo le escape private. Le chiamate DocumentEvent ad altre funzioni GDI possono produrre un comportamento non definito.

Requisiti

Requisito Valore
Client minimo supportato
Windows Vista [solo app desktop]
Server minimo supportato
Windows Server 2008 [solo app desktop]
Intestazione
Winspool.h (includere Windows.h)
Nomi Unicode e ANSI
DocumentEventW (Unicode) e DocumentEventA (ANSI)

Vedi anche

Stampa

Funzioni dell'API spooler di stampa

Windows Driver Development Kit