ExtractIconExA, fonction (shellapi.h)

  • Article

La fonction ExtractIconEx crée un tableau de descripteurs en icônes grandes ou petites extraites du fichier exécutable, dll ou fichier d’icône spécifié.

Syntaxe

UINT ExtractIconExA(
  [in]  LPCSTR lpszFile,
  [in]  int    nIconIndex,
  [out] HICON  *phiconLarge,
  [out] HICON  *phiconSmall,
        UINT   nIcons
);

Paramètres

[in] lpszFile

Type : LPCTSTR

Pointeur vers une chaîne terminée par null qui spécifie le nom d’un fichier exécutable, d’une DLL ou d’un fichier d’icône à partir duquel les icônes seront extraites.

[in] nIconIndex

Type : int

Spécifie l’index de base zéro de la première icône à extraire. Par exemple, si cette valeur est égale à zéro, la fonction extrait la première icône dans le fichier spécifié.

Si cette valeur est –1 et que phiconLarge et phiconSmall ont tous deux la valeur NULL, la fonction retourne le nombre total d’icônes dans le fichier spécifié. Si le fichier est un fichier exécutable ou une DLL, la valeur de retour est le nombre de ressources RT_GROUP_ICON. Si le fichier est un fichier .ico, la valeur de retour est 1.

Si cette valeur est un nombre négatif et que phiconLarge ou phiconSmall n’a pas la valeur NULL, la fonction commence par extraire l’icône dont l’identificateur de ressource est égal à la valeur absolue de nIconIndex. Par exemple, utilisez -3 pour extraire l’icône dont l’identificateur de ressource est 3.

[out] phiconLarge

Type : HICON*

Pointeur vers un tableau de handles d’icône qui reçoit des handles vers les grandes icônes extraites du fichier. Si ce paramètre a la valeur NULL, aucune icône volumineuse n’est extraite du fichier.

[out] phiconSmall

Type : HICON*

Pointeur vers un tableau de poignées d’icônes qui reçoit des handles vers les petites icônes extraites du fichier. Si ce paramètre a la valeur NULL, aucune petite icône n’est extraite du fichier.

nIcons

Type : UINT

Nombre d’icônes à extraire du fichier.

Valeur retournée

Type : UINT

Si le paramètre nIconIndex est -1 et que les paramètres phiconLarge et phiconSmall ont la valeur NULL, la valeur de retour correspond au nombre d’icônes contenues dans le fichier spécifié.

Si le paramètre nIconIndex est une valeur autre que -1 et que phiconLarge ou phiconSmall n’est pas NULL, la valeur de retour correspond au nombre d’icônes correctement extraites du fichier.

Notes

Si la fonction rencontre une erreur, elle retourne UINT_MAX. Dans ce cas, vous pouvez appeler GetLastError pour récupérer le code d’erreur. Par exemple, cette fonction retourne UINT_MAX si le fichier spécifié par lpszFile est introuvable alors que le paramètre nIconIndex est une valeur autre que -1 et que phiconLarge ou phiconSmall n’a pas la valeur NULL. Dans ce cas, GetLastError retourne ERROR_FILE_NOT_FOUND (2).

Remarques

Quand elles ne sont plus nécessaires, vous devez détruire toutes les icônes extraites par ExtractIconEx en appelant la fonction DestroyIcon .

Pour récupérer les dimensions des grandes et petites icônes, utilisez cette fonction avec les indicateurs SM_CXICON, SM_CYICON, SM_CXSMICON et SM_CYSMICON.

Notes

L’en-tête shellapi.h définit ExtractIconEx 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. La combinaison 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

   
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
DLL Shell32.dll
Ensemble d’API ext-ms-win-shell-shell32-l1-2-1 (introduit dans Windows 10, version 10.0.10240)

Voir aussi

ExtractAssociatedIcon

ExtractAssociatedIconEx

ExtractIcon