NAME

       VistaIOReadFile - read a Vista data file

SYNOPSIS

       #include <stdio>
       #include <vistaio.h>

       VistaIOAttrList VistaIOReadFile (file, filter)
              FILE *file;
              VistaIOReadFileFilterProc *filter;

       typedef VistaIOBoolean VistaIOReadFileFilterProc (VistaIOBundle, VistaIORepnKind);

ARGUMENTS

       file      Specifies the open stream from which the data file should be read.

       filter    May  specify  a  function  that determines which attributes' binary data is read
                 from the file, or it may be NULL to indicate that  all  binary  data  should  be
                 read.

DESCRIPTION

       VistaIOReadFile  reads  the  contents  of  a  Vista  data  file.  It returns a list of the
       attributes found in the file. Attribute values in that list will have  been  converted  to
       internal form, as described by VistaIOattribute(3) and VistaIOtype(3).

       With  the filter argument you may supply a function that gets to decide for each attribute
       value that is an object whether or not that object's binary  data  should  be  read.  This
       mechanism  allows  you to avoid the expense of reading binary data that is not of interest
       (e.g., image pixel values when images are not of concern). However, you need only supply a
       filter  function if you are particularly concerned about efficiency.  Your filter function
       should be declared:

              VistaIOBoolean MyFilter (bundle, repn)
                     VistaIOBundle bundle;
                     VistaIORepnKind repn;

       Your filter function will be called once for each object encountered at any level  in  the
       file.  It  will be passed a VistaIOBundle representing the object (including its type name
       and attribute list, but not its binary data), and the repn value obtained  by  looking  up
       its  type  name  (i.e., the value returned by VistaIOLookupType(3) on the type name, which
       could be VistaIOUnknownRepn). The object's binary data will be read  only  if  the  filter
       function  returns  TRUE.  If  it  returns  FALSE,  the  object  will be represented in the
       attribute list as a VistaIOBundle, without binary data —  it  will  not  be  converted  to
       internal  form  (e.g.,  not  to  a VistaIOImage). If no filter function is supplied (i.e.,
       filter is NULL), VistaIOReadFile will read all binary data associated with all objects.

       For backwards compatibility VistaIOReadFile will recognize and read the contents of a  UBC
       image  file  format  (IFF)  file.  If  the  first character read from the stream is ``I'',
       VistaIOReadFile uses VistaIOReadUbcIff to read a  single  UBC  IFF  image.  The  image  is
       returned  as  a  VistaIOImage  attribute value in a list containing a single attribute. In
       this case, the filter argument has no effect.

RETURN VALUE

       VistaIOReadData returns an attribute list representing the file's contents, or NULL if  an
       error  is  encountered.  In  the case of an error, the stream may not have been completely
       read.

SEE ALSO

       VistaIOReadObjects(3), VistaIOReadUbcIff(3), stdio(3),
       VistaIOBundle(3), VistaIOattribute(3), VistaIOtype(3)

NOTES

       Data is read from the stream sequentially, permitting the stream to be a pipe.  No  rewind
       is performed either before reading or after.

DIAGNOSTIC

       ``EOF encountered in name attribute.''
              The  end-of-file  was encountered unexpectedly while reading the value of the named
              attribute.

       ``File continues beyond expected EOF.''
              The end-of-file wasn't encountered immediately after all expected binary data.

       ``Invalid name attribute.''
              The named attribute is encoded incorrectly in the stream. It may, for  example,  be
              missing the ``:'' that should separate its name and value.

       ``Missing {.''
              The ``{'' marking the start of an attribute list is missing.

       ``Missing }.''
              The ``}'' marking the end of an attribute list is missing.

       ``name attribute has data but not length.''
              The  named  attribute's  value  is  an  object whose attribute list contains a data
              attribute but not a length attribute. Both attributes must be  present  to  specify
              binary  data.  (A similar diagnostic is produced if there is a length attribute but
              no data attribute.)

       ``name attribute's attr attribute incorrect.''
              The named attribute's value is an object whose  attribute  list  indicates  it  has
              binary  data.  However,  its  data  attribute  specifies an offset too early in the
              binary data portion of the file, or its data or length attribute has a  non-integer
              value.

       ``Read from stream failed.''
              An  attempt  to  read a block of binary data failed, perhaps because of a premature
              end-of-file.

       ``Vista data file delimiter not found.''
              The FORMFEED NEWLINE sequence terminating the attribute list portion  of  the  data
              file wasn't found.

       ``Vista data file isn't version 2.''
              The  data  file's  header indicates a file format version other than 2, the current
              version.

AUTHOR

       Art Pope <pope@cs.ubc.ca>

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