Función SHGetFolderPathW (shlobj_core.h)

Artículo
11/20/2024

Obsolescente. Obtiene la ruta de acceso de una carpeta identificada por un valor de 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 SHGetFolderPathW(
  [in]  HWND   hwnd,
  [in]  int    csidl,
  [in]  HANDLE hToken,
  [in]  DWORD  dwFlags,
  [out] LPWSTR pszPath
);

Parámetros

[in] hwnd

Tipo: HWND

Reservado.

[in] csidl

Tipo: int

Valor de 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 de

Un 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 se establece normalmente en null, pero es posible que tenga que asignarun valor NULL que no sea a hToken para esas carpetas que pueden tener varios usuarios, pero que se traten como pertenecientes a un solo 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 esNULL. El proceso de llamada debe tener privilegios de seguridad adecuados para el usuario determinado, incluidos TOKEN_QUERY y TOKEN_IMPERSONATE, y el subárbol del registro del usuario debe estar montado actualmente. Consulte control de acceso para obtener más información sobre los problemas de control de acceso.

Asignar el parámetro hToken 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 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 de

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 llamando 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 en 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) de FOLDERID_Music (CSIDL_MYMUSIC) es "C:\Users\nombre de usuario\Music". Si se redirigió 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: LPWSTR

Puntero a un cadena terminada en nullcadena 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 ejecuta correctamente, devuelve S_OK. De lo contrario, devuelve un hrESULT código de error.

Observaciones

Esta función es un superconjunto de SHGetSpecialFolderPath.

Solo se admiten algunos valores de 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, ...);
}

Nota

El encabezado shlobj_core.h define SHGetFolderPath 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 2000 Professional, 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	shlobj_core.h (incluya Shlobj.h, Shlobj_core.h)
biblioteca de	Shell32.lib
DLL de	Shell32.dll (versión 5.0 o posterior)

Consulte también

IKnownFolder::GetPath

Compartir a través de