Funzione MkParseDisplayName (objbase.h)

Converte una stringa in un moniker che identifica l'oggetto denominato dalla stringa.

Questa funzione è l'inverso dell'operazione IMoniker::GetDisplayName , che recupera il nome visualizzato associato a un moniker.

Sintassi

HRESULT MkParseDisplayName(
  [in]  LPBC      pbc,
  [in]  LPCOLESTR szUserName,
  [out] ULONG     *pchEaten,
  [out] LPMONIKER *ppmk
);

Parametri

[in] pbc

Puntatore all'interfaccia IBindCtx nell'oggetto contesto di associazione da utilizzare in questa operazione di associazione.

[in] szUserName

Puntatore al nome visualizzato da analizzare.

[out] pchEaten

Puntatore al numero di caratteri di szUserName utilizzati. Se la funzione ha esito positivo, *pchEaten è la lunghezza di szUserName; in caso contrario, è il numero di caratteri analizzati correttamente.

[out] ppmk

Indirizzo della variabile puntatore IMoniker* che riceve il puntatore di interfaccia al moniker creato da szUserName. Al termine, la funzione ha chiamato AddRef nel moniker e il chiamante è responsabile della chiamata a Release. Se si verifica un errore, il puntatore di interfaccia specificato conterrà la maggior parte del moniker che il metodo è stato in grado di creare prima dell'errore.

Valore restituito

Questa funzione può restituire il valore restituito standard E_OUTOFMEMORY, nonché i valori seguenti.

Codice restituito	Descrizione
S_OK	L'operazione di analisi ha avuto esito positivo e il moniker è stato creato.
MK_E_SYNTAX	Errore nella sintassi di un nome file o di un errore nella sintassi del moniker composito risultante.

 

Questa funzione può anche restituire uno dei valori di errore restituiti da IMoniker::BindToObject, IOleItemContainer::GetObject o IParseDisplayName::P arseDisplayName.

Commenti

La funzione MkParseDisplayName analizza un nome leggibile in un moniker che può essere usato per identificare un'origine di collegamento. Il moniker risultante può essere un moniker semplice ,ad esempio un moniker di file, oppure può essere un composito generico costituito dalle parti del moniker componente. Ad esempio, il nome visualizzato "c:\mydir\somefile!item 1"

può essere analizzato nel moniker composito generico seguente: FileMoniker basato su "c:\mydir\somefile") + (ItemMoniker basato su "item 1").

L'uso più comune di MkParseDisplayName è nell'implementazione della finestra di dialogo Collegamenti standard, che consente a un utente finale di specificare l'origine di un oggetto collegato digitando in una stringa. Potrebbe anche essere necessario chiamare MkParseDisplayName se l'applicazione supporta un linguaggio macro che consenta riferimenti remoti (riferimento a elementi esterni al documento).

L'analisi di un nome visualizzato richiede spesso l'attivazione degli stessi oggetti che verrebbero attivati durante un'operazione di associazione, in modo che possa essere altrettanto costoso (in termini di prestazioni) dell'associazione. Gli oggetti associati durante l'operazione di analisi vengono memorizzati nella cache nel contesto di associazione passato alla funzione. Se si prevede di associare il moniker restituito da MkParseDisplayName, è consigliabile farlo subito dopo la restituzione della funzione, usando lo stesso contesto di associazione, che rimuove la necessità di attivare gli oggetti una seconda volta.

MkParseDisplayName analizza la maggior parte del nome visualizzato compreso in un moniker. La funzione chiama quindi IMoniker::P arseDisplayName nel moniker appena creato, passando il resto del nome visualizzato. Il moniker restituito da ParseDisplayName è composto sulla fine del moniker esistente e, se uno dei nomi visualizzati rimane non analizzato, ParseDisplayName viene chiamato sul risultato della composizione. Questo processo viene ripetuto fino a quando non viene analizzato l'intero nome visualizzato.

MkParseDisplayName tenta le strategie seguenti per analizzare l'inizio del nome visualizzato, usando il primo che ha esito positivo:

1. La funzione cerca nella tabella oggetti in esecuzione per i moniker di file corrispondenti a tutti i prefissi del nome visualizzato che sono costituiti esclusivamente da caratteri di nome file validi. Questa strategia consente di identificare i documenti ancora non salvati.
2. La funzione controlla il prefisso massimo del nome visualizzato, costituito esclusivamente da caratteri di nome file validi, per verificare se un documento OLE 1 è registrato da tale nome. In questo caso, il moniker restituito è un moniker interno fornito dal livello di compatibilità OLE 1 di OLE 2.
3. La funzione consulta il file system per verificare se un prefisso del nome visualizzato corrisponde a un file esistente. Il nome del file può essere assoluto, relativo all'unità, alla directory di lavoro o iniziare con un nome di condivisione di rete esplicito. Questa è la situazione comune.
4. Se il carattere iniziale del nome visualizzato è '@', la funzione trova la stringa più lunga immediatamente successiva a quella conforme alla sintassi ProgID legale. La funzione converte questa stringa in un CLSID usando la funzione CLSIDFromProgID . Se CLSID rappresenta una classe OLE 2, la funzione carica l'oggetto classe corrispondente e richiede un puntatore all'interfaccia IParseDisplayName . All'interfaccia IParseDisplayName risultante viene quindi assegnata l'intera stringa da analizzare, a partire da '@'. Se CLSID rappresenta una classe OLE 1, la funzione considera la stringa che segue ProgID come un designatore di collegamento OLE1/DDE con sintassidell'elementodel nome file|.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [app desktop | App UWP]
Server minimo supportato	Windows 2000 Server [app desktop | App UWP]
Piattaforma di destinazione	Windows
Intestazione	objbase.h
Libreria	Ole32.lib
DLL	Ole32.dll
Set di API	ext-ms-win-com-ole32-l1-1-1 (introdotto in Windows 8.1)

Vedi anche

IMoniker::GetDisplayName

IMoniker::P arseDisplayName

IParseDisplayName