Metodo IMoniker::BindToObject (objidl.h)

Articolo
03/05/2024

Associa all'oggetto specificato. Il processo di associazione comporta la ricerca dell'oggetto, l'inserimento nello stato in esecuzione, se necessario, e la fornitura del chiamante con un puntatore a un'interfaccia specificata nell'oggetto identificato.

Sintassi

HRESULT BindToObject(
  [in]  IBindCtx *pbc,
  [in]  IMoniker *pmkToLeft,
  [in]  REFIID   riidResult,
  [out] void     **ppvResult
);

Parametri

[in] pbc

Puntatore all'interfaccia IBindCtx nell'oggetto contesto di associazione, usato in questa operazione di associazione. Il contesto di associazione memorizza nella cache gli oggetti associati durante il processo di associazione, contiene parametri che si applicano a tutte le operazioni usando il contesto di associazione e fornisce i mezzi in base al quale l'implementazione del moniker deve recuperare informazioni sull'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 moniker per consentire la cooperazione tra i vari componenti di un moniker composito. I client Moniker devono usare NULL.

[in] riidResult

L'IID dell'interfaccia che il client vuole usare per comunicare con l'oggetto identificato dal moniker.

[out] ppvResult

Indirizzo della variabile puntatore che riceve il puntatore dell'interfaccia richiesto in riid. Al termine della restituzione, *ppvResult contiene il puntatore dell'interfaccia richiesto all'oggetto identificato dal moniker. In caso di esito positivo, l'implementazione deve chiamare AddRef nel moniker. È responsabilità del chiamante chiamare Release. Se si verifica un errore, *ppvResult deve essere NULL.

Valore restituito

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

Codice restituito	Descrizione
S_OK	L'operazione di associazione ha avuto esito positivo.
MK_E_NOOBJECT	Impossibile trovare l'oggetto identificato da questo moniker o un oggetto identificato dal moniker composito di cui questo moniker fa parte.
MK_E_EXCEEDEDDEADLINE	Impossibile completare l'operazione di associazione entro il limite di tempo specificato dalla struttura di BIND_OPTS del contesto di associazione.
MK_E_CONNECTMANUALLY	L'operazione di associazione richiede assistenza dall'utente finale. Il motivo più comune per restituire questo valore è che è necessaria una password o che un floppy deve essere montato. Quando questo valore viene restituito, recuperare il moniker che ha causato l'errore con una chiamata a IBindCtx::GetObjectParam con la chiave "ConnectManually". È quindi possibile chiamare IMoniker::GetDisplayName per ottenere il nome visualizzato, visualizzare una finestra di dialogo che comunica le informazioni desiderate, ad esempio le istruzioni per montare un floppy o una richiesta per una password e quindi riprovare l'operazione di associazione.
MK_E_INTERMEDIATEINTERFACENOTSUPPORTED	È stato trovato un oggetto intermedio, ma non supportava un'interfaccia necessaria per completare l'operazione di associazione. Ad esempio, un moniker dell'elemento restituisce questo valore se il relativo contenitore non supporta l'interfaccia IOleItemContainer .
STG_E_ACCESSDENIED	Impossibile accedere all'oggetto di archiviazione.

Questo metodo può anche restituire gli errori associati al metodo IOleItemContainer::GetObject .

Commenti

BindToObject implementa la funzione primaria di un moniker, che consiste nell'individuare l'oggetto identificato dal moniker e restituire un puntatore a una delle relative interfacce.

Note ai chiamanti

Se si usa un moniker come connessione persistente tra due oggetti, si attiva la connessione chiamando BindToObject.

In genere si chiama BindToObject durante il processo seguente:

Creare un oggetto contesto di associazione con una chiamata alla funzione CreateBindCtx .
Chiamare BindToObject usando il moniker, recuperando un puntatore a un'interfaccia desiderata nell'oggetto identificato.
Rilasciare il contesto di associazione.
Tramite il puntatore dell'interfaccia acquisita, eseguire le operazioni desiderate sull'oggetto.
Al termine dell'oggetto, rilasciare il puntatore dell'interfaccia dell'oggetto.

Il frammento di codice seguente illustra questi passaggi.

HRESULT hr;       // An error code
IMoniker * pMnk;  // A previously acquired interface moniker

// Obtain an IBindCtx interface.
IBindCtx * pbc; 
hr = CreateBindCtx(NULL, &amp;pbc); 
if (FAILED(hr)) exit(0);  // Handle errors here. 
   
// Obtain an implementation of pCellRange. 
ICellRange * pCellRange; 
hr = pMnk-&gt;BindToObject(pbc, NULL, IID_ICellRange, &amp;pCellRange); 
if (FAILED(hr)) exit(0);  // Handle errors here. 

// Use pCellRange here. 

// Release interfaces after use. 
pbc-&gt;Release(); 
pCellRange-&gt;Release();

È anche possibile usare la funzione BindMoniker quando si intende solo un'operazione di associazione e non è necessario conservare l'oggetto contesto di associazione. Questa funzione helper incapsula la creazione del contesto di associazione, chiamando BindToObject e rilasciando il contesto di associazione.

I contenitori COM che supportano i collegamenti agli oggetti usano moniker per individuare e ottenere l'accesso all'oggetto collegato, ma in genere non chiamano BindToObject direttamente. Quando un utente attiva invece un collegamento in un contenitore, il contenitore di collegamento chiama in genere IOleObject::D oVerb, usando l'implementazione del gestore di collegamento, che chiama BindToObject nel moniker archiviato nell'oggetto collegato (se non riesce a gestire il verbo).

Note per gli implementatori

Ciò che l'implementazione fa dipende dal fatto che si prevede che il moniker abbia un prefisso; ovvero, se si prevede che il parametro pmkToLeft sia NULL o meno. Ad esempio, un moniker di elemento, che identifica un oggetto all'interno di un contenitore, prevede che pmkToLeft identifica il contenitore. Un moniker di elemento usa di conseguenza pmkToLeft per richiedere servizi da tale contenitore. Se si prevede che il moniker disponga di un prefisso, è necessario usare il parametro pmkToLeft ,ad esempio chiamando BindToObject su di esso, per richiedere servizi dall'oggetto identificato.

Se si prevede che il moniker non abbia alcun prefisso, l'implementazione BindToObject deve prima controllare la tabella dell'oggetto in esecuzione (ROT) per verificare se l'oggetto è già in esecuzione. Per acquisire un puntatore a ROT, l'implementazione deve chiamare IBindCtx::GetRunningObjectTable nel parametro pbc . È quindi possibile chiamare il metodo IRunningObjectTable::GetObject per verificare se il moniker corrente è stato registrato nel ROT. In tal caso, è possibile chiamare immediatamente QueryInterface per ottenere un puntatore all'interfaccia richiesta dal chiamante.

Quando l'implementazione BindToObject viene associata a un oggetto, deve usare il parametro pbc per chiamare IBindCtx::RegisterObjectBound per archiviare un riferimento all'oggetto associato nel contesto di associazione. Ciò garantisce che l'oggetto associato rimanga in esecuzione fino a quando non viene rilasciato il contesto di associazione, che può evitare la spesa di avere un'operazione di associazione successiva caricarla di nuovo in un secondo momento.

Se la struttura BIND_OPTS del contesto di associazione specifica il flag di BINDFLAGS_JUSTTESTEXISTENCE , l'implementazione ha la possibilità di restituire NULL in ppvResult (anche se è anche possibile ignorare il flag ed eseguire l'operazione di associazione completa).

Note specifiche dell'implementazione

Implementazione	Note
Anti-moniker	Questo metodo non è implementato. Restituisce E_NOTIMPL.
Moniker classe	Se pmkLeft è NULL, chiama CoGetClassObject, usando clSID il moniker di classe è stato inizializzato con (in CreateClassMoniker o tramite MkParseDisplayName) e CLSCTX dell'oggetto pbc corrente (IBindCtx). Se pmkLeft non è NULL, chiama pmkLeft-BindToObject> per IClassActivator e chiama IClassActivator::GetClassObject con CLSID inizializzato con e i parametri delle impostazioni locali e CLSCTX del pbc corrente (IBindCtx).
Moniker file	Quando pmkToLeft è NULL, il metodo cerca il moniker in ROT e, se trovato, esegue query sull'oggetto recuperato per il puntatore dell'interfaccia richiesto. Se il moniker non viene trovato nel ROT, il metodo carica l'oggetto dal file system e recupera il puntatore dell'interfaccia richiesto. Se pmkLeft non è NULL, anziché determinare la classe per creare un'istanza e inizializzare il contenuto del file a cui fa riferimento il moniker del file usando GetClassFile (o altri mezzi), chiamare pmkLeft-BindToObject> per IClassFactory e IClassActivator, recuperare questo puntatore in pcf. Se questo errore ha esito negativo con E_NOINTERFACE, restituire MK_E_INTERMEDIATEINTERFACENOTSUPPORTED. Se il puntatore IClassFactory viene recuperato correttamente, chiamare pcf-CreateInstance>(IID_IPersistFile, (void**)&ppf) per ottenere una nuova istanza della classe da inizializzare e inizializzarla usando IPersistFile o altri mezzi appropriati per i percorsi di inizializzazione esistenti del moniker di file.
Moniker composito generico	Se pmkToLeft è NULL, questo metodo cerca il moniker in ROT e, se trovato, esegue query sull'oggetto recuperato per il puntatore dell'interfaccia richiesto. Se pmkToLeft non è NULL, il metodo chiama in modo ricorsivo BindToObject nel componente più a destra del composito, passando il resto del composito come parametro pmkToLeft per tale chiamata.
Moniker elemento	Se pmkToLeft è NULL, questo metodo restituisce E_INVALIDARG. In caso contrario, il metodo chiama BindToObject nel parametro pmkToLeft , richiedendo un puntatore dell'interfaccia IOleItemContainer . Il metodo chiama quindi IOleItemContainer::GetObject, passando la stringa contenuta nel moniker e restituisce il puntatore dell'interfaccia richiesto.
Moniker OBJREF	Il parametro pmkToLeft deve essere NULL. Poiché il moniker OBJREF rappresenta un oggetto in esecuzione, non viene eseguita alcuna attivazione. Se l'oggetto rappresentato non è più in esecuzione, BindToObject non riesce con E_UNEXPECTED.
Moniker puntatore	Questo metodo esegue una query sul puntatore con wrapping per l'interfaccia richiesta.
Moniker URL	Poiché il moniker URL supporta l'associazione asincrona, il valore restituito effettivo del relativo BindToObject può variare a seconda dei parametri dell'oggetto stabiliti nel contesto di associazione. Per altre informazioni, vedere sotto.

La semantica dell'operazione di associazione per un moniker URL è identica indipendentemente dall'utilizzo sincrono o asincrono e sono i seguenti:

Il moniker URL esegue il pull di ulteriori informazioni per l'operazione di associazione dal contesto di associazione. Ad esempio, il moniker può ottenere puntatori alle interfacce IBindStatusCallback e IEnumFORMATETC registrate nel contesto di associazione. Altre informazioni possono includere opzioni di binding aggiuntive specificate nel contesto di associazione tramite IBindCtx::SetBindOptions, ad esempio il parametro dwTickCountDeadline o il valore grfFlags di BIND_MAYBOTHERUSER.
Successivamente, il moniker controlla il rot del contesto di associazione per determinare se l'oggetto a cui si fa riferimento è già in esecuzione. Il moniker può ottenere queste informazioni con le chiamate seguenti:
```
IBindCtx::GetRunningObjectTable(&amp;prot)
prot-&gt;IsRunning(this)
```
Se l'oggetto è già in esecuzione, il moniker recupera l'oggetto in esecuzione con la chiamata seguente:
```
prot-&gt;GetObject(this, &amp;punk)
```
Il moniker chiama quindi QueryInterface per l'interfaccia richiesta.
In caso contrario, il moniker esegue una query sul client chiamando IBindStatusCallback::GetBindInfo per ottenere informazioni aggiuntive sull'associazione. Il moniker avvia quindi l'operazione di associazione e passa l'interfaccia IBinding risultante al client chiamando IBindStatusCallback::OnStartBinding.
Se nel passaggio 1 è stato determinato che si tratta di un binding asincrono, BindToObject restituisce MK_S_ASYNCHRONOUS a questo punto con NULL in ppv. Il chiamante riceverà il puntatore dell'oggetto effettivo durante il metodo IBindStatusCallback::OnObjectAvailable in un secondo momento. I passaggi seguenti vengono quindi eseguiti in modo asincrono al chiamante, in genere in un altro thread di esecuzione.
La classe della risorsa designata dal moniker URL viene determinata in uno dei modi seguenti:
- Il moniker URL esamina il tipo di supporto dei dati. Se il tipo di supporto è application/x-oleobject, i primi 16 byte dei dati effettivi (Content-Body) contengono CLSID della risorsa e i dati successivi devono essere interpretati dalla classe stessa. Per tutti gli altri tipi di supporti, URL Moniker cerca nel Registro di sistema per la <chiave HKEY_CLASSES_ROOT\MIME\Database\Content-Type\tipo> di supporto\CLSID. Si noti che l'applicazione/x-oleobject verrà usata fino all'approvazione dell'applicazione/oleobject.
- Il moniker URL corrisponde alle parti dell'arrivo dei dati ai modelli registrati nel Registro di sistema in HKEY_CLASSES_ROOT\FileTypes.
- Infine, se tutto il resto ha esito negativo, il moniker URL correla l'estensione finale della risorsa, se presente, a un CLSID usando il HKEY_CLASSES_ROOT\.??? chiavi nel Registro di sistema, come fatto da GetClassFile e dalla shell.
Dopo aver determinato la classe, il moniker URL crea un'istanza usando CoCreateInstance di CLSCTX_SERVER che richiede l'interfaccia IUnknown .
Il moniker URL chiama quindi il metodo QueryInterface dell'oggetto appena creato per l'interfaccia IPersistMoniker . Se QueryInterface ha esito positivo, il moniker URL chiama IPersistMoniker::Load passando se stesso (questo) come parametro moniker. L'oggetto chiama in genere BindToStorage chiedendo l'interfaccia di archiviazione a cui sono interessati.
In caso contrario, il moniker URL chiama QueryInterface per IPersistStream e, se ha esito positivo, chiama IPersistStream::Load, passando l'oggetto un puntatore IStream per un oggetto di flusso che viene riempito in modo asincrono dal trasporto.
Se la classe chiamata non è contrassegnata con la categoria CATID_AsyncAware, chiama a ISequentialStream::Read o ISequentialStream::Write che i dati di riferimento non sono ancora disponibili finché non diventano disponibili i dati. Queste chiamate bloccano nel senso COM tradizionale. Viene immesso un ciclo di messaggi che consente l'elaborazione di determinati messaggi e viene chiamato in modo appropriato IMessageFilter del thread.

Se la classe è contrassegnata con la categoria CATID_AsyncAware, chiama a ISequentialStream::Read o ISequentialStream::Write che i dati di riferimento non sono ancora disponibili E_PENDING.
In caso contrario, il moniker URL chiama QueryInterface per IPersistFile e, se ha esito positivo, completa il download in un file temporaneo. Al termine, il moniker URL chiama IPersistFile::Load. Il file creato viene memorizzato nella cache insieme ad altri dati scaricati da Internet. Il client deve assicurarsi di non eliminare questo file.
Quando l'oggetto restituisce da una delle varie chiamate load descritte nei passaggi precedenti, il moniker URL chiama il metodo IBindStatusCallback::OnObjectAvailable per restituire il puntatore dell'interfaccia richiesto originariamente dal client quando il client chiama BindToObject.

Requisiti

Requisito	Valore
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

BindMoniker

Imoniker