COM Objects as Data Providers

  • Article

To date, MSHTML, introduced in Microsoft Internet Explorer 4.0, has used the type information of a Component Object Model (COM) object to determine if it was a data provider. This was non-standard and confusing 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.

  • Recognizing COM Objects as Data Providers
    • DISPID
  • Notifications for Data Set Changes
    • DISPID

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 Internet Explorer 4.0/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 the COM object.

Note  Internet Explorer 4.0/MSHTML 1.0 will only support COM objects that supply a single data set. Therefore, Internet Explorer 4.0/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 names of columns change, the type of columns changes, or the entire data set is reordered (as 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. This is done 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.

Note  Internet Explorer 4.0/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.

Note   Since Internet Explorer 4.0/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.

Note  Internet Explorer 4.0/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.