Funzione OpenPrinter
La funzione OpenPrinter recupera un handle per la stampante o il server di stampa specificato o altri tipi di handle nel sottosistema di stampa.
Sintassi
BOOL OpenPrinter(
_In_ LPTSTR pPrinterName,
_Out_ LPHANDLE phPrinter,
_In_ LPPRINTER_DEFAULTS pDefault
);
Parametri
-
pPrinterName [in]
-
Puntatore a una stringa con terminazione Null che specifica il nome della stampante o del server di stampa, l'oggetto stampante, XcvMonitor o XcvPort.
Per un oggetto stampante utilizzare: PrinterName, Job xxxx. Per un XcvMonitor, usare: ServerName, XcvMonitor MonitorName. Per un XcvPort, usare: ServerName, XcvPort PortName.
Se NULL, indica il server della stampante locale.
-
phPrinter [out]
-
Puntatore a una variabile che riceve un handle (non thread-safe) per la stampante aperta o l'oggetto server di stampa.
Il parametro phPrinter può restituire un handle Xcv da usare con la funzione XcvData. Per altre informazioni su XcvData, vedere DDK.
-
pDefault [in]
-
Puntatore a una struttura PRINTER_DEFAULTS . Questo valore può essere NULL.
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.
Commenti
Non chiamare questo metodo in DllMain.
Nota
Un handle ottenuto per una stampante remota da una chiamata a OpenPrinter per una stampante remota accede alla stampante tramite una cache locale nel servizio spooler di stampa. Questa cache non è accurata in tempo reale. Per ottenere dati accurati, sostituire la chiamata OpenPrinter con OpenPrinter2 con pOptions.dwFlags impostato su PRINTER_OPTION_NO_CACHE. Si noti che solo OpenPrinter2W è funzionale. La funzione restituisce un handle di stampante che usa altre chiamate API di stampa e ignora la cache locale. Questo metodo si blocca durante l'attesa della comunicazione di rete con la stampante remota, pertanto potrebbe non essere restituito 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. La chiamata di questa funzione da un thread che gestisce l'interazione dell'interfaccia utente potrebbe rendere l'applicazione non rispondente.
Nota
Un handle ottenuto da una chiamata a OpenPrinter per una stampante remota accederà alla stampante tramite una cache locale nel servizio spooler di stampa. Questa cache è, per impostazione predefinita, non accurata in tempo reale. Se è necessario ottenere dati accurati, sostituire la chiamata OpenPrinter con OpenPrinter2 con pOptions.dwFlags impostato su PRINTER_OPTION_NO_CACHE. Si noti che solo OpenPrinter2W è funzionale. In questo modo, la funzione restituisce un handle di stampante che effettua altre chiamate API di stampa per ignorare la cache locale. Si noti che questo approccio verrà bloccato durante l'attesa della comunicazione di rete di andata e ritorno alla stampante remota, pertanto potrebbe non essere restituito immediatamente. La velocità di restituzione di questa funzione dipende da fattori di runtime, ad esempio lo stato della rete, la configurazione del server di stampa e l'implementazione del driver della stampante, fattori difficili da prevedere durante la scrittura di un'applicazione. Pertanto, la chiamata di questa funzione da un thread che gestisce l'interazione con l'interfaccia utente potrebbe rendere l'applicazione non rispondente.
L'handle a cui punta phPrinter 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.
Il parametro pDefault consente di specificare i valori del tipo di dati e della modalità dispositivo utilizzati per la stampa di documenti inviati dalla funzione StartDocPrinter . È tuttavia possibile eseguire l'override di questi valori usando la funzione SetJob dopo l'avvio di un documento.
Le impostazioni DEVMODE definite nella struttura PRINTER_DEFAULTS del parametro pDefault non vengono usate quando il valore del membro pDatatype della struttura DOC_INFO_1 passata nel parametro pDocInfo della chiamata StartDocPrinter è "RAW". Quando un documento di alto livello (ad esempio un file Adobe PDF o Microsoft Word) o altri dati della stampante (ad esempio PCL, PS o HPGL) viene inviato direttamente a una stampante con pDatatype impostato su "RAW", il documento deve descrivere completamente le impostazioni del processo di stampa in stile DEVMODE nella lingua compresa dall'hardware.
È possibile chiamare la funzione OpenPrinter per aprire un handle a un server di stampa o per determinare i diritti di accesso di un client a un server di stampa. A tale scopo, specificare il nome del server di stampa nel parametro pPrinterName , impostare i membri pDatatype e pDevMode della struttura PRINTER_DEFAULTS su NULL e impostare il membro DesiredAccess per specificare un valore della maschera di accesso al server, ad esempio SERVER_ALL_ACCESS. Al termine dell'handle, passarlo alla funzione ClosePrinter per chiuderla.
Utilizzare il membro DesiredAccess della struttura PRINTER_DEFAULTS per specificare i diritti di accesso necessari per la stampante. I diritti di accesso possono essere uno dei seguenti. Se pDefault è NULL, i diritti di accesso vengono PRINTER_ACCESS_USE.
| Valore di Accesso desiderato | Significato |
|---|---|
| PRINTER_ACCESS_ADMINISTER | Per eseguire attività amministrative, ad esempio quelle fornite da SetPrinter. |
| PRINTER_ACCESS_USE | Per eseguire operazioni di stampa di base. |
| PRINTER_ALL_ACCESS | Per eseguire tutte le attività amministrative e le operazioni di stampa di base ad eccezione di SYNCHRONIZE (vedere Diritti di accesso standard. |
| PRINTER_ACCESS_MANAGE_LIMITED | Per eseguire attività amministrative, ad esempio quelle fornite da SetPrinter e SetPrinterData. Questo valore è disponibile a partire da Windows 8.1. |
| valori di sicurezza generici, ad esempio WRITE_DAC | Per consentire diritti di accesso specifici di controllo. Vedere Diritti di accesso standard. |
Se un utente non dispone dell'autorizzazione per aprire una stampante o un server di stampa specificato con l'accesso desiderato, la chiamata OpenPrinter avrà esito negativo con un valore restituito pari a zero e GetLastError restituirà il valore ERROR_ACCESS_DENIED.
Esempio
Per un programma di esempio che usa questa funzione, vedere Procedura: Stampare usando l'API di stampa GDI.
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 |
OpenPrinterW (Unicode) e OpenPrinterA (ANSI) |