DataSourceListener

The DataSourceListener methods described below should only be used 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 name of the columns changes, the type of a column changes, or the entire data set is reordered (the result of a sort operation). In such an instance, there needs to be a way for the consumer to be notified of the change so it can retrieve a new interface on the (changed) data by using a call to msDataSourceObject. Consumers will do this by registering with the provider for a notification.

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);
}

Notes

• When a data change occurs, the object will call the dataMemberChanged method of the DataSourceListener 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. dataMemberAdded and 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 addDataSourceListener(NULL). Note that this precludes multi-casting event notifications but keeps requirements on controls simple.