Funzione DrvEnablePDEV (winddi.h)

Articolo
08/27/2023

La funzione DrvEnablePDEV restituisce una descrizione delle caratteristiche del dispositivo fisico in GDI.

Sintassi

DHPDEV DrvEnablePDEV(
  [in]           DEVMODEW *pdm,
  [in]           LPWSTR   pwszLogAddress,
                 ULONG    cPat,
  [in, optional] HSURF    *phsurfPatterns,
                 ULONG    cjCaps,
  [out]          ULONG    *pdevcaps,
                 ULONG    cjDevInfo,
  [out]          DEVINFO  *pdi,
                 HDEV     hdev,
  [in]           LPWSTR   pwszDeviceName,
                 HANDLE   hDriver
);

Parametri

[in] pdm

Puntatore a una struttura DEVMODEW contenente i dati del driver.

Per un driver che supporta Windows NT 4.0, DrvEnablePDEV deve restituire la modalità predefinita dell'hardware quando GDI lo chiama con i membri DEVMODEW seguenti impostati su zero: dmBitsPerPel,dmPelsWidth, dmPelsHeight e dmDisplayFrequency.

[in] pwszLogAddress

Per i driver della stampante, punta alla stringa di indirizzo logico che corrisponde al nome dell'utente per la posizione in cui il driver sta scrivendo. Gli esempi includono "LPT1" o "My Printer".

I driver di visualizzazione devono ignorare questo parametro.

cPat

Per i driver della stampante, specifica il numero di handle di superficie nel buffer a cui punta da phsurfPatterns. Il driver non può accedere alla memoria oltre la fine del buffer.

I driver di visualizzazione devono ignorare questo parametro.

[in, optional] phsurfPatterns

I driver di visualizzazione devono ignorare questo parametro.

Per i driver della stampante, punta a un buffer che il driver riempirà con handle di superficie che rappresentano i modelli di riempimento standard. I modelli seguenti devono essere definiti in ordine:

Modello	Descrizione
HS_HORIZONTAL	Tratteggio orizzontale.
HS_VERTICAL	Tratteggio verticale.
HS_FDIAGONAL	Tratteggio verso l'alto di 45 gradi (a sinistra a destra).
HS_BDIAGONAL	Tratteggio verso il basso di 45 gradi (a sinistra a destra).
HS_CROSS	Tratteggio orizzontale e verticale.
HS_DIAGCROSS	Crosshatch di 45 gradi.

Nota Il numero di modelli di tratteggio predefiniti che richiedono il supporto del driver è stato ridotto in una versione precedente di Driver Development Kit (DDK). Di conseguenza, HS_DDI_MAX, in genere usato dai driver per dichiarare le dimensioni della matrice di pattern, è stato ridotto.

GDI chiama DrvRealizeBrush con una di queste superfici per realizzare un pennello con un modello standard.

Ognuna di queste superfici deve essere una bitmap GDI GDI (1 bit per pixel) per i dispositivi raster. Il driver di dispositivo deve scegliere modelli che saranno più simili a modelli standard quando scritti nell'area del dispositivo.

GDI non è mai necessario usare questi pennelli nelle routine di supporto per un dispositivo vettore. Pertanto, le superfici possono essere superfici supportate dal dispositivo che DrvRealizeBrush riconosce come modelli standard.

cjCaps

Specifica le dimensioni del buffer a cui punta da pdevcaps. Il driver non deve accedere alla memoria oltre la fine del buffer.

[out] pdevcaps

Puntatore a una struttura GDIINFO che verrà usata per descrivere le funzionalità del dispositivo. GDI zero inizializza questa struttura chiamando DrvEnablePDEV.

cjDevInfo

Specifica il numero di byte nella struttura DEVINFO a cui fa riferimento il pdi. Il driver non deve modificare più di questo numero di byte in DEVINFO.

[out] pdi

Puntatore alla struttura DEVINFO , che descrive il driver e il dispositivo fisico. Il driver deve modificare solo i membri che comprende. GDI riempie questa struttura con zero prima di una chiamata a DrvEnablePDEV.

hdev

Handle fornito da GDI al dispositivo. Questo handle deve essere usato come input per alcuni callback GDI, ad esempio EngGetDriverName.

[in] pwszDeviceName

Puntatore a una stringa con terminazione null che corrisponde al nome leggibile dell'utente del dispositivo.

hDriver

Gestire in un dispositivo di output. Per un driver di visualizzazione, si tratta dell'handle del dispositivo visualizzato. Per un driver della stampante, questo parametro deve essere usato come handle per la stampante nelle chiamate al spooler.

Valore restituito

Il valore restituito è un handle per PDEV che identifica il dispositivo abilitato se la funzione ha esito positivo. Ovvero , DrvEnablePDEV restituisce un handle alle informazioni sull'istanza del dispositivo privata e definita dal driver al termine dell'operazione. In caso contrario, restituisce NULL.

Commenti

Un driver di dispositivo grafico può supportare diversi dispositivi fisici collegati a diversi indirizzi logici. I driver devono supportare anche l'uso simultaneo di diverse superfici di disegno.

I fini di DrvEnablePDEV sono i seguenti:

Per informare GDI sulle caratteristiche fisiche del dispositivo.
Per creare una struttura PDEV privata che descrive l'istanza corrente del dispositivo (in base alla struttura DEVMODE ricevuta e al nome del dispositivo).

Quando GDI chiama successivamente altre funzioni DDI grafiche, fornisce l'handle restituito da DrvEnablePDEV come input (in genere all'interno di una struttura SURFOBJ) in modo che il driver possa identificare l'istanza del dispositivo.

Un singolo dispositivo logico può gestire diversi PDEV che possono essere differenziati in base al seguente:

Tipo di hardware: un singolo driver di dispositivo può supportare "LaserWhiz", "LaserWhiz II" e "LaserWhiz Super".
Indirizzo logico: un singolo driver di dispositivo può supportare stampanti associate a "LPT1", "COM2", "\SERVER1\PSLAZER" e così via. Un driver di visualizzazione che può supportare più display VGA contemporaneamente potrebbe differenziarli in base ai numeri di porta; ad esempio, 0x3CE o 0x2CE.
Superfici - Un driver di stampante può elaborare due processi di stampa contemporaneamente. Le due superfici rappresentano due pagine che verranno stampate. Analogamente, un driver di dispositivo visualizzato potrebbe supportare due desktop nello stesso dispositivo.

Quando si riceve una chiamata a questa funzione, il driver deve allocare la memoria per supportare il PDEV. Tuttavia, la superficie effettiva non deve essere supportata finché GDI chiama DrvEnableSurface.

Se una superficie del dispositivo richiede l'allocazione di una bitmap, queste allocazioni non devono essere effettuate finché non sono necessarie. Anche se le applicazioni spesso richiedono informazioni sul dispositivo prima di scrivere effettivamente nel dispositivo, in attesa di allocare risorse, ad esempio bitmap di grandi dimensioni, possono risparmiare memoria.

GDI zero inizializza il buffer a cui fa riferimento phsurfPatterns prima di chiamare questa funzione.

DrvEnablePDEV è necessario per i driver grafici.