Función SHGetKnownFolderIDList (shlobj_core.h)

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

Sintaxis

HRESULT SHGetKnownFolderIDList(
  [in]  REFKNOWNFOLDERID rfid,
  [in]  DWORD            dwFlags,
  [in]  HANDLE           hToken,
  [out] PIDLIST_ABSOLUTE *ppidl
);

Parámetros

[in] rfid

Tipo: REFKNOWNFOLDERID

Referencia a KNOWNFOLDERID que identifica la carpeta. Es posible que las carpetas asociadas a los identificadores de carpeta conocidos no existan en un sistema determinado.

[in] dwFlags

Tipo: DWORD

Marcas que especifican opciones de recuperación especiales. Este valor puede ser 0; de lo contrario, es uno o varios de los valores de KNOWN_FOLDER_FLAG .

[in] hToken

Tipo: HANDLE

Un token de acceso que se usa para representar a un usuario determinado. Este parámetro normalmente se establece en NULL, en cuyo caso la función intenta acceder a la instancia del usuario actual de la carpeta. Sin embargo, es posible que tenga que asignar un valor a hToken para esas carpetas que pueden tener varios usuarios, pero que se tratan como pertenecientes a un solo usuario. La carpeta más usada de este tipo es Documentos.

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

Al asignar el parámetro hToken un valor de -1, se indica el usuario predeterminado. Esto permite a los clientes de SHGetKnownFolderIDList 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 Documentos y Escritorio. Los elementos agregados a la carpeta Usuario predeterminado también aparecen en cualquier nueva cuenta de usuario. Tenga en cuenta que el acceso a las carpetas de usuario predeterminado requiere privilegios de administrador.

[out] ppidl

Tipo: PIDLIST_ABSOLUTE*

Cuando este método devuelve, contiene un puntero al PIDL de la carpeta. Este parámetro se pasa sin inicializar. El autor de la llamada es responsable de liberar el PIDL devuelto cuando ya no es necesario llamando a ILFree.

Valor devuelto

Tipo: HRESULT

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

Código devuelto	Descripción
E_INVALIDARG	Entre otras cosas, este valor puede indicar que el parámetro rfid hace referencia a un KNOWNFOLDERID que no está presente en el sistema. No todos los valores KNOWNFOLDERID están presentes en todos los sistemas. Use IKnownFolderManager::GetFolderIds para recuperar el conjunto de valores KNOWNFOLDERID para el sistema actual.

Comentarios

Esta función reemplaza SHGetFolderLocation. Esa función anterior ahora es simplemente un contenedor para SHGetKnownFolderIDList.

Los autores de llamadas que usan esta función deben tener al menos privilegios de usuario.

Algunas carpetas conocidas, por ejemplo, la carpeta Documentos , son por usuario. Cada usuario tiene una ruta de acceso diferente para la carpeta Documentos . Si hToken es NULL, la API intenta acceder a la instancia del usuario actual de la carpeta. Si hToken es un token de usuario válido, la API intenta suplantar al usuario mediante este token e intenta acceder a la instancia de ese usuario de la carpeta.

Requisitos

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

Consulte también

IKnownFolder::GetPath

Ejemplo de carpetas conocidas

SHGetKnownFolderPath

SHSetKnownFolderPath