Méthode IExtractImage::GetLocation (shobjidl_core.h)

Obtient un chemin d’accès à l’image à extraire.

Syntaxe

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

Paramètres

[out] pszPathBuffer

Type : LPWSTR

Mémoire tampon utilisée pour retourner la description du chemin d’accès. Cette valeur identifie l’image afin d’éviter de charger la même image plusieurs fois.

[in] cch

Type : DWORD

Taille de pszPathBuffer en caractères.

[out] pdwPriority

Type : DWORD*

Non utilisé.

Microsoft Windows XP et versions antérieures : Pointeur utilisé pour retourner la priorité de l’élément lorsque l’indicateur IEIFLAG_ASYNC est défini dans pdwFlags. Ce paramètre ne doit pas avoir la valeur NULL. La fonction échoue si ce paramètre a la valeur NULL, si IEIFLAG_ASYNC indicateur est défini ou non.

Ce paramètre est généralement utilisé pour indiquer la durée nécessaire à l’extraction de l’image. Si vous souhaitez plus de contrôle sur l’ordre dans lequel les miniatures sont extraites, vous pouvez définir plusieurs niveaux de priorité, jusqu’à 32 bits. Tant que les valeurs entières attribuées aux différents niveaux de priorité augmentent de faible à haute priorité, les nombres réels que vous utilisez ne sont pas importants. Ils sont uniquement utilisés pour déterminer l’ordre dans lequel les images seront extraites. Il existe trois niveaux de priorité standard :

IEI_PRIORITY_MAX

Priorité maximale.

IEI_PRIORITY_MIN

Priorité minimale.

IEIT_PRIORITY_NORMAL

Priorité normale.

Microsoft Windows XP. Non utilisé.

[in] prgSize

Type : const SIZE*

Pointeur vers une structure SIZE avec la largeur et la hauteur souhaitées de l’image. Ne doit pas avoir la valeur NULL.

[in] dwRecClrDepth

Type : DWORD

Profondeur de couleur recommandée en unités de bits par pixel. Ne doit pas avoir la valeur NULL.

[in, out] pdwFlags

Type : DWORD*

Indicateurs qui spécifient la façon dont l’image doit être gérée. La valeur doit être l’une ou plusieurs des valeurs suivantes :

IEIFLAG_ASPECT

Utilisé pour demander à l’objet d’utiliser le rapport d’aspect fourni. Si cet indicateur est défini, un rectangle avec le rapport d’aspect souhaité est passé dans prgSize. Cet indicateur ne peut pas être utilisé avec IEIFLAG_SCREEN.

IEIFLAG_ASYNC

Non utilisé. La miniature est toujours extraite sur un thread d’arrière-plan.

Microsoft Windows XP et versions antérieures. Permet de demander si cette instance prend en charge l’extraction asynchrone (avec thread libre). Si cet indicateur est défini par les applications appelantes, IExtractImage::GetLocation peut renvoyer E_PENDING, indiquant à l’application appelante d’extraire l’image sur un autre thread. Si E_PENDING est retourné, la priorité de l’élément est retournée dans pdwPriority.

IEIFLAG_CACHE

Non pris en charge.

Windows XP et versions antérieures : Défini par l’objet pour indiquer qu’il ne met pas en cache l’image. Si cet indicateur est retourné, l’interpréteur de commandes met en cache une copie de l’image.

IEIFLAG_GLEAM

Non pris en charge.

IEIFLAG_NOBORDER (0x0100)

Non pris en charge.

IEIFLAG_NOSTAMP (0x0080)

Non pris en charge.

IEIFLAG_OFFLINE

Utilisé pour indiquer à l’objet d’utiliser uniquement du contenu local pour le rendu.

IEIFLAG_ORIGSIZE

Version 5.0. Utilisé pour indiquer à l’objet de restituer l’image à la taille approximative passée dans prgSize, mais rognez-la si nécessaire.

IEIFLAG_QUALITY (0x0200)

Passé à la méthode IExtractImage::Extract pour indiquer qu’une image de qualité supérieure est demandée.

Si cet indicateur n’est pas défini, IExtractImage récupère une miniature incorporée si le fichier en contient une, quelle que soit la taille que l’utilisateur demande. Par exemple, si le fichier est de 2000 x 2000 pixels, mais que la miniature incorporée n’est que de 100 x 100 pixels et que l’utilisateur ne définit pas cet indicateur, mais demande une miniature de 1000 x 1000 pixels, IExtractImage retourne toujours la miniature de 100 x 100 pixels. C’est par conception, car IExtractImage ne monte pas en puissance. Si une miniature plus grande est souhaitée (les miniatures incorporées sont généralement 160x160), cet indicateur doit être défini.

IEIFLAG_REFRESH (0x0400)

Retourné par l’objet pour indiquer que Actualiser la miniature doit être affiché dans le menu contextuel de l’élément.

IEIFLAG_SCREEN

Utilisé pour indiquer à l’objet de s’afficher comme si pour l’écran. Cet indicateur ne peut pas être utilisé avec IEIFLAG_ASPECT.

Valeur retournée

Type : HRESULT

Cette méthode peut retourner un code d’erreur défini par COM ou l’un des éléments suivants :

Remarques

Microsoft Windows XP et versions antérieures : Cette méthode retourne le chemin d’accès à une image et spécifie le mode de rendu de l’image. IExtractImage::GetLocation est à thread libre, c’est-à-dire prend en charge le modèle d’appartement multithread (MTA) . Il peut donc être placé dans un thread d’arrière-plan. L’objet doit également exposer une interface IRunnableTask , afin que l’application appelante puisse démarrer et arrêter le processus d’extraction si nécessaire.

Vous devez retourner des images qui s’inscrivent dans les limites définies par prgSize. Avec les systèmes Windows 2000 et versions ultérieures, vous pouvez définir IEIFLAG_ORIGSIZE pour utiliser des objets qui n’ont pas de rapport d’aspect standard, et ils s’affichent correctement. Vous n’avez pas besoin de remplir la partie inutilisée du rectangle. Si vous essayez d’utiliser une image de format non standard avec des versions antérieures de l’interpréteur de commandes, elle sera étirée pour s’adapter au rectangle prgSize . En fonction de la différence de proportion par rapport à ce qui est spécifié, l’image peut être mal déformée.

Configuration requise