GetPrinter, fonction
La fonction GetPrinter récupère des informations sur une imprimante spécifiée.
Syntaxe
BOOL GetPrinter(
_In_ HANDLE hPrinter,
_In_ DWORD Level,
_Out_ LPBYTE pPrinter,
_In_ DWORD cbBuf,
_Out_ LPDWORD pcbNeeded
);
Paramètres
-
hPrinter [in]
-
Handle de l’imprimante pour laquelle la fonction récupère des informations. Utilisez la fonction OpenPrinter ou AddPrinter pour récupérer un handle d’imprimante.
-
Niveau [in]
-
Niveau ou type de structure que la fonction stocke dans la mémoire tampon pointée par pPrinter.
Cette valeur peut être 1, 2, 3, 4, 5, 6, 7, 8 ou 9.
-
pPrinter [out]
-
Pointeur vers une mémoire tampon qui reçoit une structure contenant des informations sur l’imprimante spécifiée. La mémoire tampon doit être suffisamment grande pour recevoir la structure et toutes les chaînes ou autres données vers lesquelles pointent les membres de la structure. Si la mémoire tampon est trop petite, le paramètre pcbNeeded retourne la taille de mémoire tampon requise.
Le type de structure est déterminé par la valeur de Level.
Level Structure - 1
Structure PRINTER_INFO_1 contenant des informations générales sur l’imprimante. - 2
Structure PRINTER_INFO_2 contenant des informations détaillées sur l’imprimante. - 3
Structure PRINTER_INFO_3 contenant les informations de sécurité de l’imprimante. - 4
Structure PRINTER_INFO_4 contenant des informations minimales sur l’imprimante, notamment le nom de l’imprimante, le nom du serveur et si l’imprimante est distante ou locale. - 5
Structure PRINTER_INFO_5 contenant des informations sur l’imprimante, telles que les attributs de l’imprimante et les paramètres de délai d’attente. - 6
Structure PRINTER_INFO_6 spécifiant la valeur status d’une imprimante. - 7
Structure PRINTER_INFO_7 qui indique si l’imprimante est publiée dans le service d’annuaire. - 8
Structure PRINTER_INFO_8 spécifiant les paramètres globaux par défaut de l’imprimante. - 9
Structure PRINTER_INFO_9 spécifiant les paramètres d’imprimante par défaut par utilisateur. -
cbBuf [in]
-
Taille, en octets, de la mémoire tampon pointée par pPrinter.
-
pcbNeeded [out]
-
Pointeur vers une variable que la fonction définit sur la taille, en octets, des informations d’imprimante. Si cbBuf est inférieur à cette valeur, GetPrinter échoue et la valeur représente la taille de mémoire tampon requise. Si cbBuf est égal ou supérieur à cette valeur, GetPrinter réussit et la valeur représente le nombre d’octets stockés dans la mémoire tampon.
Valeur retournée
Si la fonction réussit, la valeur de retour est une valeur différente de zéro.
Si la fonction échoue, la valeur de retour est égale à zéro.
Notes
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.
Le membre pDevMode dans les structures PRINTER_INFO_2, PRINTER_INFO_8 et PRINTER_INFO_9 peut être NULL. Dans ce cas, l’imprimante est inutilisable tant que le pilote n’a pas été réinstallé.
Pour les structures PRINTER_INFO_2 et PRINTER_INFO_3 qui contiennent un pointeur vers un descripteur de sécurité, la fonction récupère uniquement les composants du descripteur de sécurité que l’appelant est autorisé à lire. Pour récupérer des composants de descripteur de sécurité particuliers, vous devez spécifier les droits d’accès nécessaires lorsque vous appelez la fonction OpenPrinter pour récupérer un handle sur l’imprimante. Le tableau suivant présente les droits d’accès requis pour lire les différents composants du descripteur de sécurité.
| Droit d'accès | Composant de descripteur de sécurité |
|---|---|
| READ_CONTROL |
Propriétaire Groupe principal Liste de contrôle d’accès discrétionnaire (DACL) |
| ACCESS_SYSTEM_SECURITY |
Liste de contrôle d’accès système (SACL) |
Si vous spécifiez le niveau 7, le membre dwAction de PRINTER_INFO_7 retourne l’une des valeurs suivantes pour indiquer si l’imprimante est publiée dans le service d’annuaire.
| Valeur dwAction | Signification |
|---|---|
| DSPRINT_PUBLISH | L’imprimante est publiée. Le membre pszObjectGUID contient le GUID de l’objet file d’attente d’impression des services d’annuaire associé à l’imprimante. |
| DSPRINT_UNPUBLISH | L’imprimante n’est pas publiée. |
| DSPRINT_PENDING | Indique que le système tente d’effectuer une opération de publication ou d’annulation de publication. Si un appel SetPrinter ne parvient pas à publier ou à annuler la publication d’une imprimante, le système tente d’effectuer l’opération en arrière-plan. |
À compter de Windows Vista, les données d’imprimante retournées par GetPrinter sont récupérées à partir d’un cache local lorsque hPrinter fait référence à une imprimante hébergée par un serveur d’impression et qu’il existe au moins une connexion ouverte au serveur d’impression. Dans toutes les autres configurations, les données de l’imprimante sont interrogées à partir du serveur d’impression.
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 |
|
| Bibliothèque |
|
| DLL |
|
| Noms Unicode et ANSI |
GetPrinterW (Unicode) et GetPrinterA (ANSI) |