| Copyright | (c) 2018-2021 Sam May |
|---|---|
| License | GPL-3.0-or-later |
| Maintainer | ag@eitilt.life |
| Stability | stable |
| Portability | non-portable (requires libcdio) |
| Safe Haskell | None |
| Language | Haskell2010 |
Foreign.Libcdio.Device
Description
The entire library architecture revolves around the concept of a device—not the
disc, but the drive containing it. A function to read a segment of data is not
just a lookup from memory, but an instruction to the device to move the read
arm into position and begin interpreting the pits and ridges. With that
understanding, it makes sense that this module provides not just the means to
determine what any particular drive is capable of, but also the only means to
obtain the Cdio object the everything else revolves around.
device.h
Types
cdio_drive_cap_misc_t->DriveCapabilityMisc
cdio_drive_cap_read_t->DriveCapabilityReadCDIO_DRIVE_CAP_READ_AUDIO->ReadAnalogAudioCDIO_DRIVE_CAP_READ_CD_DA->ReadDigitalAudioCDIO_DRIVE_CAP_READ_CD_R->ReadCdRecordableCDIO_DRIVE_CAP_READ_CD_RW->ReadCdReWritableCDIO_DRIVE_CAP_READ_DVD_R->ReadDvdRecordableCDIO_DRIVE_CAP_READ_DVD_PR->ReadDvdPlusRecordableCDIO_DRIVE_CAP_READ_DVD_RW->ReadDvdReWritableCDIO_DRIVE_CAP_READ_DVD_PRW->ReadDvdPlusReWritableCDIO_DRIVE_CAP_READ_C2_ERRS->ReadC2ErrorCorrection
cdio_drive_cap_write_t->DriveCapabilityWriteNote that some values are not included in the Haskell type, as the indexing implementation is stricter than the equivalent bit operations in C.
CDIO_DRIVE_CAP_WRITE_CD_R->WriteCdRecordableCDIO_DRIVE_CAP_WRITE_CD_RW->WriteCdReWritableCDIO_DRIVE_CAP_WRITE_DVD_R->WriteDvdRecordableCDIO_DRIVE_CAP_WRITE_DVD_PR->WriteDvdPlusRecordableCDIO_DRIVE_CAP_WRITE_DVD_RW->WriteDvdReWritableCDIO_DRIVE_CAP_WRITE_DVD_PRW->WriteDvdPlusReWritableCDIO_DRIVE_CAP_WRITE_CD->capsWriteCdCDIO_DRIVE_CAP_WRITE_DVD->capsWriteDvdCDIO_DRIVE_CAP_WRITE->capsWrite
cdio_drive_misc_cap_t->DriveMiscCapscdio_drive_read_cap_t->DriveReadCapscdio_drive_write_cap_t->DriveWriteCapscdio_hwinfo_t->HardwareInfocdio_mmc_hw_len_t(type removed; values are structural constants rather than an actual enum)CDIO_MMC_HW_VENDOR_LEN->vendorLengthCDIO_MMC_HW_MODEL_LEN->modelLengthCDIO_MMC_HW_REVISION_LEN->revisionLength
cdio_src_category_mask_t(removed; never used in the public interface)driver_id_t->DriverIddriver_return_code_t->DriverReturnCode
Symbols
cdio_close_tray->closeTraycdio_destroy(removed; handled via garbage collector)cdio_device_drivers->deviceDriverscdio_driver_describe->driverDescribecdio_driver_errmsg->driverErrmsgcdio_drivers->driverscdio_eject_media->ejectMediacdio_eject_media_drive->ejectDrivecdio_free_device_list(removed; handled via garbage collector)cdio_get_arg->getArgandgetAccessModecdio_get_default_device->defaultDevice(CdIo_t*argument dropped as no non-redundant path to get one exists)cdio_get_default_device_*(removed;defaultDeviceDriverprovides the same functionality)cdio_get_devices->devicescdio_get_devices_*(removed;devicesprovides the same functionality)cdio_get_devices_with_cap->devicesWithFilesystemcdio_get_devices_with_cap_ret->devicesWithFilesystemRetcdio_get_drive_cap->driveCapcdio_get_drive_cap_dev->driveCapDevicecdio_get_driver_id->driverIdcdio_get_driver_name->driverNamecdio_get_hwinfo->hwinfocdio_get_last_session->lastSessioncdio_get_media_changed->isMediaChangedcdio_have_atapi->haveAtapicdio_have_driver->haveDrivercdio_init(removed; internal function without much external occasion for use)cdio_is_binfile->cueFromBincdio_is_cuefile->binFromCuecdio_is_device->isDevicecdio_is_nrg->isNrgcdio_is_tocfile->isToccdio_open->cdioOpencdio_open_*(removed;cdioOpenprovides the same functionality)cdio_open_am->cdioOpenAmcdio_open_am_*(removed;cdioOpenAmprovides the same functionality)cdio_os_driver->osDrivercdio_set_arg(removed; primarily intended for internal use, and is more limited than would be expected)cdio_set_blocksize->setBlocksizecdio_set_speed->setSpeed
Sound.Libcdio.Device
Cdio->Sound.Libcdio.(note, however, that the latter is a more abstractedCdioMonad)binFromCue->isCuecdioOpen->Sound.Libcdio.andopenopenDefaultcdioOpenAm->Sound.Libcdio.andopenModeopenModeDefaultcdioOpen*(removed;Sound.Libcdio.handles the auto-detection)opencloseTray->closeDeviceTrayandcloseDeviceTray'cueFromBin(removed; this andbinFromCuejust replace the file extension after validation, they don't go searching)defaultDevice*(removed; driver type isn't a public part of device opening)deviceDrivers->notisImageDriverdevicesRet(removed;Sound.Libcdio.doesn't require a specificopenDriverIdto be passed)devicesWithFilesystem(removed; can't think of a use case for searching for discs of a specific data layout)devicesWithFilesystemRet(removed; can't think of a use case for searching for discs of a specific data layout)devices*(removed;devicesdelegates via theDriverIdparameter)driveCap->capabilitiesdriveCapDevice->deviceCapabilitiesdriverId->driverejectDrive->ejectDeviceejectMedia(removed; argument to e.g.Sound.Libcdio.)opengetArg->Sound.Libcdio.getArggetAccessMode->Sound.Libcdio.getAccessModehaveDriver(removed; use`)elem`drivershwinfo->hardwarelastSession->Sound.Libcdio.Read.Data.lastSessionOffsetmodelLength(removed; unnecessary low-level detail)revisionLength(removed; unnecessary low-level detail)vendorLength(removed; unnecessary low-level detail)
Synopsis
- data Cdio
- data HardwareInfo = HardwareInfo {}
- vendorLength :: Word
- modelLength :: Word
- revisionLength :: Word
- emptyHardwareInfo :: HardwareInfo
- data DriverId
- data DriverReturnCode
- data SessionArg
- = Source
- | Cue
- | ScsiTuple
- | MmcSupported
- data AccessMode
- data DriveCapabilityRead
- type DriveReadCaps = BitArray DriveCapabilityRead
- data DriveCapabilityWrite
- type DriveWriteCaps = BitArray DriveCapabilityWrite
- capsWriteCd :: DriveWriteCaps
- capsWriteDvd :: DriveWriteCaps
- capsWrite :: DriveWriteCaps
- data DriveCapabilityMisc
- type DriveMiscCaps = BitArray DriveCapabilityMisc
- type DriveCaps = (DriveReadCaps, DriveWriteCaps, DriveMiscCaps)
- drivers :: [DriverId]
- deviceDrivers :: [DriverId]
- osDriver :: DriverId
- driverName :: Cdio -> IO (Maybe String)
- driverId :: Cdio -> IO (Maybe DriverId)
- driverDescribe :: DriverId -> String
- driverErrmsg :: DriverReturnCode -> String
- haveDriver :: DriverId -> Bool
- devices :: DriverId -> IO [FilePath]
- devicesRet :: DriverId -> IO ([FilePath], DriverId)
- devicesWithFilesystem :: [FilePath] -> Maybe Filesystem -> FilesystemClasses -> Bool -> IO [FilePath]
- devicesWithFilesystemRet :: [FilePath] -> Maybe Filesystem -> FilesystemClasses -> Bool -> IO ([FilePath], DriverId)
- defaultDevice :: IO (Maybe FilePath)
- defaultDeviceDriver :: DriverId -> IO (Maybe FilePath, DriverId)
- hwinfo :: Cdio -> IO (Maybe HardwareInfo)
- driveCap :: Cdio -> IO DriveCaps
- driveCapDevice :: FilePath -> IO DriveCaps
- haveAtapi :: Cdio -> IO (Maybe Bool)
- ejectMedia :: Cdio -> IO DriverReturnCode
- ejectDrive :: Maybe FilePath -> IO DriverReturnCode
- closeTray :: Maybe FilePath -> DriverId -> IO (DriverReturnCode, DriverId)
- getArg :: Cdio -> SessionArg -> IO (Maybe String)
- getAccessMode :: Cdio -> IO (Maybe AccessMode)
- isMediaChanged :: Cdio -> IO (Either DriverReturnCode Bool)
- setBlocksize :: Cdio -> Int -> IO DriverReturnCode
- setSpeed :: Cdio -> Int -> IO DriverReturnCode
- lastSession :: Cdio -> IO (Either DriverReturnCode Lsn)
- cdioOpen :: Maybe FilePath -> DriverId -> IO (Maybe Cdio)
- cdioOpenAm :: Maybe FilePath -> DriverId -> AccessMode -> IO (Maybe Cdio)
- isDevice :: FilePath -> DriverId -> IO Bool
- cdioOpenCd :: Maybe FilePath -> IO (Maybe Cdio)
- cdioOpenAmCd :: Maybe FilePath -> AccessMode -> IO (Maybe Cdio)
- cueFromBin :: FilePath -> IO (Maybe FilePath)
- binFromCue :: FilePath -> IO (Maybe FilePath)
- isNrg :: FilePath -> IO Bool
- isToc :: FilePath -> IO Bool
Types
A particular disc reading/writing device, along with the data contained on the loaded disc. Note well that this is always a mutable object, and is not thread-safe; moreover, any function this is passed to may wind up silently modifying the data.
data HardwareInfo #
Information defining the make and model of a (typically physical) device.
Constructors
| HardwareInfo | |
Instances
| Eq HardwareInfo # | |
Defined in Foreign.Libcdio.Device | |
| Read HardwareInfo # | |
Defined in Foreign.Libcdio.Device Methods readsPrec :: Int -> ReadS HardwareInfo # readList :: ReadS [HardwareInfo] # | |
| Show HardwareInfo # | |
Defined in Foreign.Libcdio.Device Methods showsPrec :: Int -> HardwareInfo -> ShowS # show :: HardwareInfo -> String # showList :: [HardwareInfo] -> ShowS # | |
| Storable HardwareInfo # | |
Defined in Foreign.Libcdio.Device Methods sizeOf :: HardwareInfo -> Int # alignment :: HardwareInfo -> Int # peekElemOff :: Ptr HardwareInfo -> Int -> IO HardwareInfo # pokeElemOff :: Ptr HardwareInfo -> Int -> HardwareInfo -> IO () # peekByteOff :: Ptr b -> Int -> IO HardwareInfo # pokeByteOff :: Ptr b -> Int -> HardwareInfo -> IO () # peek :: Ptr HardwareInfo -> IO HardwareInfo # poke :: Ptr HardwareInfo -> HardwareInfo -> IO () # | |
vendorLength :: Word #
Length of the drive vendor name in returned in a HardwareInfo query.
modelLength :: Word #
Length of the drive model name in returned in a HardwareInfo query.
revisionLength :: Word #
Length of the drive revision number in returned in a HardwareInfo query.
emptyHardwareInfo :: HardwareInfo #
A HardwareInfo object with values suitable as defaults.
Devices or file types supported by the library.
Constructors
| DriverUnknown | |
| DriverAix | |
| DriverFreeBsd | |
| DriverNetBsd | |
| DriverLinux | |
| DriverSolaris | |
| DriverOsX | |
| DriverWin32 | |
| DriverCdrDao | |
| DriverBinCue | |
| DriverNrg | |
| DriverDevice | |
| DriverBsdi | |
| DriverOs2 |
Instances
| Bounded DriverId # | |
| Enum DriverId # | |
Defined in Foreign.Libcdio.Types.Enums | |
| Eq DriverId # | |
| Ord DriverId # | |
Defined in Foreign.Libcdio.Types.Enums | |
| Read DriverId # | |
| Show DriverId # | |
data DriverReturnCode #
Descriptions of various error states which may be returned by driver functions.
Constructors
| MmcSenseData | |
| NoDriver | |
| BadPointer | |
| BadParameter | |
| NotPermitted | |
| Uninitialized | |
| Unsupported | |
| DriverError | |
| Success |
Instances
data SessionArg #
Metadata about the session in the form of (often freeform) text, providing
a type-safe index to getArg. Note that not every driver type supports
every item.
The key "access-mode" is handled separately by getAccessMode, to better
reflect its restricted outputs.
Constructors
| Source | |
| Cue | |
| ScsiTuple | |
| MmcSupported |
Instances
data AccessMode #
Which instruction set should be used to communicate with the driver, providing a type-safe input for session initialization. Note that not every driver type supports every item.
Constructors
| Image | |
| Ioctl | The |
| Ioctl_ | The |
| Aspi | |
| Atapi | |
| Cam | |
| Scsi | |
| ReadCd | |
| Read10 | |
| MmcReadWrite | |
| MmcReadWriteExclusive |
Instances
Capabilities
data DriveCapabilityRead #
Constructors
Instances
type DriveReadCaps = BitArray DriveCapabilityRead #
The collection of features for reading discs a device provides.
data DriveCapabilityWrite #
Constructors
| WriteCdRecordable | |
| WriteCdReWritable | |
| WriteDvdRecordable | |
| WriteDvdPlusRecordable | |
| WriteDvdRam | |
| WriteDvdReWritable | |
| WriteDvdPlusReWritable | |
| WriteMtRainier | |
| WriteBurnProof |
Instances
type DriveWriteCaps = BitArray DriveCapabilityWrite #
The collection of features for writing discs a device provides.
capsWriteCd :: DriveWriteCaps #
Capabilites indicating a device has some sort of CD-writing ability.
capsWriteDvd :: DriveWriteCaps #
Capabilites indicating a device has some sort of DVD-writing ability.
Capabilites indicating a device has some sort of disc-writing ability.
data DriveCapabilityMisc #
Miscellaneous properties a device can have, typically describing hardware
features, which are collected in DriveMiscCaps.
Constructors
| MiscCloseTray | |
| MiscEject | |
| MiscLock | |
| MiscSelectSpeed | |
| MiscSelectDisc | |
| MiscMultiSession | |
| MiscMediaChanged | |
| MiscReset | |
| MiscFile |
Instances
type DriveMiscCaps = BitArray DriveCapabilityMisc #
The collection of hardware features a device was built with.
type DriveCaps = (DriveReadCaps, DriveWriteCaps, DriveMiscCaps) #
The three types are usually passed around together, so we can simplify the type signatures using them.
Drivers
deviceDrivers :: [DriverId] #
All supported drivers for physical devices, listed in order of preference.
The particular driver for the current operating system, or DriverUnknown
if no device driver exists.
driverName :: Cdio -> IO (Maybe String) #
Describe the driver used by the session in a human-readable (English)
manner. See also driverId.
driverId :: Cdio -> IO (Maybe DriverId) #
The machine-readable identifier of the driver used by the session. This
should be preferred to driverName wherever possible.
driverDescribe :: DriverId -> String #
Describe the IO driver in a human-readable manner, as opposed to the
machine representation returned by the Show instance.
driverErrmsg :: DriverReturnCode -> String #
Describe the driver-level error in a human-readable manner, as opposed to
the machine representation returned by the Show instance.
haveDriver :: DriverId -> Bool #
Determine whether the system provides a particular driver.
Devices
devices :: DriverId -> IO [FilePath] #
List (static) available devices on the system which can be accessed with a
particular driver; some file devices (e.g. with DriverBinCue) might be
returned, but an exhaustive list should not be expected in that case.
If passed DriverDevice, the returned value will list any type of hardware
device, but no image files. Likewise, if passed DriverUnknown, all
hardware devices will be returned along with any already-known images.
devicesRet :: DriverId -> IO ([FilePath], DriverId) #
Like devices, but if DriverDevice or DriverUnknown is passed, the
second return value reflects the driver the library would use by default.
If any other DriverId is passed, that value is returned unchanged.
Arguments
| :: [FilePath] | If empty, then search all possible drives. |
| -> Maybe Filesystem | |
| -> FilesystemClasses | |
| -> Bool | If |
| -> IO [FilePath] |
Determine which of the devices may read discs fitting the given description.
Arguments
| :: [FilePath] | If empty, then search all possible drives. |
| -> Maybe Filesystem | |
| -> FilesystemClasses | |
| -> Bool | If |
| -> IO ([FilePath], DriverId) |
Like devicesWithFilesystem, but returning the type of driver found as with
devicesRet. This is only helpful if the device list is empty; otherwise
it simply returns DriverDevice.
defaultDevice :: IO (Maybe FilePath) #
Find the default disc device for the system, if one exists.
The C library allows getting the default device from a Cdio object, but
since that seems to only be initialized from either the default device
itself or with an explicit path, doing so seems rather redundant.
Arguments
| :: DriverId | |
| -> IO (Maybe FilePath, DriverId) | The name of the device, along with the associated driver if
passed |
Find the default disc device for a given driver, if one exists.
driveCapDevice :: FilePath -> IO DriveCaps #
Get the drive capabilities for a specified device.
ejectMedia :: Cdio -> IO DriverReturnCode #
Eject the media represented by the session identifier, if the device supports doing so.
Warning: Assuming this succeeds, the Cdio object is destroyed and any
further operations on it will fail!
Arguments
| :: Maybe FilePath | The name of the device to eject, or |
| -> IO DriverReturnCode |
Eject media in a CD drive, if the device supports doing so. If a Cdio
session has already been opened on the drive, ejectMedia is strongly
recommended instead.
Arguments
| :: Maybe FilePath | The name of the drive to use, or |
| -> DriverId | |
| -> IO (DriverReturnCode, DriverId) | Any errors, along with the actual driver used if passed
|
Close a CD drive, if the device supports doing so.
Session
getArg :: Cdio -> SessionArg -> IO (Maybe String) #
Retrieve the session value associated with the given key. The particular
case of "access-mode" is instead handled by getAccessMode.
getAccessMode :: Cdio -> IO (Maybe AccessMode) #
Check what instruction set is in use for reading the disc. Other session
values are handled by getArg.
isMediaChanged :: Cdio -> IO (Either DriverReturnCode Bool) #
Find out if the media has changed since the last call.
Arguments
| :: Cdio | The CdText object is mutated as a result of the function. |
| -> Int | |
| -> IO DriverReturnCode |
Set the blocksize for subsequent reads.
Arguments
| :: Cdio | The CdText object is mutated as a result of the function. |
| -> Int | |
| -> IO DriverReturnCode |
Set the drive speed. With many devices, if a value above their maximum speed is given, it will be silently capped.
Note that, unlike setSpeed, this uses a unit unique to disc drives,
which depends on the type of disc; to convert to or from Kb/s, use the
formula dt * cds = kbs where dt is either 176 for raw data or 150
for filesystem data, and cds is the Int passed to this function.
lastSession :: Cdio -> IO (Either DriverReturnCode Lsn) #
Get the starting address of the last write session of a disc.
Device paths
cdioOpen :: Maybe FilePath -> DriverId -> IO (Maybe Cdio) #
Open a session referencing the given location, or the default device if
passed Nothing.
cdioOpenAm :: Maybe FilePath -> DriverId -> AccessMode -> IO (Maybe Cdio) #
Open a session referencing the given location, or the default device if
passed Nothing, with the desired access mode.
Hardware
isDevice :: FilePath -> DriverId -> IO Bool #
Determine whether the given path refers to a hardware device, according to
the given driver. DriverUnknown or DriverDevice may be passed if the
system is unknown.
cdioOpenAmCd :: Maybe FilePath -> AccessMode -> IO (Maybe Cdio) #
Set up the specified CD-ROM device for reading, with the desired access mode.
Images
cueFromBin :: FilePath -> IO (Maybe FilePath) #
If the given file is a BIN disc image (determined by file extension), return the corresponding CUE file. Note that this simply replaces the extension to obtain the new file name.