The FORMATETC Structure

FORMATETC (pronounced "format et cetera") is a generalization—and an improvement—of the clipboard format and contains a rich description of data. The name comes from the idea that it contains a clipboard format and some more stuff—the et cetera:

typedef WORD CLIPFORMAT;

typedef struct tagFORMATETC
    {
    CLIPFORMAT      cfFormat;
    DVTARGETDEVICE *ptd;
    DWORD           dwAspect;
    LONG            lindex;
    DWORD           tymed;
    } FORMATETC;

enum tagDVASPECT
    {
    DVASPECT_CONTENT    = 1,
    DVASPECT_THUMBNAIL  = 2,
    DVASPECT_ICON       = 4,
    DVASPECT_DOCPRINT   = 8
    } DVASPECT;

Its fields carry information as follows:

• cfFormat: The clipboard format identifying the data structure. This can be a standard format such as CF_TEXT or a format that both source and consumer register with the Windows API RegisterClipboardFormat. The use of "clipboard" here is archaic—the identified structures themselves have nothing to do with the clipboard. The name stuck because the clipboard was the first data exchange protocol in Windows and the first to use a simple integer identification of structures.
• ptd: Information about the device, such as a screen or a printer, for which the data was rendered. The DVTARGETDEVICE structure looks and acts similar to the Windows DEVNAMES structure. It contains a header for a variable-length block of data, and each offset in the structure points to a specific piece of information in the block, where all strings are stored in Unicode under 32-bit OLE:

  
  

  typedef struct FARSTRUCT tagDVTARGETDEVICE
      {
      DWORD   tdSize;
      WORD    tdDriverNameOffset;
      WORD    tdDeviceNameOffset;
      WORD    tdPortNameOffset;
      WORD    tdExtDevmodeOffset;
      BYTE    tdData[1];   //Contains the names and DEVMODE
      } DVTARGETDEVICE;

• tdSize always holds the size of the entire structure, including all additional bytes that occur after the DVTARGETDEVICE header. This simplifies copying the structure when necessary. Each td…Offset field is an offset from the start of the entire structure, not from the start of tdData. Because offsets start at the top of the structure, a 0 means "not present," or a NULL value for that name.
• dwAspect: The detail contained in the rendering, particularly useful for graphical formats. Values are taken from the DVASPECT enumeration: DVASPECT_CONTENT specifies "full content," as would normally be shown in some kind of document; DVASPECT_THUMBNAIL means "thumbnail sketch," as would be used in a print preview or document preview window; DVASPECT_ICON describes an icon view appropriate for small presentations as an attachment to an e-mail message; and DVASPECT_DOCPRINT identifies the rendering as a full "printer document" that includes all page numbers, headers, and footers, just as if the data were printed as a document from its native application.
• lindex: Identifier for the piece of the data when the data must be split across page boundaries. An lindex of -1 identifies the entire data and is the most common value. Otherwise, lindex has meaning only in DVASPECT_CONTENT, in which it identifies a piece of data for extended layout negotiation, and in DVASPECT_DOCPRINT, in which it identifies the page number.1
• tymed: The medium in which the data lives with values taken from the TYMED enumeration. See "The STGMEDIUM Structure" later in this chapter.

Obviously, filling out a structure like this every time you want to describe a data format will become tedious; you need five lines of code simply to fill the structure. To address this, I have defined two macros in INC\INOLE.H that facilitate filling a FORMATETC: SETFormatEtc, which allows you to set every field in a FORMATETC structure explicitly, and SETDefFormatEtc, which allows you to set cfFormat and tymed while filling the other fields with defaults (a common operation):

#define SETFormatEtc(fe, cf, asp, td, med, li)   \
    {\
    (fe).cfFormat=cf;\
    (fe).dwAspect=asp;\
    (fe).ptd=td;\
    (fe).tymed=med;\
    (fe).lindex=li;\
    };

#define SETDefFormatEtc(fe, cf, med)   \
    {\
    (fe).cfFormat=cf;\
    (fe).dwAspect=DVASPECT_CONTENT;\
    (fe).ptd=NULL;\
    (fe).tymed=med;\
    (fe).lindex=-1;\
    };

I encourage you to use these macros when dealing with FORMATETC because they are far more convenient than writing each line of code separately.

Handling DVTARGETDEVICE

As described above, the ptd field of a FORMATETC structure is a pointer to a DVTARGETDEVICE structure. A NULL ptd always means "screen device," which is, of course, the easiest to handle. Printer devices, on the other hand, are more complex. Applications and components that deal with device-specific data will end up performing a few basic operations with such a structure: creating a structure, copying or comparing two structures, and creating a device context or an information context from a structure.

To that end, the sample code for this chapter provides a number of standard implementations of these functions, which you can find in CHAP10\TARGDEV\TARGDEV.CPP.2 In this file are the functions TargetDeviceToDC, TargetDeviceFromPrintDlg, TargetDeviceCopy, and TargetDeviceCompare. TargetDeviceToDC calls CreateDC or CreateIC with the information in a DVTARGETDEVICE structure. TargetDeviceFromPrintDlg creates a DVTARGETDEVICE structure (using the task memory allocator through CoTaskMemAlloc) from the PRINTDLG structure filled by the Windows PrintDlg API function. Applications generally use PrintDlg to obtain printer information in the first place, so it's convenient to be able to send that data to TargetDeviceFromPrintDlg and get back the OLE structure you need.

The other two functions are actually quite simple and manipulate the structure on little more than a binary level. In any case, I hope you find this code useful in your own work.

Copying and Comparing FORMATETC Structures

Whenever you want to copy or compare FORMATETC structures, keep the following in mind. When copying one structure to another, be sure to copy the entire DVTARGETDEVICE structure as well, using code such as that found in the sample TargetDeviceCopy function. Other than that, copying is a straightforward duplication of each field.

Comparing two FORMATETC structures presents a slightly different problem. First of all, the cfFormat and lindex fields must match exactly for equivalence. In addition, both structures must have the same target device structure, which is where the sample TargetDeviceCompare function comes in handy. Both dwAspect and tymed require special handling, however. You can compare these either for exact equivalence or on a subset basis. For example, if one FORMATETC has DVASPECT_CONTENT ¦ DVASPECT_THUMBNAIL, another with only DVASPECT_CONTENT could be considered equivalent but not an exact match. The same applies to TYMED_* flags. Why you'd choose either form of comparison depends on why you're making the comparison in the first place. If you want to determine whether one FORMATETC is a subset of a supported set of formats, use a subset comparison. If you need an exact match for a specific rendering, you want an exact comparison.