Metodo IExtractIconA::GetIconLocation (shlobj_core.h)

Ottiene la posizione e l'indice di un'icona.

Sintassi

HRESULT GetIconLocation(
        UINT uFlags,
  [out] PSTR pszIconFile,
        UINT cchMax,
  [out] int  *piIndex,
  [out] UINT *pwFlags
);

Parametri

uFlags

Tipo: UINT

Uno o più dei valori seguenti. Questo parametro può anche essere NULL.

GIL_ASYNC (0x0020)

Impostare questo flag per determinare se l'icona deve essere estratta in modo asincrono. Se l'icona può essere estratta rapidamente, questo flag viene in genere ignorato. Se l'estrazione richiederà più tempo, GetIconLocation dovrebbe restituire E_PENDING. Per ulteriori discussioni, vedere le osservazioni.

GIL_DEFAULTICON (0x0040)

Recuperare informazioni sull'icona di fallback. Le icone di fallback vengono in genere usate mentre l'icona desiderata viene estratta e aggiunta alla cache.

GIL_FORSHELL (0x0002)

L'icona viene visualizzata in una cartella shell.

GIL_FORSHORTCUT (0x0080)

L'icona indica un collegamento. Tuttavia, l'estrattore dell'icona non deve applicare la sovrapposizione del collegamento; che verrà fatto più avanti. Le icone di scelta rapida sono indipendenti dallo stato.

GIL_OPENICON (0x0001)

L'icona si trova nello stato aperto se sono disponibili sia immagini con stato aperto che con stato chiuso. Se questo flag non è specificato, l'icona si trova nello stato normale o chiuso. Questo flag viene in genere usato per gli oggetti cartella.

GIL_CHECKSHIELD (0x0200)

Restituisce in modo esplicito GIL_SHIELD o GIL_FORCENOSHIELD in pwFlags. Non bloccare se GIL_ASYNC è impostato.

[out] pszIconFile

Tipo: PTSTR

Puntatore a un buffer che riceve la posizione dell'icona. La posizione dell'icona è una stringa con terminazione null che identifica il file contenente l'icona.

cchMax

Tipo: UINT

Dimensioni del buffer, in caratteri, a cui fa riferimento pszIconFile.

[out] piIndex

Tipo: int*

Puntatore a un int che riceve l'indice dell'icona nel file a cui punta pszIconFile.

[out] pwFlags

Tipo: UINT*

Puntatore a un valore UINT che riceve zero o una combinazione dei valori seguenti.

GIL_DONTCACHE (0x0010)

I bit di immagine fisica per questa icona non vengono memorizzati nella cache dall'applicazione chiamante.

GIL_NOTFILENAME (0x0008)

Il percorso non è una coppia nome file/indice. I valori in pszIconFile e piIndex non possono essere passati a ExtractIcon o ExtractIconEx.

Quando questo flag viene omesso, il valore restituito in pszIconFile è un nome di percorso completo a un file .ico o a un file che può contenere icone. Inoltre, il valore restituito in piIndex è un indice in tale file che identifica quale delle icone da usare. Pertanto, quando viene omesso il flag GIL_NOTFILENAME, questi valori possono essere passati a ExtractIcon o ExtractIconEx.

GIL_PERCLASS (0x0004)

Tutti gli oggetti di questa classe hanno la stessa icona. Questo flag viene usato internamente dalla Shell. Le implementazioni tipiche di IExtractIcon non richiedono questo flag perché il flag implica che un gestore dell'icona non è necessario per risolvere l'icona in base a un oggetto. Il metodo consigliato per l'implementazione delle icone per classe consiste nel registrare un valore DefaultIcon per la classe.

GIL_PERINSTANCE (0x0002)

Ogni oggetto di questa classe ha la propria icona. Questo flag viene usato internamente dalla Shell per gestire i casi come Setup.exe, dove gli oggetti con nomi identici possono avere icone diverse. Le implementazioni tipiche di IExtractIcon non richiedono questo flag.

GIL_SIMULATEDOC (0x0001)

L'applicazione chiamante deve creare un'icona del documento usando l'icona specificata.

GIL_SHIELD (0x0200)

Solo Windows Vista. L'applicazione chiamante deve contrassegnare l'icona con lo schermo dell'interfaccia utente.

GIL_FORCENOSHIELD (0x0400)

Solo Windows Vista. L'applicazione chiamante non deve contrassegnare l'icona con lo schermo dell'interfaccia utente.

Valore restituito

Tipo: HRESULT

Restituisce S_OK se la funzione ha restituito una posizione valida o S_FALSE se shell deve usare un'icona predefinita. Se il flag GIL_ASYNC è impostato in uFlags, il metodo può restituire E_PENDING per indicare che l'estrazione dell'icona richiederà tempo.

Commenti

Quando un client imposta il flag di GIL_ASYNC in uFlags e riceve E_PENDING come valore restituito, in genere crea un thread di sfondo per estrarre l'icona. Chiama GetIconLocation da quel thread, senza il flag di GIL_ASYNC , per recuperare la posizione dell'icona. Chiama quindi IExtractIcon::Extract per estrarre l'icona. La restituzione di E_PENDING implica che l'oggetto è senza thread. In altre parole, può essere chiamato in modo sicuro simultaneamente da più thread.

Il flag GIL_DEFAULTICON viene in genere impostato nel caso in cui venga trovata l'icona desiderata, ma tale icona non è presente nella cache delle icone. L'estrazione dell'icona è un processo in background con priorità bassa e, ad esempio, può essere ritardato da altri processi. L'icona predefinita verrà visualizzata al posto dell'icona finale durante il tempo necessario per l'estrazione dell'icona finale, aggiunta alla cache e resa disponibile.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	shlobj_core.h
DLL	Shell32.dll (versione 4.0 o successiva)