Función SHGetFileInfoA (shellapi.h)
Recupera información sobre un objeto en el sistema de archivos, como un archivo, una carpeta, un directorio o una raíz de unidad.
Sintaxis
DWORD_PTR SHGetFileInfoA(
[in] LPCSTR pszPath,
DWORD dwFileAttributes,
[in, out] SHFILEINFOA *psfi,
UINT cbFileInfo,
UINT uFlags
);
Parámetros
[in] pszPath
Tipo: LPCTSTR
Puntero a una cadena terminada en null de longitud máxima MAX_PATH que contiene la ruta de acceso y el nombre de archivo. Las rutas de acceso absolutas y relativas son válidas.
Si el parámetro uFlags incluye la marca SHGFI_PIDL , este parámetro debe ser la dirección de una estructura ITEMIDLIST (PIDL) que contiene la lista de identificadores de elemento que identifica de forma única el archivo dentro del espacio de nombres del Shell. El PIDL debe ser un PIDL completo. No se permiten PIN relativos.
Si el parámetro uFlags incluye la marca SHGFI_USEFILEATTRIBUTES , este parámetro no tiene que ser un nombre de archivo válido. La función continuará como si el archivo exista con el nombre especificado y con los atributos de archivo pasados en el parámetro dwFileAttributes . Esto le permite obtener información sobre un tipo de archivo pasando solo la extensión para pszPath y pasando FILE_ATTRIBUTE_NORMAL en dwFileAttributes.
Esta cadena puede usar nombres de archivo cortos (el formulario 8.3) o largos.
dwFileAttributes
Tipo: DWORD
Combinación de una o varias marcas de atributo de archivo (FILE_ATTRIBUTE_ valores como se define en Winnt.h). Si uFlags no incluye la marca SHGFI_USEFILEATTRIBUTES , este parámetro se omite.
[in, out] psfi
Tipo: SHFILEINFO*
Puntero a una estructura SHFILEINFO para recibir la información del archivo.
cbFileInfo
Tipo: UINT
Tamaño, en bytes, de la estructura SHFILEINFO a la que apunta el parámetro psfi .
uFlags
Tipo: UINT
Marcas que especifican la información del archivo que se va a recuperar. Este parámetro puede ser una combinación de los valores siguientes.
SHGFI_ADDOVERLAYS (0x000000020)
Versión 5.0. Aplique las superposiciones adecuadas al icono del archivo. También se debe establecer la marca SHGFI_ICON .
SHGFI_ATTR_SPECIFIED (0x000020000)
Modifique SHGFI_ATTRIBUTES para indicar que el miembro dwAttributes de la estructura SHFILEINFO en psfi contiene los atributos específicos que se desean. Estos atributos se pasan a IShellFolder::GetAttributesOf. Si no se especifica esta marca, 0xFFFFFFFF se pasa a IShellFolder::GetAttributesOf, solicitando todos los atributos. Esta marca no se puede especificar con la marca SHGFI_ICON .
SHGFI_ATTRIBUTES (0x000000800)
Recupere los atributos de elemento. Los atributos se copian en el miembro dwAttributes de la estructura especificada en el parámetro psfi . Estos son los mismos atributos que se obtienen de IShellFolder::GetAttributesOf.
SHGFI_DISPLAYNAME (0x000000200)
Recupere el nombre para mostrar del archivo, que es el nombre tal y como aparece en el Explorador de Windows. El nombre se copia en el miembro szDisplayName de la estructura especificada en psfi. El nombre para mostrar devuelto usa el nombre de archivo largo, si hay uno, en lugar del formato 8.3 del nombre de archivo. Tenga en cuenta que el nombre para mostrar puede verse afectado por la configuración, como si se muestran extensiones.
SHGFI_EXETYPE (0x000002000)
Recupere el tipo del archivo ejecutable si pszPath identifica un archivo ejecutable. La información se empaqueta en el valor devuelto. Esta marca no se puede especificar con ninguna otra marca.
SHGFI_ICON (0x000000100)
Recupere el identificador del icono que representa el archivo y el índice del icono dentro de la lista de imágenes del sistema. El identificador se copia en el miembro hIcon de la estructura especificada por psfi y el índice se copia en el miembro iIcon .
SHGFI_ICONLOCATION (0x000001000)
Recupere el nombre del archivo que contiene el icono que representa el archivo especificado por pszPath, tal y como devuelve el método IExtractIcon::GetIconLocation del controlador de iconos del archivo. Recupere también el índice de icono dentro de ese archivo. El nombre del archivo que contiene el icono se copia en el miembro szDisplayName de la estructura especificada por psfi. El índice del icono se copia en el miembro iIcon de esa estructura.
SHGFI_LARGEICON (0x000000000)
Modifique SHGFI_ICON, lo que hace que la función recupere el icono grande del archivo. También se debe establecer la marca SHGFI_ICON .
SHGFI_LINKOVERLAY (0x000008000)
Modifique SHGFI_ICON, lo que hace que la función agregue la superposición de vínculo al icono del archivo. También se debe establecer la marca SHGFI_ICON .
SHGFI_OPENICON (0x000000002)
Modifique SHGFI_ICON, lo que hace que la función recupere el icono de apertura del archivo. También se usa para modificar SHGFI_SYSICONINDEX, lo que hace que la función devuelva el identificador a la lista de imágenes del sistema que contiene el pequeño icono de apertura del archivo. Un objeto contenedor muestra un icono abierto para indicar que el contenedor está abierto. También se debe establecer la marca SHGFI_ICON o SHGFI_SYSICONINDEX .
SHGFI_OVERLAYINDEX (0x000000040)
Versión 5.0. Devuelve el índice del icono de superposición. El valor del índice de superposición se devuelve en los ocho bits superiores del miembro iIcon de la estructura especificada por psfi. Esta marca requiere que también se establezca el SHGFI_ICON .
SHGFI_PIDL (0x000000008)
Indique que pszPath es la dirección de una estructura ITEMIDLIST en lugar de un nombre de ruta de acceso.
SHGFI_SELECTED (0x000010000)
Modifique SHGFI_ICON, lo que hace que la función combine el icono del archivo con el color de resaltado del sistema. También se debe establecer la marca SHGFI_ICON .
SHGFI_SHELLICONSIZE (0x000000004)
Modifique SHGFI_ICON, lo que hace que la función recupere un icono de tamaño de Shell. Si no se especifica esta marca, la función cambia el tamaño del icono según los valores de la métrica del sistema. También se debe establecer la marca SHGFI_ICON .
SHGFI_SMALLICON (0x000000001)
Modifique SHGFI_ICON, lo que hace que la función recupere el icono pequeño del archivo. También se usa para modificar SHGFI_SYSICONINDEX, lo que hace que la función devuelva el identificador a la lista de imágenes del sistema que contiene imágenes de icono pequeñas. También se debe establecer la marca SHGFI_ICON o SHGFI_SYSICONINDEX .
SHGFI_SYSICONINDEX (0x000004000)
Recupere el índice de un icono de lista de imágenes del sistema. Si se ejecuta correctamente, el índice se copia en el miembro iIcon de psfi. El valor devuelto es un identificador de la lista de imágenes del sistema. Solo las imágenes cuyos índices se copian correctamente en iIcon son válidos. Si intenta acceder a otras imágenes de la lista de imágenes del sistema, se producirá un comportamiento indefinido.
SHGFI_TYPENAME (0x000000400)
Recupere la cadena que describe el tipo del archivo. La cadena se copia en el miembro szTypeName de la estructura especificada en psfi.
SHGFI_USEFILEATTRIBUTES (0x000000010)
Indica que la función no debe intentar acceder al archivo especificado por pszPath. En su lugar, debe actuar como si el archivo especificado por pszPath exista con los atributos de archivo pasados en dwFileAttributes. Esta marca no se puede combinar con las marcas SHGFI_ATTRIBUTES, SHGFI_EXETYPE o SHGFI_PIDL .
Valor devuelto
Tipo: DWORD_PTR
Devuelve un valor cuyo significado depende del parámetro uFlags .
Si uFlags no contiene SHGFI_EXETYPE o SHGFI_SYSICONINDEX, el valor devuelto es distinto de cero si es correcto o cero en caso contrario.
Si uFlags contiene la marca SHGFI_EXETYPE , el valor devuelto especifica el tipo del archivo ejecutable. Será uno de los valores siguientes.
| Código devuelto | Descripción |
|---|---|
|
Archivo nonexecutable o una condición de error. |
|
Aplicación Windows. |
|
Archivo de .exe o .com MS-DOS |
|
Aplicación de consola o archivo de .bat |
Comentarios
Debe llamar a esta función desde un subproceso en segundo plano. Si no lo hace, la interfaz de usuario dejará de responder.
Si SHGetFileInfo devuelve un identificador de icono en el miembro hIcon de la estructura SHFILEINFO a la que apunta psfi, usted es responsable de liberarlo con DestroyIcon cuando ya no lo necesite.
Cuando se usa la marca de SHGFI_EXETYPE con una aplicación de Windows, la versión de Windows del ejecutable se asigna en la HIWORD del valor devuelto. Esta versión se devuelve como un valor hexadecimal. Para obtener más información sobre cómo equiparar este valor con una versión específica de Windows, consulta Usar los encabezados de Windows.
Ejemplos
En el ejemplo de código siguiente se usa SHGetFileInfo para recuperar el nombre para mostrar de la Papelera de reciclaje, identificado por su PIDL.
LPITEMIDLIST pidl = NULL;
hr = SHGetFolderLocation(NULL, CSIDL_BITBUCKET, NULL, 0, &pidl);
if (SUCCEEDED(hr))
{
SHFILEINFOW sfi = {0};
hr = SHGetFileInfo((LPCTSTR)pidl,
-1,
&sfi,
sizeof(sfi),
SHGFI_PIDL | SHGFI_DISPLAYNAME)
if (SUCCEEDED(hr))
{
// The display name is now held in sfi.szDisplayName.
}
}
ILFree(pidl);
Nota
El encabezado shellapi.h define SHGetFileInfo como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.
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 | shellapi.h |
| Library | Shell32.lib |
| Archivo DLL | Shell32.dll (versión 4.0 o posterior) |