Funzione SHGetKnownFolderItem (shlobj_core.h)

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:

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

Vedi anche

IKnownFolder::GetPath

IKnownFolderManager::Redirect

Esempio di cartelle note

SHCreateItemInKnownFolder

SHGetKnownFolderIDList

SHGetKnownFolderPath