Condividi tramite

Funzione DocumentEvent

  • Articolo

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)

Vedi anche