Función AddPrinter

La función AddPrinter agrega una impresora a la lista de impresoras admitidas para un servidor especificado.

Sintaxis

HANDLE AddPrinter(
  _In_ LPTSTR *pName,
  _In_ DWORD  Level,
  _In_ LPBYTE pPrinter
);

Parámetros

pName [in]

Puntero a una cadena terminada en null que especifica el nombre del servidor en el que se debe instalar la impresora. Si esta cadena es NULL, la impresora se instala localmente.

Nivel [in]

Versión de la estructura a la que apunta pPrinter . Este valor debe ser 2.

pPrinter [in]

Puntero a una estructura PRINTER_INFO_2 que contiene información sobre la impresora. Debe especificar valores no NULL para los miembros pPrinterName, pPortName, pDriverName y pPrintProcessor de esta estructura antes de llamar a AddPrinter.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es un identificador (no seguro para subprocesos) en un nuevo objeto de impresora. Cuando haya terminado con el identificador, páselo a la función ClosePrinter para cerrarla.

Si se produce un error en la función, el valor devuelto es NULL.

Comentarios

No llame a este método en DllMain.

Nota:

Se trata de una función de bloqueo o sincrónica que 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 del controlador 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.

El autor de la llamada debe tener SeLoadDriverPrivilege.

El identificador devuelto 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 controlador de impresora mediante las funciones de sincronización. Para evitar escribir código personalizado, la aplicación puede abrir un controlador de impresora en cada subproceso, según sea necesario.

A continuación se muestran los miembros de la estructura PRINTER_INFO_2 que se pueden establecer antes de llamar a la función AddPrinter :

• Atributos
• pPrintProcessor
• DefaultPriority
• Prioridad
• pComment
• pSecurityDescriptor
• pDatatype
• pSepFile
• pDevMode
• pShareName
• pLocation
• StartTime
• pParameters
• UntilTime

Los miembros Status, cJobs y AveragePPM de la estructura PRINTER_INFO_2 están reservados para su uso por la función GetPrinter . No deben establecerse antes de llamar a AddPrinter.

Si pSecurityDescriptor es NULL, el sistema asigna un descriptor de seguridad predeterminado a la impresora. El descriptor de seguridad predeterminado tiene los siguientes permisos.

Valor	Descripción
Administradores y usuarios avanzados	Control total en la cola de impresión. Esto significa que los miembros de estos grupos pueden imprimir, administrar la cola (puede eliminar la cola, cambiar cualquier configuración de la cola, incluido el descriptor de seguridad) y administrar los trabajos de impresión de todos los usuarios (eliminar, pausar, reanudar, reiniciar trabajos). Tenga en cuenta que los usuarios avanzados no existen antes de Windows XP Professional.
Creador/propietario	Puede administrar trabajos propios. Esto significa que el usuario que envía trabajos puede administrar (eliminar, pausar, reanudar, reiniciar) sus propios trabajos.
Todos	Ejecutar y el control de lectura estándar. Esto significa que los miembros del grupo de todos los usuarios pueden imprimir y leer propiedades de la cola de impresión.

Una vez que una aplicación crea un objeto de impresora con la función AddPrinter , debe usar la función PrinterProperties para especificar la configuración correcta para el controlador de impresora asociado al objeto de impresora.

La función AddPrinter devuelve un error si ya existe un objeto de impresora con el mismo nombre, a menos que ese objeto esté marcado como eliminación pendiente. En ese caso, la impresora existente no se elimina y los parámetros de creación AddPrinter se usan para cambiar la configuración de impresora existente (como si la aplicación hubiera usado la función SetPrinter ).

Use la función EnumPrintProcessors para enumerar el conjunto de procesadores de impresión instalados en un servidor. Use la función EnumPrintProcessorDatatypes para enumerar el conjunto de tipos de datos que admite un procesador de impresión. Use la función EnumPorts para enumerar el conjunto de puertos disponibles. Use la función EnumPrinterDrivers para enumerar los controladores de impresora instalados.

El autor de la llamada de la función AddPrinter debe tener SERVER_ACCESS_ADMINISTER acceso al servidor en el que se va a crear la impresora. El identificador devuelto por la función tendrá PRINTER_ALL_ACCESS permiso y se puede usar para realizar operaciones administrativas en la impresora.

Si se pasa la función DrvPrinterEvent a la marca PRINTER_EVENT_FLAG_NO_UI, el controlador no debe usar una llamada de interfaz de usuario durante DrvPrinterEvent. Para realizar trabajos relacionados con la interfaz de usuario, el instalador debe usar la entrada VendorSetup en el archivo .inf de la impresora o, para Plug and Play dispositivos, el instalador puede usar un co-instalador específico del dispositivo. Para obtener más información sobre VendorSetup, consulte el Kit de desarrollo de controladores de Microsoft Windows (DDK).

El Firewall de conexión a Internet (ICF) bloquea los puertos de impresora de forma predeterminada, pero se habilita una excepción para Uso compartido de archivos e impresión al ejecutar AddPrinter.

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	Winspool.h (incluye Windows.h)
Biblioteca	Winspool.lib
Archivo DLL	Winspool.drv
Nombres Unicode y ANSI	AddPrinterW (Unicode) y AddPrinterA (ANSI)

Consulte también

Impresión

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

ClosePrinter

DeletePrinter

EnumPorts

EnumPrinterDrivers

EnumPrintProcessors

EnumPrintProcessorDatatypes

GetPrinter

PRINTER_INFO_2

PrinterProperties

SetPrinter