Metodo IShellFolder::GetDisplayNameOf (shobjidl_core.h)

Articolo
08/26/2023

Recupera il nome visualizzato per l'oggetto file specificato o la sottocartella.

Sintassi

HRESULT GetDisplayNameOf(
  [in]  PCUITEMID_CHILD pidl,
  [in]  SHGDNF          uFlags,
  [out] STRRET          *pName
);

Parametri

[in] pidl

Tipo: PCUITEMID_CHILD

PIDL che identifica in modo univoco l'oggetto file o la sottocartella relativa alla cartella padre.

[in] uFlags

Tipo: SHGDNF

Flag usati per richiedere il tipo di nome visualizzato da restituire. Per un elenco di valori possibili, vedere il tipo enumerato SHGDNF .

[out] pName

Tipo: STRRET*

Quando questo metodo restituisce, contiene un puntatore a una struttura STRRET in cui restituire il nome visualizzato. Il tipo di nome restituito in questa struttura può essere il tipo richiesto, ma la cartella Shell potrebbe restituire un tipo diverso.

Valore restituito

Tipo: HRESULT

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

Commenti

È responsabilità del chiamante liberare le risorse allocate da questa funzione.

In genere, pidl può fare riferimento solo agli elementi contenuti dalla cartella padre. Il PIDL deve essere a livello singolo e contenere esattamente una struttura SHITEMID seguita da uno zero terminante. Se si vuole recuperare il nome visualizzato di un elemento più profondo di un livello dalla cartella padre, usare SHBindToParent per associare con la cartella padre immediata dell'elemento e quindi passare il PIDL a livello singolo dell'elemento a IShellFolder::GetDisplayNameOf.

Inoltre, se il flag SHGDN_FORPARSING è impostato in uFlags e il flag di SHGDN_INFOLDER non è impostato, pidl può fare riferimento a un oggetto a qualsiasi livello al di sotto della cartella padre nella gerarchia dello spazio dei nomi. In una sola volta, pidl potrebbe essere un PIDL a più livelli, rispetto alla cartella padre e potrebbe contenere più strutture SHITEMID . Tuttavia, questo non è più supportato e pidl dovrebbe ora fare riferimento solo a un singolo elemento figlio.

Il modo più semplice per recuperare il nome visualizzato dalla struttura puntata da pName consiste nel passarlo a StrRetToBuf o StrRetToStr. Queste funzioni accettano una struttura STRRET e restituiscono il nome. È anche possibile esaminare il membro uType della struttura e recuperare il nome dal membro appropriato.

I flag specificati in uFlags sono hint sull'uso previsto del nome. Non garantiscono che IShellFolder restituirà il formato richiesto del nome. Se tale modulo non è disponibile, potrebbe essere restituito un altro modulo. In particolare, non esiste alcuna garanzia che il nome restituito dal flag di SHGDN_FORPARSING verrà analizzato correttamente da IShellFolder::P arseDisplayName. Esistono anche alcune combinazioni di flag che potrebbero causare il round trip GetDisplayNameOf/ParseDisplayName per non restituire l'elenco di identificatori originale. Questa occorrenza è eccezionale, ma dovresti verificare di essere sicura.

Nota Il nome di analisi restituito quando uFlags ha il set di flag di SHGDN_FORPARSING non è necessariamente una normale stringa di testo. Le cartelle virtuali, ad esempio My Computer, potrebbero restituire una stringa contenente il GUID dell'oggetto cartella nel formato "::{GUID}". Gli sviluppatori che implementano IShellFolder::GetDisplayNameOf sono invitati a restituire nomi di analisi che sono più vicini ai nomi visualizzati il più possibile, perché l'utente finale spesso deve digitare o modificare questi nomi.

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

Condividi tramite