Metodo IMoniker::GetDisplayName (objidl.h)

Recupera il nome visualizzato per il moniker.

Sintassi

HRESULT GetDisplayName(
  [in]  IBindCtx *pbc,
  [in]  IMoniker *pmkToLeft,
  [out] LPOLESTR *ppszDisplayName
);

Parametri

[in] pbc

Puntatore all'interfaccia IBindCtx nel contesto di associazione da usare in questa operazione. Il contesto di associazione memorizza nella cache gli oggetti associati durante il processo di associazione, contiene parametri che si applicano a tutte le operazioni che usano il contesto di associazione e fornisce i mezzi con cui l'implementazione del moniker deve recuperare informazioni sul relativo ambiente.

[in] pmkToLeft

Se il moniker fa parte di un moniker composito, puntatore al moniker a sinistra di questo moniker. Questo parametro viene usato principalmente dagli implementatori di moniker per consentire la cooperazione tra i vari componenti di un moniker composito. I client moniker devono passare NULL.

[out] ppszDisplayName

Indirizzo di una variabile del puntatore che riceve un puntatore alla stringa del nome visualizzato per il moniker. L'implementazione deve usare IMalloc::Alloc per allocare la stringa restituita in ppszDisplayName e il chiamante è responsabile della chiamata a IMalloc::Free per liberarlo. Sia il chiamante che l'implementazione di questo metodo usano l'allocatore dell'attività COM restituito da CoGetMalloc. Se si verifica un errore, l'implementazione deve impostare *ppszDisplayName su NULL.

Valore restituito

Questo metodo può restituire i valori restituiti standard E_OUTOFMEMORY, nonché i valori seguenti.

Codice restituito	Descrizione
S_OK	Metodo completato correttamente.
MK_E_EXCEEDEDDEADLINE	Impossibile completare l'operazione di associazione entro il limite di tempo specificato dalla struttura di BIND_OPTS del contesto di associazione.
E_NOTIMPL	Non è presente alcun nome visualizzato.

Commenti

GetDisplayName fornisce una stringa che rappresenta una rappresentazione visualizzabile del moniker. Un nome visualizzato non è una rappresentazione completa dello stato interno di un moniker; è semplicemente un modulo che può essere letto dagli utenti. Di conseguenza, è possibile (anche se raro) per due moniker diversi avere lo stesso nome visualizzato. Anche se non esiste alcuna garanzia che il nome visualizzato di un moniker possa essere analizzato nuovamente in tale moniker quando si chiama la funzione MkParseDisplayName con esso, l'errore è raro.

Note ai chiamanti

È possibile che il recupero del nome visualizzato di un moniker sia un'operazione costosa. Per un'efficienza, è possibile memorizzare nella cache i risultati della prima chiamata riuscita a GetDisplayName, anziché effettuare chiamate ripetute.

Note per gli implementatori

Se si scrive una classe moniker in cui il nome visualizzato non cambia, è sufficiente memorizzare nella cache il nome visualizzato e specificare il nome memorizzato nella cache quando richiesto. Se il nome visualizzato può cambiare nel tempo, ottenere il nome visualizzato corrente potrebbe significare che il moniker deve accedere alla risorsa di archiviazione dell'oggetto o associarlo all'oggetto, che può essere un'operazione costosa. In questo caso, l'implementazione di GetDisplayName deve restituire MK_E_EXCEEDEDDEADLINE se il nome non può essere recuperato dal tempo specificato nella struttura di BIND_OPTS del contesto di associazione.

Un moniker destinato a far parte di un moniker composito generico deve includere qualsiasi delimitatore precedente (ad esempio '') come parte del nome visualizzato. Ad esempio, il nome visualizzato restituito da un moniker dell'elemento include il delimitatore specificato al momento della creazione con la funzione CreateItemMoniker . Il nome visualizzato per un moniker di file non include un delimitatore perché i moniker di file devono sempre essere il componente più a sinistra di un composito.

Note specifiche dell'implementazione

Implementazione	Note
Anti-moniker	Per ogni anti-moniker contenuto in questo moniker, questo metodo restituisce un'istanza di "\..".
Moniker di classe	Il nome visualizzato per i moniker di classe è del formato seguente: clsid:string-clsid-no-curly-braces *[";" clsid-param=value]:. Ad esempio, clsid:a7b90590-36fd-11cf-857d-00aa006d2ea4:.
Moniker file	Questo metodo restituisce il percorso rappresentato dal moniker.
Moniker composito generico	Questo metodo restituisce la concatenazione dei nomi visualizzati restituiti da ogni moniker componente del composito.
Moniker elemento	Questo metodo restituisce la concatenazione del delimitatore e il nome dell'elemento specificati al momento della creazione del moniker dell'elemento.
Moniker OBJREF	Questo metodo ottiene il nome visualizzato per il moniker OBJREF. Il nome visualizzato è una codifica a 64 bit che incapsula la posizione del computer, l'endpoint del processo e l'ID del puntatore di interfaccia (IPID) dell'oggetto in esecuzione. Per compatibilità futura, il nome visualizzato è limitato ai caratteri che possono essere specificati come parte di un URL.
Moniker puntatore	Questo metodo restituisce E_NOTIMPL.
Moniker URL	Il moniker URL tenta di restituire la stringa URL completa. Se il moniker è stato creato con una stringa URL parziale (vedere CreateURLMonikerEx), tenterà prima di tutto di trovare un moniker URL nel contesto di associazione in SZ_URLCONTEXT e cercherà successivamente il moniker a sinistra per informazioni contestuali. Se non riesce a restituire la stringa URL completa, restituirà la stringa dell'URL parziale.

Requisiti

Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	objidl.h

Vedi anche

Imoniker

MkParseDisplayName