diff --git a/include/cdio/cd_types.h b/include/cdio/cd_types.h index 9f366e3b..ec142e66 100644 --- a/include/cdio/cd_types.h +++ b/include/cdio/cd_types.h @@ -1,5 +1,5 @@ /* - $Id: cd_types.h,v 1.3 2003/10/02 02:59:57 rocky Exp $ + $Id: cd_types.h,v 1.4 2003/11/04 04:45:24 rocky Exp $ Copyright (C) 2003 Rocky Bernstein Copyright (C) 1996,1997,1998 Gerd Knorr @@ -20,11 +20,6 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ -/* - Filesystem types we understand. The highest-numbered fs type should - be less than CDIO_FS_MASK defined below. -*/ - #ifndef __CDIO_CD_TYPES_H__ #define __CDIO_CD_TYPES_H__ @@ -32,6 +27,11 @@ extern "C" { #endif /* __cplusplus */ +/*! + Filesystem types we understand. The highest-numbered fs type should + be less than CDIO_FS_MASK defined below. +*/ + #define CDIO_FS_AUDIO 1 /* audio only - not really a fs */ #define CDIO_FS_HIGH_SIERRA 2 #define CDIO_FS_ISO_9660 3 @@ -39,45 +39,53 @@ extern "C" { #define CDIO_FS_HFS 5 #define CDIO_FS_UFS 6 -/* EXT2 was the GNU/Linux native filesystem for early kernels. Newer - GNU/Linux OS's may use EXT3 which EXT2 with a journal. */ +/** + * EXT2 was the GNU/Linux native filesystem for early kernels. Newer + * GNU/Linux OS's may use EXT3 which EXT2 with a journal. + */ #define CDIO_FS_EXT2 7 -#define CDIO_FS_ISO_HFS 8 /* both hfs & isofs filesystem */ -#define CDIO_FS_ISO_9660_INTERACTIVE 9 /* both CD-RTOS and isofs filesystem */ +#define CDIO_FS_ISO_HFS 8 /**< both HFS & ISO-9660 filesystem */ +#define CDIO_FS_ISO_9660_INTERACTIVE 9 /**< both CD-RTOS and ISO filesystem */ -/* The 3DO is, technically, a set of specifications created by the 3DO -company. These specs are for making a 3DO Interactive Multiplayer -which uses a CD-player. Panasonic in the early 90's was the first -company to manufacture and market a 3DO player. */ +/** + * The 3DO is, technically, a set of specifications created by the 3DO + * company. These specs are for making a 3DO Interactive Multiplayer + * which uses a CD-player. Panasonic in the early 90's was the first + * company to manufacture and market a 3DO player. +*/ #define CDIO_FS_3DO 10 #define CDIO_FS_MASK 15 /* Should be 2*n-1 and > above */ #define CDIO_FS_UNKNOWN CDIO_FS_MASK -/* Macro to extract just the FS type portion defined above */ +/** + *Macro to extract just the FS type portion defined above +*/ #define CDIO_FSTYPE(fs) (fs & CDIO_FS_MASK) -/* - Bit masks for the classes of CD-images. These are generally - higher-level than the fs-type information above and may be determined - based of the fs type information. +/** + * Bit masks for the classes of CD-images. These are generally + * higher-level than the fs-type information above and may be determined + * based of the fs type information. */ -#define CDIO_FS_ANAL_XA 16 -#define CDIO_FS_ANAL_MULTISESSION 32 -#define CDIO_FS_ANAL_PHOTO_CD 64 -#define CDIO_FS_ANAL_HIDDEN_TRACK 128 +#define CDIO_FS_ANAL_XA 16 /**< eXtended Architecture format */ +#define CDIO_FS_ANAL_MULTISESSION 32 /**< CD has multisesion */ +#define CDIO_FS_ANAL_PHOTO_CD 64 /**< Is a Kodak Photo CD */ +#define CDIO_FS_ANAL_HIDDEN_TRACK 128 /**< Hidden track at the + beginning of the CD */ #define CDIO_FS_ANAL_CDTV 256 -#define CDIO_FS_ANAL_BOOTABLE 512 -#define CDIO_FS_ANAL_VIDEOCD 1024 /* VCD 1.1 */ +#define CDIO_FS_ANAL_BOOTABLE 512 /**< CD is bootable */ +#define CDIO_FS_ANAL_VIDEOCD 1024 /**< VCD 1.1 */ #define CDIO_FS_ANAL_ROCKRIDGE 2048 -#define CDIO_FS_ANAL_JOLIET 4096 -#define CDIO_FS_ANAL_SVCD 8192 /* Super VCD or Choiji Video CD */ -#define CDIO_FS_ANAL_CVD 16384 /* Choiji Video CD */ +#define CDIO_FS_ANAL_JOLIET 4096 /**< Has Joliet extensions */ +#define CDIO_FS_ANAL_SVCD 8192 /**< Super VCD or Choiji Video CD */ +#define CDIO_FS_ANAL_CVD 16384 /**< Choiji Video CD */ -/* Pattern which can be used by cdio_get_devices to specify matching - any sort of CD. +/** + *Pattern which can be used by cdio_get_devices to specify matching + any sort of CD. */ #define CDIO_FS_MATCH_ALL (cdio_fs_anal_t) (~CDIO_FS_MASK) @@ -90,11 +98,11 @@ typedef struct unsigned int isofs_size; } cdio_analysis_t; -/* - Try to determine what kind of CD-image and/or filesystem we - have at track track_num. Return information about the CD image - is returned in cdio_analysis and the return value. -*/ +/** + * Try to determine what kind of CD-image and/or filesystem we + * have at track track_num. Return information about the CD image + * is returned in cdio_analysis and the return value. + */ cdio_fs_anal_t cdio_guess_cd_type(const CdIo *cdio, int start_session, track_t track_num, /*out*/ cdio_analysis_t *cdio_analysis); diff --git a/include/cdio/iso9660.h b/include/cdio/iso9660.h index f64fee2d..4f673e01 100644 --- a/include/cdio/iso9660.h +++ b/include/cdio/iso9660.h @@ -1,5 +1,5 @@ /* - $Id: iso9660.h,v 1.26 2003/10/28 16:23:50 rocky Exp $ + $Id: iso9660.h,v 1.27 2003/11/04 04:45:24 rocky Exp $ Copyright (C) 2000 Herbert Valerio Riedel Copyright (C) 2003 Rocky Bernstein @@ -107,20 +107,22 @@ struct iso9660_dtime { typedef struct iso9660_dtime iso9660_dtime_t; +/*! ISO-9660 Primary Volume Descriptor. + */ struct iso9660_ltime { - char lt_year [_delta( 1, 4)]; /* Add 1900 for Julian year */ - char lt_month [_delta( 5, 6)]; /* 1..12. Note starts at 1. */ + char lt_year [_delta( 1, 4)]; /*! Add 1900 for Julian year */ + char lt_month [_delta( 5, 6)]; /*! 1..12. Note starts at 1. */ char lt_day [_delta( 7, 8)]; char lt_hour [_delta( 9, 10)]; char lt_minute [_delta( 11, 12)]; char lt_second [_delta( 13, 14)]; - char lt_hsecond [_delta( 15, 16)]; /* 1/100's of a second */ + char lt_hsecond [_delta( 15, 16)]; /*! 1/100's of a second */ int8_t lt_gmtoff [_delta( 17, 17)]; } GNUC_PACKED; typedef struct iso9660_ltime iso9660_ltime_t; -/* ISO-9660 Primary Volume Descriptor. +/*! ISO-9660 Primary Volume Descriptor. */ struct iso9660_pvd { uint8_t type; /* 711 */ @@ -175,18 +177,18 @@ typedef struct iso9660_stat iso9660_stat_t; * See mkisofs.h */ -/* Format of an ISO-9660 directory record */ +/*! Format of an ISO-9660 directory record */ struct iso9660_dir { - uint8_t length; /* 711 */ - uint8_t xa_length; /* 711 */ - uint64_t extent; /* 733 */ - uint64_t size; /* 733 */ - iso9660_dtime_t recording_time; /* 7 by 711 */ + uint8_t length; /*! 711 */ + uint8_t xa_length; /*! 711 */ + uint64_t extent; /*! 733 */ + uint64_t size; /*! 733 */ + iso9660_dtime_t recording_time; /*! 7 by 711 */ uint8_t file_flags; - uint8_t file_unit_size; /* 711 */ - uint8_t interleave_gap; /* 711 */ - uint32_t volume_sequence_number; /* 723 */ - uint8_t filename_len; /* 711 */ + uint8_t file_unit_size; /*! 711 */ + uint8_t interleave_gap; /*! 711 */ + uint32_t volume_sequence_number; /*! 723 */ + uint8_t filename_len; /*! 711 */ char filename[EMPTY_ARRAY_SIZE]; } GNUC_PACKED; diff --git a/include/cdio/logging.h b/include/cdio/logging.h index 13f44f6f..fea9afb7 100644 --- a/include/cdio/logging.h +++ b/include/cdio/logging.h @@ -1,5 +1,5 @@ /* - $Id: logging.h,v 1.3 2003/10/05 14:48:07 rocky Exp $ + $Id: logging.h,v 1.4 2003/11/04 04:45:24 rocky Exp $ Copyright (C) 2000 Herbert Valerio Riedel @@ -23,36 +23,93 @@ #include +/** + * The different log levels supported. + */ typedef enum { - CDIO_LOG_DEBUG = 1, - CDIO_LOG_INFO, - CDIO_LOG_WARN, - CDIO_LOG_ERROR, - CDIO_LOG_ASSERT + CDIO_LOG_DEBUG = 1, /**< Debug-level messages - helps debug what's up. */ + CDIO_LOG_INFO, /**< Informational - indicates perhaps something of + interest. */ + CDIO_LOG_WARN, /**< Warning conditions - something that looks funny. */ + CDIO_LOG_ERROR, /**< Error conditions - may terminate program. */ + CDIO_LOG_ASSERT /**< Critical conditions - may abort program. */ } cdio_log_level_t; -extern int cdio_loglevel_default; +/** + * The place to save the preference concerning how much verbosity + * is desired. This is used by the internal default log handler, but + * it could be use by applications which provide their own log handler. + */ +extern cdio_log_level_t cdio_loglevel_default; -void -cdio_log (cdio_log_level_t level, const char format[], ...) GNUC_PRINTF(2, 3); - +/** + * This type defines the signature of a log handler. For every + * message being logged, the handler will receive the log level and + * the message string. + * + * @see cdio_log_set_handler + * @see cdio_log_level_t + * + * @param level The log level. + * @param message The log message. + */ typedef void (*cdio_log_handler_t) (cdio_log_level_t level, const char message[]); -cdio_log_handler_t -cdio_log_set_handler (cdio_log_handler_t new_handler); +/** + * Set a custom log handler for libcdio. The return value is the log + * handler being replaced. If the provided parameter is NULL, then + * the handler will be reset to the default handler. + * + * @see cdio_log_handler_t + * + * @param new_handler The new log handler. + * @return The previous log handler. + */ +cdio_log_handler_t cdio_log_set_handler (cdio_log_handler_t new_handler); -void -cdio_debug (const char format[], ...) GNUC_PRINTF(1,2); +/** + * Handle an message with the given log level + * + * @see cdio_debug + * @see cdio_info + * @see cdio_warn + * @see cdio_error -void -cdio_info (const char format[], ...) GNUC_PRINTF(1,2); + * @param level The log level. + * @param format printf-style format string + * @param ... remaining arguments needed by format string + */ +void cdio_log (cdio_log_level_t level, + const char format[], ...) GNUC_PRINTF(2, 3); + +/** + * Handle a debugging message. + * + * @see cdio_log for a more generic routine + */ +void cdio_debug (const char format[], ...) GNUC_PRINTF(1,2); -void -cdio_warn (const char format[], ...) GNUC_PRINTF(1,2); +/** + * Handle an informative message. + * + * @see cdio_log for a more generic routine + */ +void cdio_info (const char format[], ...) GNUC_PRINTF(1,2); -void -cdio_error (const char format[], ...) GNUC_PRINTF(1,2); +/** + * Handle a warning message. + * + * @see cdio_log for a more generic routine + */ +void cdio_warn (const char format[], ...) GNUC_PRINTF(1,2); + +/** + * Handle an error message. + * + * @see cdio_log for a more generic routine + */ +void cdio_error (const char format[], ...) GNUC_PRINTF(1,2); #endif /* __LOGGING_H__ */ diff --git a/lib/logging.c b/lib/logging.c index 385b4839..3a1452ae 100644 --- a/lib/logging.c +++ b/lib/logging.c @@ -1,5 +1,5 @@ /* - $Id: logging.c,v 1.3 2003/10/05 14:47:45 rocky Exp $ + $Id: logging.c,v 1.4 2003/11/04 04:45:24 rocky Exp $ Copyright (C) 2000 Herbert Valerio Riedel @@ -30,9 +30,9 @@ #include "cdio_assert.h" -static const char _rcsid[] = "$Id: logging.c,v 1.3 2003/10/05 14:47:45 rocky Exp $"; +static const char _rcsid[] = "$Id: logging.c,v 1.4 2003/11/04 04:45:24 rocky Exp $"; -int cdio_loglevel_default = CDIO_LOG_WARN; +cdio_log_level_t cdio_loglevel_default = CDIO_LOG_WARN; static void default_cdio_log_handler (cdio_log_level_t level, const char message[])