Método IDataObject::D Advise (objidl.h)

  • Artículo

Llamado por un objeto que admite un receptor de asesoramiento para crear una conexión entre un objeto de datos y el receptor de asesoramiento. Esto permite que el receptor de aviso reciba una notificación de los cambios en los datos del objeto.

Sintaxis

HRESULT DAdvise(
  [in]  FORMATETC   *pformatetc,
  [in]  DWORD       advf,
  [in]  IAdviseSink *pAdvSink,
  [out] DWORD       *pdwConnection
);

Parámetros

[in] pformatetc

Puntero a una estructura FORMATETC que define el formato, el dispositivo de destino, el aspecto y el medio que se usarán para futuras notificaciones. Por ejemplo, es posible que un receptor quiera saber cuando va a cambiar la representación del mapa de bits de los datos en el objeto de datos. Otro receptor puede estar interesado solo en el formato de metarchivo del mismo objeto. Se notifica cada receptor de notificaciones cuando cambian los datos de interés. Estos datos se devuelven al receptor de notificaciones cuando se produce una notificación.

[in] advf

Un grupo de marcas para controlar la conexión de asesoramiento. Los valores posibles proceden de la enumeración ADVF . Sin embargo, solo algunos de los posibles valores de ADVF son relevantes para este método. En la tabla siguiente se describen brevemente los valores pertinentes.

Valor de ADVF Descripción
ADVF_NODATA Pide al objeto de datos que evite enviar datos con las notificaciones. Normalmente, se envían datos. Esta marca es una manera de invalidar el comportamiento predeterminado. Cuando se usa ADVF_NODATA, el miembro tymed de la estructura STGMEDIUM que se pasa a OnDataChange normalmente contendrá TYMED_NULL. A continuación, el autor de la llamada puede recuperar los datos con una llamada IDataObject::GetData posterior.
ADVF_ONLYONCE Hace que la conexión de aviso se destruya después de enviar la primera notificación de cambio. Se realiza una llamada implícita a IDataObject::D Unadvise en nombre del autor de la llamada para quitar la conexión.
ADVF_PRIMEFIRST Solicita una notificación inicial adicional. La combinación de ADVF_ONLYONCE y ADVF_PRIMEFIRST proporciona, en efecto, una llamada asincrónica IDataObject::GetData .
ADVF_DATAONSTOP Cuando se especifica con ADVF_NODATA, esta marca hace que se envíe una última notificación con los datos incluidos antes de que se destruya el objeto de datos.

Si se usa sin ADVF_NODATA, DAdvise se puede implementar de una de las maneras siguientes:

  • Se puede omitir el ADVF_DATAONSTOP.
  • El objeto puede comportarse como si se especificara ADVF_NODATA.
Solo se envía una notificación de cambio en el caso de apagado. Los cambios de datos antes del apagado no hacen que se envíe una notificación.

[in] pAdvSink

Puntero a la interfaz IAdviseSink en el receptor de asesoramiento que recibirá la notificación de cambio.

[out] pdwConnection

Token que identifica esta conexión. Puede usar este token más adelante para eliminar la conexión de asesoramiento (pasandolo a IDataObject::D Unadvise). Si este valor es 0, no se estableció la conexión.

Valor devuelto

Este método devuelve S_OK cuando funciona correctamente. Otros valores posibles incluyen lo siguiente.

Código devuelto Descripción
E_NOTIMPL
 Este método no se implementa en el objeto de datos.
DV_E_LINDEX
 El valor de lindex no es válido; actualmente, solo se admite -1.
DV_E_FORMATETC
 El valor de pformatetc no es válido.
OLE_E_ADVISENOTSUPPORTED
 El objeto de datos no admite la notificación de cambios.

Comentarios

DAdvise crea una conexión de notificación de cambio entre un objeto de datos y el autor de la llamada. El autor de la llamada proporciona un receptor de asesoramiento al que se pueden enviar las notificaciones cuando cambian los datos del objeto.

Los objetos usados simplemente para la transferencia de datos normalmente no admiten notificaciones de asesoramiento y devuelven OLE_E_ADVISENOTSUPPORTED de DAdvise.

Notas a los autores de llamadas

El objeto que admite el receptor de aviso llama a DAdvise para configurar la conexión, especificando el formato, el aspecto, el medio o el dispositivo de destino de interés en la estructura FORMATETC pasada. Si el objeto de datos no admite uno o varios de los atributos solicitados o el envío de notificaciones en absoluto, puede rechazar la conexión devolviendo OLE_E_ADVISENOTSUPPORTED.

Los contenedores de objetos vinculados pueden configurar conexiones de asesoramiento directamente con el origen del vínculo enlazado o indirectamente a través del objeto de vínculo OLE estándar que administra la conexión. Connections configurar con el origen del vínculo enlazado no se eliminan automáticamente. El contenedor debe llamar explícitamente a IDataObject::D Unadvise en el origen del vínculo enlazado para eliminar una conexión de asesoramiento. El objeto de vínculo OLE, manipulado a través de la interfaz IOleLink , se implementa en el controlador predeterminado. Connections configurar a través del objeto de vínculo OLE se destruye cuando se elimina el objeto de vínculo.

El objeto de vínculo predeterminado OLE crea un "aviso comodín" con el origen del vínculo para que OLE pueda mantener la hora del último cambio. Este aviso se usa específicamente para anotar el tiempo que cualquier cosa ha cambiado. OLE omite todos los formatos de datos que pueden haber cambiado, teniendo en cuenta solo la hora del último cambio. Para permitir avisos de caracteres comodín, establezca los miembros FORMATETC de la siguiente manera antes de llamar a DAdvise:

cf == 0; 
ptd == NULL; 
dwAspect == -1; 
lindex == -1 
tymed == -1;

Las marcas de aviso también deben incluir ADVF_NODATA. Las aplicaciones siempre deben aceptar los avisos comodín de OLE.

Notas para los implementadores

Para simplificar la implementación de DAdvise y los demás métodos de notificación en IDataObject (DUnadvise y EnumDAdvise) que admiten notificaciones, OLE proporciona un objeto de titular de asesoramiento que administra el registro y el envío de notificaciones. Para obtener un puntero a este objeto, llame a la función auxiliar CreateDataAdviseHolder en la primera invocación de DAdvise. Esto proporciona un puntero a la interfaz IDataAdviseHolder del objeto. A continuación, delegue la llamada al método IDataAdviseHolder::Advise en el titular del aviso de datos, que crea y administra posteriormente la conexión solicitada.

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

Consulte también

CreateDataAdviseHolder

IAdviseSink::OnDataChange

IDataObject