Función SHGetFolderPathA (shlobj_core.h)

  • Artículo

Desusado. Obtiene la ruta de acceso de una carpeta identificada por un valor CSIDL .

Nota A partir de Windows Vista, esta función es simplemente un contenedor para SHGetKnownFolderPath. El valor CSIDL se traduce a su KNOWNFOLDERID asociado y, a continuación, se llama a SHGetKnownFolderPath . Las nuevas aplicaciones deben usar el sistema de carpetas conocido en lugar del sistema CSIDL anterior, que solo se admite para la compatibilidad con versiones anteriores.
 

Sintaxis

SHFOLDERAPI SHGetFolderPathA(
  [in]  HWND   hwnd,
  [in]  int    csidl,
  [in]  HANDLE hToken,
  [in]  DWORD  dwFlags,
  [out] LPSTR  pszPath
);

Parámetros

[in] hwnd

Tipo: HWND

Reservado.

[in] csidl

Tipo: int

Valor CSIDL que identifica la carpeta cuya ruta de acceso se va a recuperar. Solo las carpetas reales son válidas. Si se especifica una carpeta virtual, se produce un error en esta función. Puede forzar la creación de una carpeta combinando el CSIDL de la carpeta con CSIDL_FLAG_CREATE.

[in] hToken

Tipo: HANDLE

Token de acceso que se puede usar para representar a un usuario determinado.

Microsoft Windows 2000 y versiones anteriores: Establezca siempre este parámetro en NULL.

Windows XP y versiones posteriores: Este parámetro suele establecerse en NULL, pero es posible que tenga que asignar un valor distinto de NULL a hToken para esas carpetas que pueden tener varios usuarios, pero que se tratan como pertenecientes a un único usuario. La carpeta más usada de este tipo es Documentos.

El proceso de llamada es responsable de la suplantación correcta cuando hToken no es NULL. El proceso de llamada debe tener los privilegios de seguridad adecuados para el usuario concreto, incluidos TOKEN_QUERY y TOKEN_IMPERSONATE, y el subárbol del registro del usuario debe montarse actualmente. Consulte Access Control para obtener más información sobre los problemas de control de acceso.

La asignación del parámetro hToken a un valor de -1 indica el usuario predeterminado. Esto permite a los clientes de SHGetFolderPath buscar ubicaciones de carpetas (como la carpeta escritorio) para el usuario predeterminado. El perfil de usuario predeterminado se duplica cuando se crea una nueva cuenta de usuario e incluye carpetas especiales como Mis documentos y escritorio. Los elementos agregados a la carpeta Usuario predeterminado también aparecen en cualquier nueva cuenta de usuario.

[in] dwFlags

Tipo: DWORD

Marcas que especifican la ruta de acceso que se va a devolver. Este valor se usa en los casos en los que la carpeta asociada a un KNOWNFOLDERID (o CSIDL) se puede mover, cambiar el nombre, redirigir o desplazarse entre idiomas por un usuario o administrador.

El sistema de carpetas conocido que subyace a SHGetFolderPath permite a los usuarios o administradores redirigir una carpeta conocida a una ubicación que se adapte a sus necesidades. Esto se logra mediante una llamada a IKnownFolderManager::Redirect, que establece el valor "actual" de la carpeta asociada a la marca SHGFP_TYPE_CURRENT.

El valor predeterminado de la carpeta, que es la ubicación de la carpeta si un usuario o administrador no lo había redirigido a otro lugar, se recupera especificando la marca SHGFP_TYPE_DEFAULT. Este valor se puede usar para implementar una característica de "restauración predeterminada" para una carpeta conocida.

Por ejemplo, el valor predeterminado (SHGFP_TYPE_DEFAULT) para FOLDERID_Music (CSIDL_MYMUSIC) es "C:\Users\user name\Music". Si se redireccionó la carpeta, el valor actual (SHGFP_TYPE_CURRENT) podría ser "D:\Music". Si no se ha redirigido la carpeta, SHGFP_TYPE_DEFAULT y SHGFP_TYPE_CURRENT recuperar la misma ruta de acceso.

SHGFP_TYPE_CURRENT

Recupere la ruta de acceso actual de la carpeta.

SHGFP_TYPE_DEFAULT

Recupere la ruta de acceso predeterminada de la carpeta.

[out] pszPath

Tipo: LPTSTR

Puntero a una cadena terminada en null de longitud MAX_PATH que recibirá la ruta de acceso. Si se produce un error o se devuelve S_FALSE, esta cadena estará vacía. La ruta de acceso devuelta no incluye una barra diagonal inversa final. Por ejemplo, se devuelve "C:\Users" en lugar de "C:\Users\".

Valor devuelto

Tipo: HRESULT

Si esta función se realiza correctamente, devuelve S_OK. De lo contrario, devuelve un código de error de HRESULT.

Comentarios

Esta función es un superconjunto de SHGetSpecialFolderPath.

Solo se admiten algunos valores CSIDL , incluidos los siguientes:

Ejemplos

En el ejemplo de código siguiente se usa SHGetFolderPath para buscar o crear una carpeta y, a continuación, se crea un archivo en él.

TCHAR szPath[MAX_PATH];

if(SUCCEEDED(SHGetFolderPath(NULL, 
                             CSIDL_PERSONAL|CSIDL_FLAG_CREATE, 
                             NULL, 
                             0, 
                             szPath))) 
{
    PathAppend(szPath, TEXT("New Doc.txt"));
    HANDLE hFile = CreateFile(szPath, ...);
}

Requisitos

Requisito Value
Cliente mínimo compatible Windows 2000 Professional, 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 (incluya Shlobj.h, Shlobj_core.h)
Library Shell32.lib
Archivo DLL Shell32.dll (versión 5.0 o posterior)

Consulte también

IKnownFolder::GetPath