claunia/libcdio-osx
Archived
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

documentation additions, mostly doxygen. More #defines become enumerations.

Browse Source
This commit is contained in:
rocky
2006-03-18 18:37:56 +00:00
parent e79890bc7d
commit aa838fc894
4 changed files with 172 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files

96
include/cdio/cdda.h
View File

@@ -1,5 +1,5 @@
/*
$Id: cdda.h,v 1.26 2006/02/16 20:09:27 rocky Exp $
$Id: cdda.h,v 1.27 2006/03/18 18:37:56 rocky Exp $
Copyright (C) 2004, 2005, 2006 Rocky Bernstein <rocky@panix.com>
Copyright (C) 2001 Xiph.org
@@ -19,6 +19,7 @@
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
/** \file cdda.h
*
* \brief The top-level interface header for libcdio_cdda.
@@ -35,24 +36,31 @@
extern "C" {
#endif /* __cplusplus */
/** cdrom_paranoia is an opaque structure which is used in all of the
library operations.
*/
typedef struct cdrom_paranoia_s cdrom_paranoia_t;
typedef struct cdrom_drive_s cdrom_drive_t;
/** For compatibility. cdrom_drive_t is deprecated, use cdrom_drive_t
instead. */
extern enum paranoia_cdda_enums {
CDDA_MESSAGE_FORGETIT = 0,
CDDA_MESSAGE_PRINTIT = 1,
CDDA_MESSAGE_LOGIT = 2,
CD_FRAMESAMPLES = CDIO_CD_FRAMESIZE_RAW / 4,
MAXTRK = (CDIO_CD_MAX_TRACKS+1)
} paranoia_cdda_enums;
/** cdrom_paranoia is an opaque structure which is used in all of the
library operations.
*/
typedef struct cdrom_paranoia_s cdrom_paranoia_t;
typedef struct cdrom_drive_s cdrom_drive_t;
/** For compatibility. cdrom_drive_t is deprecated, use cdrom_drive_t
instead. */
/**
Flags for simulating jitter used in testing.
The enumeration type one probably wouldn't really use in a program.
It is here instead of #defines to give symbolic names that can be
helpful in debuggers where wants just to say refer to
CDDA_TEST_JITTER_SMALL and get the correct value.
*/
typedef enum {
CDDA_MESSAGE_FORGETIT = 0,
CDDA_MESSAGE_PRINTIT = 1,
CDDA_MESSAGE_LOGIT = 2,
CD_FRAMESAMPLES = CDIO_CD_FRAMESIZE_RAW / 4,
MAXTRK = (CDIO_CD_MAX_TRACKS+1)
} paranoia_cdda_enums_t;
#define CD_FRAMESAMPLES (CDIO_CD_FRAMESIZE_RAW / 4)
#include <signal.h>
@@ -70,10 +78,6 @@ typedef struct TOC_s {
/** For compatibility. TOC is deprecated, use TOC_t instead. */
#define TOC TOC_t
#define CDDA_MESSAGE_FORGETIT 0
#define CDDA_MESSAGE_PRINTIT 1
#define CDDA_MESSAGE_LOGIT 2
/** \brief Structure for cdparanoia's CD-ROM access */
struct cdrom_drive_s {
@@ -134,29 +138,28 @@ struct cdrom_drive_s {
};
/*! An enumeration for some of the CDDA_TEST_* \#defines below. This
isn't really an enumeration one would really use in a program. The
enumeration is created be helpful in debuggers where wants just to
refer to the CDDA_TEST_ names and get something.
*/
extern enum paranoia_jitter_enums {
CDDA_TEST_JITTER_SMALL = 1,
CDDA_TEST_JITTER_LARGE = 2,
CDDA_TEST_JITTER_MASSIVE = 3,
CDDA_TEST_FRAG_SMALL = (1<<3),
CDDA_TEST_FRAG_LARGE = (2<<3),
CDDA_TEST_FRAG_MASSIVE = (3<<3),
CDDA_TEST_UNDERRUN = 64
} paranoia_jitter_enums;
/**
Flags for simulating jitter used in testing.
The enumeration type one probably wouldn't really use in a program.
It is here instead of #defines to give symbolic names that can be
helpful in debuggers where wants just to say refer to
CDDA_TEST_JITTER_SMALL and get the correct value.
*/
typedef enum {
CDDA_TEST_JITTER_SMALL = 1,
CDDA_TEST_JITTER_LARGE = 2,
CDDA_TEST_JITTER_MASSIVE = 3,
CDDA_TEST_FRAG_SMALL = (1<<3),
CDDA_TEST_FRAG_LARGE = (2<<3),
CDDA_TEST_FRAG_MASSIVE = (3<<3),
CDDA_TEST_UNDERRUN = 64
} paranoia_jitter_t;
/** jitter testing. The first two bits are set to determine the
byte-distance we will jitter the data; 0 is no shifting.
*/
#define CDDA_TEST_JITTER_SMALL 1
#define CDDA_TEST_JITTER_LARGE 2
#define CDDA_TEST_JITTER_MASSIVE 3
/**< jitter testing. Set the below bit to always cause jittering on reads.
The below bit only has any effect if the first two (above) bits are
nonzero. If the above bits are set, but the below bit isn't we'll
@@ -339,6 +342,7 @@ const char *strerror_tr[]={
/** Errors returned by lib:
\verbatim
001: Unable to set CDROM to read audio mode
002: Unable to read table of contents lead-out
003: CDROM reporting illegal number of tracks
@@ -361,6 +365,7 @@ const char *strerror_tr[]={
401: Invalid track number
402: Track not audio data
403: No audio tracks on disc
\endverbatim
*/
@@ -385,7 +390,7 @@ const char *strerror_tr[]={
#define cdda_track_preemp cdio_cddap_track_preemp
#define cdda_disc_firstsector cdio_cddap_disc_firstsector
#define cdda_disc_lastsector cdio_cddap_disc_lastsector
#define cdrom_drive cdrom_drive_t
#define cdrom_drive cdrom_drive_t
#endif /*DO_NOT_WANT_PARANOIA_COMPATIBILITY*/
@@ -393,5 +398,14 @@ const char *strerror_tr[]={
}
#endif /* __cplusplus */
/** The below variables are trickery to force the above enum symbol
values to be recorded in debug symbol tables. They are used to
allow one to refer to the enumeration value names in the typedefs
above in a debugger and debugger expressions
*/
extern paranoia_jitter_t debug_paranoia_jitter;
extern paranoia_cdda_enums_t debug_paranoia_cdda_enums;
#endif /*_CDDA_INTERFACE_H_*/

114
include/cdio/paranoia.h
View File

@@ -1,7 +1,7 @@
/*
$Id: paranoia.h,v 1.11 2005/10/14 02:07:06 rocky Exp $
$Id: paranoia.h,v 1.12 2006/03/18 18:37:56 rocky Exp $
Copyright (C) 2004, 2005 Rocky Bernstein <rocky@panix.com>
Copyright (C) 2004, 2005, 2006 Rocky Bernstein <rocky@panix.com>
Copyright (C) 1998 Monty xiphmont@mit.edu
This program is free software; you can redistribute it and/or modify
@@ -37,32 +37,51 @@
*/
#define CD_FRAMEWORDS (CDIO_CD_FRAMESIZE_RAW/2)
/**! Flags used in paranoia_modeset. */
/**
Flags used in paranoia_modeset.
#define PARANOIA_MODE_FULL 0xff
#define PARANOIA_MODE_DISABLE 0
#define PARANOIA_MODE_VERIFY 1
#define PARANOIA_MODE_FRAGMENT 2
#define PARANOIA_MODE_OVERLAP 4
#define PARANOIA_MODE_SCRATCH 8
#define PARANOIA_MODE_REPAIR 16
#define PARANOIA_MODE_NEVERSKIP 32
The enumeration type one probably wouldn't really use in a program.
It is here instead of #defines to give symbolic names that can be
helpful in debuggers where wants just to say refer to
PARANOIA_MODE_DISABLE and get the correct value.
*/
typedef enum {
PARANOIA_CB_READ,
PARANOIA_CB_VERIFY,
PARANOIA_CB_FIXUP_EDGE,
PARANOIA_CB_FIXUP_ATOM,
PARANOIA_CB_SCRATCH,
PARANOIA_CB_REPAIR,
PARANOIA_CB_SKIP,
PARANOIA_CB_DRIFT,
PARANOIA_CB_BACKOFF,
PARANOIA_CB_OVERLAP,
PARANOIA_CB_FIXUP_DROPPED,
PARANOIA_CB_FIXUP_DUPED,
PARANOIA_CB_READERR
PARANOIA_MODE_DISABLE = 0x00, /**< No fixups */
PARANOIA_MODE_VERIFY = 0x01, /**< Verify data integrety in overlap area*/
PARANOIA_MODE_FRAGMENT = 0x02, /**< unsupported */
PARANOIA_MODE_OVERLAP = 0x04, /**< Perform overlapped reads */
PARANOIA_MODE_SCRATCH = 0x08, /**< unsupported */
PARANOIA_MODE_REPAIR = 0x10, /**< unsupported */
PARANOIA_MODE_NEVERSKIP = 0x20, /**< Do not skip failed reads (retry
maxretries) */
PARANOIA_MODE_FULL = 0xff, /**< Maximum paranoia - all of the above
(except disable) */
} paranoia_mode_t;
/**
Flags set in a callback.
The enumeration type one probably wouldn't really use in a program.
It is here instead of #defines to give symbolic names that can be
helpful in debuggers where wants just to say refer to
PARANOIA_CB_READ and get the correct value.
*/
typedef enum {
PARANOIA_CB_READ, /**< Read off adjust ??? */
PARANOIA_CB_VERIFY, /**< Verifying jitter */
PARANOIA_CB_FIXUP_EDGE, /**< Fixed edge jitter */
PARANOIA_CB_FIXUP_ATOM, /**< Fixed atom jitter */
PARANOIA_CB_SCRATCH, /**< Unsupported */
PARANOIA_CB_REPAIR, /**< Unsupported */
PARANOIA_CB_SKIP, /**< Skip exhausted retry */
PARANOIA_CB_DRIFT, /**< Skip exhausted retry */
PARANOIA_CB_BACKOFF, /**< Unsupported */
PARANOIA_CB_OVERLAP, /**< Dynamic overlap adjust */
PARANOIA_CB_FIXUP_DROPPED, /**< Fixed dropped bytes */
PARANOIA_CB_FIXUP_DUPED, /**< Fixed duplicate bytes */
PARANOIA_CB_READERR /**< Hard read error */
} paranoia_cb_mode_t;
extern const char *paranoia_cb_mode2str[];
@@ -78,20 +97,27 @@ extern "C" {
@return new cdrom_paranoia object Call paranoia_free() when you are
done with it
*/
extern cdrom_paranoia_t *cdio_paranoia_init(cdrom_drive_t *d);
extern cdrom_paranoia_t *cdio_paranoia_init(cdrom_drive_t *d);
/*!
Free any resources associated with obj.
Free any resources associated with p.
@param p paranoia object to for which resources are to be freed.
@see paranoia_init.
*/
extern void cdio_paranoia_free(cdrom_paranoia_t *p);
extern void cdio_paranoia_free(cdrom_paranoia_t *p);
/*!
Set the kind of repair you want to on for reading.
The modes are listed above
@param p paranoia type
@mode mode paranoia mode flags built from values in
paranoia_mode_t, e.g.
PARANOIA_MODE_FULL^PARANOIA_MODE_NEVERSKIP
*/
extern void cdio_paranoia_modeset(cdrom_paranoia_t *p, int mode);
extern void cdio_paranoia_modeset(cdrom_paranoia_t *p, int mode_flags);
/*!
reposition reading offset.
@@ -101,7 +127,7 @@ extern void cdio_paranoia_modeset(cdrom_paranoia_t *p, int mode);
@param whence like corresponding parameter in libc's lseek, e.g.
SEEK_SET or SEEK_END.
*/
extern lsn_t cdio_paranoia_seek(cdrom_paranoia_t *p, off_t seek, int whence);
extern lsn_t cdio_paranoia_seek(cdrom_paranoia_t *p, off_t seek, int whence);
/*!
Reads the next sector of audio data and returns a pointer to a full
@@ -116,8 +142,9 @@ extern lsn_t cdio_paranoia_seek(cdrom_paranoia_t *p, off_t seek, int whence);
bytes. This data is not to be freed by the caller. It will persist
only until the next call to paranoia_read() for this p.
*/
extern int16_t *cdio_paranoia_read(cdrom_paranoia_t *p,
void(*callback)(long int, paranoia_cb_mode_t));
extern int16_t *cdio_paranoia_read(cdrom_paranoia_t *p,
void(*callback)(long int,
paranoia_cb_mode_t));
/*! The same as cdio_paranoia_read but the number of retries is set.
@param p paranoia object.
@@ -135,17 +162,17 @@ extern int16_t *cdio_paranoia_read(cdrom_paranoia_t *p,
@see cdio_paranoia_read.
*/
extern int16_t *cdio_paranoia_read_limited(cdrom_paranoia_t *p,
void(*callback)(long int,
extern int16_t *cdio_paranoia_read_limited(cdrom_paranoia_t *p,
void(*callback)(long int,
paranoia_cb_mode_t),
int max_retries);
int max_retries);
/*! a temporary hack */
extern void cdio_paranoia_overlapset(cdrom_paranoia_t *p,long overlap);
extern void cdio_paranoia_overlapset(cdrom_paranoia_t *p,long overlap);
extern void cdio_paranoia_set_range(cdrom_paranoia_t *p, long int start,
long int end);
extern void cdio_paranoia_set_range(cdrom_paranoia_t *p, long int start,
long int end);
#ifndef DO_NOT_WANT_PARANOIA_COMPATIBILITY
/** For compatibility with good ol' paranoia */
@@ -163,4 +190,13 @@ extern void cdio_paranoia_set_range(cdrom_paranoia_t *p, long int start,
}
#endif
/** The below variables are trickery to force the above enum symbol
values to be recorded in debug symbol tables. They are used to
allow one to refer to the enumeration value names in the typedefs
above in a debugger and debugger expressions
*/
extern paranoia_mode_t debug_paranoia_mode;
extern paranoia_cb_mode_t debug_paranoia_cb_mode;
#endif /*_CDIO_PARANOIA_H_*/