Función SetPrinterDataEx

La función SetPrinterDataEx establece los datos de configuración de una impresora o servidor de impresión. La función almacena los datos de configuración en la clave del Registro de la impresora.

Sintaxis

DWORD SetPrinterDataEx(
  _In_ HANDLE  hPrinter,
  _In_ LPCTSTR pKeyName,
  _In_ LPCTSTR pValueName,
  _In_ DWORD   Type,
  _In_ LPBYTE  pData,
  _In_ DWORD   cbData
);

Parámetros

hPrinter [in]

Identificador de la impresora o servidor de impresión para el que la función establece los datos de configuración. Use la función OpenPrinter, OpenPrinter2 o AddPrinter para recuperar un identificador de impresora.

pKeyName [in]

Puntero a una cadena terminada en null que especifica la clave que contiene el valor que se va a establecer. Si la clave o subclave especificadas no existen, la función las crea.

Para almacenar los datos de configuración que se pueden publicar en el servicio de directorio (DS), especifique una de las siguientes claves del Registro predefinidas.

Value	Significado
SPLDS_DRIVER_KEY	Los controladores de impresora usan esta clave para almacenar las propiedades del controlador.
SPLDS_SPOOLER_KEY	Reservado. Solo se usa en el administrador de trabajos de impresión para almacenar las propiedades internas del administrador de colas.
SPLDS_USER_KEY	Las aplicaciones usan esta clave para almacenar propiedades de impresora, como números de recursos de impresora.

Los valores almacenados en la clave SPLDS_USER_KEY se publican en el servicio de directorio solo si hay una propiedad correspondiente en el esquema. Un administrador de dominio debe crear la propiedad si aún no existe. Para publicar una propiedad definida por el usuario después de usar SetPrinterDataEx para agregar o cambiar un valor, llame a SetPrinter con Level = 7 y con el miembro dwAction de PRINTER_INFO_7 establecido en DSPRINT_UPDATE.

Puede especificar otras claves para almacenar datos de configuración que no son DS. Use el carácter de barra diagonal inversa ( \ ) como delimitador para especificar una ruta de acceso que tenga una o varias subclaves.

Si hPrinter es un identificador de una impresora y pKeyName es NULL o una cadena vacía, SetPrinterDataEx devuelve ERROR_INVALID_PARAMETER.

Si hPrinter es un identificador de un servidor de impresión, se omite pKeyName .

No use SPLDS_SPOOLER_KEY. Para cambiar las propiedades de la impresora de cola, use SetPrinter con Level = 2.

pValueName [in]

Puntero a una cadena terminada en null que identifica los datos que se van a establecer.

Para las impresoras, esta cadena especifica el nombre de un valor en la clave pKeyName .

En el caso de los servidores de impresión, esta cadena es una de las cadenas predefinidas enumeradas en la sección Comentarios siguiente.

Tipo [in]

Código que indica el tipo de datos al que apunta el parámetro pData . Para obtener una lista de los posibles códigos de tipo, vea Tipos de valor del Registro.

Si pKeyName especifica una de las claves de servicio de directorio predefinidas, Type debe ser REG_SZ, REG_MULTI_SZ, REG_DWORD o REG_BINARY. Si se usa REG_BINARY , cbData debe ser igual a 1 y el servicio de directorio trata los datos como un valor booleano.

pData [in]

Puntero a un búfer que contiene los datos de configuración de la impresora.

cbData [in]

Tamaño, en bytes, de la matriz.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es ERROR_SUCCESS.

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

Comentarios

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.

Para recuperar los datos de configuración existentes para una impresora o una cola de impresión, llame a la función GetPrinterDataEx .

Llamar a SetPrinterDataEx con el parámetro pKeyName establecido en "PrinterDriverData" equivale a llamar a la función SetPrinterData .

Si hPrinter es un identificador de un servidor de impresión, pValueName puede especificar uno de los siguientes valores predefinidos.

Value	Comentarios
SPLREG_ALLOW_USER_MANAGEFORMS	Windows XP con Service Pack 2 (SP2) y versiones posteriores Windows Server 2003 con Service Pack 1 (SP1) y versiones posteriores
SPLREG_BEEP_ENABLED
SPLREG_DEFAULT_SPOOL_DIRECTORY
SPLREG_EVENT_LOG
SPLREG_NET_POPUP	No se admite en Windows Server 2003 y versiones posteriores
SPLREG_PORT_THREAD_PRIORITY_DEFAULT
SPLREG_PORT_THREAD_PRIORITY
SPLREG_PRINT_DRIVER_ISOLATION_GROUPS	Windows 7 y versiones posteriores
SPLREG_PRINT_DRIVER_ISOLATION_TIME_BEFORE_RECYCLE	Windows 7 y versiones posteriores
SPLREG_PRINT_DRIVER_ISOLATION_MAX_OBJECTS_BEFORE_RECYCLE	Windows 7 y versiones posteriores
SPLREG_PRINT_DRIVER_ISOLATION_IDLE_TIMEOUT	Windows 7 y versiones posteriores
SPLREG_PRINT_DRIVER_ISOLATION_EXECUTION_POLICY	Windows 7 y versiones posteriores
SPLREG_PRINT_DRIVER_ISOLATION_OVERRIDE_POLICY	Windows 7 y versiones posteriores
SPLREG_RETRY_POPUP	Si el resultado es correcto, pData contiene 1 si el servidor está configurado para reintentar ventanas emergentes para todos los trabajos o 0 si el servidor no vuelve a intentar ventanas emergentes para todos los trabajos. No se admite en Windows Server 2003 y versiones posteriores
SPLREG_SCHEDULER_THREAD_PRIORITY
SPLREG_SCHEDULER_THREAD_PRIORITY_DEFAULT
SPLREG_WEBSHAREMGMT	Windows Server 2003 y versiones posteriores

Al pasar uno de los siguientes valores predefinidos como pValueName , se establece el comportamiento de impresión del grupo cuando se produce un error.

Value	Comentarios
SPLREG_RESTART_JOB_ON_POOL_ERROR	El valor de pData indica el tiempo, en segundos, cuando se reinicia un trabajo en otro puerto después de producirse un error. Esta configuración se usa con SPLREG_RESTART_JOB_ON_POOL_ENABLED.
SPLREG_RESTART_JOB_ON_POOL_ENABLED	Un valor distinto de cero en pData indica que SPLREG_RESTART_JOB_ON_POOL_ERROR está habilitado.

El tiempo especificado en SPLREG_RESTART_JOB_ON_POOL_ERROR es un tiempo mínimo. El tiempo real puede ser mayor, dependiendo de la siguiente configuración del monitor de puerto, que son valores del Registro en esta clave del Registro:

HKLM\SYSTEM\CurrentControlSet\Control\Print\Monitors\<MonitorName>\Ports

Llame a la función RegSetValueEx para establecer estos valores.

Configuración del monitor de puerto	Tipo de datos	Significado
StatusUpdateEnabled	REG_DWORD	Si un valor distinto de cero, permite que el monitor de puertos actualice el administrador de colas con el estado del puerto.
StatusUpdateInterval	REG_DWORD	Especifica el intervalo, en minutos, cuando el monitor de puertos actualiza el administrador de cola con el estado del puerto.

Para asegurarse de que el administrador de colas redirige los trabajos a la siguiente impresora disponible en el grupo (cuando el trabajo de impresión no se imprime en el tiempo establecido), el monitor de puertos debe admitir SNMP y los puertos de red del grupo deben configurarse como "estado SNMP habilitado". El monitor de puerto que admite SNMP es el monitor de puerto TCP/IP estándar.

En Windows 7 y versiones posteriores de Windows, los trabajos de impresión que se envían a un servidor de impresión se representan en el cliente de forma predeterminada. La representación del lado cliente de los trabajos de impresión se puede configurar estableciendo pKeyName en "PrinterDriverData" y pValueName en el valor de configuración de la tabla siguiente.

Configuración	Tipo de datos	Descripción
EMFDespoolingSetting	REG_DWORD	Un valor de 0, o si este valor no está presente en el registro, habilita la representación predeterminada del lado cliente de los trabajos de impresión. Un valor de 1 deshabilita la representación del lado cliente de los trabajos de impresión.
ForceClientSideRendering	REG_DWORD	Un valor de 0, o si este valor no está presente en el Registro, hará que los trabajos de impresión se represente en el cliente. Si no se puede representar un trabajo de impresión en el cliente, se representará en el servidor. Si no se puede representar un trabajo de impresión en el servidor, se producirá un error. Un valor de 1 representará los trabajos de impresión en el cliente. Si no se puede representar un trabajo de impresión en el cliente, se producirá un error.

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	SetPrinterDataExW (Unicode) y SetPrinterDataExA (ANSI)

Consulte también

Impresión

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

GetPrinterDataEx

OpenPrinter

SetPrinter

PRINTER_INFO_7