Función SHSetFolderPathA (shlobj_core.h)

  • Artículo

Desusado. Asigna una nueva ruta de acceso a una carpeta del sistema identificada por su CSIDL.

Sintaxis

HRESULT SHSetFolderPathA(
  [in] int    csidl,
  [in] HANDLE hToken,
  [in] DWORD  dwFlags,
  [in] LPCSTR pszPath
);

Parámetros

[in] csidl

Tipo: int

Valor CSIDL que identifica la carpeta cuya ruta de acceso se va a establecer. Solo las carpetas físicas son válidas. Si se especifica una carpeta virtual, se produce un error en esta función.

Agregue el valor CSIDL_FLAG_DONT_UNEXPAND al CSIDL para asegurarse de que la cadena se escribe en el registro exactamente como se proporciona. Si no se incluye la marca de CSIDL_FLAG_DONT_UNEXPAND , las partes de la ruta de acceso se pueden reemplazar por cadenas de entorno, como %USERPROFILE%.

[in] hToken

Tipo: HANDLE

Un token de acceso que se puede usar 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.

[in] dwFlags

Tipo: DWORD

Reservado. Se debe establecer en 0.

[in] pszPath

Tipo: LPCTSTR

Puntero a una cadena terminada en null de longitud MAX_PATH que contiene la nueva ruta de acceso de la carpeta. Este valor no puede ser NULL y la cadena no puede tener una longitud cero.

Valor devuelto

Tipo: HRESULT

Devuelve códigos HRESULT estándar, incluidos los siguientes:

Código devuelto Descripción
S_OK
 La ruta de acceso de la carpeta se actualizó correctamente.
E_INVALIDARG
 Varias condiciones de error provocan la devolución de este valor, incluidos los siguientes:
  • El valor csidl no es válido.
  • El valor csidl no hace referencia a una carpeta virtual.
  • El valor csidl no hace referencia a una carpeta del sistema.
  • El valor csidl hace referencia a una carpeta que no se puede cambiar ni mover.
  • El valor dwFlags no es 0 (cero).
  • El valor pszPath es NULL.
  • La cadena a la que apunta el valor pszPath es una cadena vacía ("") de longitud cero.

Comentarios

Nota A partir de Windows Vista, esta función es simplemente un contenedor para SHSetKnownFolderPath. El valor CSIDL se traduce a su KNOWNFOLDERID asociado y se llama a SHSetKnownFolderPath . 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.
 
SHSetFolderPath no se exporta por nombre desde Shell32.dll. Para usar la función, debe llamar a GetProcAddress con ordinal 231 para SHSetFolderPathA (para cadenas ANSI) o ordinal 232 para SHSetFolderPathW (para cadenas Unicode) para obtener un puntero de función.

Se recomienda que las rutas de acceso se expresen como cadenas Unicode porque los nombres de carpeta pueden contener caracteres Unicode no expresables en ANSI.

Nota

El encabezado shlobj_core.h define SHSetFolderPath como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito Value
Cliente mínimo compatible 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, Shlobj_core.h)
Library Shell32.lib
Archivo DLL Shell32.dll (versión 5.0 o posterior)

Consulte también

IKnownFolder::SetPath