COM Objects as Data ProvidersCOM Objects as Data Providers*
*



Contents  *



Index  *Topic Contents
*Previous Topic: IE4/MSHTML Data Binding Interfaces
*Next Topic: OLE-DB Simple Provider: A Data Binding API for IE4/MSHTML

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 that can be used 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 that, when called, returns an interface pointer to 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 be 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 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 will only use the value NULL or "" for the qualifier. The dataMemberAdded and dataMemberRemoved methods are called to notify the consumer that a multiple-dataset-capable applet has a new data set available or has removed a 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 multicasting 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.

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.