Fonction DocumentProperties

La fonction DocumentProperties récupère ou modifie les informations d’initialisation de l’imprimante ou affiche une feuille de propriétés de configuration de l’imprimante pour l’imprimante spécifiée.

Syntaxe

LONG DocumentProperties(
  _In_  HWND     hWnd,
  _In_  HANDLE   hPrinter,
  _In_  LPTSTR   pDeviceName,
  _Out_ PDEVMODE pDevModeOutput,
  _In_  PDEVMODE pDevModeInput,
  _In_  DWORD    fMode
);

Paramètres

HWND [ dans]

Handle de la fenêtre parente de la feuille de propriétés de configuration de l’imprimante.

hPrinter [ dans]

Handle d’un objet Printer. Utilisez la fonction OpenPrinter ou AddPrinter pour récupérer un handle d’imprimante.

pDeviceName [ dans]

Pointeur vers une chaîne se terminant par un caractère null qui spécifie le nom de l’appareil pour lequel la feuille de propriétés de configuration de l’imprimante est affichée.

pDevModeOutput [ à]

Pointeur vers une structure DEVMODE qui reçoit les données de configuration d’imprimante spécifiées par l’utilisateur.

pDevModeInput [ dans]

Pointeur vers une structure DEVMODE que le système d’exploitation utilise pour initialiser les contrôles de la feuille de propriétés.

Ce paramètre est utilisé uniquement si l’indicateur DM _ dans la _ mémoire tampon est défini dans le paramètre fMode . Si DM _ dans la _ mémoire tampon n’est pas défini, le système d’exploitation utilise le DEVMODEpar défaut de l’imprimante.

fMode [ dans]

Opérations exécutées par la fonction. Si ce paramètre est égal à zéro, la fonction DocumentProperties retourne le nombre d’octets requis par la structure de données DEVMODE du pilote d’imprimante. Sinon, utilisez une ou plusieurs des constantes suivantes pour construire une valeur pour ce paramètre. Notez, toutefois, que pour modifier les paramètres d’impression, une application doit spécifier au moins une valeur d’entrée et une valeur de sortie.

Valeur Signification
DM _ dans la _ mémoire tampon
Valeur d’entrée. Avant de demander, de copier ou de mettre à jour, la fonction fusionne les paramètres d’impression actuels du pilote d’imprimante avec les paramètres de la structure DEVMODE spécifiée par le paramètre pDevModeInput . La fonction met à jour la structure uniquement pour les membres spécifiés par le membre dmFields de la structure DEVMODE . Cette valeur est également définie en tant que _ modification DM. En cas de conflit pendant la fusion, les paramètres de la structure DEVMODE spécifiée par pDevModeInput remplacent les paramètres d’impression actuels du pilote d’imprimante.
DM _ dans l' _ invite
Valeur d’entrée. La fonction affiche la feuille de propriétés configuration de l’impression du pilote d’imprimante, puis modifie les paramètres de la structure de données DEVMODE de l’imprimante en fonction des valeurs spécifiées par l’utilisateur. Cette valeur est également définie en tant qu' _ invite DM.
_mémoire tampon de sortie DM _
Valeur de sortie. La fonction écrit les paramètres d’impression actuels du pilote d’imprimante, y compris les données privées, dans la structure de données DEVMODE spécifiée par le paramètre pDevModeOutput . L’appelant doit allouer une mémoire tampon suffisamment grande pour contenir les informations. Si les jeux de _ _ mémoires tampons de bits DM sont clairs, le paramètre PDevModeOutput peut avoir la valeur null. Cette valeur est également définie en tant que _ copie DM.

Valeur renvoyée

Si le paramètre fMode est égal à zéro, la valeur de retour correspond à la taille de la mémoire tampon requise pour contenir les données d’initialisation du pilote d’imprimante. Notez que cette mémoire tampon peut être plus grande qu’une structure DEVMODE si le pilote d’imprimante ajoute des données privées à la structure.

Si la fonction affiche la feuille de propriétés, la valeur de retour est IDOK ou IDCANCEL, selon le bouton sélectionné par l’utilisateur.

Si la fonction n’affiche pas la feuille de propriétés et réussit, la valeur de retour est IDOK.

Si la fonction échoue, la valeur de retour est inférieure à zéro.

Notes

Notes

Il s’agit d’une fonction de blocage ou synchrone qui peut ne pas être renvoyée immédiatement. La vitesse à laquelle cette fonction est retournée dépend des facteurs d’exécution tels que l’état du réseau, la configuration du serveur d’impression et les facteurs d’implémentation des pilotes d’imprimante qui sont difficiles à prédire lors de l’écriture d’une application. L’appel de cette fonction à partir d’un thread qui gère l’interaction avec l’interface utilisateur peut faire que l’application semble ne pas répondre.

La chaîne vers laquelle pointe le paramètre pDeviceName peut être obtenue en appelant la fonction GetPrinter .

La structure DEVMODE réellement utilisée par un pilote d’imprimante contient la partie indépendante du périphérique (telle que définie ci-dessus), suivie d’une partie spécifique au pilote qui varie en fonction de la taille et du contenu avec chaque pilote et chaque version du pilote. En raison de la dépendance de ce pilote, il est très important pour les applications d’interroger le pilote sur la taille correcte de la structure DEVMODE avant d’allouer une mémoire tampon pour celle-ci.

Pour apporter des modifications aux paramètres d’impression locaux d’une application, une application doit suivre les étapes suivantes :

  1. Obtient le nombre d’octets requis pour la structure DEVMODE complète en appelant DocumentProperties et en spécifiant zéro dans le paramètre fMode .
  2. Allouez de la mémoire pour la structure DEVMODE complète.
  3. Obtient les paramètres actuels de l’imprimante en appelant DocumentProperties. Transmettez un pointeur vers la structure DEVMODE allouée à l’étape 2 en tant que paramètre pDevModeOutput et spécifiez la valeur du _ _ tampon de sortie DM .
  4. Modifiez les membres appropriés de la structure DEVMODE retournée et indiquez les membres qui ont été modifiés en définissant les bits correspondants dans le membre dmFields du DEVMODE.
  5. Appelez DocumentProperties et transmettez à nouveau la structure DEVMODE modifiée en tant que paramètres pDevModeInput et pDevModeOutput et spécifiez les valeurs de _ _ mémoire tampon DM _ dans _ buffer et DM out (qui sont combinées à l’aide de l’opérateur or). La structure DEVMODE retournée par le troisième appel à DocumentProperties peut être utilisée comme argument dans un appel à la fonction CreateDC .

Pour créer un handle vers un contexte de périphérique d’impression à l’aide des paramètres actuels de l’imprimante, il vous suffit d’appeler DocumentProperties à deux reprises, comme décrit ci-dessus. Le premier appel obtient la taille du DEVMODE complet et le deuxième appel Initialise le DEVMODE avec les paramètres actuels de l’imprimante. Transmettez le DEVMODE initialisé à CreateDC pour obtenir le handle du contexte de périphérique d’impression.

Configuration requise

Condition requise Valeur
Client minimal pris en charge
Windows 2000 Professionnel - [Applications de bureau uniquement]
Serveur minimal pris en charge
Windows 2000 Server - [Applications de bureau uniquement]
En-tête
Winspool. h (inclure Windows. h)
Bibliothèque
Winspool. lib
DLL
Winspool. drv
Noms Unicode et ANSI
DocumentPropertiesW (Unicode) et DocumentPropertiesA (ANSI)

Voir aussi

Impression

Fonctions API du spouleur d’impression

AdvancedDocumentProperties

CreateDC

DEVMODE

GetPrinter

OpenPrinter