diff options
Diffstat (limited to 'Src/external_dependencies/libdiscid-0.6.2/include/discid')
| -rw-r--r-- | Src/external_dependencies/libdiscid-0.6.2/include/discid/discid.h | 486 | ||||
| -rw-r--r-- | Src/external_dependencies/libdiscid-0.6.2/include/discid/discid_private.h | 139 |
2 files changed, 625 insertions, 0 deletions
diff --git a/Src/external_dependencies/libdiscid-0.6.2/include/discid/discid.h b/Src/external_dependencies/libdiscid-0.6.2/include/discid/discid.h new file mode 100644 index 00000000..5631c89e --- /dev/null +++ b/Src/external_dependencies/libdiscid-0.6.2/include/discid/discid.h @@ -0,0 +1,486 @@ +/* -------------------------------------------------------------------------- + + MusicBrainz -- The Internet music metadatabase + + Copyright (C) 2013 Johannes Dewender + Copyright (C) 2006-2010 Lukas Lalinsky + Copyright (C) 2006 Matthias Friedrich + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +--------------------------------------------------------------------------- */ +#ifndef MUSICBRAINZ_DISC_ID_H +#define MUSICBRAINZ_DISC_ID_H + +#if (defined(_WIN32) || defined(_WIN64) || defined(__CYGWIN__)) +# ifdef libdiscid_EXPORTS +# define LIBDISCID_API __declspec(dllexport) +# else +# define LIBDISCID_API __declspec(dllimport) +# endif +# define LIBDISCID_INTERNAL +#elif (defined(__GNUC__) && (__GNUC__ >= 4)) || defined(__clang__) +# define LIBDISCID_API +# define LIBDISCID_INTERNAL __attribute__((visibility("hidden"))) +#elif defined(__SUNPRO_C) +# define LIBDISCID_API __global +# define LIBDISCID_INTERNAL __hidden +#else +# define LIBDISCID_API +# define LIBDISCID_INTERNAL +#endif + +#if (defined(_WIN32) || defined(_WIN64) || defined(__CYGWIN__)) +#define LIBDISCID_DEPRECATED __declspec(deprecated) +#elif (defined(__GNUC__) && (__GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1))) || defined(__clang__) +#define LIBDISCID_DEPRECATED __attribute__((deprecated)) +#else +#define LIBDISCID_DEPRECATED +#endif + +#define DISCID_VERSION_MAJOR @libdiscid_MAJOR@ +#define DISCID_VERSION_MINOR @libdiscid_MINOR@ +#define DISCID_VERSION_PATCH @libdiscid_PATCH@ +#define DISCID_VERSION_NUM @libdiscid_VERSION_NUM@ + +#ifdef __cplusplus + extern "C" { +#endif + +/*! + * \mainpage libdiscid + * \section intro Introduction + * + * Libdiscid is a C library for calculating DiscIDs + * (<a href="http://musicbrainz.org/doc/Disc ID">MusicBrainz</a> + * and <a href="http://freedb.org">freedb</a>) + * for Audio CDs. + * Additionally the library can extract the MCN/UPC/EAN and the + * <a href="http://musicbrainz.org/doc/ISRC">ISRCs</a> from disc. + * + * The idea is to have an easy to use library without any dependencies + * that can be used from scripting languages. + * + * The API is documented in discid.h. + * + * \section examples Examples + * + * This is an example of the most basic usage: + * + * \code + * + * DiscId *disc = discid_new(); + * + * if ( discid_read_sparse(disc, "/dev/cdrom", 0) == 0 ) { + * fprintf(stderr, "Error: %s\n", discid_get_error_msg(disc)); + * return 1; + * } + * + * printf("DiscID : %s\n", discid_get_id(disc)); + * printf("Submit via : %s\n", discid_get_submission_url(disc)); + * + * discid_free(disc); + * + * \endcode + * + * \section Building + * + * libdiscid provides a pkg-config script that returns the necessary compiler and linker flags, as well as the + * version number. To build a small sample program one would use: + * + * @par + * <tt>gcc libdiscid-test.c \`pkg-config libdiscid --cflags --libs\` -o libdiscid-test</tt> + * + * \section Contact + * + * - <a href="http://lists.musicbrainz.org/mailman/listinfo/musicbrainz-devel">MusicBrainz Development Mailing List</a> + * - <a href="http://tickets.musicbrainz.org/browse/LIB">MusicBrainz Bug Tracker</a> + * - <a href="http://musicbrainz.org/doc/libdiscid">MusicBrainz Documentation</a> + * - <a href="https://github.com/metabrainz/libdiscid">Github Repository</a> + * + */ + + +/** + * A transparent handle for an Audio CD. + * + * This is returned by discid_new() and has to be passed as the first + * parameter to all discid_*() functions. + */ +typedef void *DiscId; + + +/** + * Return a handle for a new DiscId object. + * + * If no memory could be allocated, NULL is returned. Don't use the created + * DiscId object before calling discid_read() or discid_put(). + * + * @return a DiscId object, or NULL. + */ +LIBDISCID_API DiscId *discid_new(); + + +/** + * Release the memory allocated for the DiscId object. + * + * @param d a DiscId object created by discid_new() + */ +LIBDISCID_API void discid_free(DiscId *d); + + +/** + * Read all supported features of the disc in the given CD-ROM/DVD-ROM drive. + * + * This function reads the disc in the drive specified by the given device + * identifier. If the device is NULL, the default drive, as returned by + * discid_get_default_device() is used. + * + * If you do not require all features provided by libdiscid, such as MCN + * or ISRC reading, you should consider using discid_read_sparse() instead + * of discid_read() for performance reasons. + * + * On error, this function returns false and sets the error message which you + * can access using discid_get_error_msg(). In this case, the other functions + * won't return meaningful values and should not be used. + * + * This function may be used multiple times with the same DiscId object. + * + * @param d a DiscId object created by discid_new() + * @param device an operating system dependent device identifier, or NULL + * @return true if successful, or false on error. + */ +LIBDISCID_API int discid_read(DiscId *d, const char *device); + + +/** + * Read the disc in the given CD-ROM/DVD-ROM drive + * extracting only the TOC and additionally specified features. + * + * This function will always read the TOC, but additional features + * like ::DISCID_FEATURE_MCN and ::DISCID_FEATURE_ISRC can be set + * using the features parameter. + * Multiple features can be set using bitwise OR. + * + * If you only want to generate a disc ID, you only need the TOC, + * so set features to 0: + * \code + * discid_read_sparse(disc, device, 0) + * \endcode + * This is a bit more verbose, but equivalent since ::DISCID_FEATURE_READ + * is always implied: + * \code + * discid_read_sparse(disc, device, DISCID_FEATURE_READ) + * \endcode + * + * If you want to read all features available, you can use discid_read(). + * + * On error, this function returns false and sets the error message which you + * can access using discid_get_error_msg(). In this case, the other functions + * won't return meaningful values and should not be used. + * + * This function may be used multiple times with the same DiscId object. + * + * \since libdiscid 0.5.0 + * + * @param d a DiscId object created by discid_new() + * @param device an operating system dependent device identifier, or NULL + * @param features a list of bit flags from the enum ::discid_feature + * @return true if successful, or false on error. + */ +LIBDISCID_API int discid_read_sparse(DiscId *d, const char *device, + unsigned int features); + +#define DISCID_HAVE_SPARSE_READ + +/** + * Provides the TOC of a known CD. + * + * This function may be used if the TOC has been read earlier and you + * want to calculate the disc ID afterwards, without accessing the disc + * drive. It replaces the discid_read function in this case. + * + * On error, this function returns false and sets the error message which you + * can access using discid_get_error_msg(). In this case, the other functions + * won't return meaningful values and should not be used. + * + * The offsets parameter points to an array which contains the track offsets + * for each track. The first element, offsets[0], is the leadout track. It + * must contain the total number of sectors on the disc. + * + * For discs with additional data tracks, the trailing data tracks + * should be ignored. offset[0] should then be the last sector of the last + * audio track. + * Make sure the length of the last audio track as returned by libdiscid + * after a put is the same as the length of your last audio track. + * Depending on your tools you might need to substract 11400 (2:32 min.). + * See also: + * <a href="http://musicbrainz.org/doc/Disc_ID_Calculation">Disc ID Calculation</a> + * + * + * @param d a DiscID object created by discid_new() + * @param first the number of the first audio track on disc (usually one) + * @param last the number of the last audio track on the disc + * @param offsets a pointer to an array of 100 track offsets + * @return true if the given data was valid, and false on error + */ +LIBDISCID_API int discid_put(DiscId *d, int first, int last, int *offsets); + + +/** + * Return a human-readable error message. + * + * This function may only be used if discid_read() failed. The returned + * error message is only valid as long as the DiscId object exists. + * + * @param d a DiscId object created by discid_new() + * @return a string describing the error that occurred + */ +LIBDISCID_API char *discid_get_error_msg(DiscId *d); + + +/** + * Return a MusicBrainz DiscID. + * + * The returned string is only valid as long as the DiscId object exists. + * + * @param d a DiscId object created by discid_new() + * @return a string containing a MusicBrainz DiscID + */ +LIBDISCID_API char *discid_get_id(DiscId *d); + + +/** + * Return a FreeDB DiscID. + * + * The returned string is only valid as long as the DiscId object exists. + * + * @param d a DiscId object created by discid_new() + * @return a string containing a FreeDB DiscID + */ +LIBDISCID_API char *discid_get_freedb_id(DiscId *d); + +/** + * Return a string representing CD Table Of Contents (TOC). + * + * The string has following values separated by space: + * first track number + * last track number + * total length in sectors + * offset of 1st track + * offset of 2nd track + * ... + * + * Example: + * 1 7 164900 150 22460 50197 80614 100828 133318 144712 + * + * The returned string is only valid as long as the DiscId object exists. + * + * @param d a DiscId object created by discid_new() + * @return a string containing TOC information + */ +LIBDISCID_API char *discid_get_toc_string(DiscId *d); + +/** + * Return an URL for submitting the DiscID to MusicBrainz. + * + * The URL leads to an interactive disc submission wizard that guides the + * user through the process of associating this disc's DiscID with a + * release in the MusicBrainz database. + * + * The returned string is only valid as long as the DiscId object exists. + * + * @param d a DiscId object created by discid_new() + * @return a string containing an URL + */ +LIBDISCID_API char *discid_get_submission_url(DiscId *d); + +/** + * Return an URL for retrieving CD information from MusicBrainz' web service + * + * The URL provides the CD information in XML. + * See http://musicbrainz.org/development/mmd for details. + * + * The returned string is only valid as long as the DiscId object exists. + * + * @param d a DiscId object created by discid_new() + * @return a string containing an URL + * + * @deprecated This function is deprecated. Please use libmusicbrainz instead + * since this function returns an URL referring the deprecated webservice. + */ +LIBDISCID_API LIBDISCID_DEPRECATED char *discid_get_webservice_url(DiscId *d); + +/** + * Return the name of the default disc drive for this machine. + * This isn't constant, but possibly depends on the drives currently + * attached, depending on the platform. + * For this reason you should call this once and save it + * when you want to make sure to use the same drive for + * multiple operations. + * + * The returned string is thread local and owned by libdiscid internally. + * + * @return a string containing an operating system dependent device identifier + */ +LIBDISCID_API char *discid_get_default_device(void); + + +/** + * Return the number of the first track on this disc. + * + * @param d a DiscId object created by discid_new() + * @return the number of the first track + */ +LIBDISCID_API int discid_get_first_track_num(DiscId *d); + + +/** + * Return the number of the last audio track on this disc. + * + * @param d a DiscId object created by discid_new() + * @return the number of the last track + */ +LIBDISCID_API int discid_get_last_track_num(DiscId *d); + + +/** + * Return the length of the disc in sectors. + * + * @param d a DiscId object created by discid_new() + * @return the length of the disc in sectors + */ +LIBDISCID_API int discid_get_sectors(DiscId *d); + + +/** + * Return the sector offset of a track. + * + * Only track numbers between (and including) discid_get_first_track_num() + * and discid_get_last_track_num() may be used. + * + * @param d a DiscId object created by discid_new() + * @param track_num the number of a track + * @return sector offset of the specified track + */ +LIBDISCID_API int discid_get_track_offset(DiscId *d, int track_num); + + +/** + * Return the length of a track in sectors. + * + * Only track numbers between (and including) discid_get_first_track_num() + * and discid_get_last_track_num() may be used. + * + * @param d a DiscId object created by discid_new() + * @param track_num the number of a track + * @return length of the specified track + */ +LIBDISCID_API int discid_get_track_length(DiscId *d, int track_num); + +/** + * Return the Media Catalogue Number (MCN) for the disc. + * + * This is essentially an EAN (= UPC with 0 prefix). + * + * \since libdiscid 0.3.0 + * + * @param d a DiscId object created by discid_new() + * @return a string containing an Media Catalogue Number of the disk + */ +LIBDISCID_API char* discid_get_mcn(DiscId *d); + +/** + * Return the ISRC for a track. + * + * Only track numbers between (and including) discid_get_first_track_num() + * and discid_get_last_track_num() may be used. + * + * \since libdiscid 0.3.0 + * + * @param d a DiscId object created by discid_new() + * @param track_num the number of a track + * @return a string containing an ISRC for the specified track + */ +LIBDISCID_API char* discid_get_track_isrc(DiscId *d, int track_num); + + +/** + * PLATFORM-DEPENDENT FEATURES + * + * The platform dependent features are currently: + * - "read" read TOC from disc + * - "mcn" read MCN from disc + * - "isrc" read ISRC from disc + * + * A table in the + * <a href="http://musicbrainz.org/doc/libdiscid">MusicBrainz Documentation</a> + * specifies which features are available on which platform in what version. + * + * In the code you can use discid_get_feature_list() or discid_has_feature() + * below to get the features for your platform in this version. + */ + +enum discid_feature { + DISCID_FEATURE_READ = 1 << 0, + DISCID_FEATURE_MCN = 1 << 1, + DISCID_FEATURE_ISRC = 1 << 2, +}; +/** + * Check if a certain feature is implemented on the current platform. + * + * This only works for single features, not bit masks with multiple features. + * + * \since libdiscid 0.4.0 + * + * @param feature as enum ::discid_feature + * @return 1 if the feature is implemented and 0 if not. + */ +LIBDISCID_API int discid_has_feature(enum discid_feature feature); + +#define DISCID_FEATURE_STR_READ "read" +#define DISCID_FEATURE_STR_MCN "mcn" +#define DISCID_FEATURE_STR_ISRC "isrc" +#define DISCID_FEATURE_LENGTH 32 +/** + * Return a list of features supported by the current platform. + * The array of length ::DISCID_FEATURE_LENGTH should be allocated by the user. + * After the call each element of the array is either NULL + * or a pointer to a static string. + * + * \since libdiscid 0.4.0 + * + * @param[out] features a static string array of length ::DISCID_FEATURE_LENGTH + */ +LIBDISCID_API void discid_get_feature_list( + char *features[DISCID_FEATURE_LENGTH]); + +/** + * Return the full version string of this library, including the name. + * This can be used for debug output. + * Don't use this to test for features, see discid_has_feature(). + * + * \since libdiscid 0.4.0 + * + * @return a string containing the version of libdiscid. + */ +LIBDISCID_API char *discid_get_version_string(void); + + +#ifdef __cplusplus + } +#endif + +#endif /* MUSICBRAINZ_DISC_ID_H */ diff --git a/Src/external_dependencies/libdiscid-0.6.2/include/discid/discid_private.h b/Src/external_dependencies/libdiscid-0.6.2/include/discid/discid_private.h new file mode 100644 index 00000000..d3715b5b --- /dev/null +++ b/Src/external_dependencies/libdiscid-0.6.2/include/discid/discid_private.h @@ -0,0 +1,139 @@ +/* -------------------------------------------------------------------------- + + MusicBrainz -- The Internet music metadatabase + + Copyright (C) 2006 Matthias Friedrich + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + + $Id$ + +--------------------------------------------------------------------------- */ +/* + * For internal use only. This header file is not installed. + */ +#ifndef MUSICBRAINZ_DISC_ID_PRIVATE_H +#define MUSICBRAINZ_DISC_ID_PRIVATE_H + +#include "discid/discid.h" + +/* Length of toc string, "xxx+xxx" + 100 tracks 7 bytes each ("+xxxxxx") + * The highest possible offset is 90 minutes * 60 seconds/minute * 75 frames/second = 405000. + * That is 6 digits plus one plus sign = 7 characters per track. + * So 3 + 3 (first and last) + 100*7 (disc length plus 99 tracks) = 706 + */ +#define MB_TOC_STRING_LENGTH (3 + 3 + 100*7) + +/* Length of a MusicBrainz DiscID in bytes (without a trailing '\0'-byte). */ +#define MB_DISC_ID_LENGTH 32 + +/* Length of a FreeDB DiscID in bytes (without a trailing '\0'-byte). */ +#define FREEDB_DISC_ID_LENGTH 8 + +/* The maximum permitted length for an error message (without the '\0'-byte). */ +#define MB_ERROR_MSG_LENGTH 255 + +/* Length of url prefixes */ +#define MB_URL_PREFIX_LENGTH 300 + +/* Maximum length of any url (including query string) */ +#define MB_MAX_URL_LENGTH (MB_URL_PREFIX_LENGTH + MB_DISC_ID_LENGTH + MB_TOC_STRING_LENGTH) + +/* The URL that can be used for submitting DiscIDs (no parameters yet) */ +#define MB_SUBMISSION_URL "http://musicbrainz.org/cdtoc/attach" + +/* The URL that can be used for retrieving XML for a CD */ +#define MB_WEBSERVICE_URL "http://musicbrainz.org/ws/1/release" + +/* Maximum length of a Media Catalogue Number string */ +#define MCN_STR_LENGTH 13 + +/* Maximum length of a ISRC code string */ +#define ISRC_STR_LENGTH 12 + +/* Maximum disc length in frames/sectors + * This is already not according to spec, but many players might still work + * Spec is 79:59.75 = 360000 + lead-in + lead-out */ +#define MAX_DISC_LENGTH (90 * 60 * 75) + +/* + * This data structure represents an audio disc. + * + * We use fixed length strings here because that way the user doesn't have to + * check for memory exhaustion conditions. As soon as the mb_disc object has + * been created, all calls returning strings will be successful. + */ +typedef struct { + int first_track_num; + int last_track_num; + int track_offsets[100]; + char id[MB_DISC_ID_LENGTH+1]; + char freedb_id[FREEDB_DISC_ID_LENGTH+1]; + char submission_url[MB_MAX_URL_LENGTH+1]; + char webservice_url[MB_MAX_URL_LENGTH+1]; + char toc_string[MB_TOC_STRING_LENGTH+1]; + char error_msg[MB_ERROR_MSG_LENGTH+1]; + char isrc[100][ISRC_STR_LENGTH+1]; + char mcn[MCN_STR_LENGTH+1]; + int success; +} mb_disc_private; + +typedef struct { + int control; + int address; +} mb_disc_toc_track; + +typedef struct { + int first_track_num; + int last_track_num; + mb_disc_toc_track tracks[100]; +} mb_disc_toc; + +/* + * This function has to be implemented once per operating system. + * + * The caller guarantees that both the disc and device parameters are + * not NULL. + * + * Implementors have to set mb_disc_private's first_track_num, last_track_num, + * and track_offsets attributes. If there is an error, the error_msg attribute + * has to be set to a human-readable error message. + * + * On error, 0 is returned. On success, 1 is returned. + */ +LIBDISCID_INTERNAL int mb_disc_read_unportable(mb_disc_private *disc, const char *device, unsigned int features); + + +/* + * This should return the name of the default/preferred CDROM/DVD device + * on this operating system. It has to be in a format usable for the second + * parameter of mb_disc_read_unportable(). + */ +LIBDISCID_INTERNAL char *mb_disc_get_default_device_unportable(void); + +/* + * This should return 1 if the feature is supported by the platform + * and 0 if not. + */ +LIBDISCID_INTERNAL int mb_disc_has_feature_unportable(enum discid_feature feature); + +/* + * Load data to the mb_disc_private structure based on mb_disc_toc. + * + * On error, 0 is returned. On success, 1 is returned. + */ +LIBDISCID_INTERNAL int mb_disc_load_toc(mb_disc_private *disc, mb_disc_toc *toc); + +#endif /* MUSICBRAINZ_DISC_ID_PRIVATE_H */ |