Función SHGetKnownFolderPath (shlobj_core.h)

Recupera la ruta de acceso completa de una carpeta conocida identificada por el KNOWNFOLDERID de la carpeta.

Sintaxis

HRESULT SHGetKnownFolderPath(
  [in]           REFKNOWNFOLDERID rfid,
  [in]           DWORD            dwFlags,
  [in, optional] HANDLE           hToken,
  [out]          PWSTR            *ppszPath
);

Parámetros

[in] rfid

Tipo: REFKNOWNFOLDERID

Referencia al KNOWNFOLDERID que identifica la carpeta.

[in] dwFlags

Tipo: DWORD

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

[in, optional] hToken

Tipo: HANDLE

Token de acceso que representa a un usuario determinado. Si este parámetro es NULL, que es el uso más común, la función solicita la carpeta conocida para el usuario actual.

Solicite la carpeta de un usuario específico pasando el hToken de ese usuario. Esto suele hacerse en el contexto de un servicio que tiene privilegios suficientes para recuperar el token de un usuario determinado. Ese token debe abrirse con derechos de TOKEN_QUERY y TOKEN_IMPERSONATE . En algunos casos, también debe incluir TOKEN_DUPLICATE. Además de pasar el hToken del usuario, se debe montar el subárbol del Registro de ese usuario específico. 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 SHGetKnownFolderPath 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] ppszPath

Tipo: PWSTR*

Cuando este método devuelve, contiene la dirección de un puntero a una cadena Unicode terminada en null que especifica la ruta de acceso de la carpeta conocida. El proceso de llamada es responsable de liberar este recurso una vez que ya no es necesario mediante una llamada a CoTaskMemFree, independientemente de si SHGetKnownFolderPath se realiza correctamente o no. 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

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

Código devuelto	Descripción
E_FAIL	Entre otras cosas, este valor puede indicar que el parámetro rfid hace referencia a un KNOWNFOLDERID que no tiene una ruta de acceso (como una carpeta marcada como KF_CATEGORY_VIRTUAL).
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 del sistema actual.

Comentarios

Esta función reemplaza SHGetFolderPath. Esa función anterior ahora es simplemente un contenedor para SHGetKnownFolderPath.

Requisitos

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)
Archivo DLL	Shell32.dll (versión 6.0.6000 o posterior)

Consulte también

IKnownFolder::GetPath

Ejemplo de carpetas conocidas

SHGetKnownFolderIDList

SHSetKnownFolderPath