Fonction OpenPrinter (Winspool.h) – Applications Win32 – Bien choisir son serveur d impression
<! –
le OpenPrinter La fonction récupère une poignée vers l'imprimante ou le serveur d'impression spécifié ou d'autres types de poignées 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 terminée par un caractère nul qui spécifie le nom de l'imprimante ou du serveur d'impression, l'objet imprimante, XcvMonitor ou XcvPort.
Pour un objet imprimante, utilisez: PrinterName, Job xxxx. Pour un XcvMonitor, utilisez: ServerName, XcvMonitor MonitorName. Pour un XcvPort, utilisez: ServerName, XcvPort PortName.
Si NUL, il indique le serveur d'impression local.
-
phPrinter [out]
-
Un pointeur vers une variable qui reçoit une poignée (non thread-safe) vers l'imprimante ouverte ou l'objet serveur d'impression.
le phPrinter Le paramètre peut renvoyer un descripteur Xcv à utiliser avec la fonction XcvData. Pour plus d'informations sur XcvData, consultez le DDK.
-
pDefault [in]
-
Un pointeur vers un PRINTER_DEFAULTS structure. Cette valeur peut être NUL.
Valeur de retour
Si la fonction réussit, la valeur de retour est une valeur non nulle.
Si la fonction échoue, la valeur de retour est zéro.
Remarques
N'appelez pas cette méthode dans DllMain.
Remarque
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 avec pOptions.dwFlags défini sur PRINTER_OPTION_NO_CACHE. Notez que seul OpenPrinter2W est fonctionnel. La fonction renvoie un descripteur 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, il se peut donc qu'elle ne revienne pas immédiatement. La vitesse de retour de cette fonction dépend de facteurs d'exécution tels que l'état du réseau, la configuration du serveur d'impression et les facteurs d'implémentation du pilote d'imprimante qui sont difficiles à prévoir 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 faire en sorte que l'application semble ne pas répondre.
Remarque
Un handle obtenu par un appel à OpenPrinter pour une imprimante distante accédera à l'imprimante via un cache local dans le service de spouleur d'impression. De par sa conception, ce cache n'est pas précis en temps réel. Si vous devez obtenir des données précises, remplacez le OpenPrinter appeler avec OpenPrinter2 avec pOptions.dwFlags mis à PRINTER_OPTION_NO_CACHE. Notez que seulement OpenPrinter2W est fonctionnel. Ce faisant, la fonction renvoie un descripteur d'imprimante qui effectue d'autres appels d'API d'impression pour contourner le cache local. Notez que cette approche se bloquera en attendant la communication réseau aller-retour avec l'imprimante distante, il est donc possible qu'elle ne revienne pas immédiatement. La rapidité de retour de cette fonction dépend de facteurs d'exécution tels que l'état du réseau, la configuration du serveur d'impression et l'implémentation du pilote d'imprimante, facteurs difficiles à prévoir 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.
La poignée pointée 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é à la poignée de l'imprimante à l'aide des fonctions de synchronisation. Pour éviter d'écrire du code personnalisé, l'application peut ouvrir une poignée d'imprimante sur chaque thread, selon les besoins.
le pDefault Le paramètre vous permet de spécifier le type de données et les valeurs de mode de périphérique utilisés pour l'impression des documents soumis par le StartDocPrinter une fonction. Cependant, vous pouvez remplacer ces valeurs en utilisant le paramètre SetJob après le démarrage d'un document.
le DEVMODE paramètres définis dans le PRINTER_DEFAULTS structure du pDefault ne sont pas utilisés lorsque la valeur de la pDatatype membre du DOC_INFO_1 structure qui a été adoptée dans le pDocInfo paramètre du StartDocPrinter l'appel 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) sont envoyés directement à une imprimante avec pDatatype réglé sur "RAW", le document doit décrire DEVMODE-les paramètres des travaux d'impression de style dans la langue comprise par le matériel.
Vous pouvez appeler le OpenPrinter pour ouvrir un descripteur sur un serveur d'impression ou pour déterminer les droits d'accès dont dispose un client sur un serveur d'impression. Pour ce faire, spécifiez le nom du serveur d'impression dans le pPrinterName , définissez le pDatatype et pDevMode membres de PRINTER_DEFAULTS structure à NULet définissez Accès souhaité membre pour spécifier une valeur de masque d'accès au serveur telle que SERVER_ALL_ACCESS. Lorsque vous avez terminé avec la poignée, passez-la au FermerImprimante fonction pour le fermer.
Utilisez le Accès souhaité membre du PRINTER_DEFAULTS pour spécifier les droits d'accès dont vous avez besoin sur l'imprimante. Les droits d'accès peuvent être l'un des suivants. (Si pDefault est NUL, les droits d'accès sont PRINTER_ACCESS_USE.)
| Valeur d'accès souhaitée | Sens |
|---|---|
| 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. Voir Droits d'accès standard. |
Si un utilisateur n'est pas autorisé à ouvrir une imprimante ou un serveur d'impression spécifié avec l'accès souhaité, le OpenPrinter l'appel échouera avec une valeur de retour de zéro et GetLastError renverra la valeur ERROR_ACCESS_DENIED.
Exemples
Pour un exemple de programme qui utilise cette fonction, consultez Comment: imprimer à l'aide de l'API d'impression GDI.
Exigences
| Client minimum pris en charge | Windows 2000 Professionnel [desktop apps only] |
| Serveur minimum pris en charge | Windows 2000 Server [desktop apps only] |
| Entête |
|
| Bibliothèque |
|
| DLL |
|
| Noms Unicode et ANSI | OpenPrinterW (Unicode) et OpenPrinterA (ANSI) |
Voir également
-
Impression
-
Fonctions de l'API du spouleur d'impression
-
WritePrinter
-
FermerImprimante
-
PRINTER_DEFAULTS
-
SetJob
-
SetPrinter
-
StartDocPrinter
<! – ->
Commentaires
Laisser un commentaire