Fonction DrvConvertDevMode (winddiui.h)

Article
08/08/2023

La fonction DrvConvertDevMode d’une DLL d’interface d’imprimante convertit la structure DEVMODEW d’une imprimante d’une version à une autre.

Syntaxe

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

Paramètres

[in] pPrinterName

Pointeur fourni par l’appelant vers une chaîne de nom d’imprimante. Pour plus d’informations sur ce paramètre, consultez la section Remarques suivante.

[in] pdmIn

Pointeur fourni par l’appelant vers une structure DEVMODEW d’entrée. Si fMode est CDM_DRIVER_DEFAULT, ce pointeur a la valeur NULL.

[out] pdmOut

Pointeur fourni par l’appelant vers une mémoire tampon pour recevoir une structure DEVMODEW de sortie. Si fMode est CDM_CONVERT la mémoire tampon contient, en entrée, une structure DEVMODEW valide indiquant la version du pilote cible.

[in, out] pcbNeeded

Pointeur fourni par l’appelant vers la taille, en octets, de la mémoire tampon pointée par pdmOut. À la sortie, la DLL d’interface d’imprimante doit remplacer la valeur de taille reçue par la taille réelle de la structure DEVMODEW convertie. Si la mémoire tampon reçue est trop petite, la DLL d’interface d’imprimante doit remplacer la valeur de taille reçue par la taille de mémoire tampon requise.

[in] fMode

Indicateur de bits fourni par l’appelant indiquant le type d’opération à effectuer. Il peut s’agir de l’un des indicateurs suivants :

CDM_CONVERT

La fonction doit convertir le contenu de la structure DEVMODEW d’entrée (pointée par pdmIn) en une nouvelle structure DEVMODEW et placer le résultat dans la structure DEVMODEW pointée vers pdmOut. Le contenu initial de la structure DEVMODEW de sortie reçue (pointée par pdmOut) doit être utilisé pour déterminer la version de sortie.

CDM_CONVERT351

La fonction doit convertir le contenu de la structure DEVMODEW d’entrée (pointée par pdmIn), créer une structure DEVMODEW de sortie compatible avec Windows NT 3.51 et placer le résultat dans la structure DEVMODEW pointée par pdmOut.

Si le pilote ne prend pas en charge une structure DEVMODEW pour Windows NT 3.51, la fonction doit convertir l’entrée DEVMODEW en version actuelle.

CDM_DRIVER_DEFAULT

La fonction doit copier la version actuelle de sa structure DEVMODEW par défaut dans la mémoire tampon pointée par pdmOut.

Valeur retournée

Si l’opération réussit, la fonction doit retourner TRUE ; sinon, il doit appeler SetLastError pour définir un code d’erreur et retourner FALSE.

Remarques

Dans un environnement client/serveur, un client peut exécuter une version du système d’exploitation ou du pilote d’imprimante pendant que le serveur (spouleur) exécute une autre, ce qui signifie que la définition de structure DEVMODEW d’une imprimante peut être incohérente entre le client et le serveur. La fonction DrvConvertDevMode doit être capable d’effectuer des conversions d’une version de la structure DEVMODEW de l’imprimante à une autre.

Lors de la conversion d’une version DEVMODEW à une autre, les membres DEVMODEW publics et privés doivent être inclus.

Le nom de l’imprimante pointé par pPrinterName peut être utilisé comme argument d’entrée pour la fonction OpenPrinter (décrite dans la documentation Microsoft Windows SDK), qui peut être appelée pour obtenir des valeurs par défaut stockées lorsque l’indicateur CDM_DRIVER_DEFAULT est reçu. Notez que la chaîne de nom d’imprimante ne doit pas être modifiée de quelque manière que ce soit avant un appel à OpenPrinter. En outre, un appel à OpenPrinter doit se trouver dans le même thread que celui utilisé pour appeler DrvConvertDevMode.

La fonction doit vérifier que pdmIn et pdmOut (le cas échéant) pointent vers des structures DEVMODEW valides. Si ce n’est pas le cas, la fonction doit appeler SetLastError(ERROR_INVALID_PARAMETER) et retourner FALSE. Si la taille DEVMODEW de sortie spécifiée par pcbNeeded est trop petite, le pilote doit remplacer la valeur de taille fournie par pcbNeeded avec la taille de mémoire tampon requise, appeler SetLastError(ERROR_INSUFFICIENT_BUFFER) et retourner FALSE.

La fonction DrvConvertDevMode s’exécute dans le contexte du spouleur et ne doit donc pas afficher d’interface utilisateur.

Lorsque DrvConvertDevMode est appelé avec un pointeur de structure DEVMODEW NULL dans le paramètre pdmOut pour obtenir la taille de mémoire tampon, le pilote doit définir la dernière erreur sur ERROR_INSUFFICIENT_BUFFER. Si la dernière erreur n’est pas définie sur cette valeur, le spouleur suppose une erreur générale.

Configuration requise

Condition requise	Valeur
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	winddiui.h (inclure Winddiui.h)

Partager via