ExtractAssociatedIconA-Funktion (shellapi.h)

  • Artikel

Ruft ein Handle für ein Symbol ab, das als Ressource in einer Datei gespeichert ist, oder ein Symbol, das in der zugeordneten ausführbaren Datei einer Datei gespeichert ist.

Syntax

HICON ExtractAssociatedIconA(
  [in]      HINSTANCE hInst,
  [in, out] LPSTR     pszIconPath,
  [in, out] WORD      *piIcon
);

Parameter

[in] hInst

Typ: HINSTANCE

Ein Handle für die instance der aufrufenden Anwendung.

[in, out] pszIconPath

Typ: LPTSTR

Zeiger auf eine Zeichenfolge, die bei der Eingabe den vollständigen Pfad und Dateinamen der Datei angibt, die das Symbol enthält. Die Funktion extrahiert das Symbolhandle aus dieser Datei oder aus einer ausführbaren Datei, die dieser Datei zugeordnet ist.

Wenn diese Funktion zurückgibt, speichert die Funktion, wenn das Symbolhandle aus einer ausführbaren Datei abgerufen wurde (entweder aus einer ausführbaren Datei, auf die von lpIconPath oder einer zugeordneten ausführbaren Datei verwiesen wird), den vollständigen Pfad und Dateinamen dieser ausführbaren Datei in dem Puffer, auf den dieser Parameter verweist.

[in, out] piIcon

Typ: LPWORD

Zeiger auf einen WORD-Wert , der bei einem Eintrag den Index des Symbols angibt, dessen Handle abgerufen werden soll.

Wenn die Funktion zurückgegeben wird und das Symbolhandle aus einer ausführbaren Datei abgerufen wurde (entweder aus einer ausführbaren Datei, auf die von lpIconPath oder einer zugeordneten ausführbaren Datei verwiesen wird), verweist dieser Wert auf den Index des Symbols in dieser Datei.

Rückgabewert

Typ: HICON

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Symbolhandle. Wenn das Symbol aus einer zugeordneten ausführbaren Datei extrahiert wird, speichert die Funktion den vollständigen Pfad und Dateinamen der ausführbaren Datei in der Zeichenfolge, auf die von lpIconPath verwiesen wird, und speichert den Bezeichner des Symbols in der WORD-Datei , auf die lpiIcon verweist.

Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL.

Hinweise

Wenn es nicht mehr benötigt wird, ist der Aufrufer dafür verantwortlich, das von ExtractAssociatedIcon zurückgegebene Symbolhandle durch Aufrufen der DestroyIcon-Funktion freizugeben.

Die ExtractAssociatedIcon-Funktion sucht zuerst nach dem indizierten Symbol in der von lpIconPath angegebenen Datei. Wenn die Funktion das Symbolhandle aus dieser Datei nicht abrufen kann und der Datei eine ausführbare Datei zugeordnet ist, sucht sie in dieser ausführbaren Datei nach einem Symbol. Zuordnungen mit ausführbaren Dateien basieren auf Dateinamenerweiterungen und werden im Pro-Benutzer-Teil der Registrierung gespeichert.

Hinweis

Der Shellapi.h-Header definiert ExtractAssociatedIcon 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

Anforderung Wert
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

ExtractAssociatedIconEx

ExtractIcon

ExtractIconEx