Funzione SHGetFolderPathA (shlobj_core.h)

Articolo
03/02/2024

Deprecato. Ottiene il percorso di una cartella identificata da un valore CSIDL .

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

Sintassi

SHFOLDERAPI SHGetFolderPathA(
  [in]  HWND   hwnd,
  [in]  int    csidl,
  [in]  HANDLE hToken,
  [in]  DWORD  dwFlags,
  [out] LPSTR  pszPath
);

Parametri

[in] hwnd

Tipo: HWND

Riservato.

[in] csidl

Tipo: int

Valore CSIDL che identifica la cartella il cui percorso deve essere recuperato. Solo le cartelle reali sono valide. Se viene specificata una cartella virtuale, questa funzione ha esito negativo. È possibile forzare la creazione di una cartella combinando CSIDL della cartella con CSIDL_FLAG_CREATE.

[in] hToken

Tipo: HANDLE

Token di accesso che può essere usato per rappresentare un determinato utente.

Microsoft Windows 2000 e versioni precedenti: Impostare sempre questo parametro su NULL.

Windows XP e versioni successive: Questo parametro è in genere impostato su NULL, ma potrebbe essere necessario assegnare un valore non NULL a hToken per tali cartelle che possono avere più utenti, ma vengono considerati come appartenenti a un singolo utente. La cartella più comunemente usata di questo tipo è Documents.

Il processo di chiamata è responsabile della rappresentazione corretta quando hToken non è NULL. Il processo di chiamata deve avere privilegi di sicurezza appropriati per l'utente specifico, tra cui TOKEN_QUERY e TOKEN_IMPERSONATE, e l'hive del Registro di sistema dell'utente deve essere attualmente montato. Per altre discussioni sui problemi di controllo degli accessi, vedere Controllo di accesso.

L'assegnazione del parametro hToken a un valore di -1 indica l'utente predefinito. Ciò consente ai client di SHGetFolderPath di trovare 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 personali e Desktop. Tutti gli elementi aggiunti alla cartella Utente predefinito vengono visualizzati anche in qualsiasi nuovo account utente.

[in] dwFlags

Tipo: DWORD

Flag che specificano il percorso da restituire. Questo valore viene usato nei casi in cui la cartella associata a un'cartella KNOWNFOLDERID (o CSIDL) può essere spostata, rinominata, reindirizzata o distribuita tra lingue da un utente o un amministratore.

Il sistema di cartelle noto che sottolizza SHGetFolderPath consente agli utenti o agli amministratori di reindirizzare una cartella nota a una posizione adatta alle proprie esigenze. Ciò viene ottenuto chiamando IKnownFolderManager::Redirect, che imposta il valore "corrente" della cartella associata al flag di SHGFP_TYPE_CURRENT.

Il valore predefinito della cartella, ovvero il percorso della cartella se un utente o un amministratore non lo ha reindirizzato altrove, viene recuperato specificando il flag di SHGFP_TYPE_DEFAULT. Questo valore può essere usato per implementare una funzionalità "ripristina impostazioni predefinite" per una cartella nota.

Ad esempio, il valore predefinito (SHGFP_TYPE_DEFAULT) per FOLDERID_Music (CSIDL_MYMUSIC) è "C:\Users\user name\Music". Se la cartella è stata reindirizzata, il valore corrente (SHGFP_TYPE_CURRENT) potrebbe essere "D:\Music". Se la cartella non è stata reindirizzata, SHGFP_TYPE_DEFAULT e SHGFP_TYPE_CURRENT recuperare lo stesso percorso.

SHGFP_TYPE_CURRENT

Recuperare il percorso corrente della cartella.

SHGFP_TYPE_DEFAULT

Recuperare il percorso predefinito della cartella.

[out] pszPath

Tipo: LPTSTR

Puntatore a una stringa con terminazione null di lunghezza MAX_PATH che riceverà il percorso. Se si verifica un errore o S_FALSE viene restituito, questa stringa sarà vuota. Il percorso restituito non include una barra rovesciata finale. Ad esempio, "C:\Users" viene restituito anziché "C:\Users\".

Valore restituito

Tipo: HRESULT

Se questa funzione ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice di errore HRESULT .

Commenti

Questa funzione è un superset di SHGetSpecialFolderPath.

Sono supportati solo alcuni valori CSIDL , inclusi i seguenti:

Esempio

L'esempio di codice seguente usa SHGetFolderPath per trovare o creare una cartella e quindi crea un file in esso.

TCHAR szPath[MAX_PATH];

if(SUCCEEDED(SHGetFolderPath(NULL, 
                             CSIDL_PERSONAL|CSIDL_FLAG_CREATE, 
                             NULL, 
                             0, 
                             szPath))) 
{
    PathAppend(szPath, TEXT("New Doc.txt"));
    HANDLE hFile = CreateFile(szPath, ...);
}

Requisiti

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

Vedi anche

IKnownFolder::GetPath

Condividi tramite