Funzione DocumentEvent

Articolo
01/04/2024

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 è 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, vedi 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 funzione AbortDoc.
DOCUMENTEVENT_CREATEDCPOST	GDI ha appena elaborato una chiamata alla 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 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 funzione EndDoc.
DOCUMENTEVENT_ENDDOCPRE o DOCUMENTEVENT_ENDDOC	GDI sta per elaborare una chiamata alla funzione EndDoc.
DOCUMENTEVENT_ENDPAGE	GDI sta per elaborare una chiamata alla relativa 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 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 supera l'evento DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_REedizione Standard TDCPOST	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 DocumentEvent con iEsc impostato su DOCUMENTEVENT_REedizione Standard TDCPRE.
DOCUMENTEVENT_REedizione Standard TDCPRE	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 relativa funzione StartPage .

cbIn

Dimensioni, 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 utilizzato.
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 utilizzato.
DOCUMENTEVENT_ENDDOCPOST	Non utilizzato.
DOCUMENTEVENT_ENDDOCPRE o DOCUMENTEVENT_ENDDOC	Non utilizzato.
DOCUMENTEVENT_ENDPAGE	Non utilizzato.
DOCUMENTEVENT_ESCAPE	pvIn punta a una struttura DOCEVENT_ESCAPE documentata in Windows Driver Development Kit.
DOCUMENTEVENT_QUERYFILTER	Uguale a per DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_REedizione Standard TDCPOST	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_REedizione Standard TDCPRE.
DOCUMENTEVENT_REedizione Standard TDCPRE	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 utilizzato.

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, usata da GDI anziché da 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 in Windows Driver Development Kit.
DOCUMENTEVENT_REedizione Standard TDCPRE	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 lo fanno e spiega il significato del DOCUMENTEVENT_SUCCESS, DOCUMENTEVENT_FAILURE e DOCUMENTEVENT_UNSUPPORTED codici restituiti.

Valore restituito	Significato
DOCUMENTEVENT_ABORTDOC	Il valore restituito non viene utilizzato e non deve essere letto.
DOCUMENTEVENT_CREATEDCPOST	Il valore restituito non viene utilizzato e non deve essere letto.
DOCUMENTEVENT_CREATEDCPRE	DOCUMENTEVENT_FAILURE : GDI non crea il contesto di dispositivo o il contesto informativo e fornisce un valore restituito pari a 0 per CreateDC o CreateIC.
DOCUMENTEVENT_DELETEDC	Il valore restituito non viene utilizzato e non deve essere letto.
DOCUMENTEVENT_ENDDOCPOST	Il valore restituito non viene utilizzato e non deve essere letto.
DOCUMENTEVENT_ENDDOCPRE o DOCUMENTEVENT_ENDDOC	Il valore restituito non viene utilizzato e non deve essere letto.
DOCUMENTEVENT_ENDPAGE	Il valore restituito non viene utilizzato e non deve essere letto.
DOCUMENTEVENT_ESCAPE	Il valore restituito non viene utilizzato e non deve essere letto.
DOCUMENTEVENT_QUERYFILTER	Vedere la sezione Osservazioni.
DOCUMENTEVENT_REedizione Standard TDCPOST	Il valore restituito non viene utilizzato e non deve essere letto.
DOCUMENTEVENT_REedizione Standard TDCPRE	DOCUMENTEVENT_FAILURE: GDI non reimposta il contesto di 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.

Osservazioni:

Per un valore iEsc di DOCUMENTEVENT_QUERYFILTER, lo 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 in Windows Driver Development Kit ). Il parametro pvOut punta a questa struttura. Quando lo spooler alloca memoria per una struttura di questo tipo, inizializza due membri di questa struttura, cElementsReturned e cElementsNeeded, ai valori noti. Dopo la restituzione di DocumentEvent , lo spooler determina se i valori di questi membri sono stati modificati e usa 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 nessuno dei membri.	Lo spooler interpreta questo valore restituito come equivalente a DOCUMENTEVENT_UNSUPPORTED. Lo spooler non è in grado di recuperare il filtro eventi dal driver, quindi persiste nella chiamata a DocumentEvent per tutti gli eventi.
DOCUMENTEVENT_SUCCESS	Il driver ha scritto uno o entrambi i membri.	Lo 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 zero. Lo spooler filtra tutti gli eventi elencati nel membro aDocEventCall di DOCEVENT_FILTER (documentato in Windows Driver Development Kit ).
DOCUMENTEVENT_UNSUPPORTED	Non applicabile	Il driver non supporta DOCUMENTEVENT_QUERYFILTER. Lo spooler non è in grado di recuperare il filtro eventi dal driver, quindi persiste nella chiamata a DocumentEvent per tutti gli eventi.
DOCUMENTEVENT_FAILURE	Non applicabile	Il driver supporta DOCUMENTEVENT_QUERYFILTER, ma si è verificato un errore interno. Lo spooler non è in grado di recuperare il filtro eventi 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 Windows Driver Development Kit.
Se il processo viene eseguito lo spooling, pvIn-pszDevice> punta al nome della porta della stampante.

Nota

Quando si esegue un'applicazione a 32 bit in una versione a 64 bit di Windows, si applicano le restrizioni seguenti. L'unica funzione GDI che DocumentEvent deve chiamare è ExtEscape e devono essere usati solo escape privati. 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 (include Windows.h)
Nomi Unicode e ANSI	DocumentEventW (Unicode) e DocumentEventA (ANSI)