Метод IDataObject::D Advise (objidl.h)

  • Статья

Вызывается объектом, поддерживающим приемник рекомендаций, для создания соединения между объектом данных и приемником рекомендаций. Это позволяет приемнику рекомендаций получать уведомления об изменениях в данных объекта .

Синтаксис

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

Параметры

[in] pformatetc

Указатель на структуру FORMATETC , которая определяет формат, целевое устройство, аспект и среду, которая будет использоваться для будущих уведомлений. Например, одному приемнику может требоваться знать только об изменениях в растровом представлении данных в объекте данных. Другой приемник может быть заинтересован только в формате метафайла того же объекта. Каждый приемник уведомлений уведомляется при изменении интересующих его данных. Эти данные передаются назад в приемник уведомлений при возникновении уведомления.

[in] advf

Группа флагов для управления консультативным подключением. Возможные значения из перечисления ADVF . Однако только некоторые из возможных значений ADVF относятся к этому методу. В следующей таблице кратко описаны соответствующие значения.

Значение ADVF Описание
ADVF_NODATA Запрашивает объект данных, чтобы избежать отправки данных с уведомлениями. Обычно отправляются данные. Этот флаг позволяет переопределить поведение по умолчанию. При использовании ADVF_NODATA элемент структурыSTGMEDIUM , передаваемый в OnDataChange , обычно содержит TYMED_NULL. Затем вызывающий объект может получить данные с помощью последующего вызова IDataObject::GetData .
ADVF_ONLYONCE Вызывает уничтожение консультативного подключения после отправки первого уведомления об изменении. Неявный вызов IDataObject::D Unadvise выполняется от имени вызывающей стороны для удаления подключения.
ADVF_PRIMEFIRST Запрашивает дополнительное начальное уведомление. Сочетание ADVF_ONLYONCE и ADVF_PRIMEFIRST фактически обеспечивает асинхронный вызов IDataObject::GetData .
ADVF_DATAONSTOP При указании с помощью ADVF_NODATA этот флаг вызывает отправку последнего уведомления с включенными данными перед уничтожением объекта данных.

При использовании без ADVF_NODATA DAdvise можно реализовать одним из следующих способов:

  • ADVF_DATAONSTOP можно игнорировать.
  • Объект может вести себя так, как если бы ADVF_NODATA было указано.
Уведомление об изменении отправляется только в случае завершения работы. Изменение данных до завершения работы не приводит к отправке уведомления.

[in] pAdvSink

Указатель на интерфейс IAdviseSink в приемнике рекомендаций, который получит уведомление об изменении.

[out] pdwConnection

Маркер, идентифицирующий это подключение. Этот маркер можно использовать позже, чтобы удалить консультативное подключение (передав его в IDataObject::D Unadvise). Если это значение равно 0, подключение не установлено.

Возвращаемое значение

Этот метод возвращает значение S_OK при успешном завершении. Ниже перечислены другие возможные значения.

Код возврата Описание
E_NOTIMPL
 Этот метод не был реализован в объекте данных.
DV_E_LINDEX
 Недопустимое значение для lindex ; В настоящее время поддерживается только -1.
DV_E_FORMATETC
 Недопустимое значение для pformatetc .
OLE_E_ADVISENOTSUPPORTED
 Объект данных не поддерживает уведомление об изменении.

Комментарии

DAdvise создает подключение уведомления об изменениях между объектом данных и вызывающим объектом. Вызывающий объект предоставляет приемник рекомендаций, в который можно отправлять уведомления при изменении данных объекта.

Объекты, используемые просто для передачи данных, обычно не поддерживают уведомления о рекомендациях и не возвращают OLE_E_ADVISENOTSUPPORTED из DAdvise.

Примечания к вызывающим абонентам

Объект, поддерживающий приемник рекомендаций, вызывает DAdvise для настройки подключения, указывая формат, аспект, среду и/или целевое устройство, интересующее переданную структуру FORMATETC . Если объект данных не поддерживает один или несколько запрошенных атрибутов или отправку уведомлений, он может отказать в подключении, возвратив OLE_E_ADVISENOTSUPPORTED.

Контейнеры связанных объектов могут настраивать консультативные подключения непосредственно с источником привязанных ссылок или косвенно через стандартный объект ссылки OLE, который управляет подключением. Connections, настроенные с использованием источника привязанной ссылки, не удаляются автоматически. Контейнер должен явно вызвать IDataObject::D Unadvise в источнике привязанной ссылки, чтобы удалить консультативное подключение. Объект ссылки OLE, которым управляет интерфейс IOleLink , реализуется в обработчике по умолчанию. Connections, настроенные с помощью объекта ссылки OLE, удаляются при удалении объекта ссылки.

Объект ссылки OLE по умолчанию создает "совет с подстановочными знаками" с источником ссылки, чтобы OLE поддерживал время последнего изменения. Этот совет специально используется, чтобы отметить время, когда что-либо изменилось. OLE игнорирует все форматы данных, которые могли измениться, указывая только время последнего изменения. Чтобы разрешить советы с подстановочными знаками, перед вызовом DAdvise задайте элементы FORMATETC следующим образом:

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

Флаги рекомендаций также должны содержать ADVF_NODATA. Советы с подстановочными знаками из OLE всегда должны приниматься приложениями.

Примечания для разработчиков

Чтобы упростить реализацию DAdvise и других методов уведомления в IDataObject (DUnadvise и EnumDAdvise), поддерживающих уведомления, OLE предоставляет объект владельца рекомендаций, который управляет регистрацией и отправкой уведомлений. Чтобы получить указатель на этот объект, вызовите вспомогательную функцию CreateDataAdviseHolder при первом вызове DAdvise. Он предоставляет указатель на интерфейс IDataAdviseHolder объекта. Затем делегируйте вызов методу IDataAdviseHolder::Advise в держателе data advise, который создает запрошенное подключение и управляет им.

Требования

Требование Значение
Минимальная версия клиента Windows 2000 Professional [только классические приложения]
Минимальная версия сервера Windows 2000 Server [только классические приложения]
Целевая платформа Windows
Header objidl.h

См. также раздел

CreateDataAdviseHolder

IAdviseSink::OnDataChange

Idataobject