Fonction SHGetFileInfoA (shellapi.h)
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 SHGetFileInfoA(
[in] LPCSTR pszPath,
DWORD dwFileAttributes,
[in, out] SHFILEINFOA *psfi,
UINT cbFileInfo,
UINT uFlags
);
Paramètres
[in] pszPath
Type : LPCTSTR
Pointeur vers une chaîne terminée par null de longueur maximale MAX_PATH qui contient le chemin d’accès et le nom de fichier. Les chemins absolu et relatif 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 PIDL doit être un PIDL complet. Les ADRESSES IPD relatives ne sont pas autorisées.
Si le paramètre uFlags inclut l’indicateur SHGFI_USEFILEATTRIBUTES , ce paramètre n’a pas besoin d’être un nom de fichier valide. La fonction se poursuit comme si le fichier existait avec le nom spécifié et avec les attributs de fichier transmis dans le paramètre dwFileAttributes . Cela vous permet d’obtenir des informations sur un type de fichier en transmettant uniquement l’extension pour pszPath et en transmettant 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 telles que définies dans Winnt.h). Si uFlags n’inclut pas l’indicateur SHGFI_USEFILEATTRIBUTES , ce paramètre est ignoré.
[in, out] psfi
Type : SHFILEINFO*
Pointeur vers une structure SHFILEINFO pour recevoir les informations de fichier.
cbFileInfo
Type : UINT
Taille, en octets, de la structure SHFILEINFO pointée vers 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 passé à 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 membre dwAttributes de la structure spécifiée dans le paramètre psfi . Il s’agit des mêmes attributs que ceux obtenus à partir de IShellFolder ::GetAttributesOf.
SHGFI_DISPLAYNAME (0x000000200)
Récupérez le nom d’affichage du fichier, qui est le nom tel qu’il apparaît dans Windows Explorer. Le nom est copié dans le membre szDisplayName de la structure spécifiée dans psfi. Le nom d’affichage retourné utilise le nom de fichier long, le cas échéant, plutôt que la forme 8.3 du nom de fichier. Notez que le nom d’affichage 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 regroupé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 de 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 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 lien à 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 d’ouverture du fichier par la fonction. Également utilisé pour modifier SHGFI_SYSICONINDEX, ce qui entraîne la fonction à renvoyer le handle à 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 nécessite que le SHGFI_ICON également être 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 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 la taille de l’interpréteur de commandes. 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 fait que la fonction récupère la petite icône du fichier. Également utilisé pour modifier SHGFI_SYSICONINDEX, ce qui entraîne la fonction à renvoyer le handle à 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érer 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 ont été correctement copiés dans iIcon sont valides. La 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. Au lieu de cela, il doit agir comme si le fichier spécifié par pszPath existait avec les attributs de fichier transmis dans dwFileAttributes. Cet indicateur ne peut pas être combiné avec les indicateurs SHGFI_ATTRIBUTES, SHGFI_EXETYPE ou SHGFI_PIDL .
Valeur retournée
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 est différente de zéro en cas de réussite, ou de 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.
| Code de retour | Description |
|---|---|
|
Fichier non exécutable ou condition d’erreur. |
|
Application Windows |
|
Fichier .exe ou .com MS-DOS |
|
Application console ou fichier .bat |
Remarques
Vous devez appeler cette fonction à partir d’un thread d’arrière-plan. Si vous ne le faites pas, l’interface utilisateur peut cesser de répondre.
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.
Lorsque vous utilisez l’indicateur SHGFI_EXETYPE avec une application Windows, la version Windows de l’exécutable est donnée dans le HIWORD de la valeur de retour. Cette version est retournée sous forme de valeur hexadécimale. Pour plus d’informations sur l’assiminement de cette valeur à 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 d’affichage 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);
Notes
L’en-tête shellapi.h définit SHGetFileInfo comme un 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.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows XP [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | shellapi.h |
| Bibliothèque | Shell32.lib |
| DLL | Shell32.dll (version 4.0 ou ultérieure) |