Función SetPrinter
La función SetPrinter establece los datos de una impresora especificada o establece el estado de la impresora especificada pausando la impresión, reanudando la impresión o borrando todos los trabajos de impresión.
Sintaxis
BOOL SetPrinter(
_In_ HANDLE hPrinter,
_In_ DWORD Level,
_In_ LPBYTE pPrinter,
_In_ DWORD Command
);
Parámetros
-
hPrinter [in]
-
Identificador de la impresora. Use la función OpenPrinter, OpenPrinter2 o AddPrinter para recuperar un identificador de impresora.
-
Nivel [in]
-
Tipo de datos que almacena la función en el búfer al que apunta pPrinter. Si el parámetro Command no es igual a cero, el parámetro Level debe ser cero.
Este valor puede ser 0, 2, 3, 4, 5, 6, 7, 8 o 9.
-
pPrinter [in]
-
Puntero a un búfer que contiene datos que se van a establecer para la impresora o que contiene información para el comando especificado por el parámetro Command . El tipo de datos del búfer viene determinado por el valor de Level.
Nivel Estructura - 0
Si el parámetro Command es PRINTER_CONTROL_SET_STATUS, pPrinter debe contener un valor DWORD que especifique el nuevo estado de la impresora que se va a establecer. Para obtener una lista de los valores de estado posibles, vea el miembro Status de la estructura PRINTER_INFO_2 . Tenga en cuenta que PRINTER_STATUS_PAUSED y PRINTER_STATUS_PENDING_DELETION no son valores de estado válidos que se van a establecer.
Si Level es 0, pero el parámetro Command no es PRINTER_CONTROL_SET_STATUS, pPrinter debe ser NULL.- 2
Estructura PRINTER_INFO_2 que contiene información detallada sobre la impresora. - 3
Estructura PRINTER_INFO_3 que contiene la información de seguridad de la impresora. - 4
Estructura PRINTER_INFO_4 que contiene información mínima de la impresora, incluido el nombre de la impresora, el nombre del servidor y si la impresora es remota o local. - 5
Estructura PRINTER_INFO_5 que contiene información de impresora, como atributos de impresora y configuración de tiempo de espera. - 6
Estructura PRINTER_INFO_6 que especifica el valor de estado de una impresora. - 7
Estructura de PRINTER_INFO_7 . El miembro dwAction de esta estructura indica si SetPrinter debe publicar, cancelar la publicación, volver a publicar o actualizar los datos de la impresora en el servicio de directorio. - 8
Estructura PRINTER_INFO_8 que especifica la configuración de impresora predeterminada global. - 9
Estructura de PRINTER_INFO_9 que especifica la configuración de impresora predeterminada por usuario. -
Comando [in]
-
la acción que se va a realizar.
Si el parámetro Level es distinto de cero, establezca el valor de este parámetro en cero. En este caso, la impresora conserva su estado actual y la función vuelve a configurar los datos de la impresora según lo especificado por los parámetros Level y pPrinter .
Si el parámetro Level es cero, establezca el valor de este parámetro en uno de los valores siguientes.
Valor Significado - PRINTER_CONTROL_PAUSE
Pausar la impresora. - PRINTER_CONTROL_PURGE
Elimine todos los trabajos de impresión de la impresora. - PRINTER_CONTROL_RESUME
Reanude una impresora en pausa. - PRINTER_CONTROL_SET_STATUS
Establezca el estado de la impresora.
Establezca el parámetro pPrinter en un puntero a un valor DWORD que especifique el nuevo estado de la impresora.
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.
Si Level es 7 y se produjo un error en la acción de publicación, SetPrinter devuelve ERROR_IO_PENDING e intenta completar la acción en segundo plano. Si Level es 7 y se produjo un error en la acción de actualización, SetPrinter devuelve ERROR_FILE_NOT_FOUND.
Comentarios
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.
No puede usar SetPrinter para cambiar la impresora predeterminada.
Para modificar la configuración actual de la impresora, llame a la función GetPrinter para recuperar la configuración actual en una estructura de PRINTER_INFO_2 , modifique los miembros de esa estructura según sea necesario y, a continuación, llame a SetPrinter.
La función SetPrinter omite los miembros pServerName, AveragePPM, Status y cJobs de una estructura de PRINTER_INFO_2 .
Pausar una impresora suspende la programación de todos los trabajos de impresión para esa impresora, excepto el trabajo de impresión que puede estar imprimiendo actualmente. Los trabajos de impresión se pueden enviar a una impresora en pausa, pero no se programarán trabajos para imprimir en esa impresora hasta que se reanude la impresión. Si se borra una impresora, se eliminan todos los trabajos de impresión de esa impresora, excepto el trabajo de impresión actual.
Si usa SetPrinter para modificar la estructura DEVMODE predeterminada para una impresora (estableciendo globalmente los valores predeterminados de la impresora), primero debe llamar a la función DocumentProperties para validar la estructura DEVMODE .
Para las estructuras de PRINTER_INFO_2 y PRINTER_INFO_3 que contienen un puntero a un descriptor de seguridad, la función solo puede establecer los componentes del descriptor de seguridad que el autor de la llamada tiene permiso para modificar. Para establecer determinados componentes del descriptor de seguridad, debe especificar los derechos de acceso necesarios al llamar a la función OpenPrinter o OpenPrinter2 para recuperar un identificador de la impresora. En la tabla siguiente se muestran los derechos de acceso necesarios para modificar los distintos componentes del descriptor de seguridad.
| Permiso de acceso | Componente descriptor de seguridad |
|---|---|
| WRITE_OWNER | Propietario Grupo primario |
| WRITE_DAC | Lista de control de acceso discrecional (DACL) |
| ACCESS_SYSTEM_SECURITY | Lista de control de acceso del sistema (SACL) |
Si el descriptor de seguridad contiene un componente que el autor de la llamada no tiene el derecho de acceso para modificar, Se produce un error en SetPrinter . Esos componentes de un descriptor de seguridad que no desea modificar deben ser NULL o no estar presentes, según corresponda. Si no desea modificar el descriptor de seguridad y llama a SetPrinter con una estructura de PRINTER_INFO_2 , establezca el miembro pSecurityDescriptor de esa estructura en NULL.
El Firewall de conexión a Internet (ICF) bloquea los puertos de impresora de forma predeterminada, pero se puede habilitar una excepción para el uso compartido de archivos e impresión. Si un administrador de la máquina llama a SetPrinter , habilita la excepción. Si lo llama un no administrador y la excepción aún no se ha habilitado, se produce un error en la llamada.
Puede usar el nivel 7 con la estructura PRINTER_INFO_7 para publicar, cancelar la publicación o actualizar los datos del servicio de directorio para la impresora. Los datos del servicio de directorio de una impresora incluyen todos los datos almacenados en las claves SPLDS_* mediante llamadas a la función SetPrinterDataEx de la impresora. Antes de llamar a SetPrinter, establezca el miembro pszObjectGUID de PRINTER_INFO_7 en NULL y establezca el miembro dwAction en uno de los valores siguientes.
| Valor | Descripción |
|---|---|
|
DSPRINT_PUBLISH |
Publica los datos del servicio de directorio. |
|
DSPRINT_REPUBLISH |
Los datos del servicio de directorio de la impresora no se publican y, a continuación, se publican de nuevo, actualizando todas las propiedades de la impresora publicada. La nueva publicación también cambia el GUID de la impresora publicada. Use este valor si sospecha que los datos publicados de la impresora están dañados. |
|
DSPRINT_UNPUBLISH |
Anula la publicación de los datos del servicio de directorio. |
|
DSPRINT_UPDATE |
Novedades los datos del servicio de directorio. Esto es lo mismo que DSPRINT_PUBLISH, salvo que SetPrinter produce un error ERROR_FILE_NOT_FOUND si la impresora aún no está publicada. Use DSPRINT_UPDATE para actualizar las propiedades publicadas, pero no forzar la publicación. Los controladores de impresora siempre deben usar DSPRINT_UPDATE en lugar de DSPRINT_PUBLISH. |
DSPRINT_PENDING no es un valor dwAction válido para SetPrinter.
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 |
SetPrinterW (Unicode) y SetPrinterA (ANSI) |