SHGetFileInfoW, fonction (shellapi.h)

Article
11/20/2024

Récupère des informations sur un objet dans le système de fichiers, comme un fichier, un dossier, un répertoire ou une racine de lecteur.

Syntaxe

DWORD_PTR SHGetFileInfoW(
  [in]      LPCWSTR     pszPath,
            DWORD       dwFileAttributes,
  [in, out] SHFILEINFOW *psfi,
            UINT        cbFileInfo,
            UINT        uFlags
);

Paramètres

[in] pszPath

Type : LPCTSTR

Pointeur vers une chaîne null-terminated de longueur maximale MAX_PATH qui contient le chemin d’accès et le nom de fichier. Les chemins absolus et relatifs sont valides.

Si le paramètre uFlags inclut l’indicateur SHGFI_PIDL, ce paramètre doit être l’adresse d’une structure ITEMIDLIST (PIDL) qui contient la liste des identificateurs d’élément qui identifie de manière unique le fichier dans l’espace de noms de l’interpréteur de commandes. Le code PIDL doit être un PIDL complet. Les PIDL relatifs ne sont pas autorisés.

Si le paramètre uFlags inclut l’indicateur SHGFI_USEFILEATTRIBUTES, ce paramètre ne doit pas être un nom de fichier valide. La fonction se poursuit comme si le fichier existe avec le nom spécifié et avec les attributs de fichier transmis dans la dwFileAttributes paramètre. Cela vous permet d’obtenir des informations sur un type de fichier en transmettant uniquement l’extension pour pszPath et en passant FILE_ATTRIBUTE_NORMAL dans dwFileAttributes.

Cette chaîne peut utiliser des noms de fichiers courts (formulaire 8.3) ou longs.

dwFileAttributes

Type : DWORD

Combinaison d’un ou plusieurs indicateurs d’attribut de fichier (FILE_ATTRIBUTE_ valeurs définies dans Winnt.h). Si uFlags n’inclut pas l’indicateur de SHGFI_USEFILEATTRIBUTES, ce paramètre est ignoré.

[in, out] psfi

Type : SHFILEINFO*

Pointeur vers une structure SHFILEINFO pour recevoir les informations du fichier.

cbFileInfo

Type : uiNT

Taille, en octets, de la structure SHFILEINFO pointée par le paramètre psfi .

uFlags

Type : uiNT

Indicateurs qui spécifient les informations de fichier à récupérer. Ce paramètre peut être une combinaison des valeurs suivantes.

SHGFI_ADDOVERLAYS (0x000000020)

version 5.0. Appliquez les superpositions appropriées à l’icône du fichier. L’indicateur SHGFI_ICON doit également être défini.

SHGFI_ATTR_SPECIFIED (0x000020000)

Modifiez SHGFI_ATTRIBUTES pour indiquer que le membre dwAttributes de la structure SHFILEINFO à psfi contient les attributs spécifiques souhaités. Ces attributs sont passés à IShellFolder ::GetAttributesOf. Si cet indicateur n’est pas spécifié, 0xFFFFFFFF est transmis à IShellFolder ::GetAttributesOf, demandant tous les attributs. Cet indicateur ne peut pas être spécifié avec l’indicateur SHGFI_ICON.

SHGFI_ATTRIBUTES (0x000000800)

Récupérez les attributs d’élément. Les attributs sont copiés dans le dwAttributes membre de la structure spécifiée dans le paramètre psfi. Il s’agit des mêmes attributs obtenus à partir de IShellFolder ::GetAttributesOf.

SHGFI_DISPLAYNAME (0x000000200)

Récupérez le nom complet du fichier, qui est le nom tel qu’il apparaît dans l’Explorateur Windows. Le nom est copié dans le szDisplayName membre de la structure spécifiée dans psfi. Le nom complet retourné utilise le nom de fichier long, s’il en existe un, plutôt que le formulaire 8.3 du nom de fichier. Notez que le nom complet peut être affecté par des paramètres tels que l’affichage des extensions.

SHGFI_EXETYPE (0x000002000)

Récupérez le type du fichier exécutable si pszPath identifie un fichier exécutable. Les informations sont empaquetées dans la valeur de retour. Cet indicateur ne peut pas être spécifié avec d’autres indicateurs.

SHGFI_ICON (0x000000100)

Récupérez le handle dans l’icône qui représente le fichier et l’index de l’icône dans la liste d’images système. Le handle est copié dans le membre hIcon de la structure spécifiée par psfi, et l’index est copié dans le membre iIcon.

SHGFI_ICONLOCATION (0x000001000)

Récupérez le nom du fichier qui contient l’icône représentant le fichier spécifié par pszPath, comme retourné par la méthode IExtractIcon ::GetIconLocation méthode du gestionnaire d’icônes du fichier. Récupérez également l’index d’icône dans ce fichier. Le nom du fichier contenant l’icône est copié dans le membre szDisplayName de la structure spécifiée par psfi. L’index de l’icône est copié dans le membre iIcon de cette structure.

SHGFI_LARGEICON (0x000000000)

Modifiez SHGFI_ICON, ce qui entraîne la récupération de l’icône volumineuse du fichier. L’indicateur SHGFI_ICON doit également être défini.

SHGFI_LINKOVERLAY (0x000008000)

Modifiez SHGFI_ICON, ce qui entraîne l’ajout de la superposition de liens à l’icône du fichier. L’indicateur SHGFI_ICON doit également être défini.

SHGFI_OPENICON (0x000000002)

Modifiez SHGFI_ICON, ce qui entraîne la récupération de l’icône ouverte du fichier. Également utilisé pour modifier SHGFI_SYSICONINDEX, ce qui provoque le retour de la fonction au handle dans la liste d’images système qui contient la petite icône ouverte du fichier. Un objet conteneur affiche une icône ouverte pour indiquer que le conteneur est ouvert. L’indicateur SHGFI_ICON et/ou SHGFI_SYSICONINDEX doit également être défini.

SHGFI_OVERLAYINDEX (0x000000040)

version 5.0. Retourne l’index de l’icône de superposition. La valeur de l’index de superposition est retournée dans les huit bits supérieurs du membre iIcon de la structure spécifiée par psfi. Cet indicateur exige que le SHGFI_ICON soit également défini.

SHGFI_PIDL (0x000000008)

Indiquez que pszPath est l’adresse d’une structure ITEMIDLIST plutôt qu’un nom de chemin d’accès.

SHGFI_SELECTED (0x000010000)

Modifiez SHGFI_ICON, ce qui entraîne la fusion de l’icône du fichier avec la couleur de surbrillance du système. L’indicateur SHGFI_ICON doit également être défini.

SHGFI_SHELLICONSIZE (0x000000004)

Modifiez SHGFI_ICON, ce qui entraîne la récupération d’une icône de taille shell. Si cet indicateur n’est pas spécifié, la fonction dimensionne l’icône en fonction des valeurs de métrique système. L’indicateur SHGFI_ICON doit également être défini.

SHGFI_SMALLICON (0x000000001)

Modifiez SHGFI_ICON, ce qui entraîne la récupération de la petite icône du fichier. Également utilisé pour modifier SHGFI_SYSICONINDEX, ce qui provoque le retour de la fonction à la poignée dans la liste d’images système qui contient de petites images d’icône. L’indicateur SHGFI_ICON et/ou SHGFI_SYSICONINDEX doit également être défini.

SHGFI_SYSICONINDEX (0x000004000)

Récupérez l’index d’une icône de liste d’images système. En cas de réussite, l’index est copié dans le membre iIcon de psfi. La valeur de retour est un handle de la liste d’images système. Seules les images dont les index sont correctement copiés dans iIcon sont valides. Toute tentative d’accès à d’autres images dans la liste d’images système entraîne un comportement non défini.

SHGFI_TYPENAME (0x000000400)

Récupérez la chaîne qui décrit le type du fichier. La chaîne est copiée dans le membre szTypeName de la structure spécifiée dans psfi.

SHGFI_USEFILEATTRIBUTES (0x000000010)

Indique que la fonction ne doit pas tenter d’accéder au fichier spécifié par pszPath. Il doit plutôt agir comme si le fichier spécifié par pszPath existe avec les attributs de fichier passés dans dwFileAttributes. Cet indicateur ne peut pas être combiné avec les indicateurs SHGFI_ATTRIBUTES, SHGFI_EXETYPEou SHGFI_PIDL.

Valeur de retour

Type : DWORD_PTR

Retourne une valeur dont la signification dépend du paramètre uFlags.

Si uFlags ne contient pas SHGFI_EXETYPE ou SHGFI_SYSICONINDEX, la valeur de retour n’est pas égale à zéro si elle réussit ou zéro dans le cas contraire.

Si uFlags contient l’indicateur SHGFI_EXETYPE, la valeur de retour spécifie le type du fichier exécutable. Il s’agit de l’une des valeurs suivantes.

Retourner le code	Description
0	Fichier non exécutable ou condition d’erreur.
LOWORD = NE ou PE et HIWORD = version Windows	Application Windows.
LOWORD = MZ et HIWORD = 0	fichier MS-DOS .exe ou .com
LOWORD = PE et HIWORD = 0	Application console ou fichier .bat

Remarques

Vous devez appeler cette fonction à partir d’un thread d’arrière-plan. L’échec de cette opération peut entraîner l’arrêt de la réponse de l’interface utilisateur.

Si SHGetFileInfo retourne un handle d’icône dans le membre hIcon de la structure SHFILEINFO pointée par psfi, vous êtes responsable de la libérer avec DestroyIcon lorsque vous n’en avez plus besoin.

Remarque Une fois que vous avez un handle vers une liste d’images système, vous pouvez utiliser l’API Liste d’images pour la manipuler comme n’importe quelle autre liste d’images. Étant donné que les listes d’images système sont créées par processus, vous devez les traiter comme des objets en lecture seule. L’écriture dans une liste d’images système peut remplacer ou supprimer l’une des images système, ce qui le rend indisponible ou incorrect pour le reste du processus.

Vous devez initialiser com (Component Object Model) avec CoInitialize ou OleInitialize avant d’appeler SHGetFileInfo.

Lorsque vous utilisez l’indicateur SHGFI_EXETYPE avec une application Windows, la version Windows de l’exécutable est donnée dans HIWORD de la valeur de retour. Cette version est retournée sous forme de valeur hexadécimale. Pour plus d’informations sur l’équilibrage de cette valeur avec une version Spécifique de Windows, consultez Utilisation des en-têtes Windows.

Exemples

L’exemple de code suivant utilise SHGetFileInfo pour récupérer le nom complet de la Corbeille, identifié par son 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);

Note

L’en-tête shellapi.h définit SHGetFileInfo comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	shellapi.h
bibliothèque	Shell32.lib
DLL	Shell32.dll (version 4.0 ou ultérieure)

Voir aussi

FileIconInit

Partager via