Метод 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 можно реализовать одним из следующих способов:
|
[in] pAdvSink
Указатель на интерфейс IAdviseSink в приемнике рекомендаций, который получит уведомление об изменении.
[out] pdwConnection
Маркер, идентифицирующий это подключение. Этот маркер можно использовать позже, чтобы удалить консультативное подключение (передав его в IDataObject::D Unadvise). Если это значение равно 0, подключение не установлено.
Возвращаемое значение
Этот метод возвращает значение S_OK при успешном завершении. Ниже перечислены другие возможные значения.
| Код возврата | Описание |
|---|---|
|
Этот метод не был реализован в объекте данных. |
|
Недопустимое значение для lindex ; В настоящее время поддерживается только -1. |
|
Недопустимое значение для pformatetc . |
|
Объект данных не поддерживает уведомление об изменении. |
Комментарии
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 |