Fonction OpenPrinter
La fonction OpenPrinter récupère un handle pour l’imprimante ou le serveur d’impression spécifié ou d’autres types de handles dans le sous-système d’impression.
Syntaxe
BOOL OpenPrinter(
_In_ LPTSTR pPrinterName,
_Out_ LPHANDLE phPrinter,
_In_ LPPRINTER_DEFAULTS pDefault
);
Paramètres
-
pPrinterName [in]
-
Pointeur vers une chaîne null qui spécifie le nom de l’imprimante ou du serveur d’impression, l’objet d’imprimante, le XcvMonitor ou le XcvPort.
Pour un objet d’imprimante, utilisez : PrinterName, Job xxxx. Pour un XcvMonitor, utilisez : ServerName, XcvMonitor MonitorName. Pour un XcvPort, utilisez : ServerName, XcvPort PortName.
Si la valeur est NULL, elle indique le serveur d’imprimante local.
-
phPrinter [out]
-
Pointeur vers une variable qui reçoit un handle (pas thread safe) vers l’objet serveur d’impression ou d’imprimante ouvert.
Le paramètre phPrinter peut retourner un handle Xcv à utiliser avec la fonction XcvData. Pour plus d’informations sur XcvData, consultez le DDK.
-
pDefault [in]
-
Pointeur vers une structure PRINTER_DEFAULTS . Cette valeur peut être NULL.
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
Un handle obtenu pour une imprimante distante par un appel à OpenPrinter pour une imprimante distante accède à l’imprimante via un cache local dans le service de spouleur d’impression. Ce cache n’est pas précis en temps réel. Pour obtenir des données précises, remplacez l’appel OpenPrinter par OpenPrinter2 par pOptions.dwFlags défini sur PRINTER_OPTION_NO_CACHE. Notez que seul OpenPrinter2W est fonctionnel. La fonction retourne un handle d’imprimante qui utilise d’autres appels d’API d’impression et contourne le cache local. Cette méthode se bloque en attendant la communication réseau avec l’imprimante distante, de sorte qu’elle risque de 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 de l’interface utilisateur peut rendre l’application ne répond pas.
Notes
Un handle obtenu par un appel à OpenPrinter pour une imprimante distante accède à l’imprimante via un cache local dans le service de spouleur d’impression. Par défaut, ce cache n’est pas précis en temps réel. Si vous avez besoin d’obtenir des données précises, remplacez l’appel OpenPrinter par OpenPrinter2 par pOptions.dwFlags défini sur PRINTER_OPTION_NO_CACHE. Notez que seul OpenPrinter2W est fonctionnel. Ainsi, la fonction retourne un handle d’imprimante qui effectue d’autres appels d’API d’impression pour contourner le cache local. Notez que cette approche se bloque en attendant la communication réseau aller-retour vers l’imprimante distante, de sorte qu’elle risque de ne pas revenir 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 l’implémentation du pilote d’imprimante, facteurs difficiles à prédire lors de l’écriture d’une application. Par conséquent, 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 handle pointé vers par phPrinter 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.
Le paramètre pDefault vous permet de spécifier le type de données et les valeurs de mode appareil utilisées pour l’impression de documents envoyés par la fonction StartDocPrinter . Toutefois, vous pouvez remplacer ces valeurs à l’aide de la fonction SetJob une fois qu’un document a été démarré.
Les paramètres DEVMODE définis dans la structure PRINTER_DEFAULTS du paramètre pDefault ne sont pas utilisés lorsque la valeur du membre pDatatype de la structure DOC_INFO_1 passée dans le paramètre pDocInfo de l’appel StartDocPrinter est « RAW ». Lorsqu’un document de haut niveau (tel qu’un fichier Adobe PDF ou Microsoft Word) ou d’autres données d’imprimante (telles que PCL, PS ou HPGL) est envoyé directement à une imprimante avec pDatatype défini sur « RAW », le document doit décrire entièrement les paramètres de travail d’impression de style DEVMODE dans la langue comprise par le matériel.
Vous pouvez appeler la fonction OpenPrinter pour ouvrir un handle sur un serveur d’impression ou pour déterminer les droits d’accès d’un client à un serveur d’impression. Pour ce faire, spécifiez le nom du serveur d’impression dans le paramètre pPrinterName , définissez les membres pDatatype et pDevMode de la structure PRINTER_DEFAULTS sur NULL et définissez le membre DesiredAccess pour spécifier une valeur de masque d’accès au serveur, telle que SERVER_ALL_ACCESS. Lorsque vous avez terminé avec le handle, passez-le à la fonction ClosePrinter pour le fermer.
Utilisez le membre DesiredAccess de la structure PRINTER_DEFAULTS pour spécifier les droits d’accès dont vous avez besoin pour l’imprimante. Les droits d’accès peuvent être l’un des suivants. (Si pDefault a la valeur NULL, les droits d’accès sont PRINTER_ACCESS_USE.)
| Valeur d’accès souhaitée | Signification |
|---|---|
| PRINTER_ACCESS_ADMINISTER | Pour effectuer des tâches administratives, telles que celles fournies par SetPrinter. |
| PRINTER_ACCESS_USE | Pour effectuer des opérations d’impression de base. |
| PRINTER_ALL_ACCESS | Pour effectuer toutes les tâches administratives et les opérations d’impression de base, à l’exception de SYNCHRONIZE (voir Droits d’accès standard). |
| PRINTER_ACCESS_MANAGE_LIMITED | Pour effectuer des tâches administratives, telles que celles fournies par SetPrinter et SetPrinterData. Cette valeur est disponible à partir de Windows 8.1. |
| valeurs de sécurité génériques, telles que WRITE_DAC | Pour autoriser des droits d’accès de contrôle spécifiques. Consultez Droits d’accès standard. |
Si un utilisateur n’a pas l’autorisation d’ouvrir une imprimante ou un serveur d’impression spécifié avec l’accès souhaité, l’appel OpenPrinter échoue avec une valeur de retour de zéro et GetLastError retourne la valeur ERROR_ACCESS_DENIED.
Exemples
Pour obtenir un exemple de programme qui utilise cette fonction, consultez Guide pratique pour imprimer à l’aide de l’API d’impression GDI.
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 |
OpenPrinterW (Unicode) et OpenPrinterA (ANSI) |