Provided by: libdevice-cdio-perl_2.0.0-2build1_amd64 bug

NAME

       Device::Cdio::Device - Class for disc and device aspects of Cdio.

SYNOPSIS

           use Device::Cdio::Device;
           $d = Device::Cdio::Device->new(-driver_id=>$perlcdio::DRIVER_DEVICE);
           $drive_name = $d->get_device();
           ($i_read_cap, $i_write_cap, $i_misc_cap) =  $d->get_drive_cap();

           $start_lsn = $d->get_first_track()->get_lsn();
           $end_lsn=$d->get_disc_last_lsn();
           $drc = $d->audio_play_lsn($start_lsn, $end_lsn);
           ($vendor, $model, $release, $drc) = $d->get_hwinfo();

METHODS

   new
         new(source, driver_id, access_mode)->$device_object

       Create a new Device object. Either parameter "source", "driver_id" or "access_mode" can be
       "undef". In fact it is probably best to not to give an "access_mode" unless you know what
       you are doing.

   audio_pause
         audio_pause()-> $status

       Pause playing CD through analog output.  The device status is returned.

   audio_play_lsn
         audio_play_lsn(start_lsn, end_lsn)-> $status

       Playing CD through analog output at the given lsn to the ending lsn The device status is
       returned.

   audio_resume
         audio_resume()-> $status

       Resume playing an audio CD through the analog interface.  The device status is returned.

   audio_stop
         audio_stop()-> $status

       Stop playing an audio CD through the analog interface.  The device status is returned.

   close
         close()->bool

       Free resources associated with cdio.  Call this when done using using CD reading/control
       operations for the current device.

   eject_media
         eject_media()->drc

       Eject media in CD drive if there is a routine to do so.  status is returned.

   get_arg
         get_arg(key)->string

   get_device
         get_device()->str

       Get the default CD device.

       If the CD object has an opened CD, return the name of the device used.  (In fact this is
       the same thing as issuing "d->get_arg("source")").

       If we haven't initialized a specific device driver, then find a suitable one and return
       the default device for that.

       In some situations of drivers or OS's we can't find a CD device if there is no media in it
       and it is possible for this routine to return undef even though there may be a hardware
       CD-ROM.

   get_disc_last_lsn
         get_disc_last_lsn(self)->int

       Get the LSN of the end of the CD. $perlcdio::INVALID_LSN is returned if there was an
       error.

   get_disc_mode
         get_disc_mode() -> str

       Get disc mode - the kind of CD: CD-DA, CD-ROM mode 1, CD-MIXED, etc.  that we've got. The
       notion of 'CD' is extended a little to include DVD's.

   get_drive_cap
         get_drive_cap()->(read_cap, write_cap, misc_cap)

       Get drive capabilities of device.

       In some situations of drivers or OS's we can't find a CD device if there is no media in
       it. In this situation capabilities will show up as empty even though there is a hardware
       CD-ROM.

   get_drive_cap_dev
         get_drive_cap_dev(device=undef)->(read_cap, write_cap, misc_cap)

       Get drive capabilities of device.

       In some situations of drivers or OS's we can't find a CD device if there is no media in
       it. In this situation capabilities will show up as empty even though there is a hardware
       CD-ROM.

   get_driver_name
         get_driver_name()-> string

       return a string containing the name of the driver in use.  "undef" is returned if there's
       an error.

   get_driver_id
         get_driver_id()-> int

   get_first_track
         get_first_track()->Track

       return a Track object of the first track. $perlcdio::INVALID_TRACK or
       $perlcdio::BAD_PARAMETER is returned if there was a problem.

       Return the driver id of the driver in use.  if object has not been initialized or is None,
       return $perlcdio::DRIVER_UNKNOWN.

   get_hwinfo
         get_hwinfo()->(vendor, model, release, drc)

       Get the CD-ROM hardware info via a SCSI MMC INQUIRY command.  An exception is raised if we
       had an error.

   audio_get_volume
           my($arr, $rc) = $dev->audio_get_volume;

       Returns the volume settings of device's 4 channels and the device return code.  In scalar
       environmet only the device return code!  See "perlcdio::driver_errmsg($rc)" for return-
       values meanings when "$rc != 0".

   audio_play_track_index
           $drc = $dev->audio_play_track_index($start_track, $start_index, $end_track, $end_track);

       Playing CD through analog output at the desired start track and index, to the end track
       and index. Tracks should be in the valid CD track range 0..99.

       Just as a track number is burned into the CD, so is a an index for a track.

       See "perlcdio::driver_errmsg($drc)" for return-values meanings when "$drc != 0".

   audio_set_volume
           $drc = $dev->audio_set_volume($channel1_volume, $channel2_volume,
                                         $channel3_volume, $channel4_volume);

       Set the volume levels of the channels 1-4. Values from 0-255 are possible.  Stereo CDROM
       devices (which is most of them) use only channels 1 and 2.

       Use -1 when the existing value should be kept.  See "perlcdio::driver_errmsg($drc)" for
       return-values meanings when "$drc != 0".

   get_disk_cdtext, get_track_cdtext
           $hash = $dev->get_disk_cdtext;
           $hash = $dev->get_cdtext_for_track(track, field);
           $hash = $dev->get_cdtext_field_for_track(track, field);
           $hash = $dev->get_cdtext_field_for_track(track, field);

       Returns a hash reference hash->{cdtext_field}="text" if found any cdtext on disk;

   get_disk_cdtext_field_for_track
           $str = $dev->get_cdtext_field_for_track($field, $track=0, $cdtext=$self->{cdtext});

       Returns the text associated with field $field of track $track of $cdtext if there is any.

   cdtext_destroy
       $dev->cdtext_destroy()

       Removes CD-TEXT memor resources associated a disc and sets $dev->{cdtext} to undef.

       Use this when you are done accessing with CD-TEXT information.

       Note: $def->close() runs this as part of its operation.

   get_cddb_discid
           $discid = $dev->get_cddb_discid;

       Returns the calculated cddb discid integer. Usually used as hexstring!

   audio_get_status
           my($hash, $drc) = $dev->audio_get_status;

       Returns a hash reference with the audio-subchannel-mmc status values:

           audio_status : value
           status_text  : audio_status as text
                       (INVALID,ERROR,NO_STATUS,UNKNOWN,playing,paused,completed)
           track : track number
           index : index in track
           msf time values as ints minutes, seconds,frames :
               abs_m,abs_s,abs_f  : total disc time played
               rel_m,rel_s,el_f   : track time played
           disk_s  : seconds disk played
           track_s : seconds track played
           address
           control

   is_tray_open
           $dev->is_tray_open

       returns true if tray seems open, 0 otherwise.

   get_joliet_level
         get_joliet_level()->int

       Return the Joliet level recognized for cdio.  This only makes sense for something that has
       an ISO-9660 filesystem.

   get_last_session
         get_last_session(self) -> (track_lsn, drc)

       Get the LSN of the first track of the last session of on the CD.

   get_last_track
         get_last_track()->Track

       return a Track object of the last track. $perlcdio::INVALID_TRACK or
       $perlcdio::BAD_PARAMETER is returned if there was a problem.

   get_mcn
       get_mcn()->str

       Get the media catalog number (MCN) from the CD.

   get_media_changed
         get_media_changed() -> int

       Find out if media has changed since the last call.  Return 1 if media has changed since
       last call, 0 if not.  A negative number indicates the driver status error.

   guess_cd_type
       $hash = $dev->guess_cd_type($lsn,$track);

       Try to determine what kind of CD-image and/or filesystem we have at track $track. First
       argument is the start lsn of track $track. Returns a hash reference with following keys:

           cdio_fs_t     (enum cdio_fs_t from libcdio) FIXME: add text
           cdio_fs_cap_t (enum cdio_fs_cap_t from libcdio) FIXME: add text
           joliet_level  If has Joliet extensions, this is the associated level
                           number (i.e. 1, 2, or 3).
           iso_label      32 byte ISO fs label.
           isofs_size     size of ISO fs.
           UDFVerMajor    UDF fs version.
           UDFVerMinor    UDF fs version.

   get_num_tracks
         get_num_tracks()->int

       Return the number of tracks on the CD.  $perlcdio::INVALID_TRACK is raised on error.

   get_track
         get_track(track_num)->track

       Set a new track object of the current disc for the given track number.

   get_track_for_lsn
         get_track_for_lsn(LSN)->Track

       Find the track which contains LSN.  undef is returned if the lsn outside of the CD or if
       there was some error.

       If the LSN is before the pregap of the first track, A track object with a 0 track is
       returned.  Otherwise we return the track that spans the lsn.

   have_ATAPI
         have_ATAPI()->bool

       return 1 if CD-ROM understand ATAPI commands.

   lseek
         lseek(offset, whence)->int

       Reposition read offset. Similar to (if not the same as) libc's fseek()

       offset is the amount to seek and whence is like corresponding parameter in libc's lseek,
       e.g.  it should be SEEK_SET or SEEK_END.

       the offset is returned or -1 on error.

   open
         open(source=undef, driver_id=$libcdio::DRIVER_UNKNOWN,
              access_mode=undef)->$cdio_obj

       Sets up to read from place specified by source, driver_id and access mode. This should be
       called before using any other routine except those that act on a CD-ROM drive by name. It
       is implicitly called when a new is done specifying a source or driver id.

       If "undef" is given as the source, we'll use the default driver device.  If "undef" is
       given as the driver_id, we'll find a suitable device driver.  Device is opened so that
       subsequent operations can be performed.

   read
         read(size)->(size, data)

       Reads the next size bytes.  Similar to (if not the same as) libc's read()

       The number of bytes read and the data is returned.

   read_data_blocks
         read_data_blocks(lsn, blocks=1)->($data, $size, $drc)

       Reads a number of data sectors (AKA blocks).

       lsn is sector to read, blocks is the number of bytes.

       The size of the data will be a multiple of $perlcdio::ISO_BLOCKSIZE.

       The number of data, size of the data, and the return code status is returned in an array
       context. In a scalar context just the data is returned. "undef" is returned as the data on
       error.

   read_sectors
         read_sectors($lsn, $read_mode, $blocks=1)->($data, $size, $drc)
         read_sectors($lsn, $read_mode, $blocks=1)->$data

       Reads a number of sectors (AKA blocks).

       lsn is sector to read, bytes is the number of bytes.

       If read_mode is $perlcdio::MODE_AUDIO, the return data size will be a multiple of
       $perlcdio::CDIO_FRAMESIZE_RAW i_blocks bytes.

       If read_mode is $perlcdio::MODE_DATA, data will be a multiple of $perlcdio::ISO_BLOCKSIZE,
       $perlcdio::M1RAW_SECTOR_SIZE or $perlcdio::M2F2_SECTOR_SIZE bytes depending on what mode
       the data is in.

       If read_mode is $perlcdio::MODE_M2F1, data will be a multiple of
       $perlcdio::M2RAW_SECTOR_SIZE bytes.

       If read_mode is $perlcdio::MODE_M2F2, the return data size will be a multiple of
       $perlcdio::CD_FRAMESIZE bytes.

       The number of data, size of the data, and the return code status is returned in an array
       context. In a scalar context just the data is returned. undef is returned as the data on
       error.

   set_blocksize
         set_blocksize(blocksize) -> $status

       Set the blocksize for subsequent reads.  The operation status code is returned.

   set_speed
         set_speed(speed)->drc

       The operation status code is returned.

   read_pvd
       $pvd = $dev->read_pvd;

       Reads and returns the ISO-9660 Primary Volume Descriptor (PVD) from the disk.  You can use
       perliso9660::get_pvd_type($pvd) ... methods to get the values.

SEE ALSO

       Device::Cdio for the top-level module, Device::Cdio::Track for track objects, and
       Device::Cdio::ISO9660 for working with ISO9660 filesystems.

       perlcdio is the lower-level interface to libcdio.

       <http://www.gnu.org/software/libcdio> has documentation on libcdio including the a manual
       and the API via doxygen.

AUTHORS

       Rocky Bernstein

COPYRIGHT

       Copyright (C) 2006, 2008, 2017 Rocky Bernstein <rocky@cpan.org>

       This program is free software: you can redistribute it and/or modify it under the terms of
       the GNU General Public License as published by the Free Software Foundation, either
       version 3 of the License, or (at your option) any later version.

       This program 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 General Public License for more details.

       You should have received a copy of the GNU General Public License along with this program.
       If not, see The GNU General Public License <http://www.gnu.org/licenses/#GPL>.