bionic (3) VistaIOBundle.3.gz

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>