ExtractIconExA-Funktion (shellapi.h)

  • Artikel

Die ExtractIconEx-Funktion erstellt ein Array von Handles für große oder kleine Symbole, die aus der angegebenen ausführbaren Datei, DLL oder Symboldatei extrahiert werden.

Syntax

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

Parameter

[in] lpszFile

Typ: LPCTSTR

Zeiger auf eine NULL-endende Zeichenfolge, die den Namen einer ausführbaren Datei, DLL oder Symboldatei angibt, aus der Symbole extrahiert werden.

[in] nIconIndex

Typ: int

Gibt den nullbasierten Index des ersten zu extrahierenden Symbols an. Wenn dieser Wert beispielsweise null ist, extrahiert die Funktion das erste Symbol in der angegebenen Datei.

Wenn dieser Wert –1 ist und phiconLarge und phiconSmallnull sind, gibt die Funktion die Gesamtzahl der Symbole in der angegebenen Datei zurück. Wenn es sich bei der Datei um eine ausführbare Datei oder DLL handelt, ist der Rückgabewert die Anzahl der RT_GROUP_ICON Ressourcen. Wenn es sich bei der Datei um eine ICO-Datei handelt, ist der Rückgabewert 1.

Wenn dieser Wert eine negative Zahl ist und entweder phiconLarge oder phiconSmall nicht NULL ist, extrahiert die Funktion zunächst das Symbol, dessen Ressourcenbezeichner dem absoluten Wert von nIconIndex entspricht. Verwenden Sie beispielsweise -3, um das Symbol zu extrahieren, dessen Ressourcenbezeichner 3 ist.

[out] phiconLarge

Typ: HICON*

Zeiger auf ein Array von Symbolhandles, das Handles zu den großen Symbolen empfängt, die aus der Datei extrahiert wurden. Wenn dieser Parameter NULL ist, werden keine großen Symbole aus der Datei extrahiert.

[out] phiconSmall

Typ: HICON*

Zeiger auf ein Array von Symbolhandles, das Handles zu den kleinen Symbolen empfängt, die aus der Datei extrahiert wurden. Wenn dieser Parameter NULL ist, werden keine kleinen Symbole aus der Datei extrahiert.

nIcons

Typ: UINT

Die Anzahl der Symbole, die aus der Datei extrahiert werden sollen.

Rückgabewert

Typ: UINT

Wenn der nIconIndex-Parameter -1 ist und sowohl die Parameter phiconLarge als auch phiconSmallNULL sind, ist der Rückgabewert die Anzahl der Symbole, die in der angegebenen Datei enthalten sind.

Wenn der nIconIndex-Parameter ein anderer Wert als -1 ist und entweder phiconLarge oder phiconSmall nicht NULL ist, ist der Rückgabewert die Anzahl der Symbole, die erfolgreich aus der Datei extrahiert wurden.

Hinweis

Wenn für die Funktion ein Fehler auftritt, wird UINT_MAX zurückgegeben. In diesem Fall können Sie GetLastError aufrufen, um den Fehlercode abzurufen. Diese Funktion gibt z . B. UINT_MAX zurück, wenn die durch lpszFile angegebene Datei nicht gefunden werden kann, während der nIconIndex-Parameter einen anderen Wert als -1 aufweist und weder phiconLarge noch phiconSmallnull ist. In diesem Fall gibt GetLastErrorERROR_FILE_NOT_FOUND (2) zurück.

Hinweise

Wenn sie nicht mehr benötigt werden, müssen Sie alle von ExtractIconEx extrahierten Symbole zerstören, indem Sie die DestroyIcon-Funktion aufrufen.

Um die Dimensionen der großen und kleinen Symbole abzurufen, verwenden Sie diese Funktion mit den Flags SM_CXICON, SM_CYICON, SM_CXSMICON und SM_CYSMICON.

Hinweis

Der Shellapi.h-Header definiert ExtractIconEx als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile shellapi.h
DLL Shell32.dll
APIs ext-ms-win-shell-shell32-l1-2-1 (eingeführt in Windows 10, Version 10.0.10240)

Weitere Informationen

ExtractAssociatedIcon

ExtractAssociatedIconEx

ExtractIcon