The Clipboard: 2.1 Transfer Data Structures: The Transfer VM File Format

GEOS SDK TechDocs

2 Transfer Data Structures

2.2 ClipboardItemFormatInfo

The Transfer VM File is a normal VM file, managed by the UI. It contains several components, each of which is accessed through special routines that take care of nearly all the synchronization issues involved with the Clipboard and quick-transfer mechanisms. Because both the Clipboard and the quick-transfer mechanism use this file and its data structures, these structures are detailed here; the following section ( Using The Clipboard ) details how to use them for either the Clipboard or the quick-transfer mechanism.

The Transfer VM File has one header block for the Clipboard transfer item and another for the quick-transfer transfer item. These headers have the same structure, and they contain all the information necessary to work with the file's contents. They contain pointers to and information about each format available for both the Clipboard and the quick-transfer functions. The transfer item's header is shown in ClipboardItemHeader .

Code Display 7-1 ClipboardItemHeader

/* The ClipboardItemHeader structure details what formats, if any, exist in the
 * Transfer VM File for both the Clipboard and quick-transfer mechanisms.*/

typedef struct {

	    /* The CIH_owner field is the optr of the object that put
	     * the current transfer item into the Transfer VM File. */
    optr			CIH_owner;

	    /* The CIH_flags field determines whether the transfer item is used by
	     * the quick transfer mechanism or by the normal Clipboard. If this
	     * field is equal to the constant CIF_QUICK, then the transfer item
	     * belongs to the quick transfer mechanism. If it is any other value,
	     * the transfer item belongs to the normal Clipboard. */
    ClipboardItemFlags			CIH_flags;
	  /* The ClipboardItemFlags type has one predefined value:
	 *	CIF_QUICK		0x4000
	 * If this flag does not apply, use TIF_NORMAL, which is 0x0000. */

	    /*  The CIH_name field is a 33-character buffer that should contain a
	     * null-terminated character string representing the name of the given
	     * transfer item. */
    ClipboardItemNameBuffer 			CIH_name;

	    /* The CIH_formatCount field indicates the number of formats of the
	     * transfer item currently available. For example, this field would be
	     * 2 if CIF_TEXT and CIF_GRAPHICS_STRING formats were supported and
	     * available in the Transfer VM File. */
    word			CIH_formatCount;

	    /* The CIH_sourceID field contains information about the source
	     * document of the transfer. Typically, this will be the optr of the
	     * parent GenDocument object. */
    dword			CIH_sourceID;

	    /* The CIH_formats field is actually an array of ten
	     * ClipboardFormatInfo structures, each of which contains the
	     * important details about a specific format of the transfer item. */
    FormatArray			CIH_formats;

	    /* This field is reserved and should not be used. */
    dword			CIH_reserved;
} ClipboardItemHeader ;

/* The FormatArray type is an array of ClipboardItemFormatInfo structures. The
 * definition of this field is shown here: */

 typedef	ClipboardItemFormatInfo			FormatArray[CLIPBOARD_MAX_FORMATS];
	/* CLIPBOARD_MAX_FORMATS is a constant defining the maximum number of
	 * formats allowed for any given transfer item. It is defined as 10. */

The rest of the Transfer VM File consists of VM blocks containing the data that is to be transferred. Each format supported will have its own VM block or series of VM blocks, pointed to by the ClipboardItemFormatInfo structure in the item's header.

The Transfer VM File actually contains two transfer items: One for the Clipboard and one for the quick-transfer mechanism (see the figure below). When calling ClipboardQueryItem() , the requesting geode must specify which item it wants. See Using The Clipboard and Using Quick-Transfer .

GEOS SDK TechDocs

2 Transfer Data Structures

2.2 ClipboardItemFormatInfo