Funzione SHSetKnownFolderPath (shlobj_core.h)

Articolo
03/15/2023

Reindirizza una cartella nota a un nuovo percorso.

Sintassi

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

Parametri

[in] rfid

Tipo: REFKNOWNFOLDERID

GUID che identifica la cartella nota.

[in] dwFlags

Tipo: DWORD

0 o il valore seguente.

KF_FLAG_DONT_UNEXPAND

Se questo flag è impostato, le parti del percorso a cui fa riferimento pszPath possono essere rappresentate da stringhe di ambiente, ad %USERPROFILE%esempio .

[in] hToken

Tipo: HANDLE

Token di accesso 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.

Se si assegna il parametro hToken , il valore -1 indica l'utente predefinito. Ciò consente ai client di SHSetKnownFolderPath di impostare i percorsi delle cartelle (ad esempio la cartella Desktop ) per l'utente predefinito. Il profilo utente predefinito viene duplicato quando viene creato un nuovo account utente e include cartelle speciali come Documenti e Desktop. Tutti gli elementi aggiunti alla cartella Utente predefinito vengono visualizzati anche in qualsiasi nuovo account utente. Si noti che l'accesso alle cartelle Utente predefinite richiede privilegi di amministratore.

[in] pszPath

Tipo: PCWSTR

Puntatore al nuovo percorso della cartella. Stringa Unicode con terminazione Null MAX_PATH. Questo percorso non può essere di lunghezza zero.

Valore restituito

Tipo: HRESULT

Restituisce S_OK in caso di esito positivo o un valore di errore, incluso quanto segue:

Codice restituito	Descrizione
E_INVALIDARG	Tra le altre cose, questo valore può indicare che il parametro rfid fa riferimento a un KNOWNFOLDERID che non è presente nel sistema. Non tutti i valori KNOWNFOLDERID sono presenti in tutti i sistemi. Usare IKnownFolderManager::GetFolderIds per recuperare il set di valori KNOWNFOLDERID per il sistema corrente.

Commenti

Questa funzione sostituisce SHSetFolderPath. Questa funzione precedente è ora semplicemente un wrapper per SHSetKnownFolderPath.

Il chiamante di questa funzione deve avere privilegi di amministratore. Per chiamare questa funzione nelle cartelle note pubbliche, il chiamante deve disporre dei privilegi di amministratore. Per le cartelle note per utente il chiamante richiede solo privilegi utente.

Alcune delle cartelle note, ad esempio la cartella Documenti , sono per utente. Ogni utente ha un percorso diverso per la cartella Documenti . Se hToken è NULL, l'API tenta di accedere all'istanza dell'applicazione chiamante della cartella, ovvero quella dell'utente corrente. Se hToken è un token utente valido, l'API tenta di rappresentare l'utente usando questo token e tenta di accedere all'istanza dell'utente.

Questa funzione non può essere chiamata nelle cartelle di tipo KF_CATEGORY_FIXED e KF_CATEGORY_VIRTUAL.

Per chiamare questa funzione in una cartella di tipo KF_CATEGORY_COMMON, l'applicazione chiamante deve essere in esecuzione con privilegi elevati.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	shlobj_core.h (includere Shlobj.h)
DLL	Shell32.dll (versione 6.0.6000 o successiva)