.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Device::Cdio::Device 3pm" .TH Device::Cdio::Device 3pm "2018-11-01" "perl v5.28.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Device::Cdio::Device \- Class for disc and device aspects of Cdio. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& 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(); .Ve .SH "METHODS" .IX Header "METHODS" .SS "new" .IX Subsection "new" .Vb 1 \& new(source, driver_id, access_mode)\->$device_object .Ve .PP Create a new Device object. Either parameter \f(CW\*(C`source\*(C'\fR, \f(CW\*(C`driver_id\*(C'\fR or \f(CW\*(C`access_mode\*(C'\fR can be \f(CW\*(C`undef\*(C'\fR. In fact it is probably best to not to give an \f(CW\*(C`access_mode\*(C'\fR unless you know what you are doing. .SS "audio_pause" .IX Subsection "audio_pause" .Vb 1 \& audio_pause()\-> $status .Ve .PP Pause playing \s-1CD\s0 through analog output. The device status is returned. .SS "audio_play_lsn" .IX Subsection "audio_play_lsn" .Vb 1 \& audio_play_lsn(start_lsn, end_lsn)\-> $status .Ve .PP Playing \s-1CD\s0 through analog output at the given lsn to the ending lsn The device status is returned. .SS "audio_resume" .IX Subsection "audio_resume" .Vb 1 \& audio_resume()\-> $status .Ve .PP Resume playing an audio \s-1CD\s0 through the analog interface. The device status is returned. .SS "audio_stop" .IX Subsection "audio_stop" .Vb 1 \& audio_stop()\-> $status .Ve .PP Stop playing an audio \s-1CD\s0 through the analog interface. The device status is returned. .SS "close" .IX Subsection "close" .Vb 1 \& close()\->bool .Ve .PP Free resources associated with cdio. Call this when done using using \&\s-1CD\s0 reading/control operations for the current device. .SS "eject_media" .IX Subsection "eject_media" .Vb 1 \& eject_media()\->drc .Ve .PP Eject media in \s-1CD\s0 drive if there is a routine to do so. status is returned. .SS "get_arg" .IX Subsection "get_arg" .Vb 1 \& get_arg(key)\->string .Ve .SS "get_device" .IX Subsection "get_device" .Vb 1 \& get_device()\->str .Ve .PP Get the default \s-1CD\s0 device. .PP If the \s-1CD\s0 object has an opened \s-1CD,\s0 return the name of the device used. (In fact this is the same thing as issuing \f(CW\*(C`d\->get_arg("source")\*(C'\fR). .PP If we haven't initialized a specific device driver, then find a suitable one and return the default device for that. .PP In some situations of drivers or \s-1OS\s0's we can't find a \s-1CD\s0 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. .SS "get_disc_last_lsn" .IX Subsection "get_disc_last_lsn" .Vb 1 \& get_disc_last_lsn(self)\->int .Ve .PP Get the \s-1LSN\s0 of the end of the \s-1CD.\s0 \f(CW$perlcdio::INVALID_LSN\fR is returned if there was an error. .SS "get_disc_mode" .IX Subsection "get_disc_mode" .Vb 1 \& get_disc_mode() \-> str .Ve .PP Get disc mode \- the kind of \s-1CD:\s0 CD-DA, CD-ROM mode 1, CD-MIXED, etc. that we've got. The notion of '\s-1CD\s0' is extended a little to include \&\s-1DVD\s0's. .SS "get_drive_cap" .IX Subsection "get_drive_cap" .Vb 1 \& get_drive_cap()\->(read_cap, write_cap, misc_cap) .Ve .PP Get drive capabilities of device. .PP In some situations of drivers or \s-1OS\s0's we can't find a \s-1CD\s0 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. .SS "get_drive_cap_dev" .IX Subsection "get_drive_cap_dev" .Vb 1 \& get_drive_cap_dev(device=undef)\->(read_cap, write_cap, misc_cap) .Ve .PP Get drive capabilities of device. .PP In some situations of drivers or \s-1OS\s0's we can't find a \s-1CD\s0 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. .SS "get_driver_name" .IX Subsection "get_driver_name" .Vb 1 \& get_driver_name()\-> string .Ve .PP return a string containing the name of the driver in use. \&\f(CW\*(C`undef\*(C'\fR is returned if there's an error. .SS "get_driver_id" .IX Subsection "get_driver_id" .Vb 1 \& get_driver_id()\-> int .Ve .SS "get_first_track" .IX Subsection "get_first_track" .Vb 1 \& get_first_track()\->Track .Ve .PP return a Track object of the first track. \f(CW$perlcdio::INVALID_TRACK\fR or \f(CW$perlcdio::BAD_PARAMETER\fR is returned if there was a problem. .PP Return the driver id of the driver in use. if object has not been initialized or is None, return \f(CW$perlcdio::DRIVER_UNKNOWN\fR. .SS "get_hwinfo" .IX Subsection "get_hwinfo" .Vb 1 \& get_hwinfo()\->(vendor, model, release, drc) .Ve .PP Get the CD-ROM hardware info via a \s-1SCSI MMC INQUIRY\s0 command. An exception is raised if we had an error. .SS "audio_get_volume" .IX Subsection "audio_get_volume" .Vb 1 \& my($arr, $rc) = $dev\->audio_get_volume; .Ve .PP Returns the volume settings of device's 4 channels and the device return code. In scalar environmet only the device return code! See \f(CW\*(C`perlcdio::driver_errmsg($rc)\*(C'\fR for return-values meanings when \f(CW\*(C`$rc != 0\*(C'\fR. .SS "audio_play_track_index" .IX Subsection "audio_play_track_index" .Vb 1 \& $drc = $dev\->audio_play_track_index($start_track, $start_index, $end_track, $end_track); .Ve .PP Playing \s-1CD\s0 through analog output at the desired start track and index, to the end track and index. Tracks should be in the valid \s-1CD\s0 track range 0..99. .PP Just as a track number is burned into the \s-1CD,\s0 so is a an index for a track. .PP See \f(CW\*(C`perlcdio::driver_errmsg($drc)\*(C'\fR for return-values meanings when \f(CW\*(C`$drc != 0\*(C'\fR. .SS "audio_set_volume" .IX Subsection "audio_set_volume" .Vb 2 \& $drc = $dev\->audio_set_volume($channel1_volume, $channel2_volume, \& $channel3_volume, $channel4_volume); .Ve .PP Set the volume levels of the channels 1\-4. Values from 0\-255 are possible. Stereo \s-1CDROM\s0 devices (which is most of them) use only channels 1 and 2. .PP Use \-1 when the existing value should be kept. See \f(CW\*(C`perlcdio::driver_errmsg($drc)\*(C'\fR for return-values meanings when \f(CW\*(C`$drc != 0\*(C'\fR. .SS "get_disk_cdtext, get_track_cdtext" .IX Subsection "get_disk_cdtext, get_track_cdtext" .Vb 4 \& $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); .Ve .PP Returns a hash reference hash\->{cdtext_field}=\*(L"text\*(R" if found any cdtext on disk; .SS "get_disk_cdtext_field_for_track" .IX Subsection "get_disk_cdtext_field_for_track" .Vb 1 \& $str = $dev\->get_cdtext_field_for_track($field, $track=0, $cdtext=$self\->{cdtext}); .Ve .PP Returns the text associated with field \f(CW$field\fR of track \f(CW$track\fR of \f(CW$cdtext\fR if there is any. .SS "cdtext_destroy" .IX Subsection "cdtext_destroy" \&\f(CW$dev\fR\->\fBcdtext_destroy()\fR .PP Removes CD-TEXT memor resources associated a disc and sets \&\f(CW$dev\fR\->{cdtext} to undef. .PP Use this when you are done accessing with CD-TEXT information. .PP Note: \f(CW$def\fR\->\fBclose()\fR runs this as part of its operation. .SS "get_cddb_discid" .IX Subsection "get_cddb_discid" .Vb 1 \& $discid = $dev\->get_cddb_discid; .Ve .PP Returns the calculated cddb discid integer. Usually used as hexstring! .SS "audio_get_status" .IX Subsection "audio_get_status" .Vb 1 \& my($hash, $drc) = $dev\->audio_get_status; .Ve .PP Returns a hash reference with the audio-subchannel-mmc status values: .PP .Vb 12 \& 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 .Ve .SS "is_tray_open" .IX Subsection "is_tray_open" .Vb 1 \& $dev\->is_tray_open .Ve .PP returns true if tray seems open, 0 otherwise. .SS "get_joliet_level" .IX Subsection "get_joliet_level" .Vb 1 \& get_joliet_level()\->int .Ve .PP Return the Joliet level recognized for cdio. This only makes sense for something that has an \s-1ISO\-9660\s0 filesystem. .SS "get_last_session" .IX Subsection "get_last_session" .Vb 1 \& get_last_session(self) \-> (track_lsn, drc) .Ve .PP Get the \s-1LSN\s0 of the first track of the last session of on the \s-1CD.\s0 .SS "get_last_track" .IX Subsection "get_last_track" .Vb 1 \& get_last_track()\->Track .Ve .PP return a Track object of the last track. \f(CW$perlcdio::INVALID_TRACK\fR or \f(CW$perlcdio::BAD_PARAMETER\fR is returned if there was a problem. .SS "get_mcn" .IX Subsection "get_mcn" \&\fBget_mcn()\fR\->str .PP Get the media catalog number (\s-1MCN\s0) from the \s-1CD.\s0 .SS "get_media_changed" .IX Subsection "get_media_changed" .Vb 1 \& get_media_changed() \-> int .Ve .PP 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. .SS "guess_cd_type" .IX Subsection "guess_cd_type" \&\f(CW$hash\fR = \f(CW$dev\fR\->guess_cd_type($lsn,$track); .PP Try to determine what kind of CD-image and/or filesystem we have at track \f(CW$track\fR. First argument is the start lsn of track \f(CW$track\fR. Returns a hash reference with following keys: .PP .Vb 8 \& 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. .Ve .SS "get_num_tracks" .IX Subsection "get_num_tracks" .Vb 1 \& get_num_tracks()\->int .Ve .PP Return the number of tracks on the \s-1CD.\s0 \&\f(CW$perlcdio::INVALID_TRACK\fR is raised on error. .SS "get_track" .IX Subsection "get_track" .Vb 1 \& get_track(track_num)\->track .Ve .PP Set a new track object of the current disc for the given track number. .SS "get_track_for_lsn" .IX Subsection "get_track_for_lsn" .Vb 1 \& get_track_for_lsn(LSN)\->Track .Ve .PP Find the track which contains \s-1LSN.\s0 undef is returned if the lsn outside of the \s-1CD\s0 or if there was some error. .PP If the \s-1LSN\s0 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. .SS "have_ATAPI" .IX Subsection "have_ATAPI" .Vb 1 \& have_ATAPI()\->bool .Ve .PP return 1 if CD-ROM understand \s-1ATAPI\s0 commands. .SS "lseek" .IX Subsection "lseek" .Vb 1 \& lseek(offset, whence)\->int .Ve .PP Reposition read offset. Similar to (if not the same as) libc's \fBfseek()\fR .PP offset is the amount to seek and whence is like corresponding parameter in libc's lseek, e.g. it should be \s-1SEEK_SET\s0 or \s-1SEEK_END.\s0 .PP the offset is returned or \-1 on error. .SS "open" .IX Subsection "open" .Vb 2 \& open(source=undef, driver_id=$libcdio::DRIVER_UNKNOWN, \& access_mode=undef)\->$cdio_obj .Ve .PP 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. .PP If \f(CW\*(C`undef\*(C'\fR is given as the source, we'll use the default driver device. If \f(CW\*(C`undef\*(C'\fR is given as the driver_id, we'll find a suitable device driver. Device is opened so that subsequent operations can be performed. .SS "read" .IX Subsection "read" .Vb 1 \& read(size)\->(size, data) .Ve .PP Reads the next size bytes. Similar to (if not the same as) libc's \fBread()\fR .PP The number of bytes read and the data is returned. .SS "read_data_blocks" .IX Subsection "read_data_blocks" .Vb 1 \& read_data_blocks(lsn, blocks=1)\->($data, $size, $drc) .Ve .PP Reads a number of data sectors (\s-1AKA\s0 blocks). .PP lsn is sector to read, blocks is the number of bytes. .PP The size of the data will be a multiple of \f(CW$perlcdio::ISO_BLOCKSIZE\fR. .PP 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. \f(CW\*(C`undef\*(C'\fR is returned as the data on error. .SS "read_sectors" .IX Subsection "read_sectors" .Vb 2 \& read_sectors($lsn, $read_mode, $blocks=1)\->($data, $size, $drc) \& read_sectors($lsn, $read_mode, $blocks=1)\->$data .Ve .PP Reads a number of sectors (\s-1AKA\s0 blocks). .PP lsn is sector to read, bytes is the number of bytes. .PP If read_mode is \f(CW$perlcdio::MODE_AUDIO\fR, the return data size will be a multiple of \f(CW$perlcdio::CDIO_FRAMESIZE_RAW\fR i_blocks bytes. .PP If read_mode is \f(CW$perlcdio::MODE_DATA\fR, data will be a multiple of \&\f(CW$perlcdio::ISO_BLOCKSIZE\fR, \f(CW$perlcdio::M1RAW_SECTOR_SIZE\fR or \&\f(CW$perlcdio::M2F2_SECTOR_SIZE\fR bytes depending on what mode the data is in. .PP If read_mode is \f(CW$perlcdio::MODE_M2F1\fR, data will be a multiple of \&\f(CW$perlcdio::M2RAW_SECTOR_SIZE\fR bytes. .PP If read_mode is \f(CW$perlcdio::MODE_M2F2\fR, the return data size will be a multiple of \f(CW$perlcdio::CD_FRAMESIZE\fR bytes. .PP 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. .SS "set_blocksize" .IX Subsection "set_blocksize" .Vb 1 \& set_blocksize(blocksize) \-> $status .Ve .PP Set the blocksize for subsequent reads. The operation status code is returned. .SS "set_speed" .IX Subsection "set_speed" .Vb 1 \& set_speed(speed)\->drc .Ve .PP The operation status code is returned. .SS "read_pvd" .IX Subsection "read_pvd" \&\f(CW$pvd\fR = \f(CW$dev\fR\->read_pvd; .PP Reads and returns the \s-1ISO\-9660\s0 Primary Volume Descriptor (\s-1PVD\s0) from the disk. You can use perliso9660::get_pvd_type($pvd) ... methods to get the values. .SH "SEE ALSO" .IX Header "SEE ALSO" Device::Cdio for the top-level module, Device::Cdio::Track for track objects, and Device::Cdio::ISO9660 for working with \s-1ISO9660\s0 filesystems. .PP perlcdio is the lower-level interface to libcdio. .PP has documentation on libcdio including the a manual and the \s-1API\s0 via doxygen. .SH "AUTHORS" .IX Header "AUTHORS" Rocky Bernstein .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2006, 2008, 2017 Rocky Bernstein .PP This program is free software: you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. .PP This program is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See the \&\s-1GNU\s0 General Public License for more details. .PP You should have received a copy of the \s-1GNU\s0 General Public License along with this program. If not, see The \s-1GNU\s0 General Public License .