Metodo IExtractImage::GetLocation (shobjidl_core.h)
Ottiene un percorso dell'immagine da estrarre.
Sintassi
HRESULT GetLocation(
[out] LPWSTR pszPathBuffer,
[in] DWORD cch,
[out] DWORD *pdwPriority,
[in] const SIZE *prgSize,
[in] DWORD dwRecClrDepth,
[in, out] DWORD *pdwFlags
);
Parametri
[out] pszPathBuffer
Tipo: LPWSTR
Buffer utilizzato per restituire la descrizione del percorso. Questo valore identifica l'immagine in modo da evitare di caricare più volte la stessa.
[in] cch
Tipo: DWORD
Dimensioni di pszPathBuffer in caratteri.
[out] pdwPriority
Tipo: DWORD*
Non usato.
Microsoft Windows XP e versioni precedenti: Puntatore usato per restituire la priorità dell'elemento quando il flag di IEIFLAG_ASYNC è impostato in pdwFlags. Questo parametro non deve essere NULL. La funzione ha esito negativo se questo parametro è NULL, indipendentemente dal fatto che IEIFLAG_ASYNC flag sia impostato o meno.
Questo parametro viene in genere usato per indicare la quantità di tempo necessaria per estrarre l'immagine. Se si vuole più controllo sull'ordine in cui vengono estratte le anteprime, è possibile definire più livelli di priorità, fino a 32 bit. Purché i valori integer assegnati ai diversi livelli di priorità aumentino da bassa a alta priorità, i numeri effettivi usati non sono importanti. Vengono usati solo per determinare l'ordine in cui verranno estratte le immagini. Esistono tre livelli di priorità standard:
IEI_PRIORITY_MAX
Priorità massima.
IEI_PRIORITY_MIN
Priorità minima.
IEIT_PRIORITY_NORMAL
Priorità normale.
Microsoft Windows XP. Non usato.
[in] prgSize
Tipo: const SIZE*
Puntatore a una struttura SIZE con la larghezza e l'altezza desiderata dell'immagine. Non deve essere NULL.
[in] dwRecClrDepth
Tipo: DWORD
Profondità del colore consigliata in unità di bit per pixel. Non deve essere NULL.
[in, out] pdwFlags
Tipo: DWORD*
Flag che specificano la modalità di gestione dell'immagine. Il valore deve essere uno o più dei seguenti:
IEIFLAG_ASPECT
Usato per chiedere all'oggetto di usare il rapporto di aspetto fornito. Se questo flag è impostato, verrà passato un rettangolo con il rapporto di aspetto desiderato in prgSize. Questo flag non può essere usato con IEIFLAG_SCREEN.
IEIFLAG_ASYNC
Non usato. L'anteprima viene sempre estratta su un thread in background.
Microsoft Windows XP e versioni precedenti. Usato per chiedere se questa istanza supporta l'estrazione asincrona (senza thread). Se questo flag viene impostato dalle applicazioni chiamanti, IExtractImage::GetLocation può restituire E_PENDING, indicando all'applicazione chiamante di estrarre l'immagine in un altro thread. Se viene restituito E_PENDING, la priorità dell'elemento viene restituita in pdwPriority.
IEIFLAG_CACHE
Non supportato.
Windows XP e versioni precedenti: Impostare dall'oggetto per indicare che non memorizza nella cache l'immagine. Se questo flag viene restituito, shell memorizza nella cache una copia dell'immagine.
IEIFLAG_GLEAM
Non supportato.
IEIFLAG_NOBORDER (0x0100)
Non supportato.
IEIFLAG_NOSTAMP (0x0080)
Non supportato.
IEIFLAG_OFFLINE
Usato per indicare all'oggetto di usare solo il contenuto locale per il rendering.
IEIFLAG_ORIGSIZE
Versione 5.0. Usato per indicare all'oggetto di eseguire il rendering dell'immagine alla dimensione approssimativa passata in prgSize, ma ritagliarla se necessario.
IEIFLAG_QUALITY (0x0200)
Passato al metodo IExtractImage::Extract per indicare che viene richiesta un'immagine di qualità superiore.
Se questo flag non è impostato, IExtractImage recupera un'anteprima incorporata se il file ha uno, indipendentemente dalle dimensioni richieste dall'utente. Ad esempio, se il file è 2000x2000 pixel, ma l'anteprima incorporata è solo 100x100 pixel e l'utente non imposta questo flag, ma richiede un'anteprima di 1000x1000 pixel, IExtractImage restituisce sempre l'anteprima di 100x100 pixel. Questo è per progettazione, poiché IExtractImage non aumenta. Se si desidera un'anteprima più grande (in genere le anteprime incorporate sono 160x160), questo flag deve essere impostato.
IEIFLAG_REFRESH (0x0400)
Restituito dall'oggetto per indicare che l'anteprima di aggiornamento deve essere visualizzata nel menu di scelta rapida dell'elemento.
IEIFLAG_SCREEN
Usato per indicare all'oggetto di eseguire il rendering come se per lo schermo. Questo flag non può essere usato con IEIFLAG_ASPECT.
Valore restituito
Tipo: HRESULT
Questo metodo può restituire un codice di errore definito da COM o uno dei seguenti:
| Codice restituito | Descrizione |
|---|---|
|
Operazione completata |
|
Windows XP e versioni precedenti: Se il flag IEIFLAG_ASYNC è impostato, questo valore restituito viene usato per indicare alla Shell che l'oggetto è senza thread. |
Commenti
Microsoft Windows XP e versioni precedenti: Questo metodo restituisce il percorso di un'immagine e specifica come eseguire il rendering dell'immagine. IExtractImage::GetLocation è free-threaded, ovvero supporta il modello MTA (Multithreaded Apartment Model), pertanto può essere inserito in un thread in background. L'oggetto deve anche esporre un'interfaccia IRunnableTask , in modo che l'applicazione chiamante possa avviare e arrestare il processo di estrazione in base alle esigenze.
È consigliabile restituire immagini che rientrano nei limiti definiti da prgSize. Con i sistemi Windows 2000 e versioni successive, è possibile impostare IEIFLAG_ORIGSIZE per l'uso di oggetti che non hanno una proporzioni standard e verranno visualizzati correttamente. Non è necessario compilare la parte inutilizzata del rettangolo. Se si tenta di usare un'immagine di proporzioni non standard con le versioni precedenti di Shell, verrà estesa per adattare il rettangolo prgSize . A seconda della quantità di proporzioni diversa da quella specificata, l'immagine potrebbe essere mal distorta.
Requisiti
| Client minimo supportato | Windows 2000 Professional, Windows XP [solo app desktop] |
| Server minimo supportato | Windows Server 2003 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | shobjidl_core.h (include Shobjidl.h) |
| DLL | Shell32.dll (versione 4.70 o successiva) |