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 de
Puntero a un cadena terminadanull 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 de 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 de
Combinación de una o varias marcas de atributos de archivo (FILE_ATTRIBUTE_ valores tal como se define en Winnt.h). Si uFlags no incluye la marca SHGFI_USEFILEATTRIBUTES, este parámetro se omite.
[in, out] psfi
Puntero a una estructura de SHFILEINFO para recibir la información del archivo.
cbFileInfo
Tipo: UINT
Tamaño, en bytes, de la estructura de 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 siguientes valores.
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 dwAttributes miembro 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
SHGFI_DISPLAYNAME (0x000000200)
Recupere el nombre para mostrar del archivo, que es el nombre tal 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
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 método 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 abierto 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 icono de apertura pequeño 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
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 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 tener acceso al archivo especificado por pszPath. En su lugar, debe actuar como si el archivo especificado por pszPath existe con los atributos de archivo pasados en dwFileAttributes. Esta marca no se puede combinar con las marcas SHGFI_ATTRIBUTES, SHGFI_EXETYPEo 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 de lo contrario.
Si uFlags contiene la marca SHGFI_EXETYPE, el valor devuelto especifica el tipo del archivo ejecutable. Será uno de los siguientes valores.
| Código devuelto | Descripción |
|---|---|
|
Archivo nonexecutable o una condición de error. |
|
Aplicación Windows. |
|
archivo de MS-DOS .exe o .com |
|
Aplicación de consola o archivo de .bat |
Observaciones
Debe llamar a esta función desde un subproceso en segundo plano. Si no lo hace, la interfaz de usuario podría dejar de responder.
Si SHGetFileInfo devuelve un identificador de icono en el miembro hIcon del SHFILEINFO estructura apuntada por psfi, usted es responsable de liberarlo con DestroyIcon cuando ya no lo necesite.
Cuando se usa la marca SHGFI_EXETYPE con una aplicación de Windows, la versión de Windows del archivo ejecutable se da en el 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, consulte Using the Windows Headers.
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 Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Windows XP [solo aplicaciones de escritorio] |
| servidor mínimo admitido | Windows 2000 Server [solo aplicaciones de escritorio] |
| de la plataforma de destino de |
Windows |
| encabezado de |
shellapi.h |
| biblioteca de |
Shell32.lib |
| DLL de |
Shell32.dll (versión 4.0 o posterior) |