Funzione SHGetFolderPathW (shlobj_core.h)

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

Sintassi

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

Parametri

[in] hwnd

Tipo: HWND

Riservato.

[in] csidl

Tipo: int

Valore CSIDL che identifica la cartella il cui percorso deve essere recuperato. Sono valide solo le cartelle reali. Se viene specificata una cartella virtuale, questa funzione ha esito negativo. È possibile forzare la creazione di una cartella combinando il 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 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.

Il processo chiamante è responsabile della rappresentazione corretta quando hToken è diverso da NULL. Il processo chiamante deve avere 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 SHGetFolderPath di trovare 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, ad esempio Documenti 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 OGGETTO KNOWNFOLDERID (o CSIDL) può essere spostata, rinominata, reindirizzata o spostata tra lingue da un utente o un amministratore.

Il sistema di cartelle note sottostante SHGetFolderPath consente agli utenti o agli amministratori di reindirizzare una cartella nota a un percorso adatto alle proprie esigenze. Questa operazione viene ottenuta 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\nome utente\Musica". 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: LPWSTR

Puntatore a una stringa con terminazione Null 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, viene restituito "C:\Users" 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 , tra cui i seguenti:

• CSIDL_ADMINTOOLS
• CSIDL_APPDATA
• CSIDL_COMMON_ADMINTOOLS
• CSIDL_COMMON_APPDATA
• CSIDL_COMMON_DOCUMENTS
• CSIDL_COOKIES
• CSIDL_FLAG_CREATE
• CSIDL_FLAG_DONT_VERIFY
• CSIDL_HISTORY
• CSIDL_INTERNET_CACHE
• CSIDL_LOCAL_APPDATA
• CSIDL_MYPICTURES
• CSIDL_PERSONAL
• CSIDL_PROGRAM_FILES
• CSIDL_PROGRAM_FILES_COMMON
• CSIDL_SYSTEM
• CSIDL_WINDOWS

Esempio

Nell'esempio di codice seguente viene usato SHGetFolderPath per trovare o creare una cartella e quindi crearne uno.

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

Vedi anche

IKnownFolder::GetPath