Función OpenPrinter
La función OpenPrinter recupera un identificador para la impresora o el servidor de impresión especificados u otros tipos de identificadores en el subsistema de impresión.
Sintaxis
BOOL OpenPrinter(
_In_ LPTSTR pPrinterName,
_Out_ LPHANDLE phPrinter,
_In_ LPPRINTER_DEFAULTS pDefault
);
Parámetros
-
pPrinterName [in]
-
Puntero a una cadena terminada en null que especifica el nombre de la impresora o el servidor de impresión, el objeto de impresora, XcvMonitor o XcvPort.
Para un objeto de impresora, use: PrinterName, Job xxxx. Para un XcvMonitor, use: ServerName, XcvMonitor MonitorName. Para un XcvPort, use: ServerName, XcvPort PortName.
Si es NULL, indica el servidor de impresora local.
-
phPrinter [out]
-
Puntero a una variable que recibe un identificador (no seguro para subprocesos) al objeto de servidor de impresión o impresora abierto.
El parámetro phPrinter puede devolver un identificador Xcv para su uso con la función XcvData. Para obtener más información sobre XcvData, vea DDK.
-
pDefault [in]
-
Puntero a una estructura de PRINTER_DEFAULTS . Este valor puede ser NULL.
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto es un valor distinto de cero.
Si la función no se realiza correctamente, el valor devuelto es cero.
Comentarios
No llame a este método en DllMain.
Nota
Un identificador obtenido para una impresora remota mediante una llamada a OpenPrinter para una impresora remota accede a la impresora a través de una caché local en el servicio de cola de impresión. Esta memoria caché no es precisa en tiempo real. Para obtener datos precisos, reemplace la llamada a OpenPrinter por OpenPrinter2 por pOptions.dwFlags establecido en PRINTER_OPTION_NO_CACHE. Tenga en cuenta que solo OpenPrinter2W es funcional. La función devuelve un identificador de impresora que usa otras llamadas API de impresión y omite la memoria caché local. Este método se bloquea mientras se espera la comunicación de red con la impresora remota, por lo que es posible que no se devuelva inmediatamente. La rapidez con la que devuelve esta función depende de factores en tiempo de ejecución, como el estado de red, la configuración del servidor de impresión y los factores de implementación de controladores de impresora que son difíciles de predecir al escribir una aplicación. Llamar a esta función desde un subproceso que administra la interacción de la interfaz de usuario podría hacer que la aplicación no responda.
Nota:
Un identificador obtenido por una llamada a OpenPrinter para una impresora remota accederá a la impresora a través de una memoria caché local en el servicio de cola de impresión. Esta memoria caché es, por diseño, no precisa en tiempo real. Si necesita obtener datos precisos, reemplace la llamada a OpenPrinter por OpenPrinter2 por pOptions.dwFlags establecido en PRINTER_OPTION_NO_CACHE. Tenga en cuenta que solo OpenPrinter2W es funcional. Al hacerlo, la función devuelve un identificador de impresora que realiza otras llamadas api de impresión para omitir la memoria caché local. Tenga en cuenta que este enfoque se bloqueará mientras espera la comunicación de red de ida y vuelta a la impresora remota, por lo que es posible que no vuelva inmediatamente. La rapidez con la que devuelve esta función depende de factores en tiempo de ejecución, como el estado de red, la configuración del servidor de impresión y la implementación del controlador de impresora, factores que son difíciles de predecir al escribir una aplicación. Por lo tanto, llamar a esta función desde un subproceso que administra la interacción con la interfaz de usuario podría hacer que la aplicación parezca que no responde.
El identificador al que apunta phPrinter no es seguro para subprocesos. Si los autores de llamadas necesitan usarlo simultáneamente en varios subprocesos, deben proporcionar acceso de sincronización personalizado al identificador de impresora mediante las funciones de sincronización. Para evitar escribir código personalizado, la aplicación puede abrir un identificador de impresora en cada subproceso, según sea necesario.
El parámetro pDefault permite especificar los valores de tipo de datos y modo de dispositivo que se usan para imprimir documentos enviados por la función StartDocPrinter . Sin embargo, puede invalidar estos valores mediante la función SetJob después de iniciar un documento.
La configuración DEVMODE definida en la estructura PRINTER_DEFAULTS del parámetro pDefault no se usa cuando el valor del miembro pDatatype de la estructura DOC_INFO_1 que se pasó en el parámetro pDocInfo de la llamada a StartDocPrinter es "RAW". Cuando un documento de alto nivel (como un archivo adobe PDF o Microsoft Word) u otros datos de impresora (como PCL, PS o HPGL) se envía directamente a una impresora con pDatatype establecido en "RAW", el documento debe describir completamente la configuración del trabajo de impresión de estilo DEVMODE en el idioma comprendido por el hardware.
Puede llamar a la función OpenPrinter para abrir un identificador en un servidor de impresión o para determinar los derechos de acceso que un cliente tiene en un servidor de impresión. Para ello, especifique el nombre del servidor de impresión en el parámetro pPrinterName , establezca los miembros pDatatype y pDevMode de la estructura de PRINTER_DEFAULTS en NULL y establezca el miembro DesiredAccess para especificar un valor de máscara de acceso de servidor, como SERVER_ALL_ACCESS. Cuando termine con el identificador, páselo a la función ClosePrinter para cerrarla.
Use el miembro DesiredAccess de la estructura PRINTER_DEFAULTS para especificar los derechos de acceso que necesita para la impresora. Los derechos de acceso pueden ser uno de los siguientes. (Si pDefault es NULL, los derechos de acceso se PRINTER_ACCESS_USE).
| Valor de Acceso deseado | Significado |
|---|---|
| PRINTER_ACCESS_ADMINISTER | Para realizar tareas administrativas, como las proporcionadas por SetPrinter. |
| PRINTER_ACCESS_USE | Para realizar operaciones de impresión básicas. |
| PRINTER_ALL_ACCESS | Para realizar todas las tareas administrativas y las operaciones de impresión básicas excepto SYNCHRONIZE (consulte Derechos de acceso estándar). |
| PRINTER_ACCESS_MANAGE_LIMITED | Para realizar tareas administrativas, como las proporcionadas por SetPrinter y SetPrinterData. Este valor está disponible a partir de Windows 8.1. |
| valores de seguridad genéricos, como WRITE_DAC | Para permitir derechos de acceso de control específicos. Consulte Derechos de acceso estándar. |
Si un usuario no tiene permiso para abrir una impresora o un servidor de impresión especificados con el acceso deseado, se producirá un error en la llamada a OpenPrinter con un valor devuelto de cero y GetLastError devolverá el valor ERROR_ACCESS_DENIED.
Ejemplos
Para obtener un programa de ejemplo que use esta función, consulte How To: Print Using the GDI Print API.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible |
Windows 2000 Professional [solo aplicaciones de escritorio] |
| Servidor mínimo compatible |
Windows 2000 Server [solo aplicaciones de escritorio] |
| Encabezado |
|
| Biblioteca |
|
| Archivo DLL |
|
| Nombres Unicode y ANSI |
OpenPrinterW (Unicode) y OpenPrinterA (ANSI) |