NAME¶
VistaIOBundle - representation for Vista object with binary data
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.
SEE ALSO¶
VistaIOattribute(3),
VistaIOtype(3),
AUTHOR¶
Art Pope <pope@cs.ubc.ca>
Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>