Compartir a través de

Función SHSetFolderPathA (shlobj_core.h)

  • Artículo

Obsolescente. 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 de 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 CSIDL_FLAG_DONT_UNEXPAND, las partes de la ruta de acceso se pueden reemplazar por cadenas de entorno, como %USERPROFILE%.

[in] hToken

Tipo: HANDLE de

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 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.

[in] dwFlags

Tipo: DWORD de

Reservado. Debe establecerse en 0.

[in] pszPath

Tipo: LPCTSTR de

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 NULLy la cadena no puede ser de longitud cero.

Valor devuelto

Tipo: HRESULT

Devuelve los códigos de 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, incluido lo siguiente:
  • El valor de csidl no es válido.
  • El valor csidl no hace referencia a una carpeta virtual.
  • El valor de 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 dwFlags valor no es 0 (cero).
  • El valor de pszPath es NULL.
  • La cadena a la que apunta valor pszPath es una cadena vacía ("") de longitud cero.

Observaciones

Nota As de Windows Vista, esta función es simplemente un contenedor para SHSetKnownFolderPath. El valor CSIDL se traduce a su KNOWNFOLDERID 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 expresar las rutas de acceso 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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito Valor
cliente mínimo admitido Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido Windows Server 2003 [solo aplicaciones de escritorio]
de la plataforma de destino de Windows
encabezado de shlobj_core.h (incluya Shlobj.h, Shlobj_core.h)
biblioteca de Shell32.lib
DLL de Shell32.dll (versión 5.0 o posterior)

Consulte también

IKnownFolder::SetPath