Fonction DocumentProperties

Article
06/12/2023

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 d’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 [in]

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

hPrinter [in]

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

pDeviceName [in]

Pointeur vers une chaîne terminée par 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 [out]

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

pDevModeInput [in]

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 n’est utilisé que si l’indicateur DM_IN_BUFFER est défini dans le paramètre fMode . Si DM_IN_BUFFER n’est pas défini, le système d’exploitation utilise le DEVMODE par défaut de l’imprimante.

fMode [in]

Opérations effectué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 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_IN_BUFFER	Valeur d’entrée. Avant d’inviter, 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 comme DM_MODIFY. 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_IN_PROMPT	Valeur d’entrée. La fonction présente la feuille de propriétés Print Setup 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 comme DM_PROMPT.
DM_OUT_BUFFER	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 le bit DM_OUT_BUFFER jeux est clair, le paramètre pDevModeOutput peut avoir la valeur NULL. Cette valeur est également définie comme DM_COPY.

Valeur retourné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

Il s’agit d’une fonction bloquante ou synchrone qui peut ne pas être retournée immédiatement. La rapidité avec laquelle cette fonction retourne dépend de facteurs d’exécution tels que l’status réseau, la configuration du serveur d’impression et les facteurs d’implémentation du pilote 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 donner l’impression que l’application ne répond pas.

La chaîne pointée vers 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 le composant indépendant du périphérique (comme défini ci-dessus) suivi d’un composant spécifique au pilote qui varie en taille et en contenu avec chaque pilote et version de pilote. En raison de cette dépendance au pilote, il est très important pour les applications d’interroger le pilote pour obtenir 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 :

Obtenez 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 .
Allouez de la mémoire pour la structure DEVMODE complète.
Obtenez les paramètres d’imprimante actuels en appelant DocumentProperties. Passez un pointeur vers la structure DEVMODE allouée à l’étape 2 en tant que paramètre pDevModeOutput et spécifiez la valeur DM_OUT_BUFFER .
Modifiez les membres appropriés de la structure DEVMODE retournée et indiquez quels membres ont été modifiés en définissant les bits correspondants dans le membre dmFields du DEVMODE.
Appelez DocumentProperties et transmettez la structure DEVMODE modifiée en tant que paramètres pDevModeInput et pDevModeOutput et spécifiez les valeurs DM_IN_BUFFER et DM_OUT_BUFFER (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 dans un contexte d’appareil d’imprimante à l’aide des paramètres d’imprimante actuels, il vous suffit d’appeler DocumentProperties deux fois, 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 d’imprimante actuels. Passez le DEVMODE initialisé à CreateDC pour obtenir le handle dans le contexte du périphérique d’imprimante.

Spécifications

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