Fonction DrvEnablePDEV (winddi.h)

Article
08/27/2023

La fonction DrvEnablePDEV retourne une description des caractéristiques de l’appareil physique à GDI.

Syntaxe

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
);

Paramètres

[in] pdm

Pointeur vers une structure DEVMODEW qui contient des données de pilote.

Pour un pilote qui prend en charge Windows NT 4.0, DrvEnablePDEV doit retourner le mode par défaut du matériel lorsque GDI l’appelle avec les membres DEVMODEW suivants définis sur zéro : dmBitsPerPel, dmPelsWidth, dmPelsHeight et dmDisplayFrequency.

[in] pwszLogAddress

Pour les pilotes d’imprimante, pointe vers la chaîne d’adresse logique qui est le nom de l’utilisateur pour l’emplacement dans lequel le pilote écrit. Par exemple, « LPT1 » ou « Mon imprimante ».

Les pilotes d’affichage doivent ignorer ce paramètre.

cPat

Pour les pilotes d’imprimante, spécifie le nombre de poignées de surface dans la mémoire tampon pointée par phsurfPatterns. Le pilote ne peut pas accéder à la mémoire au-delà de la fin de la mémoire tampon.

Les pilotes d’affichage doivent ignorer ce paramètre.

[in, optional] phsurfPatterns

Les pilotes d’affichage doivent ignorer ce paramètre.

Pour les pilotes d’imprimante, pointe vers une mémoire tampon que le pilote remplira avec des poignées de surface représentant les modèles de remplissage standard. Les modèles suivants doivent être définis dans l’ordre :

Modèle	Description
HS_HORIZONTAL	Trappe horizontale.
HS_VERTICAL	Trappe verticale.
HS_FDIAGONAL	45 degrés vers le haut (de gauche à droite).
HS_BDIAGONAL	45 degrés vers le bas (de gauche à droite).
HS_CROSS	Trappe croisée horizontale et verticale.
HS_DIAGCROSS	45 degrés de hachage croisé.

Note Le nombre de modèles de hachures par défaut qui nécessitent la prise en charge du pilote a été réduit dans une version précédente du Kit de développement de pilotes (DDK). Par conséquent, HS_DDI_MAX, généralement utilisé par les pilotes pour déclarer la taille du tableau de modèles, a été réduit.

GDI appelle DrvRealizeBrush avec l’une de ces surfaces pour réaliser un pinceau avec un modèle standard.

Chacune de ces surfaces doit être une bitmap GDI monochrome (1 bit par pixel) pour les appareils raster. Le pilote de périphérique doit choisir des modèles qui ressemblent le plus aux modèles standard lorsqu’ils sont écrits sur l’surface de l’appareil.

GDI n’est jamais nécessaire pour utiliser ces pinceaux dans les routines de prise en charge d’un appareil vectoriel. Par conséquent, les surfaces peuvent être des surfaces prises en charge par l’appareil que DrvRealizeBrush reconnaît comme des modèles standard.

cjCaps

Spécifie la taille de la mémoire tampon pointée vers pdevcaps. Le pilote ne doit pas accéder à la mémoire au-delà de la fin de la mémoire tampon.

[out] pdevcaps

Pointeur vers une structure GDIINFO qui sera utilisée pour décrire les fonctionnalités de l’appareil. GDI initialise zéro cette structure appelant DrvEnablePDEV.

cjDevInfo

Spécifie le nombre d’octets dans la structure DEVINFO pointée vers pdi. Le pilote ne doit pas modifier plus que ce nombre d’octets dans le DEVINFO.

[out] pdi

Pointeur vers la structure DEVINFO , qui décrit le pilote et le périphérique physique. Le pilote doit uniquement modifier les membres qu’il comprend. GDI remplit cette structure avec des zéros avant un appel à DrvEnablePDEV.

hdev

Handle fourni par GDI à l’appareil. Ce handle doit être utilisé comme entrée dans certains rappels GDI, tels que EngGetDriverName.

[in] pwszDeviceName

Pointeur vers une chaîne terminée par null qui est le nom lisible par l’utilisateur de l’appareil.

hDriver

Gérer sur un appareil de sortie. Pour un pilote d’affichage, il s’agit du handle de périphérique d’affichage. Pour un pilote d’imprimante, ce paramètre doit être utilisé comme handle de l’imprimante dans les appels au spouleur.

Valeur retournée

La valeur de retour est un handle du PDEV qui identifie l’appareil activé si la fonction réussit. Autrement dit, DrvEnablePDEV retourne un handle à l’appareil privé défini par le pilote instance informations en cas de réussite. Dans le cas contraire, elle retourne LA VALEUR NULL.

Remarques

Un pilote de périphérique graphique peut prendre en charge plusieurs périphériques physiques attachés à différentes adresses logiques. Les pilotes doivent également prendre en charge l’utilisation simultanée de différentes surfaces de dessin.

Les objectifs de DrvEnablePDEV sont les suivants :

Pour informer GDI des caractéristiques physiques de l’appareil.
Pour créer une structure PDEV privée décrivant le instance d’appareil actuel (en fonction de la structure DEVMODE et du nom de l’appareil reçus).

Lorsque GDI appelle par la suite d’autres fonctions DDI graphiques, il fournit le handle retourné par DrvEnablePDEV en tant qu’entrée (généralement dans une structure SURFOBJ) afin que le pilote puisse identifier l’appareil instance.

Un seul appareil logique peut gérer plusieurs PDEVs qui peuvent être différenciés par les éléments suivants :

Type de matériel : un seul pilote de périphérique peut prendre en charge « LaserWhiz », « LaserWhiz II » et « LaserWhiz Super ».
Adresse logique : un seul pilote de périphérique peut prendre en charge les imprimantes attachées à « LPT1 », « COM2 », « \SERVER1\PSLAZER », etc. Un pilote d’affichage qui peut prendre en charge plusieurs affichages VGA simultanément peut les différencier en fonction des numéros de port ; par exemple, 0x3CE ou 0x2CE.
Surfaces : un pilote d’imprimante peut traiter deux travaux d’impression simultanément. Les deux surfaces représentent deux pages qui seront imprimées. De même, un pilote de périphérique d’affichage peut prendre en charge deux bureaux sur le même appareil.

Lors de la réception d’un appel à cette fonction, le pilote doit allouer la mémoire pour prendre en charge le PDEV. Toutefois, la surface réelle n’a pas besoin d’être prise en charge tant que GDI n’appelle pas DrvEnableSurface.

Si une surface d’appareil nécessite l’allocation d’une bitmap, ces allocations ne doivent pas être effectuées tant que cela n’est pas nécessaire. Bien que les applications demandent souvent des informations sur l’appareil bien avant d’écrire sur l’appareil, en attendant d’allouer des ressources, telles que des bitmaps volumineuses, peut conserver la mémoire.

GDI initialise zéro la mémoire tampon pointée par phsurfPatterns avant d’appeler cette fonction.

DrvEnablePDEV est requis pour les pilotes graphiques.