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>