## TotemDisc TotemDisc — disc utility functions |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <totem-disc.h>

    enum                TotemDiscMediaType;
    TotemDiscMediaType  totem_cd_detect_type                (const char *device,
                                                             GError **error);
    TotemDiscMediaType  totem_cd_detect_type_with_url       (const char *device,
                                                             char **mrl,
                                                             GError **error);
    TotemDiscMediaType  totem_cd_detect_type_from_dir       (const char *dir,
                                                             char **mrl,
                                                             GError **error);
    const char *	       totem_cd_get_human_readable_name    (TotemDiscMediaType type);
    char *		            totem_cd_mrl_from_type              (const char *scheme,
                                                             const char *dir);
    gboolean            totem_cd_has_medium                 (const char *device);

## Description

This file has various different disc utility functions for getting the media types and labels of discs.

The functions in this file refer to MRLs, which are a special form of URIs used by xine to refer to things such as DVDs. An example of an MRL would be `dvd:///dev/scd0`, which is not a valid URI as far as, for example, GIO is concerned.

The rest of the totem-pl-parser API exclusively uses URIs.

## Details

### enum TotemDiscMediaType

    typedef enum {
      MEDIA_TYPE_ERROR = -1,
      MEDIA_TYPE_DATA = 1,
      MEDIA_TYPE_CDDA,
      MEDIA_TYPE_VCD,
      MEDIA_TYPE_DVD,
      MEDIA_TYPE_DVB
    } TotemDiscMediaType;

Gives the media type of a disc, or `MEDIA_TYPE_ERROR` if the media type could not be determined.

`MEDIA_TYPE_ERROR` | there was an error determining the media's type
`MEDIA_TYPE_DATA` | data disc
`MEDIA_TYPE_CDDA` | audio CD
`MEDIA_TYPE_VCD` | video CD
`MEDIA_TYPE_DVD` | video DVD
`MEDIA_TYPE_DVB` | digital television

### totem_cd_detect_type ()

    TotemDiscMediaType  totem_cd_detect_type                (const char *device,
                                                             GError **error);

Detects the disc's type, given its device node path.

Possible error codes are as per `totem_cd_detect_type_with_url()`.

`device` : | a device node path
`error` : | return location for a GError, or `NULL`
Returns : | TotemDiscMediaType corresponding to the disc's type, or MEDIA_TYPE_ERROR on failure

### totem_cd_detect_type_with_url ()

    TotemDiscMediaType  totem_cd_detect_type_with_url       (const char *device,
                                                             char **mrl,
                                                             GError **error);

Detects the disc's type, given its device node path. If a string pointer is passed to `mrl`, it will return the disc's MRL as from `totem_cd_mrl_from_type()`.

Note that this function does synchronous I/O.

Possible error codes are as per `totem_cd_detect_type_from_dir()`.

`device` : | a device node path
`mrl` : | return location for the disc's MRL, or `NULL`. [out][transfer full][allow-none]
`error` : | return location for a GError, or `NULL`
Returns : | TotemDiscMediaType corresponding to the disc's type, or MEDIA_TYPE_ERROR on failure

### totem_cd_detect_type_from_dir ()

    TotemDiscMediaType  totem_cd_detect_type_from_dir       (const char *dir,
                                                             char **mrl,
                                                             GError **error);

Detects the disc's type, given its mount directory URI. If a string pointer is passed to `mrl`, it will return the disc's MRL as from `totem_cd_mrl_from_type()`.

Note that this function does synchronous I/O.

If no disc is present in the drive, a TOTEM_PL_PARSER_ERROR_NO_DISC error will be returned. On unknown mounting errors, a TOTEM_PL_PARSER_ERROR_MOUNT_FAILED error will be returned. On other I/O errors, or if resolution of symlinked mount paths failed, a code from GIOErrorEnum will be returned.

`dir` : | a directory URI
`mrl` : | return location for the disc's MRL, or `NULL`. [out][transfer full][allow-none]
`error` : | return location for a GError, or `NULL`
Returns : | TotemDiscMediaType corresponding to the disc's type, or MEDIA_TYPE_ERROR on failure

### totem_cd_get_human_readable_name ()

    const char *	       totem_cd_get_human_readable_name    (TotemDiscMediaType type);

Returns the human-readable name for the given TotemDiscMediaType.

`type` : | a TotemDiscMediaType
Returns : | the disc media type's readable name, which must not be freed, or `NULL` for unhandled media types

### totem_cd_mrl_from_type ()

    char *		            totem_cd_mrl_from_type              (const char *scheme,
                                                             const char *dir);

Builds an MRL using the scheme `scheme` and the given URI `dir`, taking the filename from the URI if it's a `file://` and just using the whole URI otherwise.

`scheme` : | a scheme (e.g. "dvd")
`dir` : | a directory URI
Returns : | a newly-allocated string containing the MRL

### totem_cd_has_medium ()

    gboolean            totem_cd_has_medium                 (const char *device);

Returns whether the disc has a physical medium.

`device` : | a device node path
Returns : | `TRUE` if the disc physically exists