Método IMoniker::BindToObject (objidl.h)
Enlaza al objeto especificado. El proceso de enlace implica buscar el objeto, colocarlo en el estado en ejecución si es necesario y proporcionar al autor de la llamada un puntero a una interfaz especificada en el objeto identificado.
Sintaxis
HRESULT BindToObject(
[in] IBindCtx *pbc,
[in] IMoniker *pmkToLeft,
[in] REFIID riidResult,
[out] void **ppvResult
);
Parámetros
[in] pbc
Puntero a la interfaz IBindCtx en el objeto de contexto de enlace, que se usa en esta operación de enlace. El contexto de enlace almacena en caché los objetos enlazados durante el proceso de enlace, contiene parámetros que se aplican a todas las operaciones mediante el contexto de enlace y proporciona los medios por los que la implementación del moniker debe recuperar información sobre su entorno.
[in] pmkToLeft
Si el moniker forma parte de un moniker compuesto, puntero al moniker a la izquierda de este moniker. Los implementadores de moniker usan este parámetro principalmente para permitir la cooperación entre los distintos componentes de un moniker compuesto. Los clientes de Moniker deben usar NULL.
[in] riidResult
IID de la interfaz que el cliente desea usar para comunicarse con el objeto que identifica el moniker.
[out] ppvResult
Dirección de la variable de puntero que recibe el puntero de interfaz solicitado en riid. Tras la devolución correcta, *ppvResult contiene el puntero de interfaz solicitado al objeto que identifica el moniker. Cuando se ejecuta correctamente, la implementación debe llamar a AddRef en el moniker. Es responsabilidad del autor de la llamada llamar a Release. Si se produce un error, *ppvResult debe ser NULL.
Valor devuelto
Este método puede devolver los valores devueltos estándar E_OUTOFMEMORY y E_UNEXPECTED, así como los siguientes valores.
| Código devuelto | Descripción |
|---|---|
|
La operación de enlace se realizó correctamente. |
|
No se encontró el objeto identificado por este moniker o algún objeto identificado por el moniker compuesto del que este moniker es parte. |
|
No se pudo completar la operación de enlace dentro del límite de tiempo especificado por la estructura de BIND_OPTS del contexto de enlace. |
|
La operación de enlace requiere ayuda del usuario final. La razón más común para devolver este valor es que se necesita una contraseña o que se debe montar un disquete. Cuando se devuelve este valor, recupere el moniker que provocó el error con una llamada a IBindCtx::GetObjectParam con la clave "ConnectManually". A continuación, puede llamar a IMoniker::GetDisplayName para obtener el nombre para mostrar, mostrar un cuadro de diálogo que comunique la información deseada, como instrucciones para montar un disquete o una solicitud de contraseña y, a continuación, reintentar la operación de enlace. |
|
Se encontró un objeto intermedio, pero no admitía una interfaz necesaria para completar la operación de enlace. Por ejemplo, un moniker de elemento devuelve este valor si su contenedor no admite la interfaz IOleItemContainer . |
|
No se puede acceder al objeto de almacenamiento. |
Este método también puede devolver los errores asociados al método IOleItemContainer::GetObject .
Comentarios
BindToObject implementa la función principal de un moniker, que consiste en localizar el objeto identificado por el moniker y devolver un puntero a una de sus interfaces.
Notas a los autores de llamadas
Si usa un moniker como una conexión persistente entre dos objetos, active la conexión mediante una llamada a BindToObject.Normalmente, se llama a BindToObject durante el proceso siguiente:
- Cree un objeto de contexto de enlace con una llamada a la función CreateBindCtx .
- Llame a BindToObject mediante el moniker y recupere un puntero a una interfaz deseada en el objeto identificado.
- Libere el contexto de enlace.
- A través del puntero de interfaz adquirido, realice las operaciones deseadas en el objeto .
- Cuando termine con el objeto , libere el puntero de interfaz del objeto.
HRESULT hr; // An error code
IMoniker * pMnk; // A previously acquired interface moniker
// Obtain an IBindCtx interface.
IBindCtx * pbc;
hr = CreateBindCtx(NULL, &pbc);
if (FAILED(hr)) exit(0); // Handle errors here.
// Obtain an implementation of pCellRange.
ICellRange * pCellRange;
hr = pMnk->BindToObject(pbc, NULL, IID_ICellRange, &pCellRange);
if (FAILED(hr)) exit(0); // Handle errors here.
// Use pCellRange here.
// Release interfaces after use.
pbc->Release();
pCellRange->Release();
También puede usar la función BindMoniker cuando se pretende solo una operación de enlace y no es necesario conservar el objeto de contexto de enlace. Esta función auxiliar encapsula la creación del contexto de enlace, llamando a BindToObject y liberando el contexto de enlace.
Los contenedores COM que admiten vínculos a objetos usan monikers para buscar y obtener acceso al objeto vinculado, pero normalmente no llaman directamente a BindToObject . En su lugar, cuando un usuario activa un vínculo en un contenedor, el contenedor de vínculos normalmente llama a IOleObject::D oVerb, mediante la implementación del controlador de vínculos, que llama a BindToObject en el moniker almacenado en el objeto vinculado (si no puede controlar el verbo).
Notas para los implementadores
Lo que hace la implementación depende de si espera que el moniker tenga un prefijo; es decir, si espera que el parámetro pmkToLeft sea NULL o no. Por ejemplo, un moniker de elemento, que identifica un objeto dentro de un contenedor, espera que pmkToLeft identifique el contenedor. En consecuencia, un moniker de elemento usa pmkToLeft para solicitar servicios de ese contenedor. Si espera que el moniker tenga un prefijo, debe usar el parámetro pmkToLeft (por ejemplo, llamar a BindToObject en él) para solicitar servicios del objeto que identifica.Si espera que el moniker no tenga ningún prefijo, la implementación de BindToObject debe comprobar primero la tabla de objetos en ejecución (ROT) para ver si el objeto ya está en ejecución. Para adquirir un puntero a ROT, la implementación debe llamar a IBindCtx::GetRunningObjectTable en el parámetro pbc . A continuación, puede llamar al método IRunningObjectTable::GetObject para ver si el moniker actual se ha registrado en rot. Si es así, puede llamar inmediatamente a QueryInterface para obtener un puntero a la interfaz solicitada por el autor de la llamada.
Cuando la implementación de BindToObject se enlaza a algún objeto, debe usar el parámetro pbc para llamar a IBindCtx::RegisterObjectBound para almacenar una referencia al objeto enlazado en el contexto de enlace. Esto garantiza que el objeto enlazado permanece en ejecución hasta que se libere el contexto de enlace, lo que puede evitar el gasto de tener una operación de enlace posterior que vuelva a cargarlo más adelante.
Si la estructura BIND_OPTS del contexto de enlace especifica la marca BINDFLAGS_JUSTTESTEXISTENCE, la implementación tiene la opción de devolver NULL en ppvResult (aunque también puede omitir la marca y realizar la operación de enlace completa).
Notas específicas de la implementación
| Implementación | Notas |
|---|---|
| Anti-moniker | Este método no se implementa. Devuelve E_NOTIMPL. |
| Moniker de clase |
Si pmkLeft es NULL, llama a CoGetClassObject, con el CLSID con el moniker de clase inicializado (en CreateClassMoniker o a través de MkParseDisplayName) y CLSCTX del pbc actual (IBindCtx).
Si pmkLeft no es NULL, llama a pmkLeft-BindToObject> para IClassActivator y llama a IClassActivator::GetClassObject con el CLSID con y con los parámetros CLSCTX y configuración regional del pbc actual (IBindCtx). |
| Moniker de archivo |
Cuando pmkToLeft es NULL, el método busca el moniker en rot y, si se encuentra, consulta el objeto recuperado para el puntero de interfaz solicitado. Si el moniker no se encuentra en ROT, el método carga el objeto desde el sistema de archivos y recupera el puntero de interfaz solicitado.
Si pmkLeft no es NULL, en lugar de determinar la clase para crear instancias e inicializar con el contenido del archivo al que hace referencia el moniker de archivo mediante GetClassFile (u otros medios), llame a pmkLeft-BindToObject> para IClassFactory e IClassActivator, recupere este puntero en pcf. Si se produce un error con E_NOINTERFACE, devuelva MK_E_INTERMEDIATEINTERFACENOTSUPPORTED. Si el puntero IClassFactory se recupera correctamente, llame a pcf-CreateInstance>(IID_IPersistFile, (void**)&ppf) para obtener una nueva instancia de la clase que se va a inicializar e inicializar mediante IPersistFile u otros medios adecuados según las rutas de inicialización existentes del moniker de archivo. |
| Moniker compuesto genérico | Si pmkToLeft es NULL, este método busca el moniker en rot y, si se encuentra, consulta el objeto recuperado para el puntero de interfaz solicitado. Si pmkToLeft no es NULL, el método llama recursivamente a BindToObject en el componente situado más a la derecha del compuesto, pasando el resto del compuesto como parámetro pmkToLeft para esa llamada. |
| Moniker de elemento | Si pmkToLeft es NULL, este método devuelve E_INVALIDARG. De lo contrario, el método llama a BindToObject en el parámetro pmkToLeft y solicita un puntero de interfaz IOleItemContainer . A continuación, el método llama a IOleItemContainer::GetObject, pasando la cadena contenida en el moniker y devuelve el puntero de interfaz solicitado. |
| OBJREF moniker | El parámetro pmkToLeft debe ser NULL. Dado que el moniker OBJREF representa un objeto en ejecución, no se realiza ninguna activación. Si el objeto representado ya no se está ejecutando, BindToObject produce un error con E_UNEXPECTED. |
| Moniker de puntero | Este método consulta el puntero ajustado para la interfaz solicitada. |
| Moniker de dirección URL | Dado que el Moniker de dirección URL admite el enlace asincrónico, el valor devuelto real de su BindToObject puede variar en función de los parámetros de objeto establecidos en el contexto de enlace. Para obtener más información, consulte más adelante. |
La semántica de la operación de enlace para un moniker de dirección URL es idéntica, independientemente del uso sincrónico o asincrónico, y son los siguientes:
- El moniker de dirección URL extrae más información para la operación de enlace del contexto de enlace. Por ejemplo, el moniker puede obtener punteros a las interfaces IBindStatusCallback e IEnumFORMATETC registradas en el contexto de enlace. Puede incluir más opciones de enlace especificadas en el contexto de enlace a través de IBindCtx::SetBindOptions, como el parámetro dwTickCountDeadline o el valor grfFlags de BIND_MAYBOTHERUSER.
-
A continuación, el moniker comprueba el ROT del contexto de enlace para determinar si el objeto al que se hace referencia ya se está ejecutando. El moniker puede obtener esta información con las siguientes llamadas:
IBindCtx::GetRunningObjectTable(&prot) prot->IsRunning(this) -
Si el objeto ya se está ejecutando, el moniker recupera el objeto en ejecución con la siguiente llamada:
prot->GetObject(this, &punk) - A continuación, el moniker llama a QueryInterface para la interfaz solicitada.
- De lo contrario, el moniker consulta al cliente mediante una llamada a IBindStatusCallback::GetBindInfo para obtener información de enlace adicional. Después, el moniker inicia la operación de enlace y pasa la interfaz IBinding resultante al cliente llamando a IBindStatusCallback::OnStartBinding.
- Si en el paso 1 se determinó que se trata de un enlace asincrónico, BindToObject devuelve MK_S_ASYNCHRONOUS en este momento con NULL en ppv. El llamador recibirá el puntero de objeto real durante el método IBindStatusCallback::OnObjectAvailable en algún momento posterior. A continuación, los pasos siguientes se producen de forma asincrónica en el autor de la llamada, normalmente en otro subproceso de ejecución.
-
La clase del recurso designado por el Moniker de dirección URL se determina de una de las siguientes maneras:
- El moniker de dirección URL examina el tipo de medio de los datos. Si el tipo de medio es application/x-oleobject, los primeros 16 bytes de los datos reales (Content-Body) contienen el CLSID del recurso y los datos posteriores se interpretarán mediante la propia clase. Para todos los demás tipos de medios, el Moniker de dirección URL busca en el Registro del sistema la clave HKEY_CLASSES_ROOT\MIME\Database\Content-Type\<media-type>\CLSID. Tenga en cuenta que application/x-oleobject se usará hasta que se apruebe application/oleobject.
- El moniker de dirección URL coincide con partes de los datos de llegada a patrones registrados en el registro del sistema en HKEY_CLASSES_ROOT\FileTypes.
- Por último, si se produce un error en todo, el Moniker de dirección URL correlaciona la extensión final del recurso, si existe, con un CLSID mediante el HKEY_CLASSES_ROOT\.??? claves en el Registro del sistema, como lo hace GetClassFile y el shell.
- Después de determinar la clase , el moniker de dirección URL crea una instancia mediante CoCreateInstance de CLSCTX_SERVER pidiendo la interfaz IUnknown .
- El moniker de dirección URL siguiente llama al método QueryInterface del objeto recién creado para la interfaz IPersistMoniker . Si QueryInterface se realiza correctamente, el moniker de dirección URL llama a IPersistMoniker::Load pasando a sí mismo (esto) como parámetro de moniker. Normalmente, el objeto llama a BindToStorage que solicita la interfaz de almacenamiento en la que están interesados.
-
De lo contrario, el moniker de dirección URL llama a QueryInterface para IPersistStream y, si se ejecuta correctamente, llama a IPersistStream::Load, pasando el objeto un puntero IStream para un objeto de secuencia que el transporte rellena de forma asincrónica.
Si la clase a la que se llama no está marcada con la categoría CATID_AsyncAware, llama a ISequentialStream::Read o ISequentialStream::Write que los datos de referencia aún no están disponibles hasta que los datos estén disponibles. Estas llamadas se bloquean en el sentido COM tradicional. Se escribe un bucle de mensajes que permite procesar determinados mensajes y se llama adecuadamente al IMessageFilter del subproceso.
Si la clase está marcada con la categoría CATID_AsyncAware, llama a ISequentialStream::Read o ISequentialStream::Write que aún no están disponibles los datos de referencia E_PENDING.
- De lo contrario, el moniker de dirección URL llama a QueryInterface para IPersistFile y, si se ejecuta correctamente, completa la descarga en un archivo temporal. Al finalizar, el moniker de dirección URL llama a IPersistFile::Load. El archivo creado se almacena en caché junto con otros datos descargados de Internet. El cliente debe asegurarse de no eliminar este archivo.
- Cuando el objeto vuelve de una de las distintas llamadas load descritas en los pasos anteriores, el moniker de dirección URL llama al método IBindStatusCallback::OnObjectAvailable para devolver el puntero de interfaz que el cliente solicitó originalmente cuando el cliente llamó a BindToObject.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows 2000 Professional [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows 2000 Server [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | objidl.h |