Loading...
Searching...
No Matches
discid.h File Reference

Go to the source code of this file.

## Macros

#define | LIBDISCID_API
#define | LIBDISCID_INTERNAL
#define | LIBDISCID_DEPRECATED
#define | DISCID_VERSION_MAJOR 0
#define | DISCID_VERSION_MINOR 7
#define | DISCID_VERSION_PATCH 0
#define | DISCID_VERSION_NUM 700
#define | DISCID_HAVE_SPARSE_READ
#define | DISCID_FEATURE_STR_READ "read"
#define | DISCID_FEATURE_STR_MCN "mcn"
#define | DISCID_FEATURE_STR_ISRC "isrc"
#define | DISCID_FEATURE_LENGTH 32

## Typedefs

typedef void * | DiscId
| A transparent handle for an Audio CD.

## Enumerations

enum | discid_feature { DISCID_FEATURE_READ = 1 << 0 , DISCID_FEATURE_MCN = 1 << 1 , DISCID_FEATURE_ISRC = 1 << 2 }
| PLATFORM-DEPENDENT FEATURES. More...

## Functions

LIBDISCID_API DiscId * | discid_new ()
| Return a handle for a new DiscId object.
LIBDISCID_API void | discid_free (DiscId *d)
| Release the memory allocated for the DiscId object.
LIBDISCID_API int | discid_read (DiscId *d, const char *device)
| Read all supported features of the disc in the given CD-ROM/DVD-ROM drive.
LIBDISCID_API int | discid_read_sparse (DiscId *d, const char *device, unsigned int features)
| Read the disc in the given CD-ROM/DVD-ROM drive extracting only the TOC and additionally specified features.
LIBDISCID_API int | discid_put (DiscId *d, int first, int last, int *offsets)
| Provides the TOC of a known CD.
LIBDISCID_API char * | discid_get_error_msg (DiscId *d)
| Return a human-readable error message.
LIBDISCID_API char * | discid_get_id (DiscId *d)
| Return a MusicBrainz DiscID.
LIBDISCID_API char * | discid_get_freedb_id (DiscId *d)
| Return a FreeDB DiscID.
LIBDISCID_API char * | discid_get_toc_string (DiscId *d)
| Return a string representing CD Table Of Contents (TOC).
LIBDISCID_API char * | discid_get_submission_url (DiscId *d)
| Return an URL for submitting the DiscID to MusicBrainz.
LIBDISCID_API LIBDISCID_DEPRECATED char * | discid_get_webservice_url (DiscId *d)
| Return an URL for retrieving CD information from MusicBrainz' web service.
LIBDISCID_API char * | discid_get_default_device (void)
| Return the name of the default disc drive for this machine.
LIBDISCID_API int | discid_get_first_track_num (DiscId *d)
| Return the number of the first track on this disc.
LIBDISCID_API int | discid_get_last_track_num (DiscId *d)
| Return the number of the last audio track on this disc.
LIBDISCID_API int | discid_get_sectors (DiscId *d)
| Return the length of the disc in sectors.
LIBDISCID_API int | discid_get_track_offset (DiscId *d, int track_num)
| Return the sector offset of a track.
LIBDISCID_API int | discid_get_track_length (DiscId *d, int track_num)
| Return the length of a track in sectors.
LIBDISCID_API char * | discid_get_mcn (DiscId *d)
| Return the Media Catalogue Number (MCN) for the disc.
LIBDISCID_API char * | discid_get_track_isrc (DiscId *d, int track_num)
| Return the ISRC for a track.
LIBDISCID_API int | discid_has_feature (enum discid_feature feature)
| Check if a certain feature is implemented on the current platform.
LIBDISCID_API void | discid_get_feature_list (char *features[DISCID_FEATURE_LENGTH])
| Return a list of features supported by the current platform.
LIBDISCID_API char * | discid_get_version_string (void)
| Return the full version string of this library, including the name.

## Macro Definition Documentation

## DISCID_FEATURE_LENGTH

#define DISCID_FEATURE_LENGTH 32

Examples
  discisrc.c.

## DISCID_FEATURE_STR_ISRC

#define DISCID_FEATURE_STR_ISRC "isrc"

## DISCID_FEATURE_STR_MCN

#define DISCID_FEATURE_STR_MCN "mcn"

## DISCID_FEATURE_STR_READ

#define DISCID_FEATURE_STR_READ "read"

## DISCID_HAVE_SPARSE_READ

#define DISCID_HAVE_SPARSE_READ

## DISCID_VERSION_MAJOR

#define DISCID_VERSION_MAJOR 0

## DISCID_VERSION_MINOR

#define DISCID_VERSION_MINOR 7

## DISCID_VERSION_NUM

#define DISCID_VERSION_NUM 700

## DISCID_VERSION_PATCH

#define DISCID_VERSION_PATCH 0

## LIBDISCID_API

#define LIBDISCID_API

## LIBDISCID_DEPRECATED

#define LIBDISCID_DEPRECATED

## LIBDISCID_INTERNAL

#define LIBDISCID_INTERNAL

## Typedef Documentation

## DiscId

typedef void* DiscId

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.

Examples
  discid.c, and discisrc.c.

## Enumeration Type Documentation

## discid_feature

enum discid_feature

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 MusicBrainz Documentation 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.

Enumerator
DISCID_FEATURE_READ |
DISCID_FEATURE_MCN |
DISCID_FEATURE_ISRC |

## Function Documentation

## discid_free()

LIBDISCID_API void discid_free | ( | DiscId * | d | ) |

Release the memory allocated for the DiscId object.

Parameters

  d | a DiscId object created by discid_new()

Examples
  discid.c, and discisrc.c.

## discid_get_default_device()

LIBDISCID_API char * discid_get_default_device | ( | void |  | ) |

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.

Returns
  a string containing an operating system dependent device identifier

Examples
  discisrc.c.

## discid_get_error_msg()

LIBDISCID_API char * discid_get_error_msg | ( | DiscId * | d | ) |

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.

Parameters

  d | a DiscId object created by discid_new()

Returns
  a string describing the error that occurred

Examples
  discid.c, and discisrc.c.

## discid_get_feature_list()

LIBDISCID_API void discid_get_feature_list | ( | char * | features[DISCID_FEATURE_LENGTH] | ) |

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

Parameters

  [out] | features | a static string array of length DISCID_FEATURE_LENGTH

Examples
  discisrc.c.

## discid_get_first_track_num()

LIBDISCID_API int discid_get_first_track_num | ( | DiscId * | d | ) |

Return the number of the first track on this disc.

Parameters

  d | a DiscId object created by discid_new()

Returns
  the number of the first track

Examples
  discid.c, and discisrc.c.

## discid_get_freedb_id()

LIBDISCID_API char * discid_get_freedb_id | ( | DiscId * | d | ) |

Return a FreeDB DiscID.

The returned string is only valid as long as the DiscId object exists.

Parameters

  d | a DiscId object created by discid_new()

Returns
  a string containing a FreeDB DiscID

Examples
  discid.c.

## discid_get_id()

LIBDISCID_API char * discid_get_id | ( | DiscId * | d | ) |

Return a MusicBrainz DiscID.

The returned string is only valid as long as the DiscId object exists.

Parameters

  d | a DiscId object created by discid_new()

Returns
  a string containing a MusicBrainz DiscID

Examples
  discid.c.

## discid_get_last_track_num()

LIBDISCID_API int discid_get_last_track_num | ( | DiscId * | d | ) |

Return the number of the last audio track on this disc.

Parameters

  d | a DiscId object created by discid_new()

Returns
  the number of the last track

Examples
  discid.c, and discisrc.c.

## discid_get_mcn()

LIBDISCID_API char * discid_get_mcn | ( | DiscId * | d | ) |

Return the Media Catalogue Number (MCN) for the disc.

This is essentially an EAN (= UPC with 0 prefix).

Since
  libdiscid 0.3.0

Parameters

  d | a DiscId object created by discid_new()

Returns
  a string containing an Media Catalogue Number of the disk

Examples
  discisrc.c.

## discid_get_sectors()

LIBDISCID_API int discid_get_sectors | ( | DiscId * | d | ) |

Return the length of the disc in sectors.

Parameters

  d | a DiscId object created by discid_new()

Returns
  the length of the disc in sectors

Examples
  discid.c.

## discid_get_submission_url()

LIBDISCID_API char * discid_get_submission_url | ( | 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.

Parameters

  d | a DiscId object created by discid_new()

Returns
  a string containing an URL

Examples
  discid.c.

## discid_get_toc_string()

LIBDISCID_API char * discid_get_toc_string | ( | 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.

Parameters

  d | a DiscId object created by discid_new()

Returns
  a string containing TOC information

## discid_get_track_isrc()

LIBDISCID_API char * discid_get_track_isrc | ( | DiscId * | d,
|  | int | track_num )

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

Parameters

  d | a DiscId object created by discid_new()
  track_num | the number of a track

Returns
  a string containing an ISRC for the specified track

Examples
  discisrc.c.

## discid_get_track_length()

LIBDISCID_API int discid_get_track_length | ( | 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.

Parameters

  d | a DiscId object created by discid_new()
  track_num | the number of a track

Returns
  length of the specified track

Examples
  discid.c.

## discid_get_track_offset()

LIBDISCID_API int discid_get_track_offset | ( | DiscId * | d,
|  | int | track_num )

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.

Parameters

  d | a DiscId object created by discid_new()
  track_num | the number of a track

Returns
  sector offset of the specified track

Examples
  discid.c.

## discid_get_version_string()

LIBDISCID_API char * discid_get_version_string | ( | void |  | ) |

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

Returns
  a string containing the version of libdiscid.

Examples
  discisrc.c.

## discid_get_webservice_url()

LIBDISCID_API LIBDISCID_DEPRECATED char * discid_get_webservice_url | ( | DiscId * | d | ) |

Return an URL for retrieving CD information from MusicBrainz' web service.

The URL provides the CD information in XML. See https://musicbrainz.org/development/mmd for details.

The returned string is only valid as long as the DiscId object exists.

Parameters

  d | a DiscId object created by discid_new()

Returns
  a string containing an URL

Deprecated
  This function is deprecated. Please use libmusicbrainz instead since this function returns an URL referring the deprecated webservice.

## discid_has_feature()

LIBDISCID_API int discid_has_feature | ( | enum discid_feature | feature | ) |

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

Parameters

  feature | as enum discid_feature

Returns
  1 if the feature is implemented and 0 if not.

Examples
  discisrc.c.

## discid_new()

LIBDISCID_API DiscId * discid_new | ( |  | ) |

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().

Returns
  a DiscId object, or NULL.

Examples
  discid.c, and discisrc.c.

## discid_put()

LIBDISCID_API int discid_put | ( | DiscId * | d,
|  | int | first,
|  | int | last,
|  | int * | offsets )

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: Disc ID Calculation

Parameters

  d | a DiscID object created by discid_new()
  first | the number of the first audio track on disc (usually one)
  last | the number of the last audio track on the disc
  offsets | a pointer to an array of 100 track offsets

Returns
  true if the given data was valid, and false on error

## discid_read()

LIBDISCID_API int discid_read | ( | DiscId * | d,
|  | const char * | device )

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.

Parameters

  d | a DiscId object created by discid_new()
  device | an operating system dependent device identifier, or NULL

Returns
  true if successful, or false on error.

## discid_read_sparse()

LIBDISCID_API int discid_read_sparse | ( | DiscId * | d,
|  | const char * | device,
|  | unsigned int | features )

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:

discid_read_sparse(disc, device, 0)
discid_read_sparse
LIBDISCID_API int discid_read_sparse(DiscId *d, const char *device, unsigned int features)
Read the disc in the given CD-ROM/DVD-ROM drive extracting only the TOC and additionally specified fe...

This is a bit more verbose, but equivalent since DISCID_FEATURE_READ is always implied:

discid_read_sparse(disc, device, DISCID_FEATURE_READ)
DISCID_FEATURE_READ
@ DISCID_FEATURE_READ
Definition discid.h:438

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

Parameters

  d | a DiscId object created by discid_new()
  device | an operating system dependent device identifier, or NULL
  features | a list of bit flags from the enum discid_feature

Returns
  true if successful, or false on error.

Examples
  discid.c, and discisrc.c.