Metodo IExtractIconW::GetIconLocation (shlobj_core.h)

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

Sintassi

HRESULT GetIconLocation(
        UINT  uFlags,
  [out] PWSTR 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 restituirà E_PENDING. Per ulteriori informazioni, 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 di icone non deve applicare la sovrimpressione del collegamento; che verrà fatto in un secondo momento. Le icone dei tasti di scelta rapida sono indipendenti dallo stato.

GIL_OPENICON (0x0001)

L'icona è in stato aperto se sono disponibili sia immagini con stato aperto che con stato chiuso. Se questo flag non viene 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 è impostato GIL_ASYNC.

[out] pszIconFile

Tipo: PTSTR

Puntatore a un buffer che riceve la posizione dell'icona. Il percorso dell'icona è una stringa con terminazione Null che identifica il file che contiene l'icona.

cchMax

Tipo: UINT

Dimensioni del buffer, in caratteri, a cui punta 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 dell'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 per un file .ico o in un file che può contenere icone. Inoltre, il valore restituito in piIndex è un indice in tale file che identifica quale delle relative icone usare. Pertanto, quando il flag GIL_NOTFILENAME viene omesso, 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 di icone non è necessario per risolvere l'icona in base a ogni oggetto. Il metodo consigliato per l'implementazione delle icone per classe consiste nel registrare defaultIcon per la classe .

GIL_PERINSTANCE (0x0002)

Ogni oggetto di questa classe ha una propria icona. Questo flag viene usato internamente dalla shell per gestire casi come Setup.exe, in cui 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 scudo UAC.

GIL_FORCENOSHIELD (0x0400)

Solo Windows Vista. L'applicazione chiamante non deve contrassegnare l'icona con lo scudo UAC.

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à molto tempo.

Commenti

Quando un client imposta il flag 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 tale thread, senza il flag 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 è a thread libero. In altre parole, può essere chiamato in modo sicuro contemporaneamente 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 di icone è un processo in background con priorità bassa e, di conseguenza, può essere ritardato da altri processi. L'icona predefinita verrà visualizzata al posto dell'icona finale durante il tempo necessario per estrarre l'icona finale, aggiungerla alla cache e renderla disponibile.

Requisiti