Función SHSetKnownFolderPath (shlobj_core.h)

Redirige una carpeta conocida a una nueva ubicación.

Syntax

HRESULT SHSetKnownFolderPath(
  [in] REFKNOWNFOLDERID rfid,
  [in] DWORD            dwFlags,
  [in] HANDLE           hToken,
  [in] PCWSTR           pszPath
);

Parámetros

[in] rfid

Tipo: REFKNOWNFOLDERID

GUID que identifica la carpeta conocida.

[in] dwFlags

Tipo: DWORD

0 o el valor siguiente.

KF_FLAG_DONT_UNEXPAND

Si se establece esta marca, las partes de la ruta de acceso a la que hace referencia pszPath se pueden representar mediante cadenas de entorno como %USERPROFILE%.

[in] hToken

Tipo: HANDLE de

Token de acceso usado para representar a un usuario determinado. Este parámetro se establece normalmente 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 único 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 en particular, 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 SHSetKnownFolderPath establecer ubicaciones de carpeta (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 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] pszPath

Tipo: PCWSTR

Puntero a la nueva ruta de acceso de la carpeta. Se trata de una cadena Unicode terminada en NULL de longitud MAX_PATH. Esta ruta de acceso no puede tener una longitud cero.

Valor devuelto

Tipo: HRESULT

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

Observaciones

Esta función reemplaza SHSetFolderPath. Esa función anterior ahora es simplemente un contenedor para SHSetKnownFolderPath.

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

Consulte también

IKnownFolder::GetPath

IKnownFolder::SetPath

IKnownFolderManager::Redirect

Ejemplo de carpetas conocidas

SHGetKnownFolderIDList

SHGetKnownFolderPath