Funzione AddPrinter

Articolo
06/12/2023

La funzione AddPrinter aggiunge una stampante all'elenco delle stampanti supportate per un server specificato.

Sintassi

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

Parametri

pName [in]: Puntatore a una stringa con terminazione Null che specifica il nome del server in cui deve essere installata la stampante. Se questa stringa è NULL, la stampante viene installata localmente.
Livello [in]: Versione della struttura a cui punta pPrinter . Questo valore deve essere 2.
pPrinter [in]: Puntatore a una struttura PRINTER_INFO_2 contenente informazioni sulla stampante. È necessario specificare valori non NULL per i membri pPrinterName, pPortName, pDriverName e pPrintProcessor di questa struttura prima di chiamare AddPrinter.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un handle (non thread-safe) a un nuovo oggetto stampante. Al termine dell'handle, passarlo alla funzione ClosePrinter per chiuderla.

Se la funzione ha esito negativo, il valore restituito è NULL.

Commenti

Non chiamare questo metodo in DllMain.

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.

Il chiamante deve avere SeLoadDriverPrivilege.

L'handle restituito non è thread-safe. Se i chiamanti devono usarlo contemporaneamente in più thread, devono fornire l'accesso personalizzato alla sincronizzazione all'handle della stampante usando le funzioni di sincronizzazione. Per evitare di scrivere codice personalizzato, l'applicazione può aprire un handle di stampante in ogni thread, in base alle esigenze.

Di seguito sono riportati i membri della struttura PRINTER_INFO_2 che è possibile impostare prima che venga chiamata la funzione AddPrinter :

Attributes (Attributi)
pPrintProcessor
DefaultPriority
Priorità
pComment
pSecurityDescriptor
pDatatype
pSepFile
pDevMode
pShareName
pLocation
StartTime
pParameters
UntilTime

I membri Status, cJobs e AveragePPM della struttura PRINTER_INFO_2 sono riservati per l'uso dalla funzione GetPrinter . Non devono essere impostati prima di chiamare AddPrinter.

Se pSecurityDescriptor è NULL, il sistema assegna un descrittore di sicurezza predefinito alla stampante. Il descrittore di sicurezza predefinito dispone delle autorizzazioni seguenti.

Valore	Descrizione
Amministratori e utenti esperti	Controllo completo sulla coda di stampa. Ciò significa che i membri di questi gruppi possono stampare, gestire la coda (può eliminare la coda, modificare qualsiasi impostazione della coda, incluso il descrittore di sicurezza) e gestire i processi di stampa di tutti gli utenti (eliminare, sospendere, riprendere, riavviare i processi). Si noti che Power Users non esiste prima di Windows XP Professional.
Autore/proprietario	Può gestire i propri processi. Ciò significa che l'utente che invia processi può gestire (eliminare, sospendere, riprendere, riavviare) i propri processi.
Tutti	Esecuzione e controllo di lettura standard. Ciò significa che i membri del gruppo everyone possono stampare e leggere le proprietà della coda di stampa.

Dopo che un'applicazione crea un oggetto stampante con la funzione AddPrinter , deve utilizzare la funzione PrinterProperties per specificare le impostazioni corrette per il driver della stampante associato all'oggetto stampante.

La funzione AddPrinter restituisce un errore se esiste già un oggetto stampante con lo stesso nome, a meno che tale oggetto non sia contrassegnato come eliminazione in sospeso. In tal caso, la stampante esistente non viene eliminata e i parametri di creazione di AddPrinter vengono usati per modificare le impostazioni della stampante esistenti (come se l'applicazione avesse usato la funzione SetPrinter ).

Utilizzare la funzione EnumPrintProcessors per enumerare il set di processori di stampa installati in un server. Utilizzare la funzione EnumPrintProcessorDatatypes per enumerare il set di tipi di dati supportati da un processore di stampa. Usare la funzione EnumPorts per enumerare il set di porte disponibili. Usare la funzione EnumPrinterDrivers per enumerare i driver della stampante installati.

Il chiamante della funzione AddPrinter deve avere SERVER_ACCESS_ADMINISTER accesso al server in cui deve essere creata la stampante. L'handle restituito dalla funzione avrà PRINTER_ALL_ACCESS autorizzazione e può essere usato per eseguire operazioni amministrative sulla stampante.

Se alla funzione DrvPrinterEvent viene passato il flag di PRINTER_EVENT_FLAG_NO_UI, il driver non deve usare una chiamata dell'interfaccia utente durante DrvPrinterEvent. Per eseguire processi correlati all'interfaccia utente, il programma di installazione deve usare la voce VendorSetup nel file inf della stampante o, per i dispositivi Plug and Play, il programma di installazione può usare un programma di installazione di co-installazione specifico del dispositivo. Per altre informazioni su VendorSetup, vedere Microsoft Windows Driver Development Kit (DDK).

Internet Connection Firewall (ICF) blocca le porte della stampante per impostazione predefinita, ma quando si esegue AddPrinter è abilitata un'eccezione per Condivisione file e stampa.

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	AddPrinterW (Unicode) e AddPrinterA (ANSI)

Vedi anche

Stampa
Funzioni dell'API spooler di stampa
ClosePrinter
DeletePrinter
EnumPorts
EnumPrinterDrivers
EnumPrintProcessors
EnumPrintProcessorDatatypes
GetPrinter
PRINTER_INFO_2
PrinterProperties
Setprinter