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

ImpexDataClasses

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:

IDC_TEXT
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.
IDC_GRAPHICS
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.
IDC_SPREADSHEET
The data is in the Metafile Spreadsheet format. This corresponds to the Clipboard's CIF_SPREADSHEET format.
IDC_FONT
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.

ImpexTranslationParams

ImpexTranslationParams

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;
ITP_impexOD
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.
ITP_transferVMFile
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.

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

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

ITP_clipboardFormat

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