Метод IExtractImage::GetLocation (shobjidl_core.h)

Возвращает путь к извлечению изображения.

Синтаксис

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

Параметры

[out] pszPathBuffer

Тип: LPWSTR

Буфер, используемый для возврата описания пути. Это значение идентифицирует изображение, чтобы избежать его загрузки несколько раз.

[in] cch

Тип: DWORD

Размер pszPathBuffer в символах.

[out] pdwPriority

Тип: DWORD*

Не используется.

Microsoft Windows XP и более ранние версии: Указатель, используемый для возврата приоритета элемента при установке флага IEIFLAG_ASYNC в pdwFlags. Этот параметр не должен иметь значение NULL. Функция завершается ошибкой, если этот параметр имеет значение NULL, независимо от того, установлен флаг IEIFLAG_ASYNC или нет.

Этот параметр обычно используется для указания времени, необходимого для извлечения изображения. Если требуется больший контроль над порядком извлечения эскизов, можно определить несколько уровней приоритета до 32 бит. До тех пор, пока целочисленные значения, назначенные различным уровням приоритета, увеличиваются с низкого до высокого, фактические числа, которые вы используете, не важны. Они используются только для определения порядка извлечения изображений. Существует три стандартных уровня приоритета:

IEI_PRIORITY_MAX

Максимальный приоритет.

IEI_PRIORITY_MIN

Минимальный приоритет.

IEIT_PRIORITY_NORMAL

Обычный приоритет.

Microsoft Windows XP. Не используется.

[in] prgSize

Тип: const SIZE*

Указатель на структуру SIZE с требуемой шириной и высотой изображения. Не должно иметь значение NULL.

[in] dwRecClrDepth

Тип: DWORD

Рекомендуемая глубина цвета в единицах бит на пиксель. Не должно иметь значение NULL.

[in, out] pdwFlags

Тип: DWORD*

Флаги, указывающие способ обработки изображения. Значение должно быть одним или несколькими из следующих значений:

IEIFLAG_ASPECT

Используется для того, чтобы запросить у объекта использование указанного пропорции. Если этот флаг установлен, прямоугольник с нужным соотношением сторон будет передан в формате prgSize. Этот флаг нельзя использовать с IEIFLAG_SCREEN.

IEIFLAG_ASYNC

Не используется. Эскиз всегда извлекается в фоновом потоке.

Microsoft Windows XP и более ранние версии. Используется для того, чтобы узнать, поддерживает ли этот экземпляр асинхронное (свободнопоточное) извлечение. Если этот флаг установлен вызывающими приложениями, IExtractImage::GetLocation может вернуть E_PENDING, указывая вызывающей приложению на извлечение изображения в другом потоке. Если возвращается E_PENDING , приоритет элемента возвращается в pdwPriority.

IEIFLAG_CACHE

Не поддерживается.

Windows XP и более ранние версии: Задается объектом , чтобы указать, что он не будет кэшировать изображение. Если этот флаг возвращается, оболочка кэширует копию образа.

IEIFLAG_GLEAM

Не поддерживается.

IEIFLAG_NOBORDER (0x0100)

Не поддерживается.

IEIFLAG_NOSTAMP (0x0080)

Не поддерживается.

IEIFLAG_OFFLINE

Используется, чтобы сообщить объекту, что для отрисовки используется только локальное содержимое.

IEIFLAG_ORIGSIZE

Версия 5.0. Используется, чтобы сообщить объекту о необходимости отрисовки изображения до приблизительного размера, переданного в prgSize, но при необходимости обрезать его.

IEIFLAG_QUALITY (0x0200)

Передается методу IExtractImage::Extract , чтобы указать, что запрашивается изображение более высокого качества.

Если этот флаг не установлен, IExtractImage извлекает внедренный эскиз, если файл имеет его, независимо от того, какой размер запрашивает пользователь. Например, если размер файла составляет 2000 x 2000 пикселей, но внедренный эскиз составляет всего 100 x 100 пикселей и пользователь не устанавливает этот флаг, но запрашивает эскиз 1000x1000 пикселей, IExtractImage всегда возвращает эскиз 100x100 пикселей. Это связано с тем, что IExtractImage не масштабируется. Если требуется более крупный эскиз (обычно внедренные эскизы имеют размер 160 x 160), этот флаг необходимо установить.

IEIFLAG_REFRESH (0x0400)

Возвращается объектом , чтобы указать, что в контекстном меню элемента должен отображаться "Обновить эскиз ".

IEIFLAG_SCREEN

Используется для отрисовки объекта как для экрана. Этот флаг нельзя использовать с IEIFLAG_ASPECT.

Возвращаемое значение

Тип: HRESULT

Этот метод может возвращать код ошибки, определяемый COM, или один из следующих кодов:

Код возврата	Описание
S_OK	Успешное завершение
E_PENDING	Windows XP и более ранние версии: Если установлен флаг IEIFLAG_ASYNC , это возвращаемое значение используется для указания оболочке, что объект является свободным потоком.

Комментарии

Microsoft Windows XP и более ранние версии: Этот метод возвращает путь к изображению и указывает способ отрисовки изображения. IExtractImage::GetLocation является свободным потоком, то есть поддерживает многопототочную модель квартир (MTA), поэтому ее можно поместить в фоновый поток. Объект также должен предоставлять интерфейс IRunnableTask , чтобы вызывающее приложение запустите и остановит процесс извлечения по мере необходимости.

Необходимо возвращать изображения, которые помещаются в границы, определенные prgSize. В системах Windows 2000 и более поздних версий можно настроить IEIFLAG_ORIGSIZE для использования объектов, которые не имеют стандартной пропорции, и они будут отображаться правильно. Не нужно заполнять неиспользуемую часть прямоугольника. Если вы попытаетесь использовать нестандартное изображение пропорций в более ранних версиях оболочки, оно будет растянуто в соответствии с прямоугольником prgSize . В зависимости от того, насколько пропорции отличаются от указанного, изображение может быть сильно искажено.

Требования

Минимальная версия клиента	Windows 2000 Professional, Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	shobjidl_core.h (включая Shobjidl.h)
DLL	Shell32.dll (версия 4.70 или более поздняя)