Funzione DocumentProperties

La funzione DocumentProperties recupera o modifica le informazioni di inizializzazione della stampante o visualizza una scheda delle proprietà di configurazione della stampante per la stampante specificata.

Sintassi

LONG DocumentProperties(
  _In_  HWND     hWnd,
  _In_  HANDLE   hPrinter,
  _In_  LPTSTR   pDeviceName,
  _Out_ PDEVMODE pDevModeOutput,
  _In_  PDEVMODE pDevModeInput,
  _In_  DWORD    fMode
);

Parametri

hWnd [in]

Handle nella finestra padre della scheda delle proprietà di configurazione della stampante.

hPrinter [in]

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

pDeviceName [in]

Puntatore a una stringa con terminazione null che specifica il nome del dispositivo per il quale viene visualizzato il foglio delle proprietà di configurazione della stampante.

pDevModeOutput [out]

Puntatore a una struttura DEVMODE che riceve i dati di configurazione della stampante specificati dall'utente.

pDevModeInput [in]

Puntatore a una struttura DEVMODE usata dal sistema operativo per inizializzare i controlli del foglio delle proprietà.

Questo parametro viene usato solo se il flag di DM_IN_BUFFER è impostato nel parametro fMode . Se DM_IN_BUFFER non è impostato, il sistema operativo usa devMODE predefinito della stampante.

fMode [in]

Le operazioni eseguite dalla funzione. Se questo parametro è zero, la funzione DocumentProperties restituisce il numero di byte richiesti dalla struttura di dati DEVMODE del driver della stampante. In caso contrario, usare una o più costanti seguenti per costruire un valore per questo parametro; Si noti tuttavia che per modificare le impostazioni di stampa, un'applicazione deve specificare almeno un valore di input e un valore di output.

Valore	Significato
DM_IN_BUFFER	Valore di input. Prima di richiedere, copiare o aggiornare, la funzione unisce le impostazioni di stampa correnti del driver della stampante con le impostazioni nella struttura DEVMODE specificata dal parametro pDevModeInput . La funzione aggiorna la struttura solo per i membri specificati dal membro dmFields della struttura DEVMODE. Questo valore viene definito anche come DM_MODIFY. Nei casi di conflitto durante l'unione, le impostazioni nella struttura DEVMODE specificate da pDevModeInput sostituiscono le impostazioni di stampa correnti del driver della stampante.
DM_IN_PROMPT	Valore di input. La funzione presenta la scheda delle proprietà Print Setup del driver della stampante e quindi modifica le impostazioni nella struttura di dati DEVMODE della stampante in tali valori specificati dall'utente. Questo valore viene definito anche come DM_PROMPT.
DM_OUT_BUFFER	Valore di output. La funzione scrive le impostazioni di stampa correnti del driver della stampante, inclusi i dati privati, nella struttura di dati DEVMODE specificata dal parametro pDevModeOutput . Il chiamante deve allocare un buffer sufficientemente grande per contenere le informazioni. Se il bit DM_OUT_BUFFER set è chiaro, il parametro pDevModeOutput può essere NULL. Questo valore viene definito anche come DM_COPY.

Valore restituito

Se il parametro fMode è zero, il valore restituito è la dimensione del buffer necessario per contenere i dati di inizializzazione del driver della stampante. Si noti che questo buffer può essere maggiore di una struttura DEVMODE se il driver della stampante aggiunge dati privati alla struttura.

Se la funzione visualizza il foglio delle proprietà, il valore restituito è IDOK o IDCANCEL, a seconda del pulsante selezionato dall'utente.

Se la funzione non visualizza il foglio delle proprietà e ha esito positivo, il valore restituito è IDOK.

Se la funzione ha esito negativo, il valore restituito è minore di zero.

Commenti

Nota

Si tratta di una funzione di blocco o sincrona e potrebbe non restituire immediatamente. La velocità con cui questa funzione restituisce dipende da fattori di runtime come lo stato della rete, la configurazione del server di stampa e i fattori di implementazione del driver della stampante difficili da prevedere durante la scrittura di un'applicazione. La chiamata a questa funzione da un thread che gestisce l'interazione con l'interfaccia utente potrebbe rendere l'applicazione non rispondente.

La stringa a cui punta il parametro pDeviceName può essere ottenuta chiamando la funzione GetPrinter .

La struttura DEVMODE effettivamente usata da un driver di stampante contiene la parte indipendente dal dispositivo (come definito in precedenza) seguita da una parte specifica del driver che varia in dimensioni e contenuto con ogni driver e versione del driver. A causa di questa dipendenza del driver, è molto importante per le applicazioni eseguire query sul driver per le dimensioni corrette della struttura DEVMODE prima di allocare un buffer.

Per apportare modifiche alle impostazioni di stampa locali in un'applicazione, un'applicazione deve seguire questa procedura:

1. Ottenere il numero di byte necessari per la struttura DEVMODE completa chiamando DocumentProperties e specificando zero nel parametro fMode .
2. Allocare memoria per la struttura DEVMODE completa.
3. Ottenere le impostazioni correnti della stampante chiamando DocumentProperties. Passare un puntatore alla struttura DEVMODE allocata nel passaggio 2 come parametro pDevModeOutput e specificare il valore DM_OUT_BUFFER .
4. Modificare i membri appropriati della struttura DEVMODE restituita e indicare quali membri sono stati modificati impostando i bit corrispondenti nel membro dmFields di DEVMODE.
5. Chiamare DocumentProperties e passare nuovamente la struttura DEVMODE modificata come parametri pDevModeInput e pDevModeOutput e specificare sia i valori DM_IN_BUFFER che DM_OUT_BUFFER (combinati usando l'operatore OR). La struttura DEVMODE restituita dalla terza chiamata a DocumentProperties può essere usata come argomento in una chiamata alla funzione CreateDC.

Per creare un handle in un contesto di stampante-dispositivo usando le impostazioni correnti della stampante, è necessario chiamare due volte DocumentProperties , come descritto in precedenza. La prima chiamata ottiene le dimensioni dell'oggetto DEVMODE completo e la seconda chiamata inizializza DEVMODE con le impostazioni correnti della stampante. Passare DEVMODE inizializzato a CreateDC per ottenere l'handle nel contesto del dispositivo della stampante.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Intestazione	Winspool.h (include Windows.h)
Libreria	Winspool.lib
DLL	Winspool.drv
Nomi Unicode e ANSI	DocumentPropertiesW (Unicode) e DocumentPropertiesA (ANSI)

Vedi anche

Stampa

Funzioni dell'API spooler di stampa

AdvancedDocumentProperties

CreateDC

DEVMODE

GetPrinter

OpenPrinter