AddPrinter, fonction
La fonction AddPrinter ajoute une imprimante à la liste des imprimantes prises en charge pour un serveur spécifié.
Syntaxe
HANDLE AddPrinter(
_In_ LPTSTR *pName,
_In_ DWORD Level,
_In_ LPBYTE pPrinter
);
Paramètres
-
pName [in]
-
Pointeur vers une chaîne terminée par null qui spécifie le nom du serveur sur lequel l’imprimante doit être installée. Si cette chaîne a la valeur NULL, l’imprimante est installée localement.
-
Niveau [in]
-
Version de la structure vers laquelle pPrinter pointe. Cette valeur doit être 2.
-
pPrinter [in]
-
Pointeur vers une structure de PRINTER_INFO_2 qui contient des informations sur l’imprimante. Vous devez spécifier des valeurs non NULL pour les membres pPrinterName, pPortName, pDriverName et pPrintProcessor de cette structure avant d’appeler AddPrinter.
Valeur retournée
Si la fonction réussit, la valeur de retour est un handle (et non thread safe) à un nouvel objet d’imprimante. Lorsque vous avez terminé avec le handle, passez-le à la fonction ClosePrinter pour le fermer.
Si la fonction échoue, la valeur de retour est NULL.
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.
L’appelant doit avoir seLoadDriverPrivilege.
Le handle retourné n’est pas thread safe. Si les appelants doivent l’utiliser simultanément sur plusieurs threads, ils doivent fournir un accès de synchronisation personnalisé au handle d’imprimante à l’aide des fonctions de synchronisation. Pour éviter d’écrire du code personnalisé, l’application peut ouvrir un handle d’imprimante sur chaque thread, en fonction des besoins.
Voici les membres de la structure PRINTER_INFO_2 qui peuvent être définis avant l’appel de la fonction AddPrinter :
- Attributs
- pPrintProcessor
- DefaultPriority
- Priorité
- pComment
- pSecurityDescriptor
- pDatatype
- pSepFile
- pDevMode
- pShareName
- pLocation
- StartTime
- pParameters
- UntilTime
Les membres Status, cJobs et AveragePPM de la structure PRINTER_INFO_2 sont réservés à l’utilisation par la fonction GetPrinter . Ils ne doivent pas être définis avant d’appeler AddPrinter.
Si pSecurityDescriptor a la valeur NULL, le système affecte un descripteur de sécurité par défaut à l’imprimante. Le descripteur de sécurité par défaut dispose des autorisations suivantes.
| Valeur | Description |
|---|---|
| Administrateurs et utilisateurs avec pouvoir | Contrôle total sur la file d’attente d’impression. Cela signifie que les membres de ces groupes peuvent imprimer, gérer la file d’attente (peut supprimer la file d’attente, modifier n’importe quel paramètre de la file d’attente, y compris le descripteur de sécurité) et gérer les travaux d’impression de tous les utilisateurs (supprimer, suspendre, reprendre, redémarrer les travaux). Notez que les utilisateurs avec pouvoir n’existent pas avant Windows XP Professionnel. |
| Propriétaire créateur | Peut gérer ses propres travaux. Cela signifie que l’utilisateur qui envoie des travaux peut gérer (supprimer, suspendre, reprendre, redémarrer) ses propres travaux. |
| Tout le monde | Exécutez et contrôle de lecture standard. Cela signifie que les membres du groupe tout le monde peuvent imprimer et lire les propriétés de la file d’attente d’impression. |
Une fois qu’une application a créé un objet d’imprimante avec la fonction AddPrinter , elle doit utiliser la fonction PrinterProperties pour spécifier les paramètres corrects pour le pilote d’imprimante associé à l’objet d’imprimante.
La fonction AddPrinter retourne une erreur si un objet d’imprimante portant le même nom existe déjà, sauf si cet objet est marqué comme étant en attente de suppression. Dans ce cas, l’imprimante existante n’est pas supprimée et les paramètres de création AddPrinter sont utilisés pour modifier les paramètres d’imprimante existants (comme si l’application avait utilisé la fonction SetPrinter ).
Utilisez la fonction EnumPrintProcessors pour énumérer l’ensemble de processeurs d’impression installés sur un serveur. Utilisez la fonction EnumPrintProcessorDatatypes pour énumérer l’ensemble de types de données pris en charge par un processeur d’impression. Utilisez la fonction EnumPorts pour énumérer l’ensemble de ports disponibles. Utilisez la fonction EnumPrinterDrivers pour énumérer les pilotes d’imprimante installés.
L’appelant de la fonction AddPrinter doit avoir SERVER_ACCESS_ADMINISTER accès au serveur sur lequel l’imprimante doit être créée. Le handle retourné par la fonction aura PRINTER_ALL_ACCESS autorisation et peut être utilisé pour effectuer des opérations d’administration sur l’imprimante.
Si la fonction DrvPrinterEvent est transmise à l’indicateur PRINTER_EVENT_FLAG_NO_UI, le pilote ne doit pas utiliser d’appel d’interface utilisateur pendant DrvPrinterEvent. Pour effectuer des travaux liés à l’interface utilisateur, le programme d’installation doit utiliser l’entrée VendorSetup dans le fichier .inf de l’imprimante ou, pour Plug-and-Play appareils, le programme d’installation peut utiliser un co-programme d’installation spécifique à l’appareil. Pour plus d’informations sur VendorSetup, consultez microsoft Windows Driver Development Kit (DDK).
Le pare-feu de connexion Internet (ICF) bloque les ports d’imprimante par défaut, mais une exception pour le partage de fichiers et d’impression est activée lorsque vous exécutez AddPrinter.
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 |
AddPrinterW (Unicode) et AddPrinterA (ANSI) |