Funzione SHGetFileInfoA (shellapi.h)

Recupera informazioni su un oggetto nel file system, ad esempio un file, una cartella, una directory o una radice dell'unità.

Sintassi

DWORD_PTR SHGetFileInfoA(
  [in]      LPCSTR      pszPath,
            DWORD       dwFileAttributes,
  [in, out] SHFILEINFOA *psfi,
            UINT        cbFileInfo,
            UINT        uFlags
);

Parametri

[in] pszPath

Tipo: LPCTSTR

Puntatore a una stringa con terminazione Null con lunghezza massima MAX_PATH contenente il percorso e il nome del file. I percorsi assoluti e relativi sono validi.

Se il parametro uFlags include il flag SHGFI_PIDL , questo parametro deve essere l'indirizzo di una struttura ITEMIDLIST (PIDL) che contiene l'elenco di identificatori di elemento che identificano in modo univoco il file all'interno dello spazio dei nomi della shell. Il PIDL deve essere un FILE PIDL completo. I PIDL relativi non sono consentiti.

Se il parametro uFlags include il flag SHGFI_USEFILEATTRIBUTES , questo parametro non deve essere un nome di file valido. La funzione procederà come se il file esista con il nome specificato e con gli attributi del file passati nel parametro dwFileAttributes . In questo modo è possibile ottenere informazioni su un tipo di file passando solo l'estensione per pszPath e passando FILE_ATTRIBUTE_NORMAL in dwFileAttributes.

Questa stringa può usare nomi brevi (formato 8.3) o file lunghi.

dwFileAttributes

Tipo: DWORD

Combinazione di uno o più flag di attributo di file (FILE_ATTRIBUTE_ valori definiti in Winnt.h). Se uFlags non include il flag SHGFI_USEFILEATTRIBUTES , questo parametro viene ignorato.

[in, out] psfi

Tipo: SHFILEINFO*

Puntatore a una struttura SHFILEINFO per ricevere le informazioni sul file.

cbFileInfo

Tipo: UINT

Dimensione, in byte, della struttura SHFILEINFO a cui punta il parametro psfi .

uFlags

Tipo: UINT

Flag che specificano le informazioni sul file da recuperare. Questo parametro può essere una combinazione dei valori seguenti.

SHGFI_ADDOVERLAYS (0x000000020)

Versione 5.0. Applicare le sovrimpressioni appropriate all'icona del file. È necessario impostare anche il flag SHGFI_ICON .

SHGFI_ATTR_SPECIFIED (0x000020000)

Modificare SHGFI_ATTRIBUTES per indicare che il membro dwAttributes della struttura SHFILEINFO in psfi contiene gli attributi specifici desiderati. Questi attributi vengono passati a IShellFolder::GetAttributesOf. Se questo flag non viene specificato, 0xFFFFFFFF viene passato a IShellFolder::GetAttributesOf, richiedendo tutti gli attributi. Questo flag non può essere specificato con il flag SHGFI_ICON .

SHGFI_ATTRIBUTES (0x000000800)

Recuperare gli attributi dell'elemento. Gli attributi vengono copiati nel membro dwAttributes della struttura specificata nel parametro psfi . Si tratta degli stessi attributi ottenuti da IShellFolder::GetAttributesOf.

SHGFI_DISPLAYNAME (0x000000200)

Recuperare il nome visualizzato per il file, ovvero il nome visualizzato in Esplora risorse. Il nome viene copiato nel membro szDisplayName della struttura specificata in psfi. Il nome visualizzato restituito utilizza il nome di file lungo, se presente, anziché il formato 8.3 del nome file. Si noti che il nome visualizzato può essere influenzato dalle impostazioni, ad esempio se vengono visualizzate le estensioni.

SHGFI_EXETYPE (0x000002000)

Recuperare il tipo di file eseguibile se pszPath identifica un file eseguibile. Le informazioni vengono compresse nel valore restituito. Questo flag non può essere specificato con altri flag.

SHGFI_ICON (0x000000100)

Recuperare l'handle sull'icona che rappresenta il file e l'indice dell'icona all'interno dell'elenco di immagini di sistema. L'handle viene copiato nel membro hIcon della struttura specificata da psfi e l'indice viene copiato nel membro iIcon .

SHGFI_ICONLOCATION (0x000001000)

Recuperare il nome del file che contiene l'icona che rappresenta il file specificato da pszPath, come restituito dal metodo IExtractIcon::GetIconLocation del gestore icone del file. Recuperare anche l'indice dell'icona all'interno di tale file. Il nome del file contenente l'icona viene copiato nel membro szDisplayName della struttura specificata da psfi. L'indice dell'icona viene copiato nel membro iIcon della struttura.

SHGFI_LARGEICON (0x000000000)

Modificare SHGFI_ICON, causando il recupero dell'icona grande del file da parte della funzione. È necessario impostare anche il flag SHGFI_ICON .

SHGFI_LINKOVERLAY (0x000008000)

Modificare SHGFI_ICON, causando l'aggiunta della sovrimpressione del collegamento all'icona del file. È necessario impostare anche il flag SHGFI_ICON .

SHGFI_OPENICON (0x000000002)

Modificare SHGFI_ICON, causando il recupero dell'icona di apertura del file da parte della funzione. Usato anche per modificare SHGFI_SYSICONINDEX, causando la restituzione dell'handle all'elenco di immagini di sistema che contiene l'icona aperta piccola del file. Un oggetto contenitore visualizza un'icona aperta per indicare che il contenitore è aperto. È necessario impostare anche il flag SHGFI_ICON e/o SHGFI_SYSICONINDEX .

SHGFI_OVERLAYINDEX (0x000000040)

Versione 5.0. Restituisce l'indice dell'icona di sovrapposizione. Il valore dell'indice di sovrimpressione viene restituito negli otto bit superiori del membro iIcon della struttura specificata da psfi. Questo flag richiede che sia impostato anche il SHGFI_ICON .

SHGFI_PIDL (0x000000008)

Indicare che pszPath è l'indirizzo di una struttura ITEMIDLIST anziché un nome di percorso.

SHGFI_SELECTED (0x000010000)

Modificare SHGFI_ICON, causando la fusione dell'icona del file con il colore di evidenziazione del sistema. È necessario impostare anche il flag SHGFI_ICON .

SHGFI_SHELLICONSIZE (0x000000004)

Modificare SHGFI_ICON, causando il recupero di un'icona di dimensioni shell. Se questo flag non viene specificato, la funzione ridimensiona l'icona in base ai valori delle metriche di sistema. È necessario impostare anche il flag SHGFI_ICON .

SHGFI_SMALLICON (0x000000001)

Modificare SHGFI_ICON, causando il recupero dell'icona piccola del file da parte della funzione. Usato anche per modificare SHGFI_SYSICONINDEX, causando la restituzione dell'handle all'elenco di immagini di sistema che contiene immagini di icone di piccole dimensioni. È necessario impostare anche il flag SHGFI_ICON e/o SHGFI_SYSICONINDEX .

SHGFI_SYSICONINDEX (0x000004000)

Recuperare l'indice di un'icona dell'elenco di immagini di sistema. In caso di esito positivo, l'indice viene copiato nel membro iIcon di psfi. Il valore restituito è un handle per l'elenco di immagini di sistema. Solo le immagini i cui indici vengono copiati correttamente in iIcon sono valide. Il tentativo di accedere ad altre immagini nell'elenco di immagini di sistema comporterà un comportamento non definito.

SHGFI_TYPENAME (0x000000400)

Recuperare la stringa che descrive il tipo del file. La stringa viene copiata nel membro szTypeName della struttura specificata in psfi.

SHGFI_USEFILEATTRIBUTES (0x000000010)

Indica che la funzione non deve tentare di accedere al file specificato da pszPath. Deve invece agire come se il file specificato da pszPath esista con gli attributi di file passati in dwFileAttributes. Questo flag non può essere combinato con i flag SHGFI_ATTRIBUTES, SHGFI_EXETYPE o SHGFI_PIDL .

Valore restituito

Tipo: DWORD_PTR

Restituisce un valore il cui significato dipende dal parametro uFlags .

Se uFlags non contiene SHGFI_EXETYPE o SHGFI_SYSICONINDEX, il valore restituito è diverso da zero se ha esito positivo o zero in caso contrario.

Se uFlags contiene il flag di SHGFI_EXETYPE , il valore restituito specifica il tipo del file eseguibile. Sarà uno dei valori seguenti.

Commenti

È consigliabile chiamare questa funzione da un thread in background. Non è possibile che l'interfaccia utente venga arrestata.

Se SHGetFileInfo restituisce un handle dell'icona nel membro hIcon della struttura SHFILEINFO a cui fa riferimento psfi, è responsabile di liberarlo con DestroyIcon quando non è più necessario.

Quando si usa il flag SHGFI_EXETYPE con un'applicazione Windows, la versione di Windows del file eseguibile viene specificata nell'HIWORD del valore restituito. Questa versione viene restituita come valore esadecimale. Per informazioni dettagliate sull'equazione di questo valore con una versione di Windows specifica, vedere Uso delle intestazioni di Windows.

Esempio

Nell'esempio di codice seguente viene usato SHGetFileInfo per recuperare il nome visualizzato del Cestino, identificato dal codice PIDL.

LPITEMIDLIST pidl = NULL;
hr = SHGetFolderLocation(NULL, CSIDL_BITBUCKET, NULL, 0, &pidl);

if (SUCCEEDED(hr))                    
{
    SHFILEINFOW sfi = {0};
    hr = SHGetFileInfo((LPCTSTR)pidl,
                        -1,
                        &sfi,
                        sizeof(sfi),
                        SHGFI_PIDL | SHGFI_DISPLAYNAME)
            
    if (SUCCEEDED(hr))
    {
        // The display name is now held in sfi.szDisplayName.
    }
}

ILFree(pidl);

Requisiti

Vedi anche

FileIconInit