Funzione SetPrinter
La funzione SetPrinter imposta i dati per una stampante specificata o imposta lo stato della stampante specificata sospendo la stampa, riprendendo la stampa o cancellando tutti i processi di stampa.
Sintassi
BOOL SetPrinter(
_In_ HANDLE hPrinter,
_In_ DWORD Level,
_In_ LPBYTE pPrinter,
_In_ DWORD Command
);
Parametri
-
hPrinter [in]
-
Handle per la stampante. Utilizzare la funzione OpenPrinter, OpenPrinter2 o AddPrinter per recuperare un handle di stampante.
-
Livello [in]
-
Tipo di dati archiviati dalla funzione nel buffer a cui punta pPrinter. Se il parametro Command non è uguale a zero, il parametro Level deve essere zero.
Questo valore può essere 0, 2, 3, 4, 5, 6, 7, 8 o 9.
-
pPrinter [in]
-
Puntatore a un buffer contenente i dati da impostare per la stampante o contenente informazioni per il comando specificato dal parametro Command . Il tipo di dati nel buffer è determinato dal valore di Level.
Level Struttura - 0
Se il parametro Command è PRINTER_CONTROL_SET_STATUS, pPrinter deve contenere un valore DWORD che specifica lo stato della nuova stampante da impostare. Per un elenco dei valori di stato possibili, vedere il membro Status della struttura PRINTER_INFO_2 . Si noti che PRINTER_STATUS_PAUSED e PRINTER_STATUS_PENDING_DELETION non sono valori di stato validi da impostare.
Se Level è 0, ma il parametro Command non è PRINTER_CONTROL_SET_STATUS, pPrinter deve essere NULL.- 2
Struttura PRINTER_INFO_2 contenente informazioni dettagliate sulla stampante. - 3
Struttura PRINTER_INFO_3 contenente le informazioni di sicurezza della stampante. - 4
Struttura PRINTER_INFO_4 contenente informazioni minime sulla stampante, tra cui il nome della stampante, il nome del server e se la stampante è remota o locale. - 5
Struttura PRINTER_INFO_5 contenente informazioni sulla stampante, ad esempio attributi della stampante e impostazioni di timeout. - 6
Struttura PRINTER_INFO_6 che specifica il valore di stato di una stampante. - 7
Struttura PRINTER_INFO_7 . Il membro dwAction di questa struttura indica se SetPrinter deve pubblicare, annullare la pubblicazione, ripubblicare o aggiornare i dati della stampante nel servizio directory. - 8
Struttura PRINTER_INFO_8 che specifica le impostazioni predefinite globali della stampante. - 9
Struttura PRINTER_INFO_9 che specifica le impostazioni predefinite della stampante per utente. -
Comando [in]
-
l'azione da eseguire.
Se il parametro Level è diverso da zero, impostare il valore di questo parametro su zero. In questo caso, la stampante mantiene lo stato corrente e la funzione riconfigura i dati della stampante come specificato dai parametri Level e pPrinter .
Se il parametro Level è zero, impostare il valore di questo parametro su uno dei valori seguenti.
Valore Significato - PRINTER_CONTROL_PAUSE
Sospendi la stampante. - PRINTER_CONTROL_PURGE
Eliminare tutti i processi di stampa nella stampante. - PRINTER_CONTROL_RESUME
Riprendere una stampante sospesa. - PRINTER_CONTROL_SET_STATUS
Impostare lo stato della stampante.
Impostare il parametro pPrinter su un puntatore a un valore DWORD che specifica lo stato della nuova stampante.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è un valore diverso da zero.
Se la funzione ha esito negativo, il valore restituito è zero.
Se Level è 7 e l'azione di pubblicazione non è riuscita, SetPrinter restituisce ERROR_IO_PENDING e tenta di completare l'azione in background. Se Level è 7 e l'azione di aggiornamento non è riuscita, SetPrinter restituisce ERROR_FILE_NOT_FOUND.
Commenti
Nota
Si tratta di una funzione di blocco o sincrona e potrebbe non restituire immediatamente. La velocità di restituzione di questa funzione 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. Chiamando questa funzione da un thread che gestisce l'interazione con l'interfaccia utente, l'applicazione potrebbe sembrare non rispondente.
Non è possibile utilizzare SetPrinter per modificare la stampante predefinita.
Per modificare le impostazioni correnti della stampante, chiamare la funzione GetPrinter per recuperare le impostazioni correnti in una struttura PRINTER_INFO_2 , modificare i membri di tale struttura in base alle esigenze e quindi chiamare SetPrinter.
La funzione SetPrinter ignora i membri pServerName, AveragePPM, Status e cJobs di una struttura PRINTER_INFO_2 .
La sospensione di una stampante sospende la pianificazione di tutti i processi di stampa per tale stampante, ad eccezione del processo di stampa attualmente in corso di stampa. I processi di stampa possono essere inviati a una stampante sospesa, ma non verranno pianificati processi per la stampa su tale stampante fino alla ripresa della stampa. Se una stampante è deselezionata, tutti i processi di stampa per tale stampante vengono eliminati, ad eccezione del processo di stampa corrente.
Se si usa SetPrinter per modificare la struttura DEVMODE predefinita per una stampante (impostando globalmente le impostazioni predefinite della stampante), è prima necessario chiamare la funzione DocumentProperties per convalidare la struttura DEVMODE .
Per le strutture PRINTER_INFO_2 e PRINTER_INFO_3 che contengono un puntatore a un descrittore di sicurezza, la funzione può impostare solo i componenti del descrittore di sicurezza che il chiamante dispone dell'autorizzazione per la modifica. Per impostare componenti specifici del descrittore di sicurezza, è necessario specificare i diritti di accesso necessari quando si chiama la funzione OpenPrinter o OpenPrinter2 per recuperare un handle alla stampante. La tabella seguente illustra i diritti di accesso necessari per modificare i vari componenti del descrittore di sicurezza.
| Autorizzazione di accesso | Componente descrittore di sicurezza |
|---|---|
| WRITE_OWNER | Proprietario Gruppo primario |
| WRITE_DAC | Elenco di controllo di accesso discrezionale (DACL) |
| ACCESS_SYSTEM_SECURITY | Elenco di controllo di accesso di sistema (SACL) |
Se il descrittore di sicurezza contiene un componente che il chiamante non ha il diritto di accesso per la modifica, SetPrinter ha esito negativo. I componenti di un descrittore di sicurezza che non si desidera modificare devono essere NULL o non essere presenti, in base alle esigenze. Se non si vuole modificare il descrittore di sicurezza e si chiama SetPrinter con una struttura PRINTER_INFO_2 , impostare il membro pSecurityDescriptor di tale struttura su NULL.
Internet Connection Firewall (ICF) blocca le porte della stampante per impostazione predefinita, ma è possibile abilitare un'eccezione per Condivisione file e stampa. Se SetPrinter viene chiamato da un amministratore del computer, abilita l'eccezione. Se viene chiamato da un non amministratore e l'eccezione non è già stata abilitata, la chiamata ha esito negativo.
È possibile usare il livello 7 con la struttura PRINTER_INFO_7 per pubblicare, annullare la pubblicazione o aggiornare i dati del servizio directory per la stampante. I dati del servizio directory per una stampante includono tutti i dati archiviati nelle chiavi SPLDS_* chiamando la funzione SetPrinterDataEx per la stampante. Prima di chiamare SetPrinter, impostare il membro pszObjectGUID di PRINTER_INFO_7 su NULL e impostare il membro dwAction su uno dei valori seguenti.
| Valore | Descrizione |
|---|---|
|
DSPRINT_PUBLISH |
Pubblica i dati del servizio directory. |
|
DSPRINT_REPUBLISH |
I dati del servizio directory per la stampante non vengono pubblicati e quindi pubblicati nuovamente, aggiornando tutte le proprietà nella stampante pubblicata. La ripubblicazione modifica anche il GUID della stampante pubblicata. Usare questo valore se si sospetta che i dati pubblicati della stampante siano stati danneggiati. |
|
DSPRINT_UNPUBLISH |
Annulla la pubblicazione dei dati del servizio directory. |
|
DSPRINT_UPDATE |
Aggiornamenti i dati del servizio directory. Si tratta dello stesso DSPRINT_PUBLISH, ad eccezione del fatto che SetPrinter ha esito negativo con ERROR_FILE_NOT_FOUND se la stampante non è già pubblicata. Usare DSPRINT_UPDATE per aggiornare le proprietà pubblicate, ma non forzare la pubblicazione. I driver della stampante devono sempre usare DSPRINT_UPDATE anziché DSPRINT_PUBLISH. |
DSPRINT_PENDING non è un valore dwAction valido per SetPrinter.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato |
Windows 2000 Professional [solo app desktop] |
| Server minimo supportato |
Windows 2000 Server [solo app desktop] |
| Intestazione |
|
| Libreria |
|
| DLL |
|
| Nomi Unicode e ANSI |
SetPrinterW (Unicode) e SetPrinterA (ANSI) |