Fonction EnumPrinters
La fonction EnumPrinters énumère les imprimantes, les serveurs d’impression, les domaines ou les fournisseurs d’impression disponibles.
Syntaxe
BOOL EnumPrinters(
_In_ DWORD Flags,
_In_ LPTSTR Name,
_In_ DWORD Level,
_Out_ LPBYTE pPrinterEnum,
_In_ DWORD cbBuf,
_Out_ LPDWORD pcbNeeded,
_Out_ LPDWORD pcReturned
);
Paramètres
-
Indicateurs [in]
-
Types d’objets d’impression que la fonction doit énumérer. Cette valeur peut être une ou plusieurs des valeurs suivantes.
Valeur Signification - PRINTER_ENUM_LOCAL
Si l’indicateur PRINTER_ENUM_NAME n’est pas également passé, la fonction ignore le paramètre Name et énumère les imprimantes installées localement. Si PRINTER_ENUM_NAME est également transmis, la fonction énumère les imprimantes locales sur Nom. - PRINTER_ENUM_NAME
La fonction énumère l’imprimante identifiée par Nom. Il peut s’agir d’un serveur, d’un domaine ou d’un fournisseur d’impression. Si Name a la valeur NULL, la fonction énumère les fournisseurs d’impression disponibles. - PRINTER_ENUM_SHARED
La fonction énumère les imprimantes qui ont l’attribut partagé. Ne peut pas être utilisé isolément ; utilisez une opération OR à combiner avec un autre type PRINTER_ENUM. - PRINTER_ENUM_CONNECTIONS
La fonction énumère la liste des imprimantes auxquelles l’utilisateur a effectué des connexions précédentes. - PRINTER_ENUM_NETWORK
La fonction énumère les imprimantes réseau dans le domaine de l’ordinateur. Cette valeur est valide uniquement si Level est 1. - PRINTER_ENUM_REMOTE
La fonction énumère les imprimantes réseau et les serveurs d’impression dans le domaine de l’ordinateur. Cette valeur est valide uniquement si Level est 1. - PRINTER_ENUM_CATEGORY_3D
La fonction énumère uniquement les imprimantes 3D. - PRINTER_ENUM_CATEGORY_ALL
La fonction énumère tous les périphériques d’impression, y compris les imprimantes 3D. Si Level a la valeur 4, vous ne pouvez utiliser que les constantes PRINTER_ENUM_CONNECTIONS et PRINTER_ENUM_LOCAL.
Notes
Les périphériques d’impression 3D ne sont pas énumérés par défaut. Vous devez inclure à la fois PRINTER_ENUM_CATEGORY_3D et PRINTER_ENUM_LOCAL pour énumérer uniquement les imprimantes 3D. Pour inclure les imprimantes 3D, ainsi que toutes les autres imprimantes locales, utilisez PRINTER_ENUM_CATEGORY_ALL et PRINTER_ENUM_LOCAL.
-
Nom [in]
-
Si Level a la valeur 1, flags contient PRINTER_ENUM_NAME et Name est non NULL, name est un pointeur vers une chaîne null qui spécifie le nom de l’objet à énumérer. Cette chaîne peut être le nom d’un serveur, d’un domaine ou d’un fournisseur d’impression.
Si Level a la valeur 1, flags contient PRINTER_ENUM_NAME et Name a la valeur NULL, la fonction énumère les fournisseurs d’impression disponibles.
Si Level a la valeur 1, Flags contient PRINTER_ENUM_REMOTE et Name a la valeur NULL, la fonction énumère les imprimantes dans le domaine de l’utilisateur.
Si Level a la valeur 2 ou 5, Name est un pointeur vers une chaîne terminée par null qui spécifie le nom d’un serveur dont les imprimantes doivent être énumérées. Si cette chaîne a la valeur NULL, la fonction énumère les imprimantes installées sur l’ordinateur local.
Si Level a la valeur 4, Name doit avoir la valeur NULL. La fonction interroge toujours sur l’ordinateur local.
Lorsque Nom a la valeur NULL, définissez indicateurs sur PRINTER_ENUM_LOCAL | PRINTER_ENUM_CONNECTIONS énumère les imprimantes installées sur l’ordinateur local. Ces imprimantes incluent celles qui sont physiquement attachées à l’ordinateur local, ainsi que les imprimantes distantes auxquelles elle dispose d’une connexion réseau.
Lorsque Nom n’a pas la valeur NULL, définissez indicateurs sur PRINTER_ENUM_LOCAL | PRINTER_ENUM_NAME énumère les imprimantes locales installées sur le nom du serveur.
-
Niveau [in]
-
Type de structures de données pointées vers pPrinterEnum. Les valeurs valides sont 1, 2, 4 et 5, qui correspondent aux structures de données PRINTER_INFO_1, PRINTER_INFO_2 , PRINTER_INFO_4 et PRINTER_INFO_5 .
Cette valeur peut être 1, 2, 4 ou 5.
-
pPrinterEnum [out]
-
Pointeur vers une mémoire tampon qui reçoit un tableau de structures PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_4 ou PRINTER_INFO_5 . Chaque structure contient des données qui décrivent un objet d’impression disponible.
Si Level a la valeur 1, le tableau contient PRINTER_INFO_1 structures. Si Level est 2, le tableau contient PRINTER_INFO_2 structures. Si Level a la valeur 4, le tableau contient PRINTER_INFO_4 structures. Si Level a la valeur 5, le tableau contient PRINTER_INFO_5 structures.
La mémoire tampon doit être suffisamment grande pour recevoir le tableau des structures de données et toutes les chaînes ou autres données vers lesquelles les membres de la structure pointent. Si la mémoire tampon est trop petite, le paramètre pcbNeeded retourne la taille de mémoire tampon requise.
-
cbBuf [in]
-
Taille, en octets, de la mémoire tampon pointée par pPrinterEnum.
-
pcbNeeded [out]
-
Pointeur vers une valeur qui reçoit le nombre d’octets copiés si la fonction réussit ou le nombre d’octets requis si cbBuf est trop petit.
-
pcReturned [out]
-
Pointeur vers une valeur qui reçoit le nombre de structures PRINTER_INFO_1, PRINTER_INFO_2 , PRINTER_INFO_4 ou PRINTER_INFO_5 que la fonction retourne dans le tableau vers lequel pPrinterEnum pointe.
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
N’appelez pas cette méthode dans DllMain.
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.
Si EnumPrinters retourne une structure PRINTER_INFO_1 dans laquelle PRINTER_ENUM_CONTAINER est spécifié, cela indique qu’il existe une hiérarchie d’objets d’imprimante. Une application peut énumérer la hiérarchie en appelant à nouveau EnumPrinters, en définissant Name sur la valeur du membre pName de la structure PRINTER_INFO_1.
La fonction EnumPrinters ne récupère pas d’informations de sécurité. Si PRINTER_INFO_2 structures sont retournées dans le tableau pointé par pPrinterEnum, leurs membres pSecurityDescriptor sont définis sur NULL.
Pour obtenir des informations sur l’imprimante par défaut, appelez GetDefaultPrinter.
La structure PRINTER_INFO_4 offre un moyen simple et extrêmement rapide de récupérer les noms des imprimantes installées sur un ordinateur local, ainsi que les connexions à distance qu’un utilisateur a établies. Quand EnumPrinters est appelé avec une structure de données PRINTER_INFO_4 , cette fonction interroge le Registre pour obtenir les informations spécifiées, puis retourne immédiatement. Cela diffère du comportement d’EnumPrinters lorsqu’il est appelé avec d’autres niveaux de structures de données PRINTER_INFO_* . En particulier, quand EnumPrinters est appelé avec une structure de données de niveau 2 (PRINTER_INFO_2), il effectue un appel OpenPrinter sur chaque connexion distante. Si une connexion à distance est arrêtée, si le serveur distant n’existe plus ou si l’imprimante distante n’existe plus, la fonction doit attendre que le RPC expire et, par conséquent, échouer l’appel OpenPrinter . Cette opération peut prendre du temps. Le passage d’une structure de PRINTER_INFO_4 permet à une application de récupérer un minimum d’informations requises ; si vous souhaitez obtenir des informations plus détaillées, un appel enumPrinters de niveau 2 peut être effectué.
Windows Vista : Les données d’imprimante retournées par EnumPrinters sont récupérées à partir d’un cache local lorsque la valeur de Level est 4.
Le tableau suivant montre la sortie EnumPrinters pour différentes valeurs Flags lorsque le paramètre Level est défini sur 1.
Dans la colonne Paramètre nom de la table, vous devez remplacer un nom approprié pour Fournisseur d’impression, Domaine et Machine. Par exemple, pour « Fournisseur d’impression », vous pouvez utiliser le nom du fournisseur d’impression réseau ou le nom du fournisseur d’impression local. Pour récupérer des noms de fournisseur d’impression, appelez EnumPrinters avec Nom défini sur NULL.
| Paramètre Flags | Paramètre Name | Résultats |
|---|---|---|
| PRINTER_ENUM_LOCAL (et non PRINTER_ENUM_NAME) | Le paramètre Name est ignoré. |
Toutes les imprimantes locales. |
| PRINTER_ENUM_NAME | « Fournisseur d’impression » |
Tous les noms de domaine |
| PRINTER_ENUM_NAME | « Fournisseur d’impression ! Domaine » |
Toutes les imprimantes et serveurs d’impression dans le domaine de l’ordinateur |
| PRINTER_ENUM_NAME | « Fournisseur d’impression!! \\Machine » |
Toutes les imprimantes partagées sur \\Machine |
| PRINTER_ENUM_NAME | Chaîne vide, « » |
Toutes les imprimantes locales. |
| PRINTER_ENUM_NAME |
NULL |
Tous les fournisseurs d’impression dans le domaine de l’ordinateur |
| PRINTER_ENUM_CONNECTIONS | Le paramètre Name est ignoré. |
Toutes les imprimantes distantes connectées |
| PRINTER_ENUM_NETWORK | Le paramètre Name est ignoré. |
Toutes les imprimantes du domaine de l’ordinateur |
| PRINTER_ENUM_REMOTE | Chaîne vide, « » |
Toutes les imprimantes et serveurs d’impression dans le domaine de l’ordinateur |
| PRINTER_ENUM_REMOTE | « Fournisseur d’impression » |
Identique à PRINTER_ENUM_NAME |
| PRINTER_ENUM_REMOTE | « Fournisseur d’impression ! Domaine » |
Toutes les imprimantes et serveurs d’impression dans le domaine de l’ordinateur, quel que soit le domaine spécifié. |
| PRINTER_ENUM_CATEGORY_3D | Le paramètre Name est ignoré. |
Seules les imprimantes 3D sont énumérées. |
| PRINTER_ENUM_CATEGORY_ALL | Le paramètre Name est ignoré. |
Les imprimantes 3D sont énumérées, ainsi que toutes les autres imprimantes. |
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 |
EnumPrintersW (Unicode) et EnumPrintersA (ANSI) |