The Import/Export Library: 2.1 Using Impex: Common Impex Concepts

Up: GEOS SDK TechDocs| Up | Prev: 2 Using Impex | Next: 2.2 The ImportControl Object

There are certain concepts and structures which are used by both of the Impex objects. Applications which use the Impex objects will have to be familiar with them.

Metafile Formats


The Impex objects are designed to translate into a few specific formats. These formats are known collectively as the Metafile formats. These formats (except for the "font" format) are identical to the standard "Clipboard Item Formats" described in the Clipboard chapter. When an application uses the Impex objects, it has to specify what types of data it is prepared to import or export. It does this by setting an ImpexDataClasses record in both the ImportControl and the ExportControl objects. ImpexDataClasses has the following fields:

The data is in the Metafile Text format. This is identical to the Clipboard's CIF_TEXT format. In addition to text, this format records information about fonts, spacing, embedded graphics, etc.
The data is in the Metafile Graphics format. This is simply a GString in a VM chain. This format is identical to the Clipboard's CIF_GRAPHICS_STRING format.
The data is in the Metafile Spreadsheet format. This corresponds to the Clipboard's CIF_SPREADSHEET format.
The data is in the Metafile Font format. This format is used to translate fonts between representations.

Every translation library translates a DOS file into a VM chain in one of these four formats, and vice versa. When an application declares an Impex object, it specifies what formats should be supported for that application. The user will be allowed to choose translation libraries which translate to or from a supported Metafile format.



The Import and Export objects have to pass information to the application and the translation libraries. The same sort of information gets passed in many situations; for example, the objects often have to pass the VMFileHandle and VMBlockHandle which specify the VM chain. For simplicity, the Impex objects just pass a pointer to a ImpexTranslationParams structure when they send messages to the translation libraries or the application. The library or application takes the appropriate action, changing the ImpexTranslationParams structure as necessary; it then sends a response message, which takes a pointer to the same ImpexTranslationParams . ImpexTranslationParams has the following structure:

typedef struct {
	 optr			ITP_impexOD;
	Message			ITP_returnMsg;
	ImpexDataClasses			ITP_dataClass;
	VMFileHandle			ITP_transferVMFile;
	VMBlockHandle			ITP_transferVMChain;
	dword			ITP_internal;
	ManufacturerID			ITP_manufacturerID;
	ClipboardFormat			ITP_clipboardFormat;
} ImpexTranslationParams;
This field holds the optr of whatever Impex object sent the message. The response message should be addressed to this optr.
ITP _returnMsg
This field holds the message which the library or application should send to the Impex object when it is finished. This message always takes a single argument, namely a pointer to the ImpexTranslationParams . The application should just pass the pointer to the ImpexTranslationParams to the routine ImpexImportExportCompleted() ; this routine will send the appropriate notification message.
ITP _dataClass
This is a ImpexDataClasses record. Exactly one of the flags will be set, indicating what sort of Metafile format is being used.
This is the VMFileHandle of the transfer file. The transfer file is automatically created and destroyed by an Impex object.
ITP _transferVMChain
This is the VMBlockHandle of the first block in the transfer VM chain. In Import operations, the translation library creates the VM chain in the transfer file; in Export operations, the application creates it. The chain will be freed when the Impex object destroys the transfer VM file. For information about creating VM chains, see the VM chapter.

This field is for internal use by the Impex objects. You should not change it.

This field contains the manufacturer ID which should be used for the Metafile data; see the Clipboard chapter.


This field specifies what format should be used for the Metafile data; see the Clipboard chapter.

The meaning of each field can change, depending on the circumstances. For example, when the ImportControl sends its message to the application, the ITP _transferVMChain field will contain the handle of a VM chain containing the imported data. In contrast, when the ExportControl sends its message, ITP _transferVMChain contains a null handle; the application should allocate a VM chain, fill it with data, and write the VMBlockHandle of the chain to this field. When a field has a special meaning, the documentation will explain it.

Up: GEOS SDK TechDocs| Up | Prev: 2 Using Impex | Next: 2.2 The ImportControl Object