The FORMATETC and STGMEDIUM Structures

Before you're ready for the IDataObject member functions, you need to examine two important COM structures that are used as parameter types: the FORMATETC structure and the STGMEDIUM structure.

FORMATETC

The FORMATETC structure is often used instead of a clipboard format to represent data format information. However, unlike the clipboard format, the FORMATETC structure includes information about a target device, the aspect or view of the data, and a storage medium indicator. Here are the members of the FORMATETC structure.

Type	Name	Description
CLIPFORMAT	cfFormat	Structure that contains clipboard formats, such as standard interchange formats (for example, CF_TEXT, which is a text format, and CF_DIB, which is an image compression format), custom formats (such as rich text format), and OLE formats used to create linked or embedded objects
DVTARGETDEVICE*	ptd	Structure that contains information about the target device for the data, including the device driver name (can be NULL)
DWORD	dwAspect	A DVASPECT enumeration constant (DVASPECT_CONTENT, DVASPECT _THUMBNAIL, and so on)
LONG	lindex	Usually -1
DWORD	tymed	Specifies type of media used to transfer the object's data (TYMED_HGLOBAL, TYMED_FILE, TYMED_ISTORAGE, and so on)

An individual data object accommodates a collection of FORMATETC elements, and the IDataObject interface provides a way to enumerate them. A useful macro for filling in a FORMATETC structure appears below.

#define SETFORMATETC(fe, cf, asp, td, med, li)   \     ((fe).cfFormat=cf, \     (fe).dwAspect=asp, \     (fe).ptd=td, \     (fe).tymed=med, \     (fe).lindex=li) 

STGMEDIUM

The other important structure for IDataObject members is the STGMEDIUM structure. The STGMEDIUM structure is a global memory handle used for operations involving data transfer. Here are the members.

Type	Name	Description
DWORD	tymed	Storage medium value used in marshaling and unmarshaling routines
HBITMAP	hBitmap	Bitmap handle*
HMETAFILEPICT	hMetaFilePict	Metafile handle*
HENHMETAFILE	hEnhMetaFile	Enhanced metafile handle*
HGLOBAL	hGlobal	Global memory handle*
LPOLESTR	lpszFileName	Disk filename (double-byte)*
ISTREAM*	pstm	IStream interface pointer*
ISTORAGE*	pstg	IStorage interface pointer*
IUNKNOWN	pUnkForRelease	Used by clients to call Release for formats with interface pointers

* This member is part of a union, including handles, strings, and interface pointers used by the receiving process to access the transferred data.

As you can see, the STGMEDIUM structure specifies where data is stored. The tymed variable determines which union member is valid.

The IDataObject Interface Member Functions

This interface has nine member functions. Both Brockschmidt and the online documentation do a good job of describing all of these functions. Following are the functions that are important for this chapter.

HRESULT EnumFormatEtc(DWORD dwDirection, IEnumFORMATETC ppEnum);

If you have an IDataObject pointer for a data object, you can use EnumFormatEtc to enumerate all the formats that it supports. This is an ugly API that the MFC library insulates you from. You'll learn how this happens when you examine the COleDataObject class.

HRESULT GetData(FORMATETC* pFEIn, STGMEDIUM* pSTM);

GetData is the most important function in the interface. Somewhere, up in the sky, is a data object, and you have an IDataObject pointer to it. You specify, in a FORMATETC variable, the exact format you want to use when you retrieve the data, and you prepare an empty STGMEDIUM variable to accept the results. If the data object has the format you want, GetData fills in the STGMEDIUM structure. Otherwise, you get an error return value.

HRESULT QueryGetData(FORMATETC* pFE);

You call QueryGetData if you're not sure whether the data object can deliver data in the format specified in the FORMATETC structure. The return value says, "Yes, I can" (S_OK) or "No, I can't" (an error code). Calling this function is definitely more efficient than allocating a STGMEDIUM variable and calling GetData.

HRESULT SetData(FORMATETC* pFEIn, STGMEDIUM* pSTM, BOOL fRelease);

Data objects rarely support SetData. Data objects are normally loaded with formats in their own server module; clients retrieve data by calling GetData. With SetData, you'd be transferring data in the other direction—like pumping water from your house back to the water company.

Other IDataObject Member Functions—Advisory Connections

The interface contains other important functions that let you implement an advisory connection. When the program using a data object needs to be notified whether the object's data changes, the program can pass an IAdviseSink pointer to the object by calling the IDataObject::DAdvise function. The object then calls various IAdviseSink member functions, which the client program implements. You won't need advisory connections for drag-and-drop operations, but you will need them when you get to embedding in Chapter 28.