Función OpenPrinter2

Recupera un identificador de la impresora, el servidor de impresión u otros tipos de identificadores especificados en el subsistema de impresión, al tiempo que establece algunas de las opciones de impresora.

Sintaxis

BOOL OpenPrinter2(
  _In_  LPCTSTR            pPrinterName,
  _Out_ LPHANDLE           phPrinter,
  _In_  LPPRINTER_DEFAULTS pDefault,
  _In_  PPRINTER_OPTIONS   pOptions
);

Parámetros

pPrinterName [in]

Puntero a una cadena terminada en null constante que especifica el nombre de la impresora o el servidor de impresión, el objeto printer, 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.

Windows Vista: Si es NULL, indica el servidor de impresión local.

phPrinter [out]

Puntero a una variable que recibe un identificador para la impresora abierta o el objeto de servidor de impresión.

pDefault [in]

Puntero a una estructura de PRINTER_DEFAULTS . Este valor puede ser NULL.

pOptions [in]

Puntero a una estructura de PRINTER_OPTIONS . 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. Para obtener información de error extendida, llame a GetLastError.

Comentarios

No llame a este método en DllMain.

Nota

Se trata de una función de bloqueo o sincrónica y podría no devolverse 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 con la interfaz de usuario podría hacer que la aplicación parezca que no responde.

La versión ANSI de esta función no se implementa y devuelve ERROR_NOT_SUPPORTED.

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.

Puede llamar a la función OpenPrinter2 para abrir un identificador en un servidor de impresión o para determinar los derechos de acceso de cliente a 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 haya terminado 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 necesarios. Los derechos de acceso pueden ser uno de los siguientes.

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 especificada o un servidor de impresión con el acceso deseado, se producirá un error en la llamada a OpenPrinter2 y GetLastError devolverá el valor ERROR_ACCESS_DENIED.

Cuando pPrinterName es una impresora local, OpenPrinter2 omite todos los valores de dwFlags a los que apunta la estructura PRINTER_OPTIONS mediante pOptions, excepto PRINTER_OPTION_CLIENT_CHANGE. Si se pasa este último, OpenPrinter2 devolverá ERROR_ACCESS_DENIED. En consecuencia, al abrir una impresora local, OpenPrinter2 no proporciona ninguna ventaja sobre OpenPrinter.

Windows Vista: Los datos de impresora devueltos por OpenPrinter2 se recuperan de una memoria caché local a menos que la marca PRINTER_OPTION_NO_CACHE se establezca en el campo dwFlags de la estructura de PRINTER_OPTIONS a la que hace referencia pOptions.

Ejemplos

En este ejemplo, Se produce un error en OpenPrinter2 cuando se pasa PRINTER_ACCESS_MANAGE_LIMITED a la estructura de PRINTER_DEFAULTS y el usuario no tiene el permiso adecuado.

// 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);
}

Para ver un programa de ejemplo que muestra cómo usar esta función, consulte How To: Print Using the GDI Print API.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Encabezado	Winspool.h (incluye Windows.h)
Biblioteca	Winspool.lib
Archivo DLL	Spoolss.dll
Nombres Unicode y ANSI	OpenPrinter2W (Unicode) y OpenPrinter2A (ANSI)

Consulte también

Impresión

Funciones de la API del administrador de trabajos de impresión

ClosePrinter

PRINTER_DEFAULTS

PRINTER_OPTIONS

SetJob

SetPrinter

StartDocPrinter

OpenPrinter