/*
   *  IO Methods
   *
   *  The IO system treats all objects as groups of typed information.
   *  When you register your element or attribute, the "elementType" is the 
   *  binary type of your object, the "elementName" the ascii type.
   *  
   *  All objects in the metafile are made up of a "root" or parent object which
   *  defines the instantiated object type. You may define the format of your 
   *  data any way you wish as long as you use the primitives types above and the
   *  routines below.
   *
   *  Root Objects are often appended with additional child objects, called 
   *  subobjects. You may append your object with other QuickDraw 3D objects.
   *  
   *  Writing is straightforward: an object traverses itself any other objects 
   *  that make it up, then writes its own data. Writing uses two methods: 
   *  TQ3XObjectTraverseMethod and TQ3XObjectWriteMethod.
   *
   *  The TQ3XObjectTraverseMethod method should:
   *  + First, Determine if the data should be written 
   *      - if you don't want to write out your object after examining your
   *          data, return kQ3Success in your Traverse method without calling
   *          any other submit calls.
   *  + Next, calculate the size of your object on disk
   *  + Gather whatever state from the view you need to preserve
   *      - you may access the view state NOW, as the state of the
   *          view duing your TQ3XObjectWriteMethod will not be valid. You may
   *          pass a temporary buffer to your write method.
   *  + Submit your view write data using Q3View_SubmitWriteData
   *      - note that you MUST call this before any other "_Submit" call.
   *      - you may pass in a "deleteMethod" for your data. This method
   *          will be called whether or not your write method succeeds or fails.
   *  + Submit your subobjects to the view
   *  
   *  The TQ3XObjectWriteMethod method should:
   *  + Write your data format to the file using the primitives routines below.
   *      - If you passed a "deleteMethod" in your Q3View_SubmitWriteData, that
   *          method will be called upon exit of your write method.
   *
   *  Reading is less straightforward because your root object and
   *  any subobjects must be read inside of your TQ3XObjectReadDataMethod. There 
   *  is an implicit state contained in the file while reading, which you must 
   *  be aware of. When you first enter the read method, you must physically 
   *  read in your data format using the primitives routines until
   *  
   *  Q3File_IsEndOfData(file) == kQ3True
   *  
   *  Generally, your data format should be self-descriptive such that you do not
   *  need to call Q3File_IsEndOfData to determine if you are done reading. 
   *  However, this call is useful for determining zero-sized object or 
   *  determining the end of an object's data.
   *  
   *  Once you have read in all the data, you may collect subobjects. A metafile
   *  object ONLY has subobjects if it is in a container. The call
   *  
   *  Q3File_IsEndOfContainer(file)
   *  
   *  returns kQ3False if subobjects exist, and kQ3True if subobjects do not 
   *  exist.
   *  
   *  At this point, you may use
   *  
   *  Q3File_GetNextObjectType
   *  Q3File_IsNextObjectOfType
   *  Q3File_ReadObject
   *  Q3File_SkipObject
   *  
   *  to iterate through the subobjects until Q3File_IsEndOfContainer(file) 
   *  is kQ3True.
   * 
   */
  
  /*
   * IO Methods
   */
  enum {
      kQ3XMethodTypeObjectFileVersion = FOUR_CHAR_CODE('vers'),   /* version */
      kQ3XMethodTypeObjectTraverse = FOUR_CHAR_CODE('trvs'),      /* byte count */
      kQ3XMethodTypeObjectTraverseData = FOUR_CHAR_CODE('trvd'),  /* byte count */
      kQ3XMethodTypeObjectWrite   = FOUR_CHAR_CODE('writ'),       /* Dump info to file */
      kQ3XMethodTypeObjectReadData = FOUR_CHAR_CODE('rddt'),      /* Read info from file into buffer or, attach read data to parent */
      kQ3XMethodTypeObjectRead    = FOUR_CHAR_CODE('read'),
      kQ3XMethodTypeObjectAttach  = FOUR_CHAR_CODE('attc')
  };
  
  /*
   *  TQ3XObjectTraverseMethod
   *
   *  For "elements" (meaning "attributes, too), you will be passed NULL for 
   *  object. Sorry, custom objects will be available in the next major revision.
   *
   *  The "data" is a pointer to your internal element data.
   *
   *  The view is the current traversal view.
   */
  typedef CALLBACK_API_C( TQ3Status , TQ3XObjectTraverseMethod )(TQ3Object object, void *data, TQ3ViewObject view);
  /*
   *  TQ3XObjectTraverseDataMethod
   */
  typedef CALLBACK_API_C( TQ3Status , TQ3XObjectTraverseDataMethod )(TQ3Object object, void *data, TQ3ViewObject view);
  /*
   *  TQ3XObjectWriteMethod
   */
  typedef CALLBACK_API_C( TQ3Status , TQ3XObjectWriteMethod )(const void *object, TQ3FileObject theFile);
  /*
   *  Custom object writing 
   */
  typedef CALLBACK_API_C( void , TQ3XDataDeleteMethod )(void *data);
  if CALL_NOT_IN_CARBON
  EXTERN_API_C( TQ3Status )
  Q3XView_SubmitWriteData         (TQ3ViewObject          view,
                                   TQ3Size                size,
                                   void *                 data,
                                   TQ3XDataDeleteMethod   deleteData);
  
  EXTERN_API_C( TQ3Status )
  Q3XView_SubmitSubObjectData     (TQ3ViewObject          view,
                                   TQ3XObjectClass        objectClass,
                                   unsigned long          size,
                                   void *                 data,
                                   TQ3XDataDeleteMethod   deleteData);
  
  /*
   *  TQ3XObjectReadMethod
   */
  endif  /* CALL_NOT_IN_CARBON */
  
  typedef CALLBACK_API_C( TQ3Object , TQ3XObjectReadMethod )(TQ3FileObject theFile);
  /*
   *  TQ3XObjectReadDataMethod
   *
   *  For "elements" (meaning "attributes", too), you must allocate stack space 
   *  and call Q3Set_Add on "parentObject", which is an TQ3SetObject.
   *
   *  Otherwise, parentObject is whatever object your element is a subobject of...
   */
  typedef CALLBACK_API_C( TQ3Status , TQ3XObjectReadDataMethod )(TQ3Object parentObject, TQ3FileObject theFile);
  /*
   *  TQ3XObjectAttachMethod
   */
  typedef CALLBACK_API_C( TQ3Status , TQ3XObjectAttachMethod )(TQ3Object childObject, TQ3Object parentObject);