DESCRIPTION

Introduction

Since Vista allows you to invent your own types of objects and to store those objects in data files, it must provide some way for standard programs to gracefully handle objects that are unfamiliar to them. A program must at least be able to copy your custom objects intact, binary data and all, from input to output. Unfamiliar objects are represented internally by the Vista library using the VistaIOBundle data structure, which is described here.

The VistaIOBundle Representation

typedef struct {
VistaIOAttrList list;    /* object's attribute list value */
size_t length;           /* length of binary data */
VistaIOPointer data;     /* pointer to binary data */
char type_name[1];       /* beginning of object's type's name */

} VistaIOBundleRec, *VistaIOBundle;

An arbitrary object, possessing a type name, an attribute list, and possibly some binary data, can be completely represented in memory by a VistaIOBundle, which is a pointer to a variable-length structure. The structure has four fields. In type_name is the name of the object's type as a null-terminated string. In list is a handle to its attribute list. If the object includes binary data, length is the data's length in bytes and data points to storage obtained from VistaIOMalloc(3) containing the data. If, on the other hand, the object include no binary data, length is zero.

Any attribute list member can have a VistaIOBundle as its value. The attribute's value representation is denoted by the VistaIORepnKind constant VistaIOBundleRepn. Such attributes can be created, copied, deleted, and accessed much like any other.

VistaIOReadFile(3) reads a data file and returns its contents as an attribute list while recording objects with unfamiliar types as VistaIOBundle attributes. VistaIOWriteFile(3) writes a data file from the contents of an attribute list while interpreting VistaIOBundle attributes. When the two are used together, an object with any type and any binary data will be passed unchanged from input to output while being stored in memory as a VistaIOBundle.

Routines

The following routines create and destroy a VistaIOBundle:

VistaIOBundle VistaIOCreateBundle (VistaIOStringConst 

type_name, VistaIOAttrList list, size_t length, VistaIOPointer data)

VistaIOCreateBundle allocates a VistaIOBundleRec structure of the appropriate size and fills in its fields. In particular, the list and data arguments are simply stored in the new VistaIOBundleRec (i.e., the structures they point to are not copied).

void VistaIODestroyBundle (VistaIOBundle bundle)

VistaIODestroyBundle releases all storage occupied by a VistaIOBundle, including its attribute list and any binary data block.

AUTHOR

Art Pope <[email protected]>

Adaption to vistaio: Gert Wollny <[email protected]>