COM Objects as Data Providers

COM Objects as Data Providers


To date, IE4/MSHTML has used the typeinfo of a COM object to determine if it was a data provider. This was confusing, non-standard, and less than straightforward to implement with dual interface support.

This document specifies a new method for data providing COM objects to advertise that they are data providers. Additionally, it specifies a notification mechanism which can be utilized by data consumers to receive notifications when the underlying data set supplied by the object changes.

arrowy.gifRecognizing COM Objects as Data Providers

arrowy.gifNotifications for Data Set Changes

Recognizing COM Objects as Data Providers

Data providing COM objects will identify themselves as data providers by implementing a method which when called returns an interface pointer one of the IE4/MSHTML supported data interfaces. The signature for the method is as follows:

HRESULT msDataSourceObject( [in] BSTR qualifier ,
                            [out,retval] IUnknown **ppUnk);

The qualifier parameter will be used when a data providing COM object supports access to more than one set of data. When the parameter is NULL or a null string (""), the COM object should return the data interface on its default data set. What constitutes the default data set is left to COM object.

IE4/MSHTML 1.0 will only support COM objects that supply a single data set. Therefore, IE4/MSHTML will only use the msDataSourceObject(0) form of the call when invoking the interface.

DISPID

This interface will be available at the reserved DispID: -3900.

Notifications for Data Set Changes

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(s) changes, or the entire data set is reordered (result of a sort operation). In such an instance, there needs to be a way for the consumer to get notified of the change so it can retrieve a new interface on the (changed) data - 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);
}

When a data change occurs, the object will call the dataMemberChanged() method of the DataSourceListener to notify the data consumer that the shape has changed. The object will pass the corresponding qualifier to the consumer. IE4/MSHTML 1.0 this will only use the value NULL or "" for qualifier. The dataMemberAdded() and dataMemberRemoved() are called to notify the consumer that a multiple-dataset capable applet has a new data set available or has removed an previously existing data set. Since IE4/MSHTML 1.0 will not support multiple data sets, these events will be ignored.

Finally, 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.

IE4/MSHTML 1.0 will never examine the qualifier value in DataSourceListener::dataMemberChanged() since providers with multiple datasets are not supported.

DISPID

This interface will be available at the reserved DispID: -3901.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.