NAME¶
Device::Cdio - Module for CD Input and Control library.
SYNOPSIS¶
This encapsulates CD-ROM reading and control. Applications wishing to be
oblivious of the OS- and device-dependent properties of a CD-ROM can use this
library.
use Device::Cdio;
use Device::Cdio::Device;
$cd_drives = Device::Cdio::get_devices($perlcdio::DRIVER_DEVICE);
$cd_drives = Device::Cdio::get_devices_with_cap($perlcdio::FS_AUDIO, 0);
foreach my $drive (@$cd_drives) {
print "Drive $drive\n";
}
foreach my $driver_name (sort keys(%Device::Cdio::drivers)) {
print "Driver $driver_name is installed.\n"
if Device::Cdio::have_driver($driver_name) and
$driver_name !~ m{device|Unknown};
}
DESCRIPTION¶
This is an Perl Object-Oriented interface to the GNU CD Input and Control
library, "libcdio", written in C. The library encapsulates CD-ROM
reading and control. Perl programs wishing to be oblivious of the OS- and
device-dependent properties of a CD-ROM can use this library.
The encapsulation is done in two parts. The lower-level Perl interface is called
perlcdio and is generated by SWIG.
This module uses "perlcdio". Actually, there are no objects in module,
but there are in its sub modules Device::Cdio::Device and Device::Cdio::Track.
Although "perlcdio" is perfectly usable on its own, it is expected
that Cdio is what most people will use. As "perlcdio" more closely
models the C interface "libcdio", it is conceivable (if unlikely)
that die-hard libcdio C users who are very familiar with that interface could
prefer that.
CALLING ROUTINES¶
Routines accept named parameters as well as positional parameters. For named
parameters, each argument name is preceded by a dash. For example:
Device::Cdio::have_driver(-driver_id=>'GNU/Linux')
Each argument name is preceded by a dash. Neither case nor order matters in the
argument list. "-driver_id", "-Driver_ID", and
"-DRIVER_ID" are all acceptable. In fact, only the first argument
needs to begin with a dash. If a dash is present in the first argument, we
assume dashes for the subsequent parameters.
In the documentation below and elsewhere in this package the parameter name that
can be used in this style of call is given in the parameter list. For example,
for "close_tray" the documentation below reads:
close_tray(drive=undef, driver_id=$perlcdio::DRIVER_UNKNOWN)
-> ($drc, $driver_id)
So the parameter names are "drive", and "driver_id". Neither
parameter is required. If "drive" is not specified, a value of
"undef" will be used. And if "driver_id" is not specified,
a value of $perlcdio::DRIVER_UNKNOWN is used.
The older, more traditional style of positional parameters is also supported. So
the "have_driver" example from above can also be written:
Device::Cdio::have_driver('GNU/Linux')
Finally, since no parameter name can be confused with a an integer, negative
values will not get confused as a named parameter.
SUBROUTINES¶
close_tray¶
close_tray(drive=undef, driver_id=$perlcdio::DRIVER_UNKNOWN)
-> ($drc, $driver_id)
close media tray in CD drive if there is a routine to do so.
In an array context, the driver return-code status and the name of the driver
used are returned. In a scalar context, just the return code status is
returned.
driver_strerror¶
driver_strerror(rc)->$errmsg
Convert a driver return code into a string text message.
get_default_device_driver¶
get_default_device_driver(driver_id=DRIVER_DEVICE)-> ($device, $driver)
Return a string containing the default CD device if none is specified. if
driver_id is DRIVER_UNKNOWN or DRIVER_DEVICE then find a suitable one set the
default device for that.
undef is returned as the driver if we couldn't get a default device.
get_devices¶
$revices = get_devices(driver_id=$Cdio::DRIVER_UNKNOWN);
Return an array of device names. If you want a specific devices for a driver,
give that device. If you want hardware devices, give $perlcdio::DRIVER_DEVICE
and if you want all possible devices, image drivers and hardware drivers give
$perlcdio::DRIVER_UNKNOWN. undef is returned if we couldn't return a list of
devices.
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_devices_ret¶
get_devices_ret($driver_id)->(@devices, $driver_id)
Like get_devices, but we may change the p_driver_id if we were given
$perlcdio::DRIVER_DEVICE or $perlcdio::DRIVER_UNKNOWN. This is because often
one wants to get a drive name and then
open it afterwords. Giving the
driver back facilitates this, and speeds things up for libcdio as well.
get_devices_with_cap¶
$devices = get_devices_with_cap($capabilities, $any);
Get an array of device names in search_devices that have at least the
capabilities listed by the capabilities parameter.
If "any" is set false then ALL capabilities listed in the extended
portion of capabilities (i.e. not the basic filesystem) must be satisified. If
"any" is set true, then if any of the capabilities matches, we call
that a success.
To find a CD-drive of any type, use the mask $perlcdio::FS_MATCH_ALL.
The array of device names is returned or undef if we couldn't get a default
device. It is also possible to return a () but after This means nothing was
found.
get_devices_with_cap_ret¶
Like get_devices_with_cap but we return the driver we found as well. This is
because often one wants to search for kind of drive and then *open* it
afterward. Giving the driver back facilitates this, and speeds things up for
libcdio as well.
have_driver¶
have_driver(driver_id) -> bool
Return 1 if we have driver driver_id. undef is returned if driver_id is invalid.
driver_id can either be an integer driver name defined in perlcdio or a string
as defined in the hash %drivers.
is_binfile¶
is_binfile(binfile)->cue_name
Determine if binfile is the BIN file part of a CDRWIN Compact Disc image.
Return the corresponding CUE file if bin_name is a BIN file or undef if not a
BIN file.
is_cuefile¶
is_cuefile(cuefile)->bin_name
Determine if cuefile is the CUE file part of a CDRWIN Compact Disc image.
Return the corresponding BIN file if cue_name is a CUE file or undef if not a
CUE file.
is_device¶
is_device(source, driver_id=$perlcdio::DRIVER_UNKNOWN)->bool
Return True if source refers to a real hardware CD-ROM.
is_nrg¶
is_nrg(nrgfile)->bool
Determine if nrgfile is a Nero NRG file disc image.
is_tocfile¶
is_tocfile(tocfile_name)->bool
Determine if tocfile_name is a cdrdao CD disc image.
convert_drive_cap_misc¶
convert_drive_cap_misc(bitmask)->hash_ref
Convert bit mask for miscellaneous drive properties into a hash reference of
drive capabilities
convert_drive_cap_read¶
convert_drive_cap_read($bitmask)->hash_ref
Convert bit mask for read drive properties into a hash reference of drive
capabilities
convert_drive_cap_write¶
convert_drive_cap_write($bitmask)->hash_ref
SEE ALSO¶
Device::Cdio::Device for device objects and Device::Cdio::Track for track
objects and Device::Cdio::ISO9660 for working with ISO 9660 filesystems.
perlcdio is the lower-level interface to libcdio.
<
http://www.gnu.org/software/libcdio/doxygen/files.html> is documentation
via doxygen for "libcdio".
AUTHORS¶
Rocky Bernstein "<rocky at cpan.org>".
COPYRIGHT¶
Copyright (C) 2006, 2011 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 <
http://www.gnu.org/licenses/>.