Fonction EnumPrinterData
La fonction EnumPrinterData énumère les données de configuration d’une imprimante spécifiée.
Pour récupérer les données de configuration dans un seul appel, utilisez la fonction EnumPrinterDataEx .
Syntaxe
DWORD EnumPrinterData(
_In_ HANDLE hPrinter,
_In_ DWORD dwIndex,
_Out_ LPTSTR pValueName,
_In_ DWORD cbValueName,
_Out_ LPDWORD pcbValueName,
_Out_ LPDWORD pType,
_Out_ LPBYTE pData,
_In_ DWORD cbData,
_Out_ LPDWORD pcbData
);
Paramètres
-
hPrinter [in]
-
Handle de l’imprimante dont les données de configuration doivent être obtenues. Utilisez la fonction OpenPrinter ou AddPrinter pour récupérer un handle d’imprimante.
-
dwIndex [in]
-
Valeur d’index qui spécifie la valeur des données de configuration à récupérer.
Définissez ce paramètre sur zéro pour le premier appel à EnumPrinterData pour un handle d’imprimante spécifié. Incrémentez ensuite le paramètre d’un pour les appels suivants impliquant la même imprimante, jusqu’à ce que la fonction retourne ERROR_NO_MORE_ITEMS. Pour plus d’informations, consultez la section Remarques suivante.
Si vous utilisez la technique mentionnée dans les descriptions des paramètres cbValueName et cbData pour obtenir des valeurs de taille de mémoire tampon adéquates, en définissant ces deux paramètres sur zéro dans un premier appel à EnumPrinterData pour un handle d’imprimante spécifié, la valeur de dwIndex n’a pas d’importance pour cet appel. Définissez dwIndex sur zéro dans l’appel suivant à EnumPrinterData pour démarrer le processus d’énumération réel.
Les valeurs de données de configuration ne sont pas triées. Les nouvelles valeurs auront un index arbitraire. Cela signifie que la fonction EnumPrinterData peut retourner des valeurs dans n’importe quel ordre.
-
pValueName [out]
-
Pointeur vers une mémoire tampon qui reçoit le nom de la valeur de données de configuration, y compris un caractère null de fin.
-
cbValueName [in]
-
Taille, en octets, de la mémoire tampon pointée par pValueName.
Si vous souhaitez que le système d’exploitation fournisse une taille de mémoire tampon adéquate, définissez ce paramètre et le paramètre cbData sur zéro pour le premier appel à EnumPrinterData pour un handle d’imprimante spécifié. Lorsque la fonction retourne, la variable pointée par pcbValueName contient une taille de mémoire tampon suffisamment grande pour énumérer correctement tous les noms de valeurs de données de configuration de l’imprimante.
-
pcbValueName [out]
-
Pointeur vers une variable qui reçoit le nombre d’octets stockés dans la mémoire tampon pointée par pValueName.
-
pType [out]
-
Pointeur vers une variable qui reçoit un code indiquant le type de données stockées dans la valeur spécifiée. Pour obtenir la liste des codes de type possibles, consultez Types de valeurs du Registre. Le paramètre pType peut être NULL si le code de type n’est pas requis.
-
pData [out]
-
Pointeur vers une mémoire tampon qui reçoit la valeur des données de configuration.
Ce paramètre peut être NULL si la valeur des données de configuration n’est pas requise.
-
cbData [in]
-
Taille, en octets, de la mémoire tampon pointée par pData.
Si vous souhaitez que le système d’exploitation fournisse une taille de mémoire tampon adéquate, définissez ce paramètre et le paramètre cbValueName sur zéro pour le premier appel à EnumPrinterData pour un handle d’imprimante spécifié. Lorsque la fonction retourne, la variable pointée par pcbData contient une taille de mémoire tampon suffisamment grande pour énumérer correctement tous les noms de valeurs de données de configuration de l’imprimante.
-
pcbData [out]
-
Pointeur vers une variable qui reçoit le nombre d’octets stockés dans la mémoire tampon pointée par pData.
Ce paramètre peut être NULL si pData a la valeur NULL.
Valeur retournée
Si la fonction réussit, la valeur de retour est ERROR_SUCCESS.
Si la fonction échoue, la valeur de retour est un code d’erreur système.
La fonction retourne ERROR_NO_MORE_ITEMS lorsqu’il n’y a plus de valeurs de données de configuration à récupérer pour un handle d’imprimante spécifié.
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.
EnumPrinterData récupère le jeu de données de configuration de l’imprimante par la fonction SetPrinterData . Les données de configuration d’une imprimante se composent d’un ensemble de valeurs nommées et typées. La fonction EnumPrinterData obtient l’une de ces valeurs, ainsi que son nom et un code de type, chaque fois que vous l’appelez. Appelez la fonction EnumPrinterData plusieurs fois de suite pour obtenir toutes les valeurs de données de configuration d’une imprimante.
Les données de configuration de l’imprimante sont stockées dans le Registre. Lors de l’énumération des données de configuration de l’imprimante, vous devez éviter d’appeler des fonctions de Registre susceptibles de modifier ces données.
Si vous souhaitez que le système d’exploitation fournisse une taille de mémoire tampon adéquate, appelez d’abord EnumPrinterData avec les paramètres cbValueName et cbData définis sur zéro, comme indiqué précédemment dans la section Paramètres. La valeur de dwIndex n’a pas d’importance pour cet appel. Lorsque la fonction est retournée, *pcbValueName et *pcbData contiennent des tailles de mémoire tampon suffisamment grandes pour énumérer tous les noms et valeurs des valeurs des données de configuration de l’imprimante. Lors de l’appel suivant, allouez le nom de la valeur et les mémoires tampons de données, définissez cbValueName et cbData sur les tailles en octets des mémoires tampons allouées, puis définissez dwIndex sur zéro. Ensuite, continuez à appeler la fonction EnumPrinterData , en incrémentant dwIndex d’un à chaque fois, jusqu’à ce que la fonction retourne ERROR_NO_MORE_ITEMS.
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 |
EnumPrinterDataW (Unicode) et EnumPrinterDataA (ANSI) |