Funzione SetPrinterDataEx

Articolo
06/13/2023

La funzione SetPrinterDataEx imposta i dati di configurazione per una stampante o un server di stampa. La funzione archivia i dati di configurazione sotto la chiave del Registro di sistema della stampante.

Sintassi

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

Parametri

hPrinter [in]

Handle per la stampante o il server di stampa per cui la funzione imposta i dati di configurazione. Usare la funzione OpenPrinter, OpenPrinter2 o AddPrinter per recuperare un handle di stampante.

pKeyName [in]

Puntatore a una stringa con terminazione null che specifica la chiave contenente il valore da impostare. Se la chiave o le sottochiavi specificate non esistono, la funzione li crea.

Per archiviare i dati di configurazione che possono essere pubblicati nel servizio directory (DS), specificare una delle chiavi predefinite del Registro di sistema seguenti.

Valore	Significato
SPLDS_DRIVER_KEY	I driver della stampante usano questa chiave per archiviare le proprietà del driver.
SPLDS_SPOOLER_KEY	Riservato. Usato solo dallo spooler di stampa per archiviare le proprietà del spooler interno.
SPLDS_USER_KEY	Le applicazioni usano questa chiave per archiviare le proprietà della stampante, ad esempio i numeri di asset della stampante.

I valori archiviati nella chiave SPLDS_USER_KEY vengono pubblicati nel servizio directory solo se nello schema è presente una proprietà corrispondente. Un amministratore di dominio deve creare la proprietà se non esiste già. Per pubblicare una proprietà definita dall'utente dopo aver usato SetPrinterDataEx per aggiungere o modificare un valore, chiamare SetPrinter con Level = 7 e con il membro dwAction di PRINTER_INFO_7 impostato su DSPRINT_UPDATE.

È possibile specificare altre chiavi per archiviare dati di configurazione non DS. Usare il carattere della barra rovesciata ( \ ) come delimitatore per specificare un percorso con una o più sottochiave.

Se hPrinter è un handle per una stampante e pKeyName è NULL o una stringa vuota, SetPrinterDataEx restituisce ERROR_INVALID_PARAMETER.

Se hPrinter è un handle a un server di stampa, pKeyName viene ignorato.

Non usare SPLDS_SPOOLER_KEY. Per modificare le proprietà della stampante spooler, usare SetPrinter con Level = 2.

pValueName [in]

Puntatore a una stringa con terminazione null che identifica i dati da impostare.

Per le stampanti, questa stringa specifica il nome di un valore nella chiave pKeyName .

Per i server di stampa, questa stringa è una delle stringhe predefinite elencate nella sezione Osservazioni seguenti.

Tipo [in]

Codice che indica il tipo di dati a cui fa riferimento il parametro pData . Per un elenco dei codici di tipo possibili, vedere Tipi di valore del Registro di sistema.

Se pKeyName specifica una delle chiavi del servizio directory predefinite, il tipo deve essere REG_SZ, REG_MULTI_SZ, REG_DWORD o REG_BINARY. Se viene usato REG_BINARY , cbData deve essere uguale a 1 e il servizio directory considera i dati come valore booleano.

pData [in]

Puntatore a un buffer contenente i dati di configurazione della stampante.

cbData [in]

Dimensioni, in byte, della matrice.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è ERROR_SUCCESS.

Se la funzione ha esito negativo, il valore restituito è un valore di errore.

Commenti

Nota

Si tratta di una funzione di blocco o sincrona e potrebbe non restituire immediatamente. La velocità con cui questa funzione restituisce dipende da fattori di runtime come lo stato della rete, la configurazione del server di stampa e i fattori di implementazione del driver della stampante difficili da prevedere durante la scrittura di un'applicazione. La chiamata a questa funzione da un thread che gestisce l'interazione con l'interfaccia utente potrebbe rendere l'applicazione non rispondente.

Per recuperare i dati di configurazione esistenti per una stampante o uno spooler di stampa, chiamare la funzione GetPrinterDataEx .

La chiamata a SetPrinterDataEx con il parametro pKeyName impostata su "PrinterDriverData" equivale a chiamare la funzione SetPrinterData .

Se hPrinter è un handle a un server di stampa, pValueName può specificare uno dei valori predefiniti seguenti.

valore	Commenti
SPLREG_ALLOW_USER_MANAGEFORMS	Windows XP con Service Pack 2 (SP2) e versioni successive Windows Server 2003 con Service Pack 1 (SP1) e versioni successive
SPLREG_BEEP_ENABLED
SPLREG_DEFAULT_SPOOL_DIRECTORY
SPLREG_EVENT_LOG
SPLREG_NET_POPUP	Non supportato in Windows Server 2003 e versioni successive
SPLREG_PORT_THREAD_PRIORITY_DEFAULT
SPLREG_PORT_THREAD_PRIORITY
SPLREG_PRINT_DRIVER_ISOLATION_GROUPS	Windows 7 e versioni successive
SPLREG_PRINT_DRIVER_ISOLATION_TIME_BEFORE_RECYCLE	Windows 7 e versioni successive
SPLREG_PRINT_DRIVER_ISOLATION_MAX_OBJECTS_BEFORE_RECYCLE	Windows 7 e versioni successive
SPLREG_PRINT_DRIVER_ISOLATION_IDLE_TIMEOUT	Windows 7 e versioni successive
SPLREG_PRINT_DRIVER_ISOLATION_EXECUTION_POLICY	Windows 7 e versioni successive
SPLREG_PRINT_DRIVER_ISOLATION_OVERRIDE_POLICY	Windows 7 e versioni successive
SPLREG_RETRY_POPUP	Al termine della restituzione, pData contiene 1 se il server è impostato per riprovare a visualizzare le finestre popup per tutti i processi o 0 se il server non riprova le finestre popup per tutti i processi. Non supportato in Windows Server 2003 e versioni successive
SPLREG_SCHEDULER_THREAD_PRIORITY
SPLREG_SCHEDULER_THREAD_PRIORITY_DEFAULT
SPLREG_WEBSHAREMGMT	Windows Server 2003 e versioni successive

Passando uno dei valori predefiniti seguenti come pValueName imposta il comportamento di stampa del pool quando si verifica un errore.

valore	Commenti
SPLREG_RESTART_JOB_ON_POOL_ERROR	Il valore di pData indica l'ora, in secondi, quando un processo viene riavviato in un'altra porta dopo un errore. Questa impostazione viene usata con SPLREG_RESTART_JOB_ON_POOL_ENABLED.
SPLREG_RESTART_JOB_ON_POOL_ENABLED	Un valore diverso da zero in pData indica che SPLREG_RESTART_JOB_ON_POOL_ERROR è abilitato.

L'ora specificata in SPLREG_RESTART_JOB_ON_POOL_ERROR è un tempo minimo. Il tempo effettivo può essere più lungo, a seconda delle impostazioni di monitoraggio delle porte seguenti, che sono valori del Registro di sistema in questa chiave del Registro di sistema:

HKLM\SYSTEM\CurrentControlSet\Control\Print\Monitor<\MonitorName>\Porte

Chiamare la funzione RegSetValueEx per impostare questi valori.

Impostazione di Monitoraggio porte	Tipo di dati	Significato
StatusUpdateEnabled	REG_DWORD	Se un valore diverso da zero, consente al monitoraggio della porta di aggiornare lo spooler con lo stato della porta.
StatusUpdateInterval	REG_DWORD	Specifica l'intervallo, espresso in minuti, quando il monitoraggio delle porte aggiorna lo spooler con lo stato della porta.

Per garantire che lo spooler reindirizzi i processi alla successiva stampante disponibile nel pool (quando il processo di stampa non viene stampato entro il tempo impostato), il monitoraggio delle porte deve supportare SNMP e le porte di rete nel pool devono essere configurate come "STATO SNMP abilitato". Il monitoraggio delle porte che supporta SNMP è il monitoraggio della porta TCP/IP Standard.

In Windows 7 e versioni successive di Windows i processi di stampa inviati a un server di stampa vengono visualizzati sul client per impostazione predefinita. Il rendering lato client dei processi di stampa può essere configurato impostando pKeyName su "PrinterDriverData" e pValueName sul valore di impostazione nella tabella seguente.

Impostazione	Tipo di dati	Descrizione
EMFDespoolingSetting	REG_DWORD	Il valore 0 o se questo valore non è presente nel Registro di sistema, abilita il rendering lato client predefinito dei processi di stampa. Il valore 1 disabilita il rendering lato client dei processi di stampa.
ForceClientSideRendering	REG_DWORD	Se questo valore non è presente nel Registro di sistema, il rendering dei processi di stampa verrà eseguito nel client. Se non è possibile eseguire il rendering di un processo di stampa nel client, verrà eseguito il rendering nel server. Se non è possibile eseguire il rendering di un processo di stampa nel server, l'operazione avrà esito negativo. Il valore 1 eseguirà il rendering dei processi di stampa nel client. Se non è possibile eseguire il rendering di un processo di stampa nel client, l'operazione avrà esito negativo.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Intestazione	Winspool.h (include Windows.h)
Libreria	Winspool.lib
DLL	Winspool.drv
Nomi Unicode e ANSI	SetPrinterDataExW (Unicode) e SetPrinterDataExA (ANSI)

Vedi anche

Stampa
Funzioni dell'API spooler di stampa
GetPrinterDataEx
OpenPrinter
Setprinter
PRINTER_INFO_7

Condividi tramite