IExtractIconA::GetIconLocation-Methode (shlobj_core.h)

Artikel
08/26/2023

Ruft den Speicherort und den Index eines Symbols ab.

Syntax

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

Parameter

uFlags

Typ: UINT

Mindestens einer der folgenden Werte: Dieser Parameter kann auch NULL sein.

GIL_ASYNC (0x0020)

Legen Sie dieses Flag fest, um zu bestimmen, ob das Symbol asynchron extrahiert werden soll. Wenn das Symbol schnell extrahiert werden kann, wird dieses Flag in der Regel ignoriert. Wenn die Extraktion mehr Zeit in Anspruch nimmt, sollte GetIconLocation E_PENDING zurückgeben. Weitere Informationen finden Sie in den Anmerkungen.

GIL_DEFAULTICON (0x0040)

Rufen Sie Informationen zum Fallbacksymbol ab. Fallbacksymbole werden normalerweise verwendet, während das gewünschte Symbol extrahiert und dem Cache hinzugefügt wird.

GIL_FORSHELL (0x0002)

Das Symbol wird in einem Shell-Ordner angezeigt.

GIL_FORSHORTCUT (0x0080)

Das Symbol zeigt eine Verknüpfung an. Der Symbolextraktor sollte die Verknüpfungsüberlagerung jedoch nicht anwenden. dies wird später geschehen. Tastenkombinationssymbole sind zustandsunabhängig.

GIL_OPENICON (0x0001)

Das Symbol befindet sich im geöffneten Zustand, wenn sowohl Open-State- als auch Closed-State-Images verfügbar sind. Wenn dieses Flag nicht angegeben wird, befindet sich das Symbol im normalen oder geschlossenen Zustand. Dieses Flag wird in der Regel für Ordnerobjekte verwendet.

GIL_CHECKSHIELD (0x0200)

Geben Sie explizit GIL_SHIELD oder GIL_FORCENOSHIELD in pwFlags zurück. Blockieren Sie nicht, wenn GIL_ASYNC festgelegt ist.

[out] pszIconFile

Typ: PTSTR

Ein Zeiger auf einen Puffer, der die Symbolposition empfängt. Der Symbolspeicherort ist eine NULL-Zeichenfolge, die die Datei identifiziert, die das Symbol enthält.

cchMax

Typ: UINT

Die Größe des Puffers in Zeichen, auf die von pszIconFile verwiesen wird.

[out] piIndex

Typ: int*

Ein Zeiger auf einen int , der den Index des Symbols in der Datei empfängt, auf die von pszIconFile verwiesen wird.

[out] pwFlags

Typ: UINT*

Ein Zeiger auf einen UINT-Wert , der null oder eine Kombination der folgenden Werte empfängt.

GIL_DONTCACHE (0x0010)

Die physischen Bildbits für dieses Symbol werden von der aufrufenden Anwendung nicht zwischengespeichert.

GIL_NOTFILENAME (0x0008)

Der Speicherort ist kein Dateinamen-Index-Paar. Die Werte in pszIconFile und piIndex können nicht an ExtractIcon oder ExtractIconEx übergeben werden.

Wenn dieses Flag nicht angegeben wird, ist der in pszIconFile zurückgegebene Wert ein vollqualifizierter Pfadname für eine .ico-Datei oder für eine Datei, die Symbole enthalten kann. Außerdem ist der in piIndex zurückgegebene Wert ein Index in dieser Datei, der das zu verwendende Symbol angibt. Wenn das GIL_NOTFILENAME-Flag nicht angegeben wird, können diese Werte daher an ExtractIcon oder ExtractIconEx übergeben werden.

GIL_PERCLASS (0x0004)

Alle Objekte dieser Klasse haben das gleiche Symbol. Dieses Flag wird intern von der Shell verwendet. Für typische Implementierungen von IExtractIcon ist dieses Flag nicht erforderlich, da das Flag impliziert, dass kein Symbolhandler erforderlich ist, um das Symbol auf Objektbasis aufzulösen. Die empfohlene Methode für die Implementierung von Symbolen pro Klasse besteht darin, ein DefaultIcon für die -Klasse zu registrieren.

GIL_PERINSTANCE (0x0002)

Jedes Objekt dieser Klasse verfügt über ein eigenes Symbol. Dieses Flag wird intern von der Shell verwendet, um Fälle wie Setup.exe zu behandeln, in denen Objekte mit identischen Namen unterschiedliche Symbole aufweisen können. Für typische Implementierungen von IExtractIcon ist dieses Flag nicht erforderlich.

GIL_SIMULATEDOC (0x0001)

Die aufrufende Anwendung sollte mithilfe des angegebenen Symbols ein Dokumentsymbol erstellen.

GIL_SHIELD (0x0200)

Nur Windows Vista. Die aufrufende Anwendung muss das Symbol mit dem UAC-Shield stempeln.

GIL_FORCENOSHIELD (0x0400)

Nur Windows Vista. Die aufrufende Anwendung darf das Symbol nicht mit dem UAC-Shield stempeln.

Rückgabewert

Typ: HRESULT

Gibt S_OK zurück, wenn die Funktion einen gültigen Speicherort zurückgegeben hat, oder S_FALSE, wenn die Shell ein Standardsymbol verwenden soll. Wenn das flag GIL_ASYNC in uFlags festgelegt ist, kann die Methode E_PENDING zurückgeben, um anzugeben, dass die Symbolextraktion zeitaufwendig ist.

Hinweise

Wenn ein Client das GIL_ASYNC-Flag in uFlags festlegt und E_PENDING als Rückgabewert empfängt, erstellt er in der Regel einen Hintergrundthread, um das Symbol zu extrahieren. Es ruft GetIconLocation aus diesem Thread ohne das GIL_ASYNC-Flag auf, um den Symbolspeicherort abzurufen. Anschließend wird IExtractIcon::Extract aufgerufen, um das Symbol zu extrahieren. Das Zurückgeben von E_PENDING impliziert, dass das Objekt ein freier Thread ist. Mit anderen Worten, es kann sicher gleichzeitig von mehreren Threads aufgerufen werden.

Das GIL_DEFAULTICON-Flag wird normalerweise in dem Fall festgelegt, in dem das gewünschte Symbol gefunden wird, aber dieses Symbol ist nicht im Symbolcache vorhanden. Die Symbolextraktion ist ein Hintergrundprozess mit niedriger Priorität und kann daher durch andere Prozesse verzögert werden. Das Standardsymbol wird anstelle des endgültigen Symbols angezeigt, während es benötigt wird, bis das endgültige Symbol extrahiert, dem Cache hinzugefügt und verfügbar gemacht wird.

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	shlobj_core.h
DLL	Shell32.dll (Version 4.0 oder höher)

Freigeben über