Metodo IShellFolder::P arseDisplayName (shobjidl_core.h)

Articolo
08/26/2023

Converte il nome visualizzato di un oggetto file o una cartella in un elenco di identificatori di elemento.

Sintassi

HRESULT ParseDisplayName(
  [in]      HWND             hwnd,
  [in]      IBindCtx         *pbc,
  [in]      LPWSTR           pszDisplayName,
  [out]     ULONG            *pchEaten,
  [out]     PIDLIST_RELATIVE *ppidl,
  [in, out] ULONG            *pdwAttributes
);

Parametri

[in] hwnd

Tipo: HWND

Handle di finestra. Il client deve fornire un handle di finestra se visualizza una finestra di dialogo o una finestra di messaggio. In caso contrario, impostare hwnd su NULL.

[in] pbc

Tipo: IBindCtx*

facoltativo. Puntatore a un contesto di associazione usato per passare i parametri come input e output alla funzione di analisi. Questi parametri passati sono spesso specifici dell'origine dati e sono documentati dai proprietari dell'origine dati. Ad esempio, l'origine dati del file system accetta il nome da analizzare (come struttura WIN32_FIND_DATA ), usando il parametro di contesto di associazione STR_FILE_SYS_BIND_DATA . STR_PARSE_PREFER_FOLDER_BROWSING può essere passato per indicare che gli URL vengono analizzati usando l'origine dati del file system quando possibile. Creare un oggetto contesto di associazione usando CreateBindCtx e popolare i valori usando IBindCtx::RegisterObjectParam. Per un elenco completo di questi elementi, vedere Associa chiavi stringa di contesto .

Se non vengono passati dati o ricevuti dalla funzione di analisi, questo valore può essere NULL.

[in] pszDisplayName

Tipo: LPWSTR

Stringa Unicode con terminazione null con il nome visualizzato. Poiché ogni cartella shell definisce la propria sintassi di analisi, la maschera che questa stringa può richiedere può variare. La cartella desktop, ad esempio, accetta percorsi come "C:\My Docs\My File.txt". Accetta anche riferimenti agli elementi nello spazio dei nomi associati a tali elementi usando la sintassi ":{GUID}". Ad esempio, per recuperare un elenco di identificatori completo per il pannello di controllo dalla cartella desktop, è possibile usare quanto segue:

::{CLSID for Control Panel}\::{CLSID for printers folder}

[out] pchEaten

Tipo: ULONG*

Puntatore a un valore ULONG che riceve il numero di caratteri del nome visualizzato analizzato. Se l'applicazione non ha bisogno di queste informazioni, impostare pchEaten su NULL e non verrà restituito alcun valore.

[out] ppidl

Tipo: PIDLIST_RELATIVE*

Quando questo metodo restituisce, contiene un puntatore al PIDL per l'oggetto . L'elenco di identificatori di elemento restituito specifica l'elemento relativo alla cartella di analisi. Se l'oggetto associato a pszDisplayName si trova all'interno della cartella di analisi, l'elenco di identificatori di elemento restituito conterrà solo una struttura SHITEMID . Se l'oggetto si trova in una sottocartella della cartella di analisi, l'elenco di identificatori di elemento restituito conterrà più strutture SHITEMID . Se si verifica un errore, viene restituito NULL in questo indirizzo.

Quando non è più necessario, è responsabilità del chiamante liberare questa risorsa chiamando CoTaskMemFree.

[in, out] pdwAttributes

Tipo: ULONG*

Valore utilizzato per eseguire query sugli attributi di file. Se non usato, deve essere impostato su NULL. Per eseguire una query per uno o più attributi, inizializzare questo parametro con i flag SFGAO che rappresentano gli attributi di interesse. In caso di restituzione, tali attributi true e richiesti verranno impostati.

Valore restituito

Tipo: HRESULT

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

Commenti

Alcune cartelle di Shell potrebbero non implementare IShellFolder::P arseDisplayName. Ogni cartella che esegue definirà la sintassi di analisi personalizzata.

ParseDisplayName non è previsto gestire gli indicatori relativi del percorso o della cartella padre ("." o ".."). Il chiamante deve rimuovere questi elementi in modo appropriato.

Non usare il flag SFGAO_VALIDATE in pdwAttributes per verificare l'esistenza dell'elemento il cui nome viene analizzato. IShellFolder::P arseDisplayName convalida in modo implicito l'esistenza dell'elemento a meno che tale comportamento non venga sottoposto a override da un parametro di contesto di binding speciale.

L'esecuzione di query per alcuni attributi può essere relativamente lenta e usare quantità significative di memoria. Ad esempio, per determinare se un file è condiviso, shell caricherà i componenti di rete. Questa procedura può richiedere il caricamento di diverse DLL. Lo scopo di pdwAttributes è quello di consentire di limitare la query solo a tali informazioni necessarie. Il frammento di codice seguente illustra come individuare se un file è compresso.

LPITEMIDLIST pidl;
ULONG cbEaten;
DWORD dwAttribs = SFGAO_COMPRESSED;

hres = psf->ParseDisplayName(NULL,
                             NULL,
                             lpwszDisplayName,
                             &cbEaten,  // This can be NULL
                             &pidl,
                             &dwAttribs);

if(dwAttribs & SFGAO_COMPRESSED)
{
    // Do something with the compressed file
}

Poiché pdwAttributes è un parametro in/out, deve essere sempre inizializzato. Se si passa un valore non inizializzato, alcuni dei bit possono essere impostati inavvertitamente. IShellFolder::P arseDisplayName eseguirà quindi una query per gli attributi corrispondenti, che potrebbero causare ritardi indesiderati o richieste di memoria. Se non si vuole eseguire una query per gli attributi, impostare pdwAttributes su NULL per evitare comportamenti imprevedibili.

Questo metodo è simile al metodo IParseDisplayName::P arseDisplayName .

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	shobjidl_core.h (include Shobjidl.h)
DLL	Shell32.dll (versione 4.0 o successiva)

Vedi anche

IShellFolder

IShellFolder2

IShellFolder::GetAttributesOf

IShellLink

Condividi tramite