OpenPrinter2, fonction
Récupère un handle pour l’imprimante, le serveur d’impression ou d’autres types de handles spécifiés dans le sous-système d’impression, tout en définissant certaines des options d’imprimante.
Syntaxe
BOOL OpenPrinter2(
_In_ LPCTSTR pPrinterName,
_Out_ LPHANDLE phPrinter,
_In_ LPPRINTER_DEFAULTS pDefault,
_In_ PPRINTER_OPTIONS pOptions
);
Paramètres
-
pPrinterName [in]
-
Pointeur vers une chaîne constante terminée par un caractère Null qui spécifie le nom de l’imprimante ou du serveur d’impression, de l’objet d’imprimante, du XcvMonitor ou du XcvPort.
Pour un objet d’imprimante, utilisez : PrinterName,Job xxxx. Pour un XcvMonitor, utilisez : ServerName,XcvMonitor MonitorName. Pour un XcvPort, utilisez : ServerName,XcvPort PortName.
Windows Vista : Si la valeur est NULL, elle indique le serveur d’impression local.
-
phPrinter [out]
-
Pointeur vers une variable qui reçoit un handle vers l’objet serveur d’impression ou d’imprimante ouvert.
-
pDefault [in]
-
Pointeur vers une structure PRINTER_DEFAULTS . Cette valeur peut être NULL.
-
pOptions [in]
-
Pointeur vers une structure PRINTER_OPTIONS . 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. Pour obtenir des informations d’erreur étendues, appelez GetLastError.
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.
La version ANSI de cette fonction n’est pas implémentée et retourne ERROR_NOT_SUPPORTED.
Le paramètre pDefault vous permet de spécifier les valeurs de type de données et de mode d’appareil utilisées pour l’impression des documents envoyés par la fonction StartDocPrinter . Toutefois, vous pouvez remplacer ces valeurs à l’aide de la fonction SetJob après le démarrage d’un document.
Vous pouvez appeler la fonction OpenPrinter2 pour ouvrir un handle sur un serveur d’impression ou pour déterminer les droits d’accès 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, puis 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 nécessaires. Les droits d’accès peuvent être l’un des suivants.
| Valeur d’accès souhaitée | Signification |
|---|---|
| PRINTER_ACCESS_ADMINISTER | Pour effectuer des tâches d’administration, 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 d’administration et les opérations d’impression de base à l’exception de SYNCHRONIZE. Consultez Droits d’accès standard. |
| PRINTER_ACCESS_MANAGE_LIMITED | Pour effectuer des tâches d’administration, 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’est pas autorisé à ouvrir une imprimante ou un serveur d’impression spécifié avec l’accès souhaité, l’appel OpenPrinter2 échoue et GetLastError retourne la valeur ERROR_ACCESS_DENIED.
Lorsque pPrinterName est une imprimante locale, OpenPrinter2 ignore toutes les valeurs des dwFlags vers lesquelles la structure PRINTER_OPTIONS pointe à l’aide de pOptions, à l’exception de PRINTER_OPTION_CLIENT_CHANGE. Si ce dernier est passé, OpenPrinter2 retourne ERROR_ACCESS_DENIED. Par conséquent, lors de l’ouverture d’une imprimante locale, OpenPrinter2 n’offre aucun avantage par rapport à OpenPrinter.
Windows Vista : Les données d’imprimante retournées par OpenPrinter2 sont récupérées à partir d’un cache local, sauf si l’indicateur PRINTER_OPTION_NO_CACHE est défini dans le champ dwFlags de la structure PRINTER_OPTIONS référencée par pOptions.
Exemples
Dans cet exemple, OpenPrinter2 échoue quand PRINTER_ACCESS_MANAGE_LIMITED est passé à la structure PRINTER_DEFAULTS et que l’utilisateur ne dispose pas de l’autorisation appropriée.
// Specify the limited management permission.
PRINTER_DEFAULTS defaults = {};
defaults.DesiredAccess = PRINTER_ACCESS_MANAGE_LIMITED;
// Open a printer to which the user has no administrative rights.
HANDLE printer = nullptr;
assert(!OpenPrinter2(L QueueWithNoAdminRights , // Queue name
&printer, // Printer handle
&defaults, // Printer defaults
nullptr)); // Printer options
assert(GetLastError() == ERROR_ACCESS_DENIED);
if (printer)
{
ClosePrinter(printer);
}
Pour obtenir un exemple de programme qui montre comment utiliser cette fonction, consultez How To: Print Using the GDI Print API.
Spécifications
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge |
Windows Vista [applications de bureau uniquement] |
| Serveur minimal pris en charge |
Windows Server 2008 [applications de bureau uniquement] |
| En-tête |
|
| Bibliothèque |
|
| DLL |
|
| Noms Unicode et ANSI |
OpenPrinter2W (Unicode) et OpenPrinter2A (ANSI) |