Método IExtractIconW::GetIconLocation (shlobj_core.h)

Obtiene la ubicación y el índice de un icono.

Sintaxis

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

Parámetros

uFlags

Tipo: UINT

Uno o varios de los valores siguientes. Este parámetro también puede ser NULL.

GIL_ASYNC (0x0020)

Establezca esta marca para determinar si el icono se debe extraer de forma asincrónica. Si el icono se puede extraer rápidamente, normalmente se omite esta marca. Si la extracción tardará más tiempo, GetIconLocation debe devolver E_PENDING. Vea los comentarios para obtener más información.

GIL_DEFAULTICON (0x0040)

Recupere información sobre el icono de reserva. Los iconos de reserva se suelen usar mientras se extrae el icono deseado y se agrega a la memoria caché.

GIL_FORSHELL (0x0002)

El icono se muestra en una carpeta shell.

GIL_FORSHORTCUT (0x0080)

El icono indica un acceso directo. Sin embargo, el extractor de iconos no debe aplicar la superposición de acceso directo; que se hará más adelante. Los iconos de acceso directo son independientes del estado.

GIL_OPENICON (0x0001)

El icono está en estado abierto si están disponibles las imágenes de estado abierto y cerrado. Si no se especifica esta marca, el icono está en estado normal o cerrado. Esta marca se usa normalmente para los objetos de carpeta.

GIL_CHECKSHIELD (0x0200)

Devuelve explícitamente GIL_SHIELD o GIL_FORCENOSHIELD en pwFlags. No bloquee si se establece GIL_ASYNC.

[out] pszIconFile

Tipo: PTSTR

Puntero a un búfer que recibe la ubicación del icono. La ubicación del icono es una cadena terminada en null que identifica el archivo que contiene el icono.

cchMax

Tipo: UINT

Tamaño del búfer, en caracteres, al que apunta pszIconFile.

[out] piIndex

Tipo: int*

Puntero a un valor int que recibe el índice del icono en el archivo al que apunta pszIconFile.

[out] pwFlags

Tipo: UINT*

Puntero a un valor UINT que recibe cero o una combinación de los valores siguientes.

GIL_DONTCACHE (0x0010)

La aplicación que realiza la llamada no almacena en caché los bits de imagen física de este icono.

GIL_NOTFILENAME (0x0008)

La ubicación no es un par de nombre de archivo o índice. Los valores de pszIconFile y piIndex no se pueden pasar a ExtractIcon o ExtractIconEx.

Cuando se omite esta marca, el valor devuelto en pszIconFile es un nombre de ruta de acceso completo a un archivo .ico o a un archivo que puede contener iconos. Además, el valor devuelto en piIndex es un índice en ese archivo que identifica cuáles de sus iconos se van a usar. Por lo tanto, cuando se omite la marca de GIL_NOTFILENAME, estos valores se pueden pasar a ExtractIcon o ExtractIconEx.

GIL_PERCLASS (0x0004)

Todos los objetos de esta clase tienen el mismo icono. El Shell usa internamente esta marca. Las implementaciones típicas de IExtractIcon no requieren esta marca porque la marca implica que un controlador de iconos no es necesario para resolver el icono por objeto. El método recomendado para implementar iconos por clase es registrar un defaultIcon para la clase .

GIL_PERINSTANCE (0x0002)

Cada objeto de esta clase tiene su propio icono. El Shell usa internamente esta marca para controlar casos como Setup.exe, donde los objetos con nombres idénticos pueden tener iconos diferentes. Las implementaciones típicas de IExtractIcon no requieren esta marca.

GIL_SIMULATEDOC (0x0001)

La aplicación que realiza la llamada debe crear un icono de documento con el icono especificado.

GIL_SHIELD (0x0200)

Solo Windows Vista. La aplicación que llama debe marcar el icono con el escudo UAC.

GIL_FORCENOSHIELD (0x0400)

Solo Windows Vista. La aplicación que realiza la llamada no debe marcar el icono con el escudo UAC.

Valor devuelto

Tipo: HRESULT

Devuelve S_OK si la función devolvió una ubicación válida o S_FALSE si shell debe usar un icono predeterminado. Si la marca GIL_ASYNC se establece en uFlags, el método puede devolver E_PENDING para indicar que la extracción de iconos tardará mucho tiempo.

Comentarios

Cuando un cliente establece la marca de GIL_ASYNC en uFlags y recibe E_PENDING como valor devuelto, normalmente crea un subproceso en segundo plano para extraer el icono. Llama a GetIconLocation desde ese subproceso, sin la marca GIL_ASYNC , para recuperar la ubicación del icono. A continuación, llama a IExtractIcon::Extract para extraer el icono. Devolver E_PENDING implica que el objeto está libre de subprocesos. En otras palabras, varios subprocesos pueden llamarse de forma simultánea de forma segura.

La marca de GIL_DEFAULTICON se establece normalmente en el caso en el que se encuentra el icono deseado, pero ese icono no está presente en la caché de iconos. La extracción de iconos es un proceso en segundo plano de prioridad baja y, como tal, otros procesos pueden retrasarse. El icono predeterminado se mostrará en lugar del icono final durante el tiempo necesario para que se extraiga ese icono final, se agregue a la memoria caché y esté disponible.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	shlobj_core.h
Archivo DLL	Shell32.dll (versión 4.0 o posterior)