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 un nullstringa con terminazione con lunghezza massima MAX_PATH che contiene 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 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 di file brevi (formato 8.3) o 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 dwAttributes membro 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 dwAttributes membro 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 usa il nome 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 inserite 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 psfie l'indice viene copiato nel membro iIcon .

SHGFI_ICONLOCATION (0x000001000)

Recuperare il nome del file contenente 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 la funzione di recuperare l'icona grande del file. È 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. Usato anche per modificare SHGFI_SYSICONINDEX, causando la restituzione dell'handle all'elenco di immagini di sistema che contiene l'icona aperta 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 impostata anche la 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 la funzione di recuperare l'icona piccola del file. Usato anche per modificare SHGFI_SYSICONINDEX, causando la restituzione dell'handle all'elenco di immagini di sistema che contiene immagini icona 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_EXETYPEo 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 SHGFI_EXETYPE, il valore restituito specifica il tipo del file eseguibile. Sarà uno dei valori seguenti.

Osservazioni

È necessario chiamare questa funzione da un thread in background. In caso contrario, l'interfaccia utente smette di rispondere.

Se SHGetFileInfo restituisce un handle icona nel membro hIcon della struttura SHFILEINFO a cui punta psfi, si è responsabili di liberarlo con DestroyIcon quando non è più necessario.

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

Esempi

L'esempio di codice seguente usa SHGetFileInfo per recuperare il nome visualizzato del Cestino, identificato dal relativo 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);

Fabbisogno

Vedere anche

FileIconInit