Funzione SHSetFolderPathA (shlobj_core.h)

Articolo
03/02/2024

Deprecato. Assegna un nuovo percorso a una cartella di sistema identificata dal relativo CSIDL.

Sintassi

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

Parametri

[in] csidl

Tipo: int

Valore CSIDL che identifica la cartella il cui percorso deve essere impostato. Sono valide solo le cartelle fisiche. Se viene specificata una cartella virtuale, questa funzione ha esito negativo.

Aggiungere il valore CSIDL_FLAG_DONT_UNEXPAND al linguaggio CSIDL per assicurarsi che la stringa venga scritta nel Registro di sistema esattamente come specificato. Se il flag CSIDL_FLAG_DONT_UNEXPAND non è incluso, le parti del percorso possono essere sostituite da stringhe di ambiente, ad esempio %USERPROFILE%.

[in] hToken

Tipo: HANDLE

Token di accesso che può essere usato per rappresentare un determinato utente. Questo parametro è in genere impostato su NULL, nel qual caso la funzione tenta di accedere all'istanza dell'utente corrente della cartella. Tuttavia, potrebbe essere necessario assegnare un valore a hToken per le cartelle che possono avere più utenti, ma vengono considerate come appartenenti a un singolo utente. La cartella più comunemente usata di questo tipo è Documents.

L'applicazione chiamante è responsabile della rappresentazione corretta quando hToken è diverso da Null. Deve disporre di privilegi di sicurezza appropriati per l'utente specifico, inclusi TOKEN_QUERY e TOKEN_IMPERSONATE, e l'hive del Registro di sistema dell'utente deve essere attualmente montato. Per altre informazioni sui problemi di controllo di accesso, vedere Controllo di accesso.

[in] dwFlags

Tipo: DWORD

Riservato. Deve essere 0.

[in] pszPath

Tipo: LPCTSTR

Puntatore a una stringa con terminazione Null di lunghezza MAX_PATH che contiene il nuovo percorso della cartella. Questo valore non può essere NULL e la stringa non può essere di lunghezza zero.

Valore restituito

Tipo: HRESULT

Restituisce codici HRESULT standard, inclusi i seguenti:

Codice restituito	Descrizione
S_OK	Il percorso della cartella è stato aggiornato correttamente.
E_INVALIDARG	Diverse condizioni di errore causano la restituzione di questo valore, tra cui: Il valore csidl non è valido. Il valore csidl non fa riferimento a una cartella virtuale. Il valore csidl non fa riferimento a una cartella di sistema. Il valore csidl fa riferimento a una cartella che non può essere rinominata o spostata. Il valore dwFlags non è 0 (zero). Il valore pszPath è NULL. La stringa a cui punta il valore pszPath è una stringa vuota ("") di lunghezza zero.

Codice restituito

Descrizione

S_OK

Il percorso della cartella è stato aggiornato correttamente.

E_INVALIDARG

Diverse condizioni di errore causano la restituzione di questo valore, tra cui:

Il valore csidl non è valido.
Il valore csidl non fa riferimento a una cartella virtuale.
Il valore csidl non fa riferimento a una cartella di sistema.
Il valore csidl fa riferimento a una cartella che non può essere rinominata o spostata.
Il valore dwFlags non è 0 (zero).
Il valore pszPath è NULL.
La stringa a cui punta il valore pszPath è una stringa vuota ("") di lunghezza zero.

Commenti

Nota A partire da Windows Vista, questa funzione è semplicemente un wrapper per SHSetKnownFolderPath. Il valore CSIDL viene convertito nel valore KNOWNFOLDERID associato e viene chiamato SHSetKnownFolderPath . Le nuove applicazioni devono usare il sistema di cartelle note anziché il sistema CSIDL precedente, supportato solo per la compatibilità con le versioni precedenti.

SHSetFolderPath non viene esportato per nome da Shell32.dll. Per usare la funzione, è necessario chiamare GetProcAddress con ordinale 231 per SHSetFolderPathA (per le stringhe ANSI) o ordinale 232 per SHSetFolderPathW (per le stringhe Unicode) per ottenere un puntatore a funzione.

È consigliabile esprimere i percorsi come stringhe Unicode perché i nomi delle cartelle potrebbero contenere caratteri Unicode non espressi in ANSI.

Nota

L'intestazione shlobj_core.h definisce SHSetFolderPath come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	shlobj_core.h (include Shlobj.h, Shlobj_core.h)
Libreria	Shell32.lib
DLL	Shell32.dll (versione 5.0 o successiva)

Vedi anche

IKnownFolder::SetPath

Share via