Share via

DataSourceListener

  • Article

The DataSourceListener methods described below should be used only when the provider is being written in Microsoft? Visual Basic? or Microsoft Visual J++?. Implement the methods in your provider code using the appropriate IDispatch methods.

There are instances where a consumer already has an interface to a data set supplied by the object and the shape of the data set changes. For example, the number of columns changes, the names of the columns change, the type of a column changes, or the entire data set is reordered (the result of a sort operation). In such an instance, the consumer needs to be notified of the change so it can retrieve a new interface on the (changed) data by using a call to IDispatch::msDataSourceObject. Consumers will do this by registering with the provider for a notification.

Important

This feature will be removed in a future version of Windows. Avoid using this feature in new development work, and plan to modify applications that currently use this feature. Instead, write a fully functional OLE DB provider using the native OLE DB interfaces.

The object must support a method whereby the consumer can register for receiving such notifications. The method has the following signature:

HRESULT addDataSourceListener(
   [in] DataSourceListener    *pEvent);

DataSourceListener is defined as follows:

[ local, object, version(1.0)
  uuid(7c0ffab2-cd84-11d0-949a-00a0c91110ed) ]
interface DataSourceListener : IUnknown
{
   HRESULT dataMemberChanged([in] BSTR qualifier);
   HRESULT dataMemberAdded([in] BSTR qualifier);
   HRESULT dataMemberRemoved([in] BSTR qualifier);
}

Comments

When a data change occurs, the object will call the IDataSourceListener::dataMemberChanged method of the DataSourceListener method to notify the consumer that the shape has changed. The object will pass the corresponding qualifier to the consumer. However, only the values NULL or "" are valid for the qualifier. IDataSourceListener::dataMemberAdded and IDataSourceListener::dataMemberRemoved are called to notify the consumer that a multiple-dataset?capable control has a new data set available or has removed a previously existing one. Because providers with multiple data sets are not currently supported, these events are ignored.

A data consumer can notify a provider that it is no longer interested in data shape change notifications by calling IDataSource::addDataSourceListener(NULL). This precludes multicasting event notifications but keeps requirements on controls simple.