Función SHGetFolderLocation (shlobj_core.h)

  • Artículo

Desusado. Recupera la ruta de acceso de una carpeta como una estructura ITEMIDLIST .

Sintaxis

SHSTDAPI SHGetFolderLocation(
  [in]  HWND             hwnd,
  [in]  int              csidl,
  [in]  HANDLE           hToken,
  [in]  DWORD            dwFlags,
  [out] PIDLIST_ABSOLUTE *ppidl
);

Parámetros

[in] hwnd

Tipo: HWND

Reservado.

[in] csidl

Tipo: int

Valor CSIDL que identifica la carpeta que se va a ubicar. Es posible que las carpetas asociadas a los CSIDLs no existan en un sistema determinado.

[in] hToken

Tipo: HANDLE

Token de acceso que se puede usar para representar a un usuario determinado. Normalmente se establece en NULL, pero puede ser necesario cuando hay varios usuarios para esas carpetas que se tratan como pertenecientes a un único usuario. La carpeta más usada de este tipo es Mis documentos. La aplicación que realiza la llamada es responsable de la suplantación correcta cuando hToken no es NULL. Debe tener los privilegios de seguridad adecuados para el usuario concreto 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 SHGetFolderLocation 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

[out] ppidl

Tipo: PIDLIST_ABSOLUTE*

Dirección de un puntero a una estructura de lista de identificadores de elemento que especifica la ubicación de la carpeta relativa a la raíz del espacio de nombres (el escritorio). El parámetro ppidl se establece en NULL en caso de error. La aplicación que realiza la llamada es responsable de liberar este recurso mediante una llamada a ILFree.

Valor devuelto

Tipo: HRESULT

Devuelve S_OK si se ejecuta correctamente o un valor de error de lo contrario, incluido lo siguiente:

Código devuelto Descripción
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)
 CsiDL en nFolder es válido, pero la carpeta no existe.
E_INVALIDARG
 El CSIDL en nFolder no es válido.

Comentarios

Nota A partir de Windows Vista, esta función es simplemente un contenedor para SHGetKnownFolderIDList. El valor CSIDL se traduce a su KNOWNFOLDERID asociado y se llama a SHGetKnownFolderIDList . 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.
 
Las funciones SHGetFolderLocation, SHGetFolderPath, SHGetSpecialFolderLocation y SHGetSpecialFolderPath son las formas preferidas de obtener identificadores de carpetas en sistemas anteriores a Windows Vista. Es posible que las funciones como ExpandEnvironmentStrings que usen los nombres de variables de entorno directamente, con el formato %VariableName%, no sean confiables.

Esta función es un superconjunto de SHGetSpecialFolderLocation, incluido con versiones anteriores del Shell.

Requisitos

Requisito Value
Cliente mínimo compatible Windows 2000 Professional, Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado shlobj_core.h (incluya Shlobj.h)
Library Shell32.lib
Archivo DLL Shell32.dll (versión 5.0 o posterior)

Consulte también

IKnownFolder::GetIDList