| C & C++ Programming | MFC Programming | Download | Site Index |


 

 

 

 

Supplementary note for MFC Programming Module 25

 

 

 

 

 

 

What do we have in this Module?

  1. The FORMATETC Structure

  2. FORMATETC

  3. The STGMEDIUM Structure

  4. STGMEDIUM

  5. TYMED Enum

 

 

The FORMATETC Structure

 

The FORMATETC structure is a generalized clipboard format, enhanced to encompass a target device, an aspect or view of the data, and a storage medium. A data consumer, such as an OLE container application, passes the FORMATETC structure as an argument in calls to IDataObject to indicate the type of data it wants from a data source, such as a compound document object. The source uses the FORMATETC structure to describe what formats it can provide. FORMATETC can describe virtually any data, including other objects such as monikers. A container can ask one of its embedded objects to list its data formats by calling IDataObject::EnumFormatetc, which returns an enumerator object that implements the IEnumFormatEtc interface. Instead of replying merely that it has “text and a bitmap,” the object can provide a detailed description of the data, including the device (normally screen or printer) for which it is rendered, the aspect to be presented to the user (full contents, thumbnail, icon, or formatted for printing), and the storage medium containing the data (global memory, disk file, storage object, or stream). This ability to tightly describe data will, in time, result in higher quality printer and screen output as well as more efficiency in data browsing, where a thumbnail sketch is much faster to retrieve and display than a fully detailed rendering. The following table lists fields of the FORMATETC data structure and the information they specify:

 

Field

Specifies

cfFormat

The format in which the data is to be rendered, which can be a standard clipboard format, a proprietary format, or an OLE format.

ptd

A DVTARGETDEVICE structure, which contains enough information about a Windows target device, such as a screen or printer, so that a handle to its device context (hDC) can be created using the Windows CreateDC() function.

dwAspect

The aspect or view of the data to be rendered; can be the full contents, a thumbnail sketch, an icon, or formatted for printing.

lindex

The part of the aspect that is of interest; for the present, the value must be -1, indicating that the entire view is of interest.

tymed

The data’s storage medium, which can be global memory, disk file, or an instance of one of COM’s structured-storage interfaces.

 

 Table 1.

 

FORMATETC

 

Item

Description

Structure

FORMATETC.

Info

The FORMATETC structure is a generalized Clipboard format. It is enhanced to encompass a target device, the aspect or view of the data, and a storage medium indicator. Where one might expect to find a Clipboard format, OLE uses a FORMATETC data structure instead. This structure is used as a parameter in OLE functions and methods that require data format information.

Definition

typedef struct tagFORMATETC

{

CLIPFORMAT      cfFormat;

DVTARGETDEVICE  *ptd;

DWORD           dwAspect;

LONG            lindex;

DWORD           tymed;

}FORMATETC, *LPFORMATETC;

Members

cfFormat - Particular clipboard format of interest. There are three types of formats recognized by OLE:

  1. Standard interchange formats, such as CF_TEXT.

  2. Private application formats understood only by the application offering the format, or by other applications offering similar features.

  3. OLE formats, which are used to create linked or embedded objects.

ptd - Pointer to a DVTARGETDEVICE structure containing information about the target device for which the data is being composed. A NULL value is used whenever the specified data format is independent of the target device or when the caller doesn't care what device is used. In the latter case, if the data requires a target device, the object should pick an appropriate default device (often the display for visual components). Data obtained from an object with a NULL target device, such as most metafiles, is independent of the target device. The resulting data is usually the same as it would be if the user chose the Save As command from the File menu and selected an interchange format.

dwAspect - One of the DVASPECT enumeration constants that indicate how much detail should be contained in the rendering. A single clipboard format can support multiple aspects or views of the object. Most data and presentation transfer and caching methods pass aspect information. For example, a caller might request an object's iconic picture, using the metafile clipboard format to retrieve it. Note that only one DVASPECT value can be used in dwAspect. That is, dwAspect cannot be the result of a BOOLEAN OR operation on several DVASPECT values.

lindex - Part of the aspect when the data must be split across page boundaries. The most common value is -1, which identifies all of the data. For the aspects DVASPECT_THUMBNAIL and DVASPECT_ICON, lindex is ignored.

tymed - One of the TYMED enumeration constants which indicate the type of storage medium used to transfer the object's data. Data can be transferred using whatever medium makes sense for the object. For example, data can be passed using global memory, a disk file, or structured storage objects.

Header file

objidl.h.

Remark

The FORMATETC structure is used by methods in the data transfer and presentation interfaces as a parameter specifying the data being transferred. For example, the IDataObject::GetData method uses the FORMATETC structure to indicate exactly what kind of data the caller is requesting.

 

Table 2.

 

The STGMEDIUM Structure

 

Just as the FORMATETC structure is an enhancement of the Windows clipboard format identifier, so the STGMEDIUM structure is an improvement of the global memory handle used to transfer the data. The STGMEDIUM structure includes a flag, tymed, which indicates the medium to be used, and a union comprising pointers and a handle for getting whichever medium is specified in tymed.

The STGMEDIUM structure enables both data sources and consumers to choose the most efficient exchange medium on a per-rendering basis. If the data is so big that it should be kept on disk, the data source can indicate a disk-based medium in its preferred format, only using global memory as a backup if that’s the only medium the consumer understands. Being able to use the best medium for exchanges as the default improves overall performance of data exchange between applications. For example, if some of the data to be transferred is already on disk, the source application can move or copy it to a new destination, either in the same application or in some other, without having first to load the data into global memory. At the receiving end, the consumer of the data does not have to write it back to disk.

 

STGMEDIUM

 

Item

Description

Structure

 STGMEDIUM.

Info

A generalized global memory handle used for data transfer operations by the IAdviseSink, IDataObject, and IOleCache interfaces.

Definition

typedef struct tagSTGMEDIUM

{

DWORD tymed;

[switch_type(DWORD), switch_is((DWORD) tymed)]

union {

[case(TYMED_GDI)]      HBITMAP        hBitmap;

[case(TYMED_MFPICT)]   HMETAFILEPICT  hMetaFilePict;

[case(TYMED_ENHMF)]    HENHMETAFILE   hEnhMetaFile;

[case(TYMED_HGLOBAL)]  HGLOBAL        hGlobal;

[case(TYMED_FILE)]     LPWSTR         lpszFileName;

[case(TYMED_ISTREAM)]  IStream        *pstm;

[case(TYMED_ISTORAGE)] IStorage       *pstg;

[default];

};

[unique] IUnknown *pUnkForRelease;

}STGMEDIUM;

typedef STGMEDIUM *LPSTGMEDIUM;

Members

tymed - Type of storage medium. The marshaling and unmarshaling routines use this value to determine which union member was used. This value must be one of the elements of the TYMED enumeration.

 

union member

 

Handle, string, or interface pointer that the receiving process can use to access the data being transferred. If tymed is TYMED_NULL, the union member is undefined; otherwise, it is one of the following:

  1. hBitmap - Bitmap handle. The tymed member is TYMED_GDI.

  2. hMetaFilePict - Metafile handle. The tymed member is TYMED_MFPICT.

  3. hEnhMetaFile - Enhanced metafile handle. The tymed member is TYMED_ENHMF.

  4. hGlobal - Global memory handle. The tymed member is TYMED_HGLOBAL.

  5. lpszFileName - Pointer to the path of a disk file that contains the data. The tymed member is TYMED_FILE.

  6. pstm - Pointer to an IStream interface. The tymed member is TYMED_ISTREAM.

  7. pstg - Pointer to an IStorage interface. The tymed member is TYMED_ISTORAGE.

  8. pUnkForRelease - Pointer to an interface instance that allows the sending process to control the way the storage is released when the receiving process calls the ReleaseStgMedium() function. If pUnkForRelease is NULL, ReleaseStgMedium() uses default procedures to release the storage; otherwise, ReleaseStgMedium() uses the specified IUnknown interface.

Header file

objidl.h.

Remark

-

 

Table 3

 

 

 

 

 

 

 

 

TYMED

 

Item

Description

Enumeration type

TYMED.

Info

The TYMED enumeration values indicate the type of storage medium being used in a data transfer. They are used in the STGMEDIUM or FORMATETC structures.

Definition

typedef [transmit_as(long)] enum tagTYMED

{

TYMED_HGLOBAL     = 1,

TYMED_FILE        = 2,

TYMED_ISTREAM     = 4,

TYMED_ISTORAGE    = 8,

TYMED_GDI         = 16,

TYMED_MFPICT      = 32,

TYMED_ENHMF       = 64,

TYMED_NULL        = 0

} TYMED;

Constants

TYMED_HGLOBAL - The storage medium is a global memory handle (HGLOBAL). Allocate the global handle with the GMEM_SHARE flag. If the STGMEDIUM punkForRelease member is NULL, the destination process should use GlobalFree() to release the memory.

TYMED_FILE - The storage medium is a disk file identified by a path. If the STGMEDIUM punkForRelease member is NULL, the destination process should use OpenFile() to delete the file.

TYMED_ISTREAM - The storage medium is a stream object identified by an IStream pointer. Use ISequentialStream::Read to read the data. If the STGMEDIUM punkForRelease member is not NULL, the destination process should use IStream::Release to release the stream component.

TYMED_ISTORAGE - The storage medium is a storage component identified by an IStorage pointer. The data is in the streams and storages contained by this IStorage instance. If the STGMEDIUM punkForRelease member is not NULL, the destination process should use IStorage::Release to release the storage component.

TYMED_GDI - The storage medium is a GDI component (HBITMAP). If the STGMEDIUM punkForRelease member is NULL, the destination process should use DeleteObject() to delete the bitmap.

TYMED_MFPICT - The storage medium is a metafile (HMETAFILE). Use the Windows or WIN32 functions to access the metafile's data. If the STGMEDIUM punkForRelease member is NULL, the destination process should use DeleteMetaFile() to delete the bitmap.

TYMED_ENHMF - The storage medium is an enhanced metafile. If the STGMEDIUM punkForRelease member is NULL, the destination process should use DeleteEnhMetaFile() to delete the bitmap.

TYMED_NULL - No data is being passed.

Header file

objidl.h.

Remark

During data transfer operations, a storage medium is specified. This medium must be released after the data transfer operation. The provider of the medium indicates its choice of ownership scenarios in the value it provides in the STGMEDIUM structure. A NULL value for the IUNKNOWN field indicates that the receiving body of code owns and can free the medium. A non-NULL pointer specifies that ReleaseStgMedium() can always be called to free the medium.

 

Table 4.

 

 

 

 

 

 


| C & C++ Programming | MFC Programming | Download | Site Index |