IExtractImage::GetLocation-Methode (shobjidl_core.h)

  • Artikel

Ruft einen Pfad zu dem Image ab, das extrahiert werden soll.

Syntax

HRESULT GetLocation(
  [out]     LPWSTR     pszPathBuffer,
  [in]      DWORD      cch,
  [out]     DWORD      *pdwPriority,
  [in]      const SIZE *prgSize,
  [in]      DWORD      dwRecClrDepth,
  [in, out] DWORD      *pdwFlags
);

Parameter

[out] pszPathBuffer

Typ: LPWSTR

Der Puffer, der verwendet wird, um die Pfadbeschreibung zurückzugeben. Dieser Wert identifiziert das Bild, sodass Sie vermeiden können, dasselbe Bild mehrmals zu laden.

[in] cch

Art: DWORD

Die Größe von pszPathBuffer in Zeichen.

[out] pdwPriority

Typ: DWORD*

Wird nicht verwendet.

Microsoft Windows XP und früher: Der Zeiger, der verwendet wird, um die Priorität des Elements zurückzugeben, wenn das IEIFLAG_ASYNC-Flag in pdwFlags festgelegt ist. Dieser Parameter darf nicht NULL sein. Die Funktion schlägt fehl, wenn dieser Parameter NULL ist, unabhängig davon, ob IEIFLAG_ASYNC Flag festgelegt ist oder nicht.

Dieser Parameter wird in der Regel verwendet, um anzugeben, wie lange das Bild extrahiert werden muss. Wenn Sie mehr Kontrolle über die Reihenfolge haben möchten, in der Miniaturansichten extrahiert werden, können Sie mehrere Prioritätsebenen mit bis zu 32 Bit definieren. Solange die ganzzahligen Werte, die den verschiedenen Prioritätsebenen zugewiesen sind, von niedriger zu hoher Priorität steigen, sind die tatsächlichen Zahlen, die Sie verwenden, nicht wichtig. Sie werden nur verwendet, um die Reihenfolge zu bestimmen, in der die Bilder extrahiert werden. Es gibt drei Standardprioritätsstufen:

IEI_PRIORITY_MAX

Maximale Priorität.

IEI_PRIORITY_MIN

Mindestpriorität.

IEIT_PRIORITY_NORMAL

Normale Priorität.

Microsoft Windows XP. Wird nicht verwendet.

[in] prgSize

Typ: const SIZE*

Ein Zeiger auf eine SIZE-Struktur mit der gewünschten Breite und Höhe des Bilds. Darf nicht NULL sein.

[in] dwRecClrDepth

Art: DWORD

Die empfohlene Farbtiefe in Biteinheiten pro Pixel. Darf nicht NULL sein.

[in, out] pdwFlags

Typ: DWORD*

Flags, die angeben, wie das Image behandelt werden soll. Der Wert muss mindestens eine der folgenden Werte aufweisen:

IEIFLAG_ASPECT

Wird verwendet, um das Objekt aufzufordern, das angegebene Seitenverhältnis zu verwenden. Wenn dieses Flag festgelegt ist, wird ein Rechteck mit dem gewünschten Seitenverhältnis in prgSize übergeben. Dieses Flag kann nicht mit IEIFLAG_SCREEN verwendet werden.

IEIFLAG_ASYNC

Wird nicht verwendet. Die Miniaturansicht wird immer in einem Hintergrundthread extrahiert.

Microsoft Windows XP und früher. Wird verwendet, um zu fragen, ob dieser instance die asynchrone Extraktion (Freethreading) unterstützt. Wenn dieses Flag von den aufrufenden Anwendungen festgelegt wird, gibt IExtractImage::GetLocation möglicherweise E_PENDING zurück, was angibt, dass die aufrufende Anwendung das Image in einem anderen Thread extrahieren soll. Wenn E_PENDING zurückgegeben wird, wird die Priorität des Elements in pdwPriority zurückgegeben.

IEIFLAG_CACHE

Wird nicht unterstützt.

Windows XP und früher: Legen Sie durch das -Objekt fest, um anzugeben, dass das Image nicht zwischengespeichert wird. Wenn dieses Flag zurückgegeben wird, speichert die Shell eine Kopie des Images zwischen.

IEIFLAG_GLEAM

Wird nicht unterstützt.

IEIFLAG_NOBORDER (0x0100)

Wird nicht unterstützt.

IEIFLAG_NOSTAMP (0x0080)

Wird nicht unterstützt.

IEIFLAG_OFFLINE

Wird verwendet, um das Objekt anweisen, nur lokale Inhalte zum Rendern zu verwenden.

IEIFLAG_ORIGSIZE

Version 5.0. Wird verwendet, um das -Objekt anweisen, das Bild auf die in prgSize übergebene ungefähre Größe zu rendern, aber bei Bedarf zuzuschneiden.

IEIFLAG_QUALITY (0x0200)

Wird an die IExtractImage::Extract-Methode übergeben, um anzugeben, dass ein Image mit höherer Qualität angefordert wird.

Wenn dieses Flag nicht festgelegt ist, ruft IExtractImage eine eingebettete Miniaturansicht ab, wenn die Datei eine hat, unabhängig davon, welche Größe der Benutzer anfordert. Wenn die Datei beispielsweise 2000 x 2000 Pixel ist, die eingebettete Miniaturansicht jedoch nur 100 x 100 Pixel ist und der Benutzer dieses Flag nicht festgelegt, aber eine Miniaturansicht von 1000 x 1000 Pixel anfordert, gibt IExtractImage immer die Miniaturansicht 100x100 Pixel zurück. Dies ist beabsichtigt, da IExtractImage nicht hochskaliert wird. Wenn eine größere Miniaturansicht gewünscht ist (normalerweise sind eingebettete Miniaturansichten 160 x 160), muss dieses Flag festgelegt werden.

IEIFLAG_REFRESH (0x0400)

Wird vom -Objekt zurückgegeben, um anzugeben, dass Miniaturansicht aktualisieren im Kontextmenü des Elements angezeigt werden soll.

IEIFLAG_SCREEN

Wird verwendet, um das Objekt zu anweisen, wie für den Bildschirm zu rendern. Dieses Flag kann nicht mit IEIFLAG_ASPECT verwendet werden.

Rückgabewert

Typ: HRESULT

Diese Methode gibt möglicherweise einen COM-definierten Fehlercode oder einen der folgenden Zurück:

Rückgabecode BESCHREIBUNG
S_OK
 Erfolg
E_PENDING
 Windows XP und früher: Wenn das IEIFLAG_ASYNC-Flag festgelegt ist, wird dieser Rückgabewert verwendet, um der Shell anzugeben, dass das Objekt freithreaded ist.

Hinweise

Microsoft Windows XP und früher: Diese Methode gibt den Pfad zu einem Bild zurück und gibt an, wie das Bild gerendert werden soll. IExtractImage::GetLocation ist Freethreaded, d. h. unterstützt das Multithreaded Apartment Model (MTA) und kann daher in einem Hintergrundthread platziert werden. Das Objekt muss auch eine IRunnableTask-Schnittstelle verfügbar machen, damit die aufrufende Anwendung den Extraktionsprozess nach Bedarf starten und beenden kann.

Sie sollten Bilder zurückgeben, die innerhalb der von prgSize definierten Grenzen passen. Mit Windows 2000 und höher können Sie IEIFLAG_ORIGSIZE so festlegen, dass Objekte verwendet werden, die kein Standardseitenverhältnis aufweisen, und sie werden ordnungsgemäß angezeigt. Sie müssen den nicht verwendeten Teil des Rechtecks nicht ausfüllen. Wenn Sie versuchen, ein nicht standardmäßiges Seitenverhältnisbild mit früheren Versionen der Shell zu verwenden, wird es so gestreckt, dass es dem prgSize-Rechteck entspricht. Je nachdem, wie sehr sich das Seitenverhältnis von dem angegebenen unterscheidet, kann das Bild stark verzerrt sein.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows 2000 Professional, Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile shobjidl_core.h (shobjidl.h einschließen)
DLL Shell32.dll (Version 4.70 oder höher)