Data Objects and the IDataObject Interface

Any component that is a source of formatted data structures is a data object if it implements IDataObject. Any and all code that in one way or another has data to share can do so with a data object. The great benefit of doing this is that once you have a data object implementation around, you can use that data object in any transfer protocol, be it clipboard, drag and drop, compound documents, OLE Automation, and so on, and any new format you might support is instantly provided through all the protocols. A source can centralize the code that renders data into this data object implementation; a consumer can centralize the code necessary to check available formats in a data object and also centralize the code used to paste that data. Centralization reduces both the overall amount of code you must implement and the number of different API functions for dealing with each protocol.

Centralization is possible because the IDataObject interface combines the functionality of the existing data transfer protocols, thereby providing more functionality in an OLE data transfer than is available for any other existing protocol. The definition of the IDataObject interface is as follows:

interface IDataObject : IUnknown
    {
    HRESULT GetData(LPFORMATETC pFEIn, LPSTGMEDIUM pSTM);
    HRESULT GetDataHere(LPFORMATETC pFE, LPSTGMEDIUM pSTM);
    HRESULT QueryGetData(LPFORMATETC pFE);
    HRESULT GetCanonicalFormatEtc(LPFORMATETC pFEIn
        , LPFORMATETC pFEOut);
    HRESULT SetData(LPFORMATETC pFE, LPSTGMEDIUM pSTM, BOOL fRelease);
    HRESULT EnumFormatEtc(DWORD dwDirection, LPENUMFORMATETC *ppEnum);
    HRESULT DAdvise(LPFORMATETC pFE, DWORD grfAdv, LPADVISESINK pAdvSink
        , LPDWORD pdwConnection);
    HRESULT DUnadvise(DWORD dwConnection);
    HRESULT EnumDAdvise(LPENUMSTATDATA *ppEnum);
    };

Many of the member functions have equivalents in specific Windows API functions; keep in mind, however, that data objects are used to describe data transferred by means of any protocol, and thus they provide the ability to treat data in a uniform fashion regardless of how you obtained the IDataObject pointer. The following list describes each IDataObject member in more detail and lists the similar (but not always exact) functionality that exists in the clipboard, DDE, and outdated OLE 1 transfer protocols:

• GetData renders the data described by a FORMATETC and returns it in the out-parameter STGMEDIUM, which then becomes the caller's responsibility.

• SetData provides data to the source described by a FORMATETC and referenced by the in-parameter STGMEDIUM. The data object is responsible for releasing the data if the fRelease flag is TRUE. When you call SetData, the tymed fields in both FORMATETC and STGMEDIUM structures must match.

• GetDataHere allows the caller to provide a preallocated medium in which to render the data. For example, if the caller provides an IStream object and asks for CF_BITMAP, the source should serialize its bitmap into that stream instead of allocating a new stream on its own as it would through GetData. This capability is not found in any existing protocol.
• QueryGetData answers whether the data object can render data described by the given FORMATETC. The caller can be as specific as desired. QueryGetData returns NOERROR for "yes" or S_FALSE for "no," so don't use the SUCCEEDED or FAILED macro to test return values; compare directly with NOERROR.

• GetCanonicalFormatEtc provides a different but logically equivalent FORMATETC structure, allowing the caller to determine whether a rendering it has already obtained is identical to what would be obtained by calling GetData with a different FORMATETC. There is no equivalent to this function in any existing protocol.
• EnumFormatEtc instantiates and returns a FORMATETC enumerator object through which the caller can determine all available formats that the object can provide. There must be a unique element in the enumeration for each cfFormat, dwAspect, and ptd variation, although you can combine TYMED_* values in tymed. The enumerator object implements the single IEnumFORMATETC interface, and the caller is responsible for calling IEnumFORMATETC::Release when it has finished so the object can free itself. The caller can ask for an enumerator for either "direction," GetData or SetData. See the section "FORMATETC Enumerators and Format Ordering" beginning on page 508 for more details on this enumerator.

• DAdvise3 sets up an advisory connection between the data object and a caller, providing an advise sink in which the caller indicates the data of interest in a FORMATETC. The data object calls IAdviseSink::OnDataChange when a change occurs, possibly sending the data along with the notification.

• DUnadvise terminates an advisory connection previously established with DAdvise.

• EnumDAdvise returns an enumerator with the IEnumSTATDATA interface. There is no equivalent to this function in any existing protocol. A STATDATA structure holds information pertaining to each advisory connection to the data object:

  
  

  typedef struct  tagSTATDATA
      {
      FORMATETC    formatetc;
      DWORD        advf;
      IAdviseSink *pAdvSink;
      DWORD        dwConnection;
      }   STATDATA;

You can see from the preceding list that no existing protocol supports the full range of functionality that IDataObject provides for all protocols. This is not to say that any arbitrary data object that a client might obtain actually implements the full functionality of every member function. Some data objects—such as a static bitmap on the clipboard—will refuse any advisory connections. Others might not support any SetData calls. But you are always allowed to try to learn the data object's capabilities through error return values. With existing protocols, you are not even allowed to play a little.

Related to IDataObject is an OLE API function that you might find useful in your work: OleDuplicateData. This function will copy any global-memory–based format, including metafiles, bitmaps, and palettes. Its signature is as follows:

HANDLE OleDuplicateData(HANDLE hSrc, CLIPFORMAT cf, UINT uiFlags);

where hSrc is the handle of the source data, cf identifies the format of the data, and uiFlags specifies the flags to pass to GlobalAlloc if such memory needs allocation. If uiFlags is 0, the function assumes GMEM_MOVEABLE.

OleDuplicateData will perform a bytewise duplication of the data except in the case of CF_METAFILEPICT, CF_ENHMETAFILE, CF_PALETTE, and CF_BITMAP, for which special handling is required. Accordingly, hSrc must be a global-memory handle for any bytewise duplication, whereas it is the appropriate handle type when used with these other four formats.