Funzione EnumPrinters

La funzione EnumPrinters enumera stampanti, server di stampa, domini o provider di stampa disponibili.

Sintassi

BOOL EnumPrinters(
  _In_  DWORD   Flags,
  _In_  LPTSTR  Name,
  _In_  DWORD   Level,
  _Out_ LPBYTE  pPrinterEnum,
  _In_  DWORD   cbBuf,
  _Out_ LPDWORD pcbNeeded,
  _Out_ LPDWORD pcReturned
);

Parametri

Flag [in]

Tipi di oggetti di stampa che la funzione deve enumerare. Questo valore può essere uno o più dei valori seguenti.

Valore	Significato
PRINTER_ENUM_LOCAL	Se il flag di PRINTER_ENUM_NAME non viene passato, la funzione ignora il parametro Name ed enumera le stampanti installate in locale. Se PRINTER_ENUM_NAME viene passato anche, la funzione enumera le stampanti locali in Nome.
PRINTER_ENUM_NAME	La funzione enumera la stampante identificata da Name. Può essere un server, un dominio o un provider di stampa. Se Name è NULL, la funzione enumera i provider di stampa disponibili.
PRINTER_ENUM_SHARED	La funzione enumera le stampanti con l'attributo condiviso. Impossibile usare in isolamento; usare un'operazione OR per combinare un altro tipo di PRINTER_ENUM.
PRINTER_ENUM_CONNECTIONS	La funzione enumera l'elenco delle stampanti a cui l'utente ha effettuato connessioni precedenti.
PRINTER_ENUM_NETWORK	La funzione enumera le stampanti di rete nel dominio del computer. Questo valore è valido solo se Level è 1.
PRINTER_ENUM_REMOTE	La funzione enumera le stampanti di rete e i server di stampa nel dominio del computer. Questo valore è valido solo se Level è 1.
PRINTER_ENUM_CATEGORY_3D	La funzione enumera solo stampanti 3D.
PRINTER_ENUM_CATEGORY_ALL	La funzione enumera tutti i dispositivi di stampa, incluse le stampanti 3D.

Se Il livello è 4, è possibile usare solo le costanti PRINTER_ENUM_CONNECTIONS e PRINTER_ENUM_LOCAL.

Nota

I dispositivi di stampa 3D non vengono enumerati per impostazione predefinita. È necessario includere sia PRINTER_ENUM_CATEGORY_3D che PRINTER_ENUM_LOCAL per enumerare solo stampanti 3D. Per includere stampanti 3D, insieme a tutte le altre stampanti locali, usare PRINTER_ENUM_CATEGORY_ALL e PRINTER_ENUM_LOCAL.

Nome [in]

Se Il livello è 1, i flag contengono PRINTER_ENUM_NAME e Name non NULL, name è un puntatore a una stringa con terminazione null che specifica il nome dell'oggetto da enumerare. Questa stringa può essere il nome di un server, un dominio o un provider di stampa.

Se il livello è 1, i flag contengono PRINTER_ENUM_NAME e Name è NULL, la funzione enumera i provider di stampa disponibili.

Se il livello è 1, i flag contengono PRINTER_ENUM_REMOTE e Name è NULL, la funzione enumera le stampanti nel dominio dell'utente.

Se Level è 2 o 5,Name è un puntatore a una stringa con terminazione null che specifica il nome di un server le cui stampanti devono essere enumerate. Se questa stringa è NULL, la funzione enumera le stampanti installate nel computer locale.

Se il livello è 4, il nome deve essere NULL. La funzione esegue sempre query sul computer locale.

Quando Name è NULL, impostare Flag su PRINTER_ENUM_LOCAL | PRINTER_ENUM_CONNECTIONS enumera le stampanti installate nel computer locale. Queste stampanti includono quelle collegate fisicamente al computer locale e alle stampanti remote a cui ha una connessione di rete.

Quando Nome non è NULL, impostare Flag su PRINTER_ENUM_LOCAL | PRINTER_ENUM_NAME enumera le stampanti locali installate nel nome del server.

Livello [in]

Tipo di strutture di dati a cui fa riferimento pPrinterEnum. I valori validi sono 1, 2, 4 e 5, che corrispondono alle strutture di dati PRINTER_INFO_1, PRINTER_INFO_2 , PRINTER_INFO_4 e PRINTER_INFO_5.

Questo valore può essere 1, 2, 4 o 5.

pPrinterEnum [out]

Puntatore a un buffer che riceve una matrice di PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_4 o strutture di PRINTER_INFO_5. Ogni struttura contiene dati che descrivono un oggetto di stampa disponibile.

Se Il livello è 1, la matrice contiene strutture PRINTER_INFO_1 . Se Level è 2, la matrice contiene PRINTER_INFO_2 strutture. Se Il livello è 4, la matrice contiene strutture PRINTER_INFO_4 . Se Level è 5, la matrice contiene PRINTER_INFO_5 strutture.

Il buffer deve essere abbastanza grande per ricevere la matrice di strutture di dati e qualsiasi stringa o altri dati a cui puntano i membri della struttura. Se il buffer è troppo piccolo, il parametro pcbNeeded restituisce le dimensioni del buffer necessarie.

cbBuf [in]

Dimensioni, in byte, del buffer a cui fa riferimento pPrinterEnum.

pcbNeeded [out]

Puntatore a un valore che riceve il numero di byte copiati se la funzione ha esito positivo o il numero di byte necessari se cbBuf è troppo piccolo.

pcReturned [out]

Puntatore a un valore che riceve il numero di PRINTER_INFO_1, PRINTER_INFO_2 , PRINTER_INFO_4o strutture PRINTER_INFO_5 restituite dalla funzione nella matrice a cui pPrinterEnum punti.

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.

Se EnumPrinters restituisce una struttura PRINTER_INFO_1 in cui è specificato PRINTER_ENUM_CONTAINER , ciò indica che esiste una gerarchia di oggetti stampante. Un'applicazione può enumerare la gerarchia chiamando di nuovo EnumPrinters, impostando Nome sul valore del membro pName della struttura PRINTER_INFO_1.

La funzione EnumPrinters non recupera le informazioni di sicurezza. Se PRINTER_INFO_2 strutture vengono restituite nella matrice a cui fa riferimento pPrinterEnum, i membri pSecurityDescriptor verranno impostati su NULL.

Per ottenere informazioni sulla stampante predefinita, chiamare GetDefaultPrinter.

La struttura PRINTER_INFO_4 offre un modo semplice ed estremamente rapido per recuperare i nomi delle stampanti installate in un computer locale, nonché le connessioni remote stabilite da un utente. Quando EnumPrinters viene chiamato con una struttura di dati PRINTER_INFO_4 , tale funzione esegue una query sul Registro di sistema per le informazioni specificate, quindi restituisce immediatamente. Ciò è diverso dal comportamento di EnumPrinters quando viene chiamato con altri livelli di PRINTER_INFO_* strutture di dati. In particolare, quando EnumPrinters viene chiamato con una struttura di dati di livello 2 (PRINTER_INFO_2), esegue una chiamata OpenPrinter in ogni connessione remota. Se una connessione remota è inattiva o il server remoto non esiste più o la stampante remota non esiste più, la funzione deve attendere il timeout di RPC e quindi non riuscire la chiamata OpenPrinter . L'operazione può richiedere un po' di tempo. Il passaggio di una struttura PRINTER_INFO_4 consente a un'applicazione di recuperare un minimo di informazioni necessarie; se si desidera ottenere informazioni più dettagliate, è possibile effettuare una chiamata successiva di EnumPrinters livello 2.

Windows Vista: I dati della stampante restituiti da EnumPrinters vengono recuperati da una cache locale quando il valore di Level è 4.

La tabella seguente mostra l'output EnumPrinters per vari valori Flags quando il parametro Level è impostato su 1.

Nella colonna Nome parametro della tabella è necessario sostituire un nome appropriato per il provider di stampa, il dominio e il computer. Ad esempio, per "Provider di stampa", è possibile usare il nome del provider di stampa di rete o il nome del provider di stampa locale. Per recuperare i nomi del provider di stampa, chiamare EnumPrinters con Nome impostato su NULL.

Requisiti

Vedi anche

Stampa

Funzioni dell'API spooler di stampa

Addprinter

DeletePrinter

GetPrinter

PRINTER_INFO_1

PRINTER_INFO_2

PRINTER_INFO_4

PRINTER_INFO_5

Setprinter