Funzione SHGetKnownFolderItem (shlobj_core.h)

Articolo
03/15/2023

Recupera un oggetto IShellItem che rappresenta una cartella nota.

Sintassi

HRESULT SHGetKnownFolderItem(
  [in]  REFKNOWNFOLDERID  rfid,
  [in]  KNOWN_FOLDER_FLAG flags,
  [in]  HANDLE            hToken,
  [in]  REFIID            riid,
  [out] void              **ppv
);

Parametri

[in] rfid

Tipo: REFKNOWNFOLDERID

Riferimento a KNOWNFOLDERID, UN GUID che identifica la cartella che contiene l'elemento.

[in] flags

Tipo: KNOWN_FOLDER_FLAG

Flag che specificano opzioni speciali usate nel recupero della cartella nota IShellItem. Questo valore può essere KF_FLAG_DEFAULT; in caso contrario, uno o più dei valori KNOWN_FOLDER_FLAG .

[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] riid

Tipo: REFIID

Riferimento all'IID dell'interfaccia che rappresenta l'elemento, in genere IID_IShellItem o IID_IShellItem2.

[out] ppv

Tipo: void**

Quando termina, questo metodo contiene il puntatore di interfaccia richiesto in riid.

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

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 7 [solo app desktop]
Server minimo supportato	Windows Server 2008 R2 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	shlobj_core.h (includere Shlobj.h)
Libreria	Shell32.lib
DLL	Shell32.dll (versione 6.1 o successiva)
Set di API	ext-ms-win-shell-shell32-l1-2-1 (introdotto in Windows 10, versione 10.0.10240)