Struttura DEVMODEW

La struttura DEVMODEW è la versione Unicode della struttura DEVMODE, descritta nella documentazione di Microsoft Windows SDK. (Il suffisso 'W' in DEVMODEW è "wide" o caratteri Unicode). Anche se le applicazioni possono usare una struttura, i driver devono usare la struttura DEVMODEW anziché la struttura DEVMODE.

Membri pubblici e privati

Immediatamente dopo i membri definiti di una struttura DEVMODEW (spesso denominati membri DEVMODEW pubblici), è possibile creare un set di membri definiti dal driver (membri DEVMODEW privati). Nella figura seguente viene illustrata la sezione pubblica (la struttura DEVMODEW effettiva) e la sezione privata.

In genere, i membri privati vengono usati solo dai driver della stampante. Il driver fornisce le dimensioni, in byte, di questa area privata nel membro dmDriverExtra . I membri privati definiti dal driver sono destinati all'uso esclusivo del driver.

Per i driver della stampante, la struttura DEVMODEW viene usata per specificare le scelte utente per un documento di stampa. Viene usato anche per specificare i valori predefiniti di queste scelte per le stampanti, ad esempio il numero di copie da stampare, dimensioni carta e altri attributi. Per i dispositivi visualizzati, la struttura DEVMODEW specifica gli attributi di visualizzazione, ad esempio il numero di bit per pixel, dimensioni pixel e frequenza di visualizzazione.

Inizializzazione di una struttura DEVMODEW

A seconda che venga usato da un driver di visualizzazione o da un driver di stampante, viene inizializzata una struttura DEVMODEW in due modi diversi.

• Inizializzazione del driver DEVMODEW

  Il punto di ingresso DrvGetModes di un driver visualizzato inizializza tutti i membri della struttura DEVMODEW su zero. DrvGetModes copia quindi il nome della DLL del driver visualizzato nel membro dmDeviceName , compila i membri dmSpecVersion e dmDriverVersion con la versione della struttura DEVMODEW e copia le informazioni sull'attributo ai membri appropriati.

• Inizializzazione del driver della stampante DEVMODEW

  Quando un'applicazione effettua una chiamata a DocumentProperties (una funzione DLL dell'interfaccia della stampante descritta nella documentazione di Microsoft Windows SDK) o DrvDocumentPropertySheets (grafica DDI del sistema operativo basato su NT), viene creata una struttura DEVMODEW con valori predefiniti. Un'applicazione è quindi gratuita per modificare uno dei membri DEVMODEW pubblici. Dopo le modifiche, l'applicazione deve quindi effettuare una seconda chiamata alla stessa funzione chiamata prima, per unire i membri modificati con quelli della struttura DEVMODEW interna del driver. La seconda chiamata è necessaria perché alcune modifiche potrebbero non funzionare correttamente; il driver della stampante deve essere chiamato per correggere la struttura DEVMODEW. Quando il documento sta per essere stampato, l'applicazione passa la struttura DEVMODEW unita a CreateDC (descritta nella documentazione di Microsoft Windows SDK), che lo passa a DrvEnablePDEV DDI. In quel momento, la DLL di rendering del driver convalida la struttura DEVMODEW e esegue le riparazioni, se necessario, prima di eseguire il processo di stampa.

Uso di una struttura DEVMODEW

Diverse API e DDI grafiche usano le informazioni nella struttura DEVMODEW per scopi quali stampa, query sulle funzionalità del dispositivo, visualizzazione dell'interfaccia utente e altri. Ad esempio, DrvConvertDevMode è una grafica Spooler di stampa che converte la struttura DEVMODEW da una versione del sistema operativo a un'altra. Questo potrebbe essere necessario se un driver della stampante ottiene una struttura DEVMODEW da un altro computer in esecuzione in una versione del sistema operativo diversa.

Modifica di una struttura DEVMODEW

Le applicazioni e i driver sono liberi di chiedere una struttura DEVMODEW e modificare direttamente la sua parte pubblica. Tuttavia, sono consentiti solo i driver per modificare i membri della struttura DEVMODEW privati.

Per modificare i membri della struttura DEVMODEW privati, un driver deve prima determinare l'offset dell'inizio dei dati privati. Dato un puntatore all'inizio di questa struttura e al membro dmSize , che contiene le dimensioni della parte pubblica della struttura, è possibile trovare l'inizio della parte privata. Nell'esempio seguente viene illustrato come inizializzare un puntatore all'inizio della sezione privata. In questo esempio pdm punta all'inizio della struttura DEVMODEW.

PVOID pvDriverData = (PVOID)  (((BYTE *) pdm) + (pdm -> dmSize));

Differenze del driver stampante/display driver DEVMODEW

I membri della struttura DEVMODEW rientrano in tre categorie:

• Membri usati solo dai driver della stampante

• Membri usati solo dai driver di visualizzazione

• Membri usati sia dalla stampante che dai driver di visualizzazione

La tabella seguente elenca diversi membri DEVMODEW pubblici usati solo dai driver della stampante:

Usato solo dai driver della stampante	Scopo
dmScale	Specifica la percentuale in base alla quale l'immagine deve essere ridimensionata per la stampa.
dmCopies	Specifica il numero di copie da stampare.
dmColor	Specifica se una stampante a colori deve stampare colore o monocromia.
dmOrientation	Specifica l'orientamento della carta, verticale o orizzontale.

La tabella successiva elenca diversi membri DEVMODEW pubblici usati solo dai driver di visualizzazione:

Usato solo dai driver di visualizzazione	Scopo
dmBitsPerPel	Specifica la risoluzione dei colori, in bit per pixel, del dispositivo visualizzato.
dmPelsWidth	Specifica la larghezza, in pixel, dell'area del dispositivo visibile.
dmPelsHeight	Specifica l'altezza, in pixel, dell'area del dispositivo visibile.
dmDisplayFlags	Specifica la modalità di visualizzazione : colore rispetto al monocromatico, interlacciato o non interlacciato.
dmDisplayFrequency	Specifica, in hertz, la frequenza di aggiornamento della visualizzazione.

La terza tabella elenca diversi membri DEVMODEW pubblici usati sia dalla stampante che dai driver di visualizzazione:

Usato dalla stampante e dai driver di visualizzazione	Scopo
dmDeviceName	Per visualizzare, specifica la DLL del driver di visualizzazione. Per le stampanti, specifica il "nome descrittivo" della stampante.
dmFields	Specifica i flag di bit che identificano i membri DEVMODEW che seguono sono in uso. Ad esempio, il flag di DM_BITSPERPEL viene impostato quando il membro dmBitsPerPel contiene dati validi.
dmSize	Specifica le dimensioni, in byte, della parte pubblica della struttura DEVMODEW.
dmDriverExtra	Specifica il numero di byte di dati del driver privato che seguono i membri della struttura pubblica. Per i driver di visualizzazione, questo è in genere zero.