libvcd 0.7.20, libcdio 0.68

CVS patchset: 6388
CVS date: 2004/04/11 12:20:31

1 files changed, 51 insertions, 21 deletions

diff --git a/src/input/vcd/libcdio/cdio/xa.h b/src/input/vcd/libcdio/cdio/xa.h
index 06e5df250..5ff7addd4 100644
--- a/src/input/vcd/libcdio/cdio/xa.h
+++ b/src/input/vcd/libcdio/cdio/xa.h
@@ -1,8 +1,8 @@
 /*
-    $Id: xa.h,v 1.1 2003/10/13 11:47:12 f1rmb Exp $
+    $Id: xa.h,v 1.2 2004/04/11 12:20:31 miguelfreitas Exp $
 
     Copyright (C) 2000 Herbert Valerio Riedel <hvr@gnu.org>
-    Copyright (C) 2003 Rocky Bernstein <rocky@panix.com>
+    Copyright (C) 2003, 2004 Rocky Bernstein <rocky@panix.com>
 
     See also iso9660.h by Eric Youngdale (1993) and in cdrtools. These
     are 
@@ -24,6 +24,11 @@
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */
+/*!
+   \file xa.h 
+   \brief Things related to the ISO-9660 XA (Extended Attributes) format
+*/
+
 
 #ifndef __CDIO_XA_H__
 #define __CDIO_XA_H__
@@ -34,17 +39,17 @@
 #define ISO_XA_MARKER_OFFSET    1024
 
 /* XA attribute definitions */
-#define XA_PERM_RSYS          0x0001   /* System Group Read */
-#define XA_PERM_XSYS          0x0004   /* System Group Execute */
+#define XA_PERM_RSYS          0x0001   /**< System Group Read */
+#define XA_PERM_XSYS          0x0004   /**< System Group Execute */
 
-#define XA_PERM_RUSR          0x0010   /* User (owner) Read */
-#define XA_PERM_XUSR          0x0040   /* User (owner) Execute */
+#define XA_PERM_RUSR          0x0010   /**< User (owner) Read */
+#define XA_PERM_XUSR          0x0040   /**< User (owner) Execute */
 
-#define XA_PERM_RGRP          0x0100   /* Group Read */
-#define XA_PERM_XGRP          0x0400   /* Group Execute */
+#define XA_PERM_RGRP          0x0100   /**< Group Read */
+#define XA_PERM_XGRP          0x0400   /**< Group Execute */
 
-#define	XA_PERM_ROTH	      0x1000   /* Other (world) Read */
-#define	XA_PERM_XOTH	      0x4000   /* Other (world) Execute */
+#define	XA_PERM_ROTH	      0x1000   /**< Other (world) Read */
+#define	XA_PERM_XOTH	      0x4000   /**< Other (world) Execute */
 
 #define XA_ATTR_MODE2FORM1     (1 << 11)
 #define XA_ATTR_MODE2FORM2     (1 << 12)
@@ -61,18 +66,37 @@
 #define XA_FORM1_FILE   (XA_ATTR_MODE2FORM1 | XA_PERM_ALL_ALL)
 #define XA_FORM2_FILE   (XA_ATTR_MODE2FORM2 | XA_PERM_ALL_ALL)
 
-/*
- * Extended Attributes record according to Yellow Book.
- */
-typedef struct iso9660_xa /* big endian!! */
+/*! \brief "Extended Architecture according t the Philips Yellow Book.
+ 
+CD-ROM EXtended Architecture is a modification to the CD-ROM
+specification that defines two new types of sectors.  CD-ROM XA was
+developed jointly by Sony, Philips, and Microsoft, and announced in
+August 1988. Its specifications were published in an extension to the
+Yellow Book.  CD-i, Photo CD, Video CD and CD-EXTRA have all
+subsequently been based on CD-ROM XA.
+
+CD-XA defines another way of formatting sectors on a CD-ROM, including
+headers in the sectors that describe the type (audio, video, data) and
+some additional info (markers, resolution in case of a video or audio
+sector, file numbers, etc).
+
+The data written on a CD-XA is consistent with and can be in ISO-9660
+file system format and therefore be readable by ISO-9660 file system
+translators. But also a CD-I player can also read CD-XA discs even if
+its own `Green Book' file system only resembles ISO 9660 and isn't
+fully compatible. 
+
+ Note structure is big-endian.
+*/
+typedef struct iso9660_xa 
 {
-  uint16_t group_id;      /* 0 */
-  uint16_t user_id;       /* 0 */
-  uint16_t attributes;    /* XA_ATTR_ */ 
-  uint8_t  signature[2];  /* { 'X', 'A' } */
-  uint8_t  filenum;       /* file number, see also XA subheader */
-  uint8_t  reserved[5];   /* zero */
-} iso9660_xa_t GNUC_PACKED;
+  uint16_t group_id;      /**< 0 */
+  uint16_t user_id;       /**< 0 */
+  uint16_t attributes;    /**< XA_ATTR_ */ 
+  uint8_t  signature[2];  /**< { 'X', 'A' } */
+  uint8_t  filenum;       /**< file number, see also XA subheader */
+  uint8_t  reserved[5];   /**< zero */
+} GNUC_PACKED iso9660_xa_t;
 
 
 /*!
@@ -106,6 +130,12 @@ typedef struct iso9660_xa /* big endian!! */
 const char *
 iso9660_get_xa_attr_str (uint16_t xa_attr);
   
+/*! 
+  Allocates and initalizes a new iso9600_xa_t variable and returns
+  it. The caller should free the returned result.
+
+  @see iso9660_xa
+*/
 iso9660_xa_t *
 iso9660_xa_init (iso9660_xa_t *_xa, uint16_t uid, uint16_t gid, uint16_t attr, 
 		 uint8_t filenum);