Función SHGetKnownFolderItem (shlobj_core.h)
Recupera un objeto IShellItem que representa una carpeta conocida.
Sintaxis
HRESULT SHGetKnownFolderItem(
[in] REFKNOWNFOLDERID rfid,
[in] KNOWN_FOLDER_FLAG flags,
[in] HANDLE hToken,
[in] REFIID riid,
[out] void **ppv
);
Parámetros
[in] rfid
Tipo: REFKNOWNFOLDERID
Referencia a KNOWNFOLDERID, un GUID que identifica la carpeta que contiene el elemento.
[in] flags
Tipo: KNOWN_FOLDER_FLAG
Marcas que especifican opciones especiales usadas en la recuperación de la carpeta conocida IShellItem. Este valor puede ser KF_FLAG_DEFAULT; de lo contrario, 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 SHSetKnownFolderPath establecer 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.
[in] riid
Tipo: REFIID
Referencia al IID de la interfaz que representa el elemento, normalmente IID_IShellItem o IID_IShellItem2.
[out] ppv
Tipo: void**
Cuando este método devuelve, contiene el puntero de interfaz solicitado en riid.
Valor devuelto
Tipo: HRESULT
Devuelve S_OK si se ejecuta correctamente o un valor de error, incluido lo siguiente:
Código devuelto | Descripción |
---|---|
|
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
El autor de la llamada de esta función debe tener privilegios de administrador. Para llamar a esta función en carpetas conocidas públicas, el autor de la llamada debe tener privilegios de administrador. Para las carpetas conocidas por usuario, el autor de la llamada solo requiere privilegios de usuario.
Algunas de las carpetas conocidas, por ejemplo, la carpeta Documentos , son por usuario. Cada usuario tiene una ruta de acceso diferente para su carpeta Documentos . Si hToken es NULL, la API intenta acceder a la instancia de la aplicación que realiza la llamada de la carpeta , que es la del usuario actual. 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.
No se puede llamar a esta función en carpetas de tipo KF_CATEGORY_FIXED y KF_CATEGORY_VIRTUAL.
Para llamar a esta función en una carpeta de tipo KF_CATEGORY_COMMON, la aplicación que realiza la llamada debe ejecutarse con privilegios elevados.
Requisitos
Requisito | Value |
---|---|
Cliente mínimo compatible | Windows 7 [solo aplicaciones de escritorio] |
Servidor mínimo compatible | Windows Server 2008 R2 [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.1 o posterior) |
Conjunto de API | ext-ms-win-shell-shell32-l1-2-1 (introducido en Windows 10, versión 10.0.10240) |