Méthode IExtractIconA ::GetIconLocation (shlobj_core.h)

Article
08/26/2023

Obtient l’emplacement et l’index d’une icône.

Syntaxe

HRESULT GetIconLocation(
        UINT uFlags,
  [out] PSTR pszIconFile,
        UINT cchMax,
  [out] int  *piIndex,
  [out] UINT *pwFlags
);

Paramètres

uFlags

Type : UINT

Une ou plusieurs des valeurs suivantes. Ce paramètre peut également être NULL.

GIL_ASYNC (0x0020)

Définissez cet indicateur pour déterminer si l’icône doit être extraite de manière asynchrone. Si l’icône peut être extraite rapidement, cet indicateur est généralement ignoré. Si l’extraction prend plus de temps, GetIconLocation doit retourner E_PENDING. Pour en savoir plus, consultez les remarques.

GIL_DEFAULTICON (0x0040)

Récupérez des informations sur l’icône de secours. Les icônes de secours sont généralement utilisées pendant que l’icône souhaitée est extraite et ajoutée au cache.

GIL_FORSHELL (0x0002)

L’icône s’affiche dans un dossier Shell.

GIL_FORSHORTCUT (0x0080)

L’icône indique un raccourci. Toutefois, l’extracteur d’icônes ne doit pas appliquer la superposition de raccourcis ; ce sera fait plus tard. Les icônes de raccourci sont indépendantes de l’état.

GIL_OPENICON (0x0001)

L’icône est à l’état ouvert si les images d’état ouvert et d’état fermé sont disponibles. Si cet indicateur n’est pas spécifié, l’icône est dans l’état normal ou fermé. Cet indicateur est généralement utilisé pour les objets de dossier.

GIL_CHECKSHIELD (0x0200)

Retourne explicitement GIL_SHIELD ou GIL_FORCENOSHIELD dans pwFlags. Ne bloquez pas si GIL_ASYNC est défini.

[out] pszIconFile

Type : PTSTR

Pointeur vers une mémoire tampon qui reçoit l’emplacement de l’icône. L’emplacement de l’icône est une chaîne terminée par null qui identifie le fichier qui contient l’icône.

cchMax

Type : UINT

Taille de la mémoire tampon, en caractères, pointée par pszIconFile.

[out] piIndex

Type : int*

Pointeur vers un int qui reçoit l’index de l’icône dans le fichier pointé par pszIconFile.

[out] pwFlags

Type : UINT*

Pointeur vers une valeur UINT qui reçoit zéro ou une combinaison des valeurs suivantes.

GIL_DONTCACHE (0x0010)

Les bits d’image physique de cette icône ne sont pas mis en cache par l’application appelante.

GIL_NOTFILENAME (0x0008)

L’emplacement n’est pas une paire nom de fichier/index. Les valeurs dans pszIconFile et piIndex ne peuvent pas être passées à ExtractIcon ou ExtractIconEx.

Lorsque cet indicateur est omis, la valeur retournée dans pszIconFile est un nom de chemin d’accès complet à un fichier .ico ou à un fichier qui peut contenir des icônes. En outre, la valeur retournée dans piIndex est un index dans ce fichier qui identifie les icônes à utiliser. Par conséquent, lorsque l’indicateur GIL_NOTFILENAME est omis, ces valeurs peuvent être passées à ExtractIcon ou ExtractIconEx.

GIL_PERCLASS (0x0004)

Tous les objets de cette classe ont la même icône. Cet indicateur est utilisé en interne par l’interpréteur de commandes. Les implémentations classiques d’IExtractIcon ne nécessitent pas cet indicateur, car l’indicateur implique qu’un gestionnaire d’icônes n’est pas nécessaire pour résoudre l’icône par objet. La méthode recommandée pour implémenter des icônes par classe consiste à inscrire un DefaultIcon pour la classe .

GIL_PERINSTANCE (0x0002)

Chaque objet de cette classe a sa propre icône. Cet indicateur est utilisé en interne par l’interpréteur de commandes pour gérer des cas tels que Setup.exe, où les objets portant des noms identiques peuvent avoir des icônes différentes. Les implémentations classiques d’IExtractIcon ne nécessitent pas cet indicateur.

GIL_SIMULATEDOC (0x0001)

L’application appelante doit créer une icône de document à l’aide de l’icône spécifiée.

GIL_SHIELD (0x0200)

Windows Vista uniquement. L’application appelante doit marquer l’icône avec le bouclier UAC.

GIL_FORCENOSHIELD (0x0400)

Windows Vista uniquement. L’application appelante ne doit pas marquer l’icône avec le bouclier UAC.

Valeur retournée

Type : HRESULT

Retourne S_OK si la fonction a retourné un emplacement valide, ou S_FALSE si l’interpréteur de commandes doit utiliser une icône par défaut. Si l’indicateur GIL_ASYNC est défini dans uFlags, la méthode peut retourner E_PENDING pour indiquer que l’extraction d’icônes prendra beaucoup de temps.

Remarques

Lorsqu’un client définit l’indicateur GIL_ASYNC dans uFlags et reçoit E_PENDING en tant que valeur de retour, il crée généralement un thread d’arrière-plan pour extraire l’icône. Il appelle GetIconLocation à partir de ce thread, sans l’indicateur GIL_ASYNC , pour récupérer l’emplacement de l’icône. Il appelle ensuite IExtractIcon ::Extract pour extraire l’icône. Le retour E_PENDING implique que l’objet est thread libre. En d’autres termes, il peut être appelé en toute sécurité simultanément par plusieurs threads.

L’indicateur GIL_DEFAULTICON est généralement défini dans le cas où l’icône souhaitée est trouvée, mais cette icône n’est pas présente dans le cache d’icônes. L’extraction d’icônes est un processus en arrière-plan de faible priorité et, par conséquent, peut être retardé par d’autres processus. L’icône par défaut s’affiche à la place de l’icône finale pendant le temps nécessaire à l’extraction de cette icône finale, à son ajout au cache et à sa mise à disposition.

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	shlobj_core.h
DLL	Shell32.dll (version 4.0 ou ultérieure)

Partager via