Funzione DrvConvertDevMode (winddiui.h)

La funzione DrvConvertDevMode di una DLL dell'interfaccia della stampante converte la struttura DEVMODEW di una stampante da una versione a un'altra.

Sintassi

BOOL DrvConvertDevMode(
  [in]      LPTSTR   pPrinterName,
  [in]      PDEVMODE pdmIn,
  [out]     PDEVMODE pdmOut,
  [in, out] PLONG    pcbNeeded,
  [in]      DWORD    fMode
);

Parametri

[in] pPrinterName

Puntatore fornito dal chiamante a una stringa di nome della stampante. Per altre informazioni su questo parametro, vedere la sezione Osservazioni seguenti.

[in] pdmIn

Puntatore fornito dal chiamante a una struttura DEVMODEW di input. Se fMode è CDM_DRIVER_DEFAULT, questo puntatore è NULL.

[out] pdmOut

Puntatore fornito dal chiamante a un buffer per ricevere una struttura DEVMODEW di output. Se fMode è CDM_CONVERT il buffer contiene, in input, una struttura DEVMODEW valida che indica la versione del driver di destinazione.

[in, out] pcbNeeded

Puntatore fornito dal chiamante alle dimensioni, in byte, del buffer a cui punta pdmOut. In output, la DLL dell'interfaccia della stampante deve sovrascrivere il valore delle dimensioni ricevute con le dimensioni effettive della struttura DEVMODEW convertita. Se il buffer ricevuto è troppo piccolo, la DLL dell'interfaccia della stampante deve sovrascrivere il valore di dimensione ricevuta con le dimensioni del buffer necessarie.

[in] fMode

Flag di bit fornito dal chiamante che indica il tipo di operazione da eseguire. Questo può essere uno dei flag seguenti:

CDM_CONVERT

La funzione deve convertire il contenuto della struttura DEVMODEW di input (puntata da pdmIn) in una nuova struttura DEVMODEW e posizionare il risultato nella struttura DEVMODEW puntata da pdmOut. Il contenuto iniziale della struttura DEVMODEW dell'output ricevuto (a cui fa riferimento pdmOut) deve essere usato per determinare la versione di output.

CDM_CONVERT351

La funzione deve convertire il contenuto della struttura DEVMODEW di input (puntata da pdmIn), creando una struttura DEVMODEW di output compatibile con Windows NT 3.51 e posizionare il risultato nella struttura DEVMODEW puntata da pdmOut.

Se il driver non supporta una struttura DEVMODEW per Windows NT 3.51, la funzione deve convertire l'input DEVMODEW nella versione corrente.

CDM_DRIVER_DEFAULT

La funzione deve copiare la versione corrente della struttura DEVMODEW predefinita nel buffer a cui punta pdmOut.

Valore restituito

Se l'operazione ha esito positivo, la funzione deve restituire TRUE; in caso contrario, deve chiamare SetLastError per impostare un codice di errore e restituire FALSE.

Commenti

In un ambiente client/server, un client potrebbe eseguire una versione del sistema operativo o del driver della stampante mentre il server (spooler) esegue un altro, il che significa che la definizione della struttura DEVMODEW di una stampante potrebbe essere incoerente tra il client e il server. La funzione DrvConvertDevMode deve essere in grado di eseguire conversioni da una versione della struttura DEVMODEW della stampante a un'altra.

Quando si converte da una versione DEVMODEW a un'altra, è necessario includere membri DEVMODEW pubblici e privati.

Il nome della stampante a cui fa riferimento pPrinterName può essere usato come argomento di input per la funzione OpenPrinter (descritta nella documentazione di Microsoft Windows SDK), che può essere chiamato per ottenere valori predefiniti archiviati quando viene ricevuto il flag CDM_DRIVER_DEFAULT. Si noti che la stringa del nome della stampante non deve essere modificata in alcun modo prima di una chiamata a OpenPrinter. Inoltre, una chiamata a OpenPrinter deve trovarsi nello stesso thread usato per chiamare DrvConvertDevMode.

La funzione deve verificare che sia pdmIn che pdmOut (se applicabile) puntino a strutture DEVMODEW valide. In caso contrario, la funzione deve chiamare SetLastError(ERROR_INVALID_PARAMETER) e restituire FALSE. Se le dimensioni DEVMODEW di output specificate da pcbNeeded sono troppo piccole, il driver deve sovrascrivere il valore di dimensione fornito da pcbNeed con le dimensioni del buffer necessarie, chiamare SetLastError(ERROR_INSUFFICIENT_BUFFER) e restituire FALSE.

La funzione DrvConvertDevMode viene eseguita nel contesto del spooler e non deve quindi visualizzare un'interfaccia utente.

Quando DrvConvertDevMode viene chiamato con un puntatore della struttura NULL DEVMODEW nel parametro pdmOut per ottenere le dimensioni del buffer, il driver deve impostare l'ultimo errore su ERROR_INSUFFICIENT_BUFFER. Se l'ultimo errore non è impostato su questo valore, lo spooler presuppone un errore generale.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Desktop
Intestazione	winddiui.h (include Winddiui.h)