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.

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.

Spécifications

Voir aussi

Impression

Fonctions API du spouleur d’impression

Addprinter

DeletePrinter

GetPrinter

PRINTER_INFO_1

PRINTER_INFO_2

PRINTER_INFO_4

PRINTER_INFO_5

SetPrinter