.ds Vv 1.2.14
.TH VistaIOBundle 3 "21 January 1994" "VistaIO Version \*(Vv"
.SH NAME
VistaIOBundle \- representation for Vista object with binary data
.SH DESCRIPTION
.SS 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
\fBVistaIOBundle\fP data structure, which is described here.
.SS "The VistaIOBundle Representation"
.nf
.ft B
.ta 25n
typedef struct {
.RS
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 */
.RE
} VistaIOBundleRec, *VistaIOBundle;
.DT
.fi
.PP
An arbitrary object, possessing a type name, an attribute list, and
possibly some binary data, can be completely represented in memory by a
\fBVistaIOBundle\fP, which is a pointer to a variable-length structure. The
structure has four fields. In \fBtype_name\fP is the name of the object's
type as a null-terminated string. In \fBlist\fP is a handle to its
attribute list. If the object includes binary data, \fBlength\fP is the
data's length in bytes and \fBdata\fP points to storage obtained from
\fBVistaIOMalloc\fP(3) containing the data. If, on the other hand, the object
include no binary data, \fBlength\fP is zero.
.PP
Any attribute list member can have a \fBVistaIOBundle\fP as its value. The 
attribute's value representation is denoted by the \fBVistaIORepnKind\fP constant 
\fBVistaIOBundleRepn\fP. Such attributes can be created, copied, deleted, 
and accessed much like any other.
.PP
\fBVistaIOReadFile\fP(3) reads a data file and returns its contents as an
attribute list while recording objects with unfamiliar types as
\fBVistaIOBundle\fP attributes. \fBVistaIOWriteFile\fP(3) writes a data file from
the contents of an attribute list while interpreting \fBVistaIOBundle\fP
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 \fBVistaIOBundle\fP.
.SS Routines
The following routines create and destroy a \fBVistaIOBundle\fP:
.HP 10n
.na
.nh
.ft B
VistaIOBundle VistaIOCreateBundle (VistaIOStringConst\ \fItype_name\fP, 
VistaIOAttrList\ \fIlist\fP, size_t\ \fIlength\fP, VistaIOPointer \fIdata\fP)
.ft
.ad
.hy
.IP "" 0.5i
\fBVistaIOCreateBundle\fP allocates a \fBVistaIOBundleRec\fP structure of the
appropriate size and fills in its fields. In particular, the \fIlist\fP and
\fIdata\fP arguments are simply stored in the new \fBVistaIOBundleRec\fP (i.e.,
the structures they point to are not copied).
.PP
.B "void VistaIODestroyBundle (VistaIOBundle \fIbundle\fP)"
.IP
\fBVistaIODestroyBundle\fP releases all storage occupied by a \fBVistaIOBundle\fP,
including its attribute list and any binary data block.
.SH "SEE ALSO"
.BR VistaIOattribute (3),
.BR VistaIOtype (3),

.SH AUTHOR
Art Pope <pope@cs.ubc.ca>

Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>