Beta Release

CHANGES MADE TO THE INTERFACE AND FUNCTIONALITY FROM ALPHA

A. Terminology Changes

In order for the code to stay in-synch with the overview document
terminology and in order to make the terminology more clear, several
terms have been changed. Only some of them will affect compilation.

   1. fileDataStart -> labelLimit

      ALPHA: This term refers to the sector number of the beginning of
      data. This is where the Archive object promises not to intrude,
      unless told that space is free above that point. The minimum
      here was 300. Thus, the Archive object demanded that a minimum
      of 300 sectors (sectors 0 thru 299) be reserved for its label
      information.

      BETA: This term has not changed in meaning, but is now called
      "labelLimit". It can be viewed as a number of sectors at the
      beginning of the media which the labeling information must limit
      itself to.

   2. Directory terminology:

      numberOfEntries() -> numDirEntries()
      addDirectoryEntry -> addDirEntry(True,...)
      addFileEntry() -> addDirEntry(False,...)
      getFirstEntry() -> getFirstDirEntry()
      getNextEntry() -> getNextDirEntry()
      getEntry() -> getDirEntry()

      ALPHA: The terminology for accessing directory entries was
      confusing because it overlapped with UDF specification
      (actually, ISO/IEC13346) terms. a UDF "FileEntry" is an "entry"
      into an ICB hierarchy, NOT in a directory.

      BETA: To clear this up, the "Entries" were all changed to
      "DirEntries", as listed above. Also, addFileEntry() and
      addDirectoryEntry() were merged into addDirEntry() with a
      boolean to indicate whether a subdirectory (True) or a file
      (False) were being added.

   3. FreeSpace -> UnerasedSpace

      ALPHA: When free space information was passed into the Archive
      object, it was in the form of a "freeSpace" and an
      "erasedSpace". This was a little loose, since BOTH ExtentLists
      represent "free" space.

      BETA: Now, the terms are, "erasedSpace" and
      "unerasedSpace". NOTE that on WORM, where there is NO erasure,
      the "unerasedSpace" list is to be used. The Archive object maps
      these ExtentLists into their appropriate UDF/ISO structures:

      Rewritable:
          unerasedSpace : FreedSpaceTable
          erasedSpace   : UnallocatedSpaceTable
      Worm:
          unerasedSpace : UnallocatedSpaceTable

   4. metaDataSpace -> icbSpace

      ALPHA: One of the BeginImport() signatures allowed users to
      obtain the space used by the ICBTable (representing all ICB
      FileEntries plus overflow sectors), via an argument called,
      "metaDataSpace". This was misleading, because it did not return
      all of the metadata space (for example, the space occupied by
      the directories.

      BETA: Now, the argument has been renamed, "icbSpace", which is
      more clear. It returns the same information as before.

B. Attribute revamp

   The attributes structure is the main holder of information about
   files and directories in the Archive object. It must provide access
   to the UDF/ISO structures efficiently and unambiguously. The key
   changes from Alpha to Beta are

   1. It is no longer a UNIX-only attributes struct.

      The attributes structure defined in the alpha release was
      designed for UNIX, holding such things as the "mode" of a file,
      and only just before shipment, containing the DOS "system" and
      "archive" bits.

      The new attributes struct stores ALL information associated with
      attributes, in a UDF-specific fashion, rather than a
      UNIX-specific fashion. The UNIX support has been moved out from
      the organization of the bits to the provision of methods for
      it. For example, rather than containing a data member "mode", it
      supports get/setUnixMode() methods.

   2. It is customizable

      For users who wish to customize the Attributes class to their
      own platform's needs, there are two principal options. First,
      they may (as we have) simply support new methods which pack and
      unpack information form a native-friendly form (such as the unix
      "mode"). Because this allows the attributes struct to hold ALL
      information, regardless of its relevance to the current
      platform, this brings the advantage of allowing the setting of
      some attribute information without losing any.

      The second option is for the user to rewrite the class,
      potentially removing much of the attribute information not
      relevant to their platform. This yields the benefits of a
      lighter-weight attributes struct, but also loses information
      when going from ISO. When this is done, the user only needs to
      properly write the toFileEntry() and fromFileEntry() functions.


   3. It may be directly accessed from a C compiler.

      The changes have been made to the Attributes structure without
      losing the C-compiler compatibility present in the Alpha
      release. No virtual functions are used, so that this may be
      treated just like a c struct if desired. The C face of
      Attributes is a struct with public data members, with constants
      defined for masks and bit positions, instead of the much more
      convenient C++ methods.

      The responsibility, then, of the C user is only to use what
      we've provided as a struct, or if they restructure it, to also
      provide the methods required by UDF -- namely, toFileEntry() and
      fromFileEntry().

   4. It supports an enumerated fileType

      The type of file was held in the attributes in Alpha, in the
      form of two bits: isDirectory and isSymbolicLink. The
      implication was that normal files had both of these bits
      cleared, and the meaning of both of them set was never
      defined. In order to clear up this ambiguity, this has been
      replaced by an enmeration of all the possible file types.

      NOTE that while this supports all file types, only the original
      three are supported by the Archive object:

        File Type                   Supported
        ==========================  =========
        file_Unspecified                NO
        file_Directory                 YES
        file_Raw                       YES
        file_SpecialBlockDevice         NO
        file_SpecialCharacterDevice     NO
        file_ExtendedAttributes         NO
        file_Fifo                       NO
        file_Sock                       NO
        file_SymbolicLink              YES

   5. It has linkCount field.

      The Alpha release reflected our intention of eliminating the
      linkCount field from the Attributes structure. This was in order
      to hide the somewhat strange UDF/ISO definition of symbolic link
      from the user. However, in order to meet the constraints of
      release 2.0 of the toolkit, we went ahead and included it in the
      Attributes definition.

      The user will now have to supply a valid UDF/ISO linkCount
      inside of the Attributes class to every writeNextICB() method. This
      is done INSTEAD OF supplying a numSubDirs argument.

      The UDF/ISO definition of the linkCount field (from ISO/IEC13346
      P4/14.9.6) is as follows:

      FileLinkCount "shall specify the number of File Identifier
      Descriptors identifying this ICB."

      This definition is the same as in UNIX, but ends up being a
      different value for directories. This is because in UNIX, all
      directories contain a "." entry, which is absent in
      UDF/ISO. Thus, the UNIX number equals 2 plus the number of
      subdirectories, while UDF/ISO is 1 plus the number of
      subdirectories. The way to think of this is that every file's or
      directory's parent has an entry for it, and every child has an
      entry for it. When hard links are used, each parent has an entry
      for it. Thus, the following formulae:

         For directories: 1+numSubDirs
         For files:       1+numHardLinks

      NOTE that the Archive object does NOT support hard links, so the
      value for all files should be 1.

   6. It does NOT have an information length

      As in the Alpha release, the Information Length of the file is
      held in the ExtentList associated with the file, and NOT in the
      Attributes structure. Thus, no fileSize or equivalent member is
      provided.

C. Free Space Changes

   The main change to free space handling is that it must be supplied
   both when growing a volume (i.e., for all new volumes), and when
   exporting. The labelLimit parameter has also changed (somewhat
   subtlely).

   1. Initial free space required when labeling

      The UDF label now contains free space information. This makes
      sure that when growing a volume set, the newly-added volumes are
      on equal footing with the older previously-exported-to volumes
      -- they all have free space information, all available through
      getVolumeInfo().

      Note that if the real free space information is not known at
      that time, this could be simply filled in with an empty extent
      list (indicating that NO free space exists on the volume, or
      with a full extentList, indicating that it is all free. Since
      this gets overridden at export, and since the volumeSet may ONLY
      be marked CLEAN by the export process, this may not be important
      to an application.

      NOTE also that the single use which may be made of this space is
      if a long file set history is to be propagated to a new root
      volume, it will need to allocate space from the free space, so
      it must at least provide some space for this. This feature is
      currently disabled in the code, (although implemented), and is
      not even REQUIRED if an adequate labelLimit is chosen.

   2. Updated free space required upon Export

      Upon export, the data and potentially ExtendedAttributes must
      have been written to (or at least allocated from) the disk
      first. Thus, the volume's free space will have changed from that
      at the time of addUnlabeledVolume(). Therefore, it must be
      re-supplied ot the archive object, via the method
      setAvailSpace(). This no longer contains the labelLimit
      argument, as that is supplied only and always at
      addUnlabeledVolume().

   3. labelLimit gets rounded down, and then never changed.

      The value of labelLimit gets returned on getVolumeInfo(), but
      may be different than that supplied during
      addUnlabeledVolume(). This is because this position gets rounded
      down to where the number of sectors reserved from the beginning
      of the partition (currently, 257) and the end of the
      FileSetDescriptor Sequence is a multiple of four.

D. No need to specify root volume.

   Most (all?) of the methods which required a rootSid argument no
   longer do so. This is because the root volume is defined to be the
   highest-numbered volume in the volume set, and can therefore be
   determined by the Archive object.

   Some methods had included this argument, so that they could offer
   access to some information or functionality without all of the
   volumes being loaded into the archive object. Some methods STILL
   support this, but now require that the openArchive() and
   addLabeledVolume() methods be called first. That is, if the user
   wishes to have access to the functionality without loading all
   labeled volumes into the Archive object, he must at least add the
   root volume beforehand.

   The methods which used to require a root Sid, but which no longer
   do are:

      checkOpenIntegrity()
      getWriteProtect()
      setWriteProtect()

   The only method which allows any access to the rootSid is
   getRootVolume(). It is provided solely to allow the user to give
   the volume special treatment if desired.

E. Explicit Volume Set Growth

   1. prepareRoot() goes away.

      This used to be the Archive object's opportunity to move the
      root information (e.g., fileset history) to the new root
      volume. This is not performed during completGrowth().

      It also used to check to make sure there was enough space on the
      root volume for the label updating which is required by the
      export process. This has been swept into beginExport().

   2. Disallow growth if writeProtected

      An error will be returned if beginGrow() is called on a volume
      which has been writeProtected. Use the getWriteProtect() and
      setWriteProtect() methods to check/modify the write protections.

      Although this has not been officially mandated by OSTA, this is
      the recommended practice as of October, 1995.

   3. Disallow growth if volumeSet is marked CLOSED.

      The volume set must be marked OPEN via markOpenIntegrity()
      before the beginGrow() method is called. 

F. Clarification to Volume Set Integrity

   1. Volume Sets may be OPEN or CLOSED when they are grown, and their
      state is preserved through the grow process.

      New volume sets are always marked OPEN, since no file system
      metadata has been laid down on the volumes.

      Users may mark the volume set OPEN at any time, but the only way
      to mark it CLOSED is by doing an Export.

      - markOpenIntegrity() -- marks OPEN
      - checkOpenIntegrity() -- Returns status.
      - beginGrow() -- holds OPEN or CLOSED
      - completeGrow() -- marked with held state from beginGrow()
      - beginExport() -- verifies that already marked OPEN.
      - completeExport() -- marked CLOSED.

G. Changes to VolumeSetInfo

   The getVolSetInfo() method has been slightly modified to allow
   retrieval of information on partially-loaded volume sets, and to
   make it more clear what is and what is not valid.

   The VolumeInfo struct has been divided into two sections - The
   first section is valid at any time. It consists of:

       UINT16            expectedVols <--from openArchive()
       UINT32            sectorSize   <--from openArchive()
       MediaType         mediaType    <--from openArchive()
       String            volSetName   <--from openArchive()
       VolumeInfoList    volInfoList  <--grabbed from each
                                         addLabeledVolume() and/or
                                         addUnlabeledVolume()
       Boolean           isComplete   <--same as isCompleteVolSet()

   These structures will be correct for even partially-loaded volume
   sets.

   The second part of the structure is valid ONLY if the isComplete
   field is True. It consists of information associated with or found
   on the "root" volume, including all of the following:

       sid_t             rootSid          <--same as getRootVol()
       IntegrityType     integrityType    <--integ_Open,Closed
       WriteProtectType  writeProtectType <--same as getWriteProtect()
       FileSetList       fileSetList      <--Info about each fileset

H. Changes to Extended Attribute interface

   The Beta release only supports EAs for non-root ICBs in this
   release, and the form that this information takes has changed from
   Alpha.

   Instead of supplying EAExtLists to the ICBs, the implementation
   must simply supply the ICB Address of the EA. Thus, the EA's ICB
   will NOT be written by the Archive object in
   writeNextICB(). Rather, it must be independently written, and only
   its address (in the form of an Extent) must be supplied to
   writeNextICB(). On the flip side, the EAICBAddr is returned on
   readNextICB() when importing.

   The methods to support reading and writing the EAs and their ICBs
   will be provided in a future release.
