You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
4397 lines
191 KiB
4397 lines
191 KiB
/* -*- indent-tabs-mode: t; tab-width: 8; c-basic-offset: 8; -*- */ |
|
|
|
/* Copyright (c) 2004 - 2006 Derek Foreman, Ben Jansens |
|
Copyright (c) 2006 - 2017 Thomas Schmitt <scdbackup@gmx.net> |
|
Provided under GPL version 2 or later. |
|
|
|
This is the official API definition of libburn. |
|
|
|
*/ |
|
/* Important: If you add a public API function then add its name to file |
|
libburn/libburn.ver |
|
*/ |
|
|
|
|
|
#ifndef LIBBURN_H |
|
#define LIBBURN_H |
|
|
|
/* |
|
|
|
Applications must use 64 bit off_t. E.g. by defining |
|
#define _LARGEFILE_SOURCE |
|
#define _FILE_OFFSET_BITS 64 |
|
or take special precautions to interface with the library by 64 bit integers |
|
where this .h files prescribe off_t. |
|
|
|
To prevent 64 bit file i/o in the library would keep the application from |
|
processing tracks of more than 2 GB size. |
|
|
|
*/ |
|
#include <sys/types.h> |
|
|
|
#ifndef DOXYGEN |
|
|
|
#if defined(__cplusplus) |
|
#define BURN_BEGIN_DECLS \ |
|
namespace burn { \ |
|
extern "C" { |
|
#define BURN_END_DECLS \ |
|
} \ |
|
} |
|
#else |
|
#define BURN_BEGIN_DECLS |
|
#define BURN_END_DECLS |
|
#endif |
|
|
|
BURN_BEGIN_DECLS |
|
|
|
#endif |
|
|
|
/** References a physical drive in the system */ |
|
struct burn_drive; |
|
|
|
/** References a whole disc */ |
|
struct burn_disc; |
|
|
|
/** References a single session on a disc */ |
|
struct burn_session; |
|
|
|
/** References a single track on a disc */ |
|
struct burn_track; |
|
|
|
/* ts A61111 */ |
|
/** References a set of write parameters */ |
|
struct burn_write_opts; |
|
|
|
/** Session format for normal audio or data discs */ |
|
#define BURN_CDROM 0 |
|
/** Session format for obsolete CD-I discs */ |
|
#define BURN_CDI 0x10 |
|
/** Session format for CDROM-XA discs */ |
|
#define BURN_CDXA 0x20 |
|
|
|
#define BURN_POS_END 100 |
|
|
|
/** Mask for mode bits */ |
|
#define BURN_MODE_BITS 127 |
|
|
|
/** Track mode - mode 0 data |
|
0 bytes of user data. it's all 0s. mode 0. get it? HAH |
|
*/ |
|
#define BURN_MODE0 (1 << 0) |
|
/** Track mode - mode "raw" - all 2352 bytes supplied by app |
|
FOR DATA TRACKS ONLY! |
|
*/ |
|
#define BURN_MODE_RAW (1 << 1) |
|
/** Track mode - mode 1 data |
|
2048 bytes user data, and all the LEC money can buy |
|
*/ |
|
#define BURN_MODE1 (1 << 2) |
|
/** Track mode - mode 2 data |
|
defaults to formless, 2336 bytes of user data, unprotected |
|
| with a data form if required. |
|
*/ |
|
#define BURN_MODE2 (1 << 3) |
|
/** Track mode modifier - Form 1, | with MODE2 for reasonable results |
|
2048 bytes of user data, 4 bytes of subheader |
|
*/ |
|
#define BURN_FORM1 (1 << 4) |
|
/** Track mode modifier - Form 2, | with MODE2 for reasonable results |
|
lots of user data. not much LEC. |
|
*/ |
|
#define BURN_FORM2 (1 << 5) |
|
/** Track mode - audio |
|
2352 bytes per sector. may be | with 4ch or preemphasis. |
|
NOT TO BE CONFUSED WITH BURN_MODE_RAW |
|
Audio data must be 44100Hz 16bit stereo with no riff or other header at |
|
beginning. Extra header data will cause pops or clicks. Audio data should |
|
also be in little-endian byte order. Big-endian audio data causes static. |
|
*/ |
|
#define BURN_AUDIO (1 << 6) |
|
/** Track mode modifier - 4 channel audio. */ |
|
#define BURN_4CH (1 << 7) |
|
/** Track mode modifier - Digital copy permitted, can be set on any track.*/ |
|
#define BURN_COPY (1 << 8) |
|
/** Track mode modifier - 50/15uS pre-emphasis */ |
|
#define BURN_PREEMPHASIS (1 << 9) |
|
/** Input mode modifier - subcodes present packed 16 */ |
|
#define BURN_SUBCODE_P16 (1 << 10) |
|
/** Input mode modifier - subcodes present packed 96 */ |
|
#define BURN_SUBCODE_P96 (1 << 11) |
|
/** Input mode modifier - subcodes present raw 96 */ |
|
#define BURN_SUBCODE_R96 (1 << 12) |
|
|
|
/* ts B11230 */ |
|
/** Track mode modifier - Serial Copy Management System, SAO only |
|
If this is set and BURN_COPY is not set, then copying the emerging |
|
track will be forbidden. |
|
@since 1.2.0 |
|
*/ |
|
#define BURN_SCMS (1 << 13) |
|
|
|
|
|
/** Possible disc writing style/modes */ |
|
enum burn_write_types |
|
{ |
|
/** Packet writing. |
|
currently unsupported, (for DVD Incremental Streaming use TAO) |
|
*/ |
|
BURN_WRITE_PACKET, |
|
|
|
/** With CD: Track At Once recording |
|
2s gaps between tracks, no fonky lead-ins |
|
|
|
With sequential DVD-R[W]: Incremental Streaming |
|
With DVD+R and BD-R: Track of open size |
|
With DVD-RAM, DVD+RW, BD-RE: Random Writeable (used sequentially) |
|
With overwriteable DVD-RW: Rigid Restricted Overwrite |
|
*/ |
|
BURN_WRITE_TAO, |
|
|
|
/** With CD: Session At Once |
|
Block type MUST be BURN_BLOCK_SAO |
|
ts A70122: Currently not capable of mixing data and audio tracks. |
|
|
|
With sequential DVD-R[W]: Disc-at-once, DAO |
|
Single session, single track, fixed size mandatory, (-dvd-compat) |
|
With other DVD or BD media: same as BURN_WRITE_TAO but may demand |
|
that track size is known in advance. |
|
*/ |
|
BURN_WRITE_SAO, |
|
|
|
/** With CD: Raw disc at once recording. |
|
all subcodes must be provided by lib or user |
|
only raw block types are supported |
|
With DVD and BD media: not supported. |
|
|
|
ts A90901: This had been disabled because its implementation |
|
relied on code from cdrdao which is not understood |
|
currently. |
|
A burn run will abort with "FATAL" error message |
|
if this mode is attempted. |
|
@since 0.7.2 |
|
ts A91016: Re-implemented according to ECMA-130 Annex A and B. |
|
Now understood, explained and not stemming from cdrdao. |
|
@since 0.7.4 |
|
*/ |
|
BURN_WRITE_RAW, |
|
|
|
/** In replies this indicates that not any writing will work. |
|
As parameter for inquiries it indicates that no particular write |
|
mode shall is specified. |
|
Do not use for setting a write mode for burning. It will not work. |
|
*/ |
|
BURN_WRITE_NONE |
|
}; |
|
|
|
/** Data format to send to the drive */ |
|
enum burn_block_types |
|
{ |
|
/** sync, headers, edc/ecc provided by lib/user */ |
|
BURN_BLOCK_RAW0 = 1, |
|
/** sync, headers, edc/ecc and p/q subs provided by lib/user */ |
|
BURN_BLOCK_RAW16 = 2, |
|
/** sync, headers, edc/ecc and packed p-w subs provided by lib/user */ |
|
BURN_BLOCK_RAW96P = 4, |
|
/** sync, headers, edc/ecc and raw p-w subs provided by lib/user */ |
|
BURN_BLOCK_RAW96R = 8, |
|
/** only 2048 bytes of user data provided by lib/user */ |
|
BURN_BLOCK_MODE1 = 256, |
|
/** 2336 bytes of user data provided by lib/user */ |
|
BURN_BLOCK_MODE2R = 512, |
|
/** 2048 bytes of user data provided by lib/user |
|
subheader provided in write parameters |
|
are we ever going to support this shit? I vote no. |
|
(supposed to be supported on all drives...) |
|
*/ |
|
BURN_BLOCK_MODE2_PATHETIC = 1024, |
|
/** 2048 bytes of data + 8 byte subheader provided by lib/user |
|
hey, this is also dumb |
|
*/ |
|
BURN_BLOCK_MODE2_LAME = 2048, |
|
/** 2324 bytes of data provided by lib/user |
|
subheader provided in write parameters |
|
no sir, I don't like it. |
|
*/ |
|
BURN_BLOCK_MODE2_OBSCURE = 4096, |
|
/** 2332 bytes of data supplied by lib/user |
|
8 bytes sub header provided in write parameters |
|
this is the second least suck mode2, and is mandatory for |
|
all drives to support. |
|
*/ |
|
BURN_BLOCK_MODE2_OK = 8192, |
|
/** SAO block sizes are based on cue sheet, so use this. */ |
|
BURN_BLOCK_SAO = 16384 |
|
}; |
|
|
|
/** Possible status of the drive in regard to the disc in it. */ |
|
enum burn_disc_status |
|
{ |
|
/** The current status is not yet known */ |
|
BURN_DISC_UNREADY, |
|
|
|
/** The drive holds a blank disc. It is ready for writing from scratch. |
|
Unused multi-session media: |
|
CD-R, CD-RW, DVD-R, DVD-RW, DVD+R, BD-R |
|
Blanked multi-session media (i.e. treated by burn_disc_erase()) |
|
CD-RW, DVD-RW |
|
Overwriteable media with or without valid data |
|
DVD-RAM, DVD+RW, formatted DVD-RW, BD-RE |
|
*/ |
|
BURN_DISC_BLANK, |
|
|
|
/** There is no disc at all in the drive */ |
|
BURN_DISC_EMPTY, |
|
|
|
/** There is an incomplete disc in the drive. It is ready for appending |
|
another session. |
|
Written but not yet closed multi-session media |
|
CD-R, CD-RW, DVD-R, DVD-RW, DVD+R, BD-R |
|
*/ |
|
BURN_DISC_APPENDABLE, |
|
|
|
/** There is a disc with data on it in the drive. It is usable only for |
|
reading. |
|
Written and closed multi-session media |
|
CD-R, CD-RW, DVD-R, DVD-RW, DVD+R, BD-R |
|
Read-Only media |
|
CD-ROM, DVD-ROM, BD-ROM |
|
Note that many DVD-ROM drives report any written media |
|
as Read-Only media and not by their real media types. |
|
*/ |
|
BURN_DISC_FULL, |
|
|
|
/* ts A61007 */ |
|
/* @since 0.2.4 */ |
|
/** The drive was not grabbed when the status was inquired */ |
|
BURN_DISC_UNGRABBED, |
|
|
|
/* ts A61020 */ |
|
/* @since 0.2.6 */ |
|
/** The media seems to be unsuitable for reading and for writing */ |
|
BURN_DISC_UNSUITABLE |
|
}; |
|
|
|
|
|
/** Possible data source return values */ |
|
enum burn_source_status |
|
{ |
|
/** The source is ok */ |
|
BURN_SOURCE_OK, |
|
/** The source is at end of file */ |
|
BURN_SOURCE_EOF, |
|
/** The source is unusable */ |
|
BURN_SOURCE_FAILED |
|
}; |
|
|
|
|
|
/** Possible busy states for a drive */ |
|
enum burn_drive_status |
|
{ |
|
/** The drive is not in an operation */ |
|
BURN_DRIVE_IDLE, |
|
/** The library is spawning the processes to handle a pending |
|
operation (A read/write/etc is about to start but hasn't quite |
|
yet) */ |
|
BURN_DRIVE_SPAWNING, |
|
/** The drive is reading data from a disc */ |
|
BURN_DRIVE_READING, |
|
/** The drive is writing data to a disc */ |
|
BURN_DRIVE_WRITING, |
|
/** The drive is writing Lead-In */ |
|
BURN_DRIVE_WRITING_LEADIN, |
|
/** The drive is writing Lead-Out */ |
|
BURN_DRIVE_WRITING_LEADOUT, |
|
/** The drive is erasing a disc */ |
|
BURN_DRIVE_ERASING, |
|
/** The drive is being grabbed */ |
|
BURN_DRIVE_GRABBING, |
|
|
|
/* ts A61102 */ |
|
/* @since 0.2.6 */ |
|
/** The drive gets written zeroes before the track payload data */ |
|
BURN_DRIVE_WRITING_PREGAP, |
|
/** The drive is told to close a track (TAO only) */ |
|
BURN_DRIVE_CLOSING_TRACK, |
|
/** The drive is told to close a session (TAO only) */ |
|
BURN_DRIVE_CLOSING_SESSION, |
|
|
|
/* ts A61223 */ |
|
/* @since 0.3.0 */ |
|
/** The drive is formatting media */ |
|
BURN_DRIVE_FORMATTING, |
|
|
|
/* ts A70822 */ |
|
/* @since 0.4.0 */ |
|
/** The drive is busy in synchronous read (if you see this then it |
|
has been interrupted) */ |
|
BURN_DRIVE_READING_SYNC, |
|
/** The drive is busy in synchronous write (if you see this then it |
|
has been interrupted) */ |
|
BURN_DRIVE_WRITING_SYNC |
|
|
|
}; |
|
|
|
|
|
/** Information about a track on a disc - this is from the q sub channel of the |
|
lead-in area of a disc. The documentation here is very terse. |
|
See a document such as mmc3 for proper information. |
|
|
|
CAUTION : This structure is prone to future extension ! |
|
|
|
Do not restrict your application to unsigned char with any counter like |
|
"session", "point", "pmin", ... |
|
Do not rely on the current size of a burn_toc_entry. |
|
|
|
*/ |
|
struct burn_toc_entry |
|
{ |
|
/** Session the track is in */ |
|
unsigned char session; |
|
/** Type of data. for this struct to be valid, it must be 1 */ |
|
unsigned char adr; |
|
/** Type of data in the track */ |
|
unsigned char control; |
|
/** Zero. Always. Really. */ |
|
unsigned char tno; |
|
/** Track number or special information */ |
|
unsigned char point; |
|
unsigned char min; |
|
unsigned char sec; |
|
unsigned char frame; |
|
unsigned char zero; |
|
/** Track start time minutes for normal tracks */ |
|
unsigned char pmin; |
|
/** Track start time seconds for normal tracks */ |
|
unsigned char psec; |
|
/** Track start time frames for normal tracks */ |
|
unsigned char pframe; |
|
|
|
/* Indicates whether extension data are valid and eventually override |
|
older elements in this structure: |
|
bit0= DVD extension is valid @since 0.3.2 |
|
@since 0.5.2 : DVD extensions are made valid for CD too |
|
bit1= LRA extension is valid @since 0.7.2 |
|
bit2= Track status bits extension is valid @since 1.2.8 |
|
*/ |
|
unsigned char extensions_valid; |
|
|
|
/* ts A70201 : DVD extension. extensions_valid:bit0 |
|
If invalid the members are guaranteed to be 0. */ |
|
/* @since 0.3.2 */ |
|
/* Tracks and session numbers are 16 bit. Here are the high bytes. */ |
|
unsigned char session_msb; |
|
unsigned char point_msb; |
|
/* pmin, psec, and pframe may be too small if DVD extension is valid */ |
|
int start_lba; |
|
/* min, sec, and frame may be too small if DVD extension is valid */ |
|
int track_blocks; |
|
|
|
/* ts A90909 : LRA extension. extensions_valid:bit1 */ |
|
/* @since 0.7.2 */ |
|
/* MMC-5 6.27.3.18 : The Last Recorded Address is valid for DVD-R, |
|
DVD-R DL when LJRS = 00b, DVD-RW, HD DVD-R, and BD-R. |
|
This would mean profiles: 0x11, 0x15, 0x13, 0x14, 0x51, 0x41, 0x42 |
|
*/ |
|
int last_recorded_address; |
|
|
|
/* ts B30112 : Track status bits extension. extensions_valid:bit2 */ |
|
/* @since 1.2.8 */ |
|
/* Names as of READ TRACK INFORMATION, MMC-5 6.27.3 : |
|
bit0 - bit3 = Track Mode |
|
bit4 = Copy |
|
bit5 = Damage |
|
bit6 - bit7 = LJRS |
|
bit8 - bit11 = Data Mode |
|
bit12 = FP |
|
bit13 = Packet/Inc |
|
bit14 = Blank |
|
bit15 = RT |
|
bit16 = NWA_V |
|
bit17 = LRA_V |
|
*/ |
|
int track_status_bits; |
|
|
|
}; |
|
|
|
|
|
/** Data source interface for tracks. |
|
This allows you to use arbitrary program code as provider of track input |
|
data. |
|
|
|
Objects compliant to this interface are either provided by the application |
|
or by API calls of libburn: burn_fd_source_new() , burn_file_source_new(), |
|
and burn_fifo_source_new(). |
|
|
|
The API calls may use any file object as data source. Consider to feed |
|
an eventual custom data stream asynchronously into a pipe(2) and to let |
|
libburn handle the rest. |
|
In this case the following rule applies: |
|
Call burn_source_free() exactly once for every source obtained from |
|
libburn API. You MUST NOT otherwise use or manipulate its components. |
|
|
|
In general, burn_source objects can be freed as soon as they are attached |
|
to track objects. The track objects will keep them alive and dispose them |
|
when they are no longer needed. With a fifo burn_source it makes sense to |
|
keep the own reference for inquiring its state while burning is in |
|
progress. |
|
|
|
--- |
|
|
|
The following description of burn_source applies only to application |
|
implemented burn_source objects. You need not to know it for API provided |
|
ones. |
|
|
|
If you really implement an own passive data producer by this interface, |
|
then beware: it can do anything and it can spoil everything. |
|
|
|
In this case the functions (*read), (*get_size), (*set_size), (*free_data) |
|
MUST be implemented by the application and attached to the object at |
|
creation time. |
|
Function (*read_sub) is allowed to be NULL or it MUST be implemented and |
|
attached. |
|
|
|
burn_source.refcount MUST be handled properly: If not exactly as many |
|
references are freed as have been obtained, then either memory leaks or |
|
corrupted memory are the consequence. |
|
All objects which are referred to by *data must be kept existent until |
|
(*free_data) is called via burn_source_free() by the last referer. |
|
*/ |
|
struct burn_source { |
|
|
|
/** Reference count for the data source. MUST be 1 when a new source |
|
is created and thus the first reference is handed out. Increment |
|
it to take more references for yourself. Use burn_source_free() |
|
to destroy your references to it. */ |
|
int refcount; |
|
|
|
|
|
/** Read data from the source. Semantics like with read(2), but MUST |
|
either deliver the full buffer as defined by size or MUST deliver |
|
EOF (return 0) or failure (return -1) at this call or at the |
|
next following call. I.e. the only incomplete buffer may be the |
|
last one from that source. |
|
libburn will read a single sector by each call to (*read). |
|
The size of a sector depends on BURN_MODE_*. The known range is |
|
2048 to 2352. |
|
|
|
If this call is reading from a pipe then it will learn |
|
about the end of data only when that pipe gets closed on the |
|
feeder side. So if the track size is not fixed or if the pipe |
|
delivers less than the predicted amount or if the size is not |
|
block aligned, then burning will halt until the input process |
|
closes the pipe. |
|
|
|
IMPORTANT: |
|
If this function pointer is NULL, then the struct burn_source is of |
|
version >= 1 and the job of .(*read)() is done by .(*read_xt)(). |
|
See below, member .version. |
|
*/ |
|
int (*read)(struct burn_source *, unsigned char *buffer, int size); |
|
|
|
|
|
/** Read subchannel data from the source (NULL if lib generated) |
|
WARNING: This is an obscure feature with CD raw write modes. |
|
Unless you checked the libburn code for correctness in that aspect |
|
you should not rely on raw writing with own subchannels. |
|
ADVICE: Set this pointer to NULL. |
|
*/ |
|
int (*read_sub)(struct burn_source *, unsigned char *buffer, int size); |
|
|
|
|
|
/** Get the size of the source's data. Return 0 means unpredictable |
|
size. If application provided (*get_size) might return 0, then |
|
the application MUST provide a fully functional (*set_size). |
|
*/ |
|
off_t (*get_size)(struct burn_source *); |
|
|
|
|
|
/* ts A70125 : BROKE BINARY BACKWARD COMPATIBILITY AT libburn-0.3.1. */ |
|
/* @since 0.3.2 */ |
|
/** Program the reply of (*get_size) to a fixed value. It is advised |
|
to implement this by a attribute off_t fixed_size; in *data . |
|
The read() function does not have to take into respect this fake |
|
setting. It is rather a note of libburn to itself. Eventually |
|
necessary truncation or padding is done in libburn. Truncation |
|
is usually considered a misburn. Padding is considered ok. |
|
|
|
libburn is supposed to work even if (*get_size) ignores the |
|
setting by (*set_size). But your application will not be able to |
|
enforce fixed track sizes by burn_track_set_size() and possibly |
|
even padding might be left out. |
|
*/ |
|
int (*set_size)(struct burn_source *source, off_t size); |
|
|
|
|
|
/** Clean up the source specific data. This function will be called |
|
once by burn_source_free() when the last referer disposes the |
|
source. |
|
*/ |
|
void (*free_data)(struct burn_source *); |
|
|
|
|
|
/** Next source, for when a source runs dry and padding is disabled |
|
WARNING: This is an obscure feature. Set to NULL at creation and |
|
from then on leave untouched and uninterpreted. |
|
*/ |
|
struct burn_source *next; |
|
|
|
|
|
/** Source specific data. Here the various source classes express their |
|
specific properties and the instance objects store their individual |
|
management data. |
|
E.g. data could point to a struct like this: |
|
struct app_burn_source |
|
{ |
|
struct my_app *app_handle; |
|
... other individual source parameters ... |
|
off_t fixed_size; |
|
}; |
|
|
|
Function (*free_data) has to be prepared to clean up and free |
|
the struct. |
|
*/ |
|
void *data; |
|
|
|
|
|
/* ts A71222 : Supposed to be binary backwards compatible extension. */ |
|
/* @since 0.4.2 */ |
|
/** Valid only if above member .(*read)() is NULL. This indicates a |
|
version of struct burn_source younger than 0. |
|
From then on, member .version tells which further members exist |
|
in the memory layout of struct burn_source. libburn will only touch |
|
those announced extensions. |
|
|
|
Versions: |
|
0 has .(*read)() != NULL, not even .version is present. |
|
1 has .version, .(*read_xt)(), .(*cancel)() |
|
*/ |
|
int version; |
|
|
|
/** This substitutes for (*read)() in versions above 0. */ |
|
int (*read_xt)(struct burn_source *, unsigned char *buffer, int size); |
|
|
|
/** Informs the burn_source that the consumer of data prematurely |
|
ended reading. This call may or may not be issued by libburn |
|
before (*free_data)() is called. |
|
*/ |
|
int (*cancel)(struct burn_source *source); |
|
}; |
|
|
|
|
|
/** Information on a drive in the system */ |
|
struct burn_drive_info |
|
{ |
|
/** Name of the vendor of the drive */ |
|
char vendor[9]; |
|
/** Name of the drive */ |
|
char product[17]; |
|
/** Revision of the drive */ |
|
char revision[5]; |
|
|
|
/** Invalid: Was: "Location of the drive in the filesystem." */ |
|
/** This string has no meaning any more. Once it stored the drive |
|
device file address. Now always use function burn_drive_d_get_adr() |
|
to inquire a device file address. ^^^^^ ALWAYS ^^^^^^^*/ |
|
char location[17]; |
|
|
|
/* NOTE: The capability to write particular media types is also |
|
announced by their profile number being in the list returned |
|
by burn_drive_get_all_profile(). This is the only way to |
|
inquire types DVD-RW, DVD+R, DVD+R DL, DVD+RW, BD-R, BD-RE. |
|
*/ |
|
/** Can the drive read DVD-RAM discs */ |
|
unsigned int read_dvdram:1; |
|
/** Can the drive read DVD-R discs */ |
|
unsigned int read_dvdr:1; |
|
/** Can the drive read DVD-ROM discs */ |
|
unsigned int read_dvdrom:1; |
|
/** Can the drive read CD-R discs */ |
|
unsigned int read_cdr:1; |
|
/** Can the drive read CD-RW discs */ |
|
unsigned int read_cdrw:1; |
|
|
|
/** Can the drive write DVD-RAM discs */ |
|
unsigned int write_dvdram:1; |
|
/** Can the drive write DVD-R discs */ |
|
unsigned int write_dvdr:1; |
|
/** Can the drive write CD-R discs */ |
|
unsigned int write_cdr:1; |
|
/** Can the drive write CD-RW discs */ |
|
unsigned int write_cdrw:1; |
|
|
|
/** Can the drive simulate a write */ |
|
unsigned int write_simulate:1; |
|
|
|
/** DEPRECATED: Can the drive report C2 errors */ |
|
unsigned int c2_errors:1; |
|
|
|
/** DEPRECATED: The size of the drive's buffer (in kilobytes) */ |
|
int buffer_size; |
|
|
|
|
|
/** |
|
* The supported block types in tao mode. |
|
* They should be tested with the desired block type. |
|
* See also burn_block_types. |
|
*/ |
|
int tao_block_types; |
|
/** |
|
* The supported block types in sao mode. |
|
* They should be tested with the desired block type. |
|
* See also burn_block_types. |
|
*/ |
|
int sao_block_types; |
|
/** |
|
* The supported block types in raw mode. |
|
* They should be tested with the desired block type. |
|
* See also burn_block_types. |
|
*/ |
|
int raw_block_types; |
|
/** |
|
* The supported block types in packet mode. |
|
* They should be tested with the desired block type. |
|
* See also burn_block_types. |
|
*/ |
|
int packet_block_types; |
|
|
|
/** The value by which this drive can be indexed when using functions |
|
in the library. This is the value to pass to all libbburn functions |
|
that operate on a drive. */ |
|
struct burn_drive *drive; |
|
}; |
|
|
|
|
|
/** Operation progress report. All values are 0 based indices. |
|
* */ |
|
struct burn_progress { |
|
/** The total number of sessions */ |
|
int sessions; |
|
/** Current session.*/ |
|
int session; |
|
/** The total number of tracks */ |
|
int tracks; |
|
/** Current track. */ |
|
int track; |
|
/** The total number of indices */ |
|
int indices; |
|
/** Curent index. */ |
|
int index; |
|
/** The starting logical block address */ |
|
int start_sector; |
|
/** On write: The number of sectors. |
|
On blank: 0x10000 as upper limit for relative progress steps */ |
|
int sectors; |
|
/** On write: The current sector being processed. |
|
On blank: Relative progress steps 0 to 0x10000 */ |
|
int sector; |
|
|
|
/* ts A61023 */ |
|
/* @since 0.2.6 */ |
|
/** The capacity of the drive buffer */ |
|
unsigned buffer_capacity; |
|
/** The free space in the drive buffer (might be slightly outdated) */ |
|
unsigned buffer_available; |
|
|
|
/* ts A61119 */ |
|
/* @since 0.2.6 */ |
|
/** The number of bytes sent to the drive buffer */ |
|
off_t buffered_bytes; |
|
/** The minimum number of bytes stored in buffer during write. |
|
(Caution: Before surely one buffer size of bytes was processed, |
|
this value is 0xffffffff.) |
|
*/ |
|
unsigned buffer_min_fill; |
|
}; |
|
|
|
|
|
/* ts A61226 */ |
|
/* @since 0.3.0 */ |
|
/** Description of a speed capability as reported by the drive in conjunction |
|
with eventually loaded media. There can be more than one such object per |
|
drive. So they are chained via .next and .prev , where NULL marks the end |
|
of the chain. This list is set up by burn_drive_scan() and gets updated |
|
by burn_drive_grab(). |
|
A copy may be obtained by burn_drive_get_speedlist() and disposed by |
|
burn_drive_free_speedlist(). |
|
For technical background info see SCSI specs MMC and SPC: |
|
mode page 2Ah (from SPC 5Ah MODE SENSE) , mmc3r10g.pdf , 6.3.11 Table 364 |
|
ACh GET PERFORMANCE, Type 03h , mmc5r03c.pdf , 6.8.5.3 Table 312 |
|
*/ |
|
struct burn_speed_descriptor { |
|
|
|
/** Where this info comes from : |
|
0 = misc |
|
1 = mode page 2Ah |
|
2 = ACh GET PERFORMANCE Type 03h |
|
3 = ACh GET PERFORMANCE Type 00h Data Type 10h (read speed) |
|
*/ |
|
int source; |
|
|
|
/** The media type that was current at the time of report |
|
-2 = state unknown, -1 = no media was loaded , else see |
|
burn_disc_get_profile() */ |
|
int profile_loaded; |
|
char profile_name[80]; |
|
|
|
/** The attributed capacity of appropriate media in logical block units |
|
i.e. 2352 raw bytes or 2048 data bytes. -1 = capacity unknown. */ |
|
int end_lba; |
|
|
|
/** Speed is given in 1000 bytes/s , 0 = invalid. The numbers |
|
are supposed to be usable with burn_drive_set_speed() */ |
|
int write_speed; |
|
int read_speed; |
|
|
|
/** Expert info from ACh GET PERFORMANCE and/or mode page 2Ah. |
|
Expect values other than 0 or 1 to get a meaning in future.*/ |
|
/* Rotational control: 0 = CLV/default , 1 = CAV */ |
|
int wrc; |
|
/* 1 = drive promises reported performance over full media */ |
|
int exact; |
|
/* 1 = suitable for mixture of read and write */ |
|
int mrw; |
|
|
|
/** List chaining. Use .next until NULL to iterate over the list */ |
|
struct burn_speed_descriptor *prev; |
|
struct burn_speed_descriptor *next; |
|
}; |
|
|
|
|
|
/** Initialize the library. |
|
This must be called before using any other functions in the library. It |
|
may be called more than once with no effect. |
|
It is possible to 'restart' the library by shutting it down and |
|
re-initializing it. Once this was necessary if you follow the older and |
|
more general way of accessing a drive via burn_drive_scan() and |
|
burn_drive_grab(). See burn_drive_scan_and_grab() with its strong |
|
urges and its explanations. |
|
@return Nonzero if the library was able to initialize; zero if |
|
initialization failed. |
|
*/ |
|
int burn_initialize(void); |
|
|
|
/** Shutdown the library. |
|
This should be called before exiting your application. Make sure that all |
|
drives you have grabbed are released <i>before</i> calling this. |
|
*/ |
|
void burn_finish(void); |
|
|
|
|
|
/* ts A61002 */ |
|
/** Abort any running drive operation and eventually call burn_finish(). |
|
|
|
You MUST shut down the busy drives if an aborting event occurs during a |
|
burn run. For that you may call this function either from your own signal |
|
handling code or indirectly by activating the built-in signal handling: |
|
burn_set_signal_handling("my_app_name : ", NULL, 0); |
|
Else you may eventually call burn_drive_cancel() on the active drives and |
|
wait for them to assume state BURN_DRIVE_IDLE. |
|
@param patience Maximum number of seconds to wait for drives to |
|
finish. |
|
@since 0.7.8 : |
|
If this is -1, then only the cancel operations will |
|
be performed and no burn_finish() will happen. |
|
@param pacifier_func If not NULL: a function to produce appeasing messages. |
|
See burn_abort_pacifier() for an example. |
|
@param handle Opaque handle to be used with pacifier_func |
|
@return 1 ok, all went well |
|
0 had to leave a drive in unclean state |
|
<0 severe error, do no use libburn again |
|
@since 0.2.6 |
|
*/ |
|
int burn_abort(int patience, |
|
int (*pacifier_func)(void *handle, int patience, int elapsed), |
|
void *handle); |
|
|
|
/** A pacifier function suitable for burn_abort. |
|
@param handle If not NULL, a pointer to a text suitable for printf("%s") |
|
@param patience Maximum number of seconds to wait |
|
@param elapsed Elapsed number of seconds |
|
*/ |
|
int burn_abort_pacifier(void *handle, int patience, int elapsed); |
|
|
|
|
|
/** ts A61006 : This is for development only. Not suitable for applications. |
|
Set the verbosity level of the library. The default value is 0, which means |
|
that nothing is output on stderr. The more you increase this, the more |
|
debug output should be displayed on stderr for you. |
|
@param level The verbosity level desired. 0 for nothing, higher positive |
|
values for more information output. |
|
*/ |
|
void burn_set_verbosity(int level); |
|
|
|
/* ts A91111 */ |
|
/** Enable or disable logging of SCSI commands. |
|
This call can be made at any time - even before burn_initialize(). |
|
It is in effect for all active drives and currently not very thread |
|
safe for multiple drives. |
|
@param flag Bitfield for control purposes. The default is 0. |
|
bit0= log to file /tmp/libburn_sg_command_log |
|
bit1= log to stderr |
|
bit2= flush output after each line |
|
@since 0.7.4 |
|
*/ |
|
void burn_set_scsi_logging(int flag); |
|
|
|
/* ts A60813 */ |
|
/** Set parameters for behavior on opening device files. To be called early |
|
after burn_initialize() and before any bus scan. But not mandatory at all. |
|
Parameter value 1 enables a feature, 0 disables. |
|
Default is (1,0,0). Have a good reason before you change it. |
|
@param exclusive |
|
0 = no attempt to make drive access exclusive. |
|
1 = Try to open only devices which are not marked as busy |
|
and try to mark them busy if opened successfully. (O_EXCL |
|
on GNU/Linux , flock(LOCK_EX) on FreeBSD.) |
|
2 = in case of a SCSI device, also try to open exclusively |
|
the matching /dev/sr, /dev/scd and /dev/st . |
|
One may select a device SCSI file family by adding |
|
0 = default family |
|
4 = /dev/sr%d |
|
8 = /dev/scd%d |
|
16 = /dev/sg%d |
|
Do not use other values ! |
|
Add 32 to demand on GNU/Linux an exclusive lock by |
|
fcntl(,F_SETLK,) after open() has succeeded. |
|
@param blocking Try to wait for drives which do not open immediately but |
|
also do not return an error as well. (O_NONBLOCK) |
|
This might stall indefinitely with /dev/hdX hard disks. |
|
@param abort_on_busy Unconditionally abort process when a non blocking |
|
exclusive opening attempt indicates a busy drive. |
|
Use this only after thorough tests with your app. |
|
@since 0.2.2 |
|
*/ |
|
void burn_preset_device_open(int exclusive, int blocking, int abort_on_busy); |
|
|
|
|
|
/* ts A70223 */ |
|
/** Allows the use of media types which are implemented in libburn but not yet |
|
tested. The list of those untested profiles is subject to change. |
|
- Currently no media types are under test reservation - |
|
If you really test such media, then please report the outcome on |
|
libburn-hackers@pykix.org |
|
If ever then this call should be done soon after burn_initialize() before |
|
any drive scanning. |
|
@param yes 1=allow all implemented profiles, 0=only tested media (default) |
|
@since 0.3.4 |
|
*/ |
|
void burn_allow_untested_profiles(int yes); |
|
|
|
|
|
/* ts A60823 */ |
|
/** Acquire a drive with known device file address. |
|
|
|
This is the sysadmin friendly way to open one drive and to leave all |
|
others untouched. It bundles the following API calls to form a |
|
non-obtrusive way to use libburn: |
|
burn_drive_add_whitelist() , burn_drive_scan() , burn_drive_grab() |
|
You are *strongly urged* to use this call whenever you know the drive |
|
address in advance. |
|
|
|
If not, then you have to use directly above calls. In that case, you are |
|
*strongly urged* to drop any unintended drive which will be exclusively |
|
occupied and not closed by burn_drive_scan(). |
|
This can be done by shutting down the library including a call to |
|
burn_finish(). You may later start a new libburn session and should then |
|
use the function described here with an address obtained after |
|
burn_drive_scan() via burn_drive_d_get_adr(drive_infos[driveno].drive,adr). |
|
Another way is to drop the unwanted drives by burn_drive_info_forget(). |
|
|
|
Operating on multiple drives: |
|
|
|
Different than with burn_drive_scan() it is allowed to call |
|
burn_drive_scan_and_grab() without giving up any other scanned drives. So |
|
this call can be used to get a collection of more than one acquired drives. |
|
The attempt to acquire the same drive twice will fail, though. |
|
|
|
Pseudo-drives: |
|
|
|
burn_drive_scan_and_grab() is able to acquire virtual drives which will |
|
accept options much like a MMC burner drive. Many of those options will not |
|
cause any effect, though. The address of a pseudo-drive begins with |
|
prefix "stdio:" followed by a path. |
|
Examples: "stdio:/tmp/pseudo_drive" , "stdio:/dev/null" , "stdio:-" |
|
|
|
If the path is empty, the result is a null-drive = drive role 0. |
|
It pretends to have loaded no media and supports no reading or writing. |
|
|
|
If the path leads to an existing regular file, or to a not yet existing |
|
file, or to an existing block device, then the result is a random access |
|
stdio-drive capable of reading and writing = drive role 2. |
|
|
|
If the path leads to an existing file of any type other than directory, |
|
then the result is a sequential write-only stdio-drive = drive role 3. |
|
|
|
The special address form "stdio:/dev/fd/{number}" is interpreted literally |
|
as reference to open file descriptor {number}. This address form coincides |
|
with real files on some systems, but it is in fact hardcoded in libburn. |
|
Special address "stdio:-" means stdout = "stdio:/dev/fd/1". |
|
The role of such a drive is determined by the file type obtained via |
|
fstat({number}). |
|
|
|
Roles 2 and 3 perform all their eventual data transfer activities on a file |
|
via standard i/o functions open(2), lseek(2), read(2), write(2), close(2). |
|
The media profile is reported as 0xffff. Write space information from those |
|
media is not necessarily realistic. |
|
|
|
The capabilities of role 2 resemble DVD-RAM but it can simulate writing. |
|
If the path does not exist in the filesystem yet, it is attempted to create |
|
it as a regular file as soon as write operations are started. |
|
|
|
The capabilities of role 3 resemble a blank DVD-R. Nevertheless each |
|
burn_disc_write() run may only write a single track. |
|
|
|
One may distinguish pseudo-drives from MMC drives by call |
|
burn_drive_get_drive_role(). |
|
|
|
@param drive_infos On success returns a one element array with the drive |
|
(cdrom/burner). Thus use with driveno 0 only. On failure |
|
the array has no valid elements at all. |
|
The returned array should be freed via burn_drive_info_free() |
|
when it is no longer needed. |
|
This is a result from call burn_drive_scan(). See there. |
|
Use with driveno 0 only. |
|
@param adr The device file address of the desired drive. Either once |
|
obtained by burn_drive_d_get_adr() or composed skillfully by |
|
application or its user. E.g. "/dev/sr0". |
|
Consider to preprocess it by burn_drive_convert_fs_adr(). |
|
@param load Nonzero to make the drive attempt to load a disc (close its |
|
tray door, etc). |
|
@return 1 = success , 0 = drive not found , -1 = other error |
|
@since 0.2.2 |
|
*/ |
|
int burn_drive_scan_and_grab(struct burn_drive_info *drive_infos[], |
|
char* adr, int load); |
|
|
|
|
|
/* ts A51221 */ |
|
/* @since 0.2.2 */ |
|
/** Maximum number of particularly permissible drive addresses */ |
|
#define BURN_DRIVE_WHITELIST_LEN 255 |
|
|
|
/** Add a device to the list of permissible drives. As soon as some entry is in |
|
the whitelist all non-listed drives are banned from scanning. |
|
@return 1 success, <=0 failure |
|
@since 0.2.2 |
|
*/ |
|
int burn_drive_add_whitelist(char *device_address); |
|
|
|
/** Remove all drives from whitelist. This enables all possible drives. */ |
|
void burn_drive_clear_whitelist(void); |
|
|
|
|
|
/** Scan for drives. This function MUST be called until it returns nonzero. |
|
In case of re-scanning: |
|
All pointers to struct burn_drive and all struct burn_drive_info arrays |
|
are invalidated by using this function. Do NOT store drive pointers across |
|
calls to this function ! |
|
To avoid invalid pointers one MUST free all burn_drive_info arrays |
|
by burn_drive_info_free() before calling burn_drive_scan() a second time. |
|
If there are drives left, then burn_drive_scan() will refuse to work. |
|
|
|
After this call all drives depicted by the returned array are subject |
|
to eventual (O_EXCL) locking. See burn_preset_device_open(). This state |
|
ends either with burn_drive_info_forget() or with burn_drive_release(). |
|
It is unfriendly to other processes on the system to hold drives locked |
|
which one does not definitely plan to use soon. |
|
@param drive_infos Returns an array of drive info items (cdroms/burners). |
|
The returned array must be freed by burn_drive_info_free() |
|
before burn_finish(), and also before calling this function |
|
burn_drive_scan() again. |
|
@param n_drives Returns the number of drive items in drive_infos. |
|
@return 0 while scanning is not complete |
|
>0 when it is finished successfully, |
|
<0 when finished but failed. |
|
*/ |
|
int burn_drive_scan(struct burn_drive_info *drive_infos[], |
|
unsigned int *n_drives); |
|
|
|
/* ts A60904 : ticket 62, contribution by elmom */ |
|
/** Release memory about a single drive and any exclusive lock on it. |
|
Become unable to inquire or grab it. Expect FATAL consequences if you try. |
|
@param drive_info pointer to a single element out of the array |
|
obtained from burn_drive_scan() : &(drive_infos[driveno]) |
|
@param force controls degree of permissible drive usage at the moment this |
|
function is called, and the amount of automatically provided |
|
drive shutdown : |
|
0= drive must be ungrabbed and BURN_DRIVE_IDLE |
|
1= try to release drive even if in state BURN_DRIVE_GRABBING |
|
Use these two only. Further values are to be defined. |
|
@return 1 on success, 2 if drive was already forgotten, |
|
0 if not permissible, <0 on other failures, |
|
@since 0.2.2 |
|
*/ |
|
int burn_drive_info_forget(struct burn_drive_info *drive_info, int force); |
|
|
|
|
|
/** When no longer needed, free a whole burn_drive_info array which was |
|
returned by burn_drive_scan(). |
|
For freeing single drive array elements use burn_drive_info_forget(). |
|
*/ |
|
void burn_drive_info_free(struct burn_drive_info drive_infos[]); |
|
|
|
|
|
/* ts A60823 */ |
|
/* @since 0.2.2 */ |
|
/** Maximum length+1 to expect with a drive device file address string */ |
|
#define BURN_DRIVE_ADR_LEN 1024 |
|
|
|
/* ts A70906 */ |
|
/** Inquire the device file address of the given drive. |
|
@param drive The drive to inquire. |
|
@param adr An application provided array of at least BURN_DRIVE_ADR_LEN |
|
characters size. The device file address gets copied to it. |
|
@return >0 success , <=0 error (due to libburn internal problem) |
|
@since 0.4.0 |
|
*/ |
|
int burn_drive_d_get_adr(struct burn_drive *drive, char adr[]); |
|
|
|
/* A60823 */ |
|
/** Inquire the device file address of a drive via a given drive_info object. |
|
(Note: This is a legacy call.) |
|
@param drive_info The drive to inquire.Usually some &(drive_infos[driveno]) |
|
@param adr An application provided array of at least BURN_DRIVE_ADR_LEN |
|
characters size. The device file address gets copied to it. |
|
@return >0 success , <=0 error (due to libburn internal problem) |
|
@since 0.2.6 |
|
*/ |
|
int burn_drive_get_adr(struct burn_drive_info *drive_info, char adr[]); |
|
|
|
|
|
/* ts A60922 ticket 33 */ |
|
/** Evaluate whether the given address would be a drive device file address |
|
which could be listed by a run of burn_drive_scan(). No check is made |
|
whether a device file with this address exists or whether it leads |
|
to a usable MMC drive. |
|
@return 1 means yes, 0 means no |
|
@since 0.2.6 |
|
*/ |
|
int burn_drive_is_enumerable_adr(char *adr); |
|
|
|
/* ts A60922 ticket 33 */ |
|
/** Try to convert a given existing filesystem address into a drive device file |
|
address. This succeeds with symbolic links or if a hint about the drive's |
|
system address can be read from the filesystem object and a matching drive |
|
is found. |
|
@param path The address of an existing file system object |
|
@param adr An application provided array of at least BURN_DRIVE_ADR_LEN |
|
characters size. The device file address gets copied to it. |
|
@return 1 = success , 0 = failure , -1 = severe error |
|
@since 0.2.6 |
|
*/ |
|
int burn_drive_convert_fs_adr(char *path, char adr[]); |
|
|
|
/* ts A60923 */ |
|
/** Try to convert a given SCSI address of bus,host,channel,target,lun into |
|
a drive device file address. If a SCSI address component parameter is < 0 |
|
then it is not decisive and the first enumerated address which matches |
|
the >= 0 parameters is taken as result. |
|
Note: bus and (host,channel) are supposed to be redundant. |
|
@param bus_no "Bus Number" (something like a virtual controller) |
|
@param host_no "Host Number" (something like half a virtual controller) |
|
@param channel_no "Channel Number" (other half of "Host Number") |
|
@param target_no "Target Number" or "SCSI Id" (a device) |
|
@param lun_no "Logical Unit Number" (a sub device) |
|
@param adr An application provided array of at least BURN_DRIVE_ADR_LEN |
|
characters size. The device file address gets copied to it. |
|
@return 1 = success , 0 = failure , -1 = severe error |
|
@since 0.2.6 |
|
*/ |
|
int burn_drive_convert_scsi_adr(int bus_no, int host_no, int channel_no, |
|
int target_no, int lun_no, char adr[]); |
|
|
|
/* ts B10728 */ |
|
/** Try to convert a given drive device file address into the address of a |
|
symbolic link that points to this drive address. |
|
Modern GNU/Linux systems may shuffle drive addresses from boot to boot. |
|
The udev daemon is supposed to create links which always point to the |
|
same drive, regardless of its system address. |
|
This call tries to find such links. |
|
@param dev_adr Should contain a drive address as returned by |
|
burn_drive_scan(). |
|
@param link_adr An application provided array of at least |
|
BURN_DRIVE_ADR_LEN characters size. The found link |
|
address gets copied to it. |
|
@param dir_adr The address of the directory where to look for links. |
|
Normally: "/dev" |
|
@param templ An array of pointers to name templates, which |
|
links have to match. A symbolic link in dir_adr matches |
|
a name template if it begins by that text. E.g. |
|
link address "/dev/dvdrw1" matches template "dvdrw". |
|
If templ is NULL, then the default array gets used: |
|
{"dvdrw", "cdrw", "dvd", "cdrom", "cd"} |
|
If several links would match, then a link will win, |
|
which matches the template with the lowest array index. |
|
Among these candidates, the one with the lowest strcmp() |
|
rank will be chosen as link_adr. |
|
@param num_templ Number of array elements in templ. |
|
@param flag Bitfield for control purposes. Unused yet. Submit 0. |
|
@return <0 severe error, 0 failed to search, 2 nothing found |
|
1 success, link_adr is valid |
|
@since 1.1.4 |
|
*/ |
|
int burn_lookup_device_link(char *dev_adr, char link_adr[], |
|
char *dir_adr, char **templ, int num_templ, int flag); |
|
|
|
/* ts A60923 - A61005 */ |
|
/** Try to obtain bus,host,channel,target,lun from path. If there is an SCSI |
|
address at all, then this call should succeed with a drive device file |
|
address obtained via burn_drive_d_get_adr(). It is also supposed to |
|
succeed with any device file of a (possibly emulated) SCSI device. |
|
@return 1 = success , 0 = failure , -1 = severe error |
|
@since 0.2.6 |
|
*/ |
|
int burn_drive_obtain_scsi_adr(char *path, int *bus_no, int *host_no, |
|
int *channel_no, int *target_no, int *lun_no); |
|
|
|
/** Grab a drive. This must be done before the drive can be used (for reading, |
|
writing, etc). |
|
@param drive The drive to grab. This is found in a returned |
|
burn_drive_info struct. |
|
@param load Nonzero to make the drive attempt to load a disc (close its |
|
tray door, etc). |
|
@return 1 if it was possible to grab the drive, else 0 |
|
*/ |
|
int burn_drive_grab(struct burn_drive *drive, int load); |
|
|
|
/* ts B00114 */ |
|
/* Probe available CD write modes and block types. In earlier versions this |
|
was done unconditionally on drive examination or aquiration. But it is |
|
lengthy and obtrusive, up to spoiling burn runs on the examined drives. |
|
So now this probing is omitted by default. All drives which announce to be |
|
capable of CD or DVD writing, get blindly attributed the capability for |
|
SAO and TAO. Applications which are interested in RAW modes or want to |
|
rely on the traditional write mode information, may use this call. |
|
@param drive_info drive object to be inquired |
|
@return >0 indicates success, <=0 means failure |
|
@since 0.7.6 |
|
*/ |
|
int burn_drive_probe_cd_write_modes(struct burn_drive_info *drive_info); |
|
|
|
/* ts A90824 */ |
|
/** Calm down or alert a drive. Some drives stay alert after reading for |
|
quite some time. This saves time with the startup for the next read |
|
operation but also causes noise and consumes extra energy. It makes |
|
sense to calm down the drive if no read operation is expected for the |
|
next few seconds. The drive will get alert automatically if operations |
|
are required. |
|
@param d The drive to influence. |
|
@param flag Bitfield for control purposes |
|
bit0= become alert (else start snoozing) |
|
This is not mandatory for further drive operations |
|
@return 1= success , 0= drive role not suitable for calming |
|
@since 0.7.0 |
|
*/ |
|
int burn_drive_snooze(struct burn_drive *d, int flag); |
|
|
|
|
|
/** Re-assess drive and media status. This should be done after a drive |
|
underwent a status change and shall be further used without intermediate |
|
burn_drive_release(), burn_drive_grab(). E.g. after blanking or burning. |
|
@param d The already grabbed drive to re-assess. |
|
@param flag Unused yet. Submit 0. |
|
@return 1 success , <= 0 could not determine drive and media state |
|
@since 1.1.8 |
|
*/ |
|
int burn_drive_re_assess(struct burn_drive *d, int flag); |
|
|
|
|
|
/** Release a drive. This should not be done until the drive is no longer |
|
busy (see burn_drive_get_status). |
|
@param drive The drive to release. |
|
@param eject Nonzero to make the drive eject the disc in it. |
|
*/ |
|
void burn_drive_release(struct burn_drive *drive, int eject); |
|
|
|
|
|
/* ts A70918 */ |
|
/** Like burn_drive_release() but keeping the drive tray closed and its |
|
eject button disabled. This physically locked drive state will last until |
|
the drive is grabbed again and released via burn_drive_release(). |
|
Programs like eject, cdrecord, growisofs will break that ban too. |
|
@param d The drive to release and leave locked. |
|
@param flag Bitfield for control purposes (unused yet, submit 0) |
|
@return 1 means success, <=0 means failure |
|
@since 0.4.0 |
|
*/ |
|
int burn_drive_leave_locked(struct burn_drive *d, int flag); |
|
|
|
|
|
/** Returns what kind of disc a drive is holding. This function may need to be |
|
called more than once to get a proper status from it. See burn_disc_status |
|
for details. |
|
@param drive The drive to query for a disc. |
|
@return The status of the drive, or what kind of disc is in it. |
|
Note: BURN_DISC_UNGRABBED indicates wrong API usage |
|
*/ |
|
enum burn_disc_status burn_disc_get_status(struct burn_drive *drive); |
|
|
|
|
|
/* ts A61020 */ |
|
/** WARNING: This revives an old bug-like behavior that might be dangerous. |
|
Sets the drive status to BURN_DISC_BLANK if it is BURN_DISC_UNREADY |
|
or BURN_DISC_UNSUITABLE. Thus marking media as writable which actually |
|
failed to declare themselves either blank or (partially) filled. |
|
@return 1 drive status has been set , 0 = unsuitable drive status |
|
@since 0.2.6 |
|
*/ |
|
int burn_disc_pretend_blank(struct burn_drive *drive); |
|
|
|
|
|
/* ts A61106 */ |
|
/** WARNING: This overrides the safety measures against unsuitable media. |
|
Sets the drive status to BURN_DISC_FULL if it is BURN_DISC_UNREADY |
|
or BURN_DISC_UNSUITABLE. Thus marking media as blankable which actually |
|
failed to declare themselves either blank or (partially) filled. |
|
@since 0.2.6 |
|
*/ |
|
int burn_disc_pretend_full(struct burn_drive *drive); |
|
|
|
|
|
/* ts B31110 */ |
|
/** WARNING: This overrides the safety measures against unsuitable media. |
|
Sets the drive status to BURN_DISC_FULL unconditionally. |
|
@since 1.3.4 |
|
*/ |
|
int burn_disc_pretend_full_uncond(struct burn_drive *drive); |
|
|
|
|
|
/* ts B51016 */ |
|
/** Returns the Drive Serial Number as of MMC feature 108h. |
|
@param d The drive to inquire. |
|
@param sno Returns the bytes of the serial number. A trailing 0-byte |
|
is appended for convenience. MMC specifies ASCII 0x20 to |
|
0x7h as possible byte values. But given drive firmware |
|
habits there is no warranty that *sno contains no other |
|
byte values. |
|
Submit *sno as NULL or pointing to free()-able memory. |
|
Apply free() to *sno when no longer needed. |
|
@param sno_len Returns the number of valid bytes in returned *sno, |
|
not counting the appended trailing 0. |
|
@return 1= success (but maybe *sno_len is 0), <= 0 severe failure |
|
@since 1.4.2 |
|
*/ |
|
int burn_drive_get_serial_no(struct burn_drive *d, char **sno, int *sno_len); |
|
|
|
|
|
/* ts B51016 */ |
|
/** Returns the Media Serial Number as of MMC feature 109h and command ABh |
|
READ MEDIA SERIAL NUMBER. |
|
|
|
Note: This call will return an empty result unless the macro |
|
Libburn_enable_scsi_cmd_ABh |
|
is defined at compile time. |
|
This is because the command READ MEDIA SERIAL NUMBER demands |
|
superuser authority on Linux, because no medium with serial number |
|
could be tested yet, and because this command made one of the test |
|
drives unusable until power cycle when it was executed despite |
|
feature 109h was not announced as "current". |
|
|
|
@param d The drive to inquire. |
|
@param sno Returns the bytes of the serial number. A trailing 0-byte |
|
is appended for convenience. There is no warranty that |
|
*sno contains only non-zero printable bytes. |
|
Submit *sno as NULL or pointing to free()-able memory. |
|
Apply free() to *sno when no longer needed. |
|
@param sno_len Returns the number of valid bytes in returned *sno, |
|
not counting the appended trailing 0. |
|
@return 1= success (but maybe *sno_len is 0), <= 0 severe failure |
|
@since 1.4.2 |
|
*/ |
|
int burn_drive_get_media_sno(struct burn_drive *d, char **sno, int *sno_len); |
|
|
|
|
|
/* ts A61021 */ |
|
/** Reads ATIP information from inserted media. To be obtained via |
|
burn_drive_get_write_speed(), burn_drive_get_min_write_speed(), |
|
burn_drive_get_start_end_lba(). The drive must be grabbed for this call. |
|
@param drive The drive to query. |
|
@return 1=success, 0=no valid ATIP info read, -1 severe error |
|
@since 0.2.6 |
|
*/ |
|
int burn_disc_read_atip(struct burn_drive *drive); |
|
|
|
|
|
/* ts B70206 */ |
|
/** Tells whether a BD-R medium with Pseudo Overwrite (POW) formatting is in |
|
the drive. Such a formatting may have been applied by dvd+rw-tools. It |
|
prevents sequential multi-session. |
|
libburn will refuse to write to such a medium. |
|
@param drive The drive to query. |
|
@return 1 if BD-R Pseudo Overwrite , 0 if not BD-R or not POW |
|
@since 1.4.8 |
|
*/ |
|
int burn_drive_get_bd_r_pow(struct burn_drive *drive); |
|
|
|
|
|
/* ts A61020 */ |
|
/** Returns start and end lba of the media which is currently inserted |
|
in the given drive. The drive has to be grabbed to have hope for reply. |
|
Shortcomming (not a feature): unless burn_disc_read_atip() was called |
|
only blank media will return valid info. |
|
@param drive The drive to query. |
|
@param start_lba Returns the start lba value |
|
@param end_lba Returns the end lba value |
|
@param flag Bitfield for control purposes (unused yet, submit 0) |
|
@return 1 if lba values are valid , 0 if invalid |
|
@since 0.2.6 |
|
*/ |
|
int burn_drive_get_start_end_lba(struct burn_drive *drive, |
|
int *start_lba, int *end_lba, int flag); |
|
|
|
|
|
/* ts A90902 */ |
|
/** Guess the manufacturer name of CD media from the ATIP addresses of lead-in |
|
and lead-out. (Currently only lead-in is interpreted. Lead-out may in |
|
future be used to identify the media type in more detail.) |
|
The parameters of this call should be obtained by burn_disc_read_atip(d), |
|
burn_drive_get_start_end_lba(d, &start_lba, &end_lba, 0), |
|
burn_lba_to_msf(start_lba, &m_li, &s_li, &f_li) and |
|
burn_lba_to_msf(end_lba, &m_lo, &s_lo, &f_lo). |
|
@param m_li "minute" part of ATIP lead-in or start_lba |
|
@param s_li "second" of lead-in or start_lba |
|
@param f_li "frame" of lead-in |
|
@param m_lo "minute" part of ATIP lead-out |
|
@param s_lo "second" of lead-out |
|
@param f_lo "frame" of lead-out |
|
@param flag Bitfield for control purposes, |
|
bit0= append a text "(aka ...)" to reply if other brands or |
|
vendor names are known. |
|
@return Printable text or NULL on memory shortage. |
|
Dispose by free() when no longer needed. |
|
@since 0.7.2 |
|
*/ |
|
char *burn_guess_cd_manufacturer(int m_li, int s_li, int f_li, |
|
int m_lo, int s_lo, int f_lo, int flag); |
|
|
|
/* ts A90909 */ |
|
/** Retrieve some media information which is mainly specific to CD. For other |
|
media only the bits in reply parameter valid are supposed to be meaningful. |
|
@param d The drive to query. |
|
@param disc_type A string saying either "CD-DA or CD-ROM", or "CD-I", |
|
or ""CD-ROM XA", or "undefined". |
|
@param disc_id A 32 bit number read from the media. (Meaning unclear yet) |
|
@param bar_code 8 hex digits from a barcode on media read by the drive |
|
(if the drive has a bar code reader built in). |
|
@param app_code The Host Application Code which must be set in the Write |
|
Parameters Page if the media is not unrestricted (URU==0). |
|
@param valid Replies bits which indicate the validity of other reply |
|
parameters or the state of certain CD info bits: |
|
bit0= disc_type is valid |
|
bit1= disc_id is valid |
|
bit2= bar_code is valid |
|
bit3= disc_app_code is valid |
|
bit4= Disc is unrestricted (URU bit, 51h READ DISC INFO) |
|
This seems to be broken with my drives. The bit is |
|
0 and the validity bit for disc_app_code is 0 too. |
|
bit5= Disc is nominally erasable (Erasable bit) |
|
This will be set with overwriteable media which |
|
libburn normally considers to be unerasable blank. |
|
@return 1 success, <= 0 an error occurred |
|
@since 0.7.2 |
|
*/ |
|
int burn_disc_get_cd_info(struct burn_drive *d, char disc_type[80], |
|
unsigned int *disc_id, char bar_code[9], int *app_code, |
|
int *valid); |
|
|
|
/* ts B11201 */ |
|
/** Read the array of CD-TEXT packs from the Lead-in of an audio CD. |
|
Each pack consists of 18 bytes, of which 4 are header. 12 bytes are pieces |
|
of 0-terminated texts or binary data. 2 bytes hold a CRC. |
|
For a description of the format of the array, see file doc/cdtext.txt. |
|
@param d The drive to query. |
|
@param text_packs Will point to an allocated memory buffer with CD-TEXT. |
|
It will only contain text packs, and not be prepended |
|
by the TOC header of four bytes, which gets stored with |
|
file cdtext.dat by cdrecord -vv -toc. (The first two of |
|
these bytes are supposed to hold the number of CD-TEXT |
|
bytes + 2. The other two bytes are supposed to be 0.) |
|
Dispose this buffer by free(), when no longer needed. |
|
@param num_packs Will tell the number of text packs, i.e. the number of |
|
bytes in text_packs divided by 18. |
|
@param flag Bitfield for control purposes, |
|
Unused yet. Submit 0. |
|
@return 1 success, 0= no CD-TEXT found, < 0 an error occurred |
|
@since 1.2.0 |
|
*/ |
|
int burn_disc_get_leadin_text(struct burn_drive *d, |
|
unsigned char **text_packs, int *num_packs, |
|
int flag); |
|
|
|
/* ts B00924 */ |
|
/** Read the current usage of the eventual BD Spare Area. This area gets |
|
reserved on BD media during formatting. During writing it is used to |
|
host replacements of blocks which failed the checkread immediately after |
|
writing. |
|
This call applies only to recordable BD media. I.e. profiles 0x41 to 0x43. |
|
@param d The drive to query. |
|
@param alloc_blocks Returns the number of blocks reserved as Spare Area |
|
@param free_blocks Returns the number of yet unused blocks in that area |
|
@param flag Bitfield for control purposes (unused yet, submit 0) |
|
@return 1 = reply prarameters are valid, |
|
<=0 = reply is invalid (e.g. because no BD profile) |
|
@since 0.8.8 |
|
*/ |
|
int burn_disc_get_bd_spare_info(struct burn_drive *d, |
|
int *alloc_blocks, int *free_blocks, int flag); |
|
|
|
/* ts B10801 */ |
|
/** Retrieve some media information which is mainly specific to media of |
|
the DVD-R family: DVD-R , DVD-RW , DVD-R DL , HD DVD-R |
|
Currently the information cannot be retrieved from other media types. |
|
@param d The drive to query. |
|
@param disk_category returns DVD Book to which the media complies |
|
@param book_name returns a pointer to the book name of disk_category. |
|
This memory is static. Do not alter or free it ! |
|
@param part_version returns the Media Version in the DVD Book |
|
@param num_layers returns the number of media layers |
|
@param num_blocks returns the number of blocks between pysical start |
|
and physical end of the media |
|
@param flag Bitfield for control purposes (unused yet, submit 0) |
|
@return 1 = reply prarameters are valid, |
|
<=0 = reply is invalid (e.g. because no DVD-R) |
|
@since 1.1.4 |
|
*/ |
|
int burn_disc_get_phys_format_info(struct burn_drive *d, int *disk_category, |
|
char **book_name, int *part_version, int *num_layers, |
|
int *num_blocks, int flag); |
|
|
|
/* ts A61110 */ |
|
/** Read start lba and Next Writeable Address of a track from media. |
|
Usually a track lba is obtained from the result of burn_track_get_entry(). |
|
This call retrieves an updated lba, eventual nwa, and can address the |
|
invisible track to come. |
|
The drive must be grabbed for this call. One may not issue this call |
|
during ongoing burn_disc_write() or burn_disc_erase(). |
|
@param d The drive to query. |
|
@param o If not NULL: write parameters to be set on drive before query |
|
@param trackno 0=next track to come, >0 number of existing track |
|
The first existing track on a CD may have a number higher |
|
than 1. Use burn_session_get_start_tno() to inquire this |
|
start number. |
|
@param lba return value: start lba |
|
@param nwa return value: Next Writeable Address |
|
@return 1=nwa is valid , 0=nwa is not valid , -1=error |
|
@since 0.2.6 |
|
*/ |
|
int burn_disc_track_lba_nwa(struct burn_drive *d, struct burn_write_opts *o, |
|
int trackno, int *lba, int *nwa); |
|
|
|
/* ts B10525 */ |
|
/** Tells whether a previous attempt to determine the Next Writeable Address |
|
of the upcoming track reveiled that the READ TRACK INFORMATION Damage Bit |
|
is set for this track and that no valid writable address is available. |
|
See MMC-5 6.27.3.7 Damage Bit, 6.27.3.11 NWA_V (NWA valid) |
|
@param d The drive to query. |
|
@param flag Bitfield for control purposes (unused yet, submit 0) |
|
@return 0= Looks ok: Damage Bit is not set, NWA_V is set |
|
1= Damaged and theoretically writable (NWA_V is set) |
|
2= Not writable: NWA_V is not set |
|
3= Damaged and not writable (NWA_V is not set), |
|
@since 1.1.0 |
|
*/ |
|
int burn_disc_next_track_is_damaged(struct burn_drive *d, int flag); |
|
|
|
/* ts B10527 */ |
|
/** Try to close the last track and session of media which have bit0 set in |
|
the return value of call burn_disc_next_track_is_damaged(). |
|
Whether it helps depends much on the reason why the media is reported |
|
as damaged by the drive. |
|
This call works only for profiles 0x09 CD-R, 0x0a CD-RW, 0x11 DVD-R, |
|
0x14 DVD-RW sequential, 0x1b DVD+R, 0x2b DVD+R DL, 0x41 BD-R sequential. |
|
Note: After writing it is advised to give up the drive and to grab it again |
|
in order to learn about its view on the new media state. |
|
@param o Write options created by burn_write_opts_new() and |
|
manipulated by burn_write_opts_set_multi(). |
|
burn_write_opts_set_write_type() should be set to |
|
BURN_WRITE_TAO, burn_write_opts_set_simulate() should be |
|
set to 0. |
|
@param flag Bitfield for control purposes |
|
bit0= force close, even if no damage was seen |
|
@return <=0 media not marked as damaged, or media type not suitable, |
|
or closing attempted but failed |
|
1= attempt finished without error indication |
|
@since 1.1.0 |
|
*/ |
|
int burn_disc_close_damaged(struct burn_write_opts *o, int flag); |
|
|
|
|
|
/* ts A70131 */ |
|
/** Read start lba of the first track in the last complete session. |
|
This is the first parameter of mkisofs option -C. The second parameter |
|
is nwa as obtained by burn_disc_track_lba_nwa() with trackno 0. |
|
@param d The drive to query. |
|
@param start_lba returns the start address of that track |
|
@return <= 0 : failure, 1 = ok |
|
@since 0.3.2 |
|
*/ |
|
int burn_disc_get_msc1(struct burn_drive *d, int *start_lba); |
|
|
|
|
|
/* ts A70213 */ |
|
/** Return the best possible estimation of the currently available capacity of |
|
the media. This might depend on particular write option settings. For |
|
inquiring the space with such a set of options, the drive has to be |
|
grabbed and BURN_DRIVE_IDLE. If not, then one will only get a canned value |
|
from the most recent automatic inquiry (e.g. during last drive grabbing). |
|
An eventual start address from burn_write_opts_set_start_byte() will be |
|
taken into respect with the capacity estimation. Negative results get |
|
defaulted to 0. |
|
If the drive is actually a file in a large filesystem or a large block |
|
device, then the capacity is curbed to a maximum of 0x7ffffff0 blocks |
|
= 4 TB - 32 KB. |
|
@param d The drive to query. |
|
@param o If not NULL: write parameters to be set on drive before query |
|
@return number of most probably available free bytes |
|
@since 0.3.4 |
|
*/ |
|
off_t burn_disc_available_space(struct burn_drive *d, |
|
struct burn_write_opts *o); |
|
|
|
/* ts A61202 */ |
|
/** Tells the MMC Profile identifier of the loaded media. The drive must be |
|
grabbed in order to get a non-zero result. |
|
libburn currently writes only to profiles |
|
0x09 "CD-R" |
|
0x0a "CD-RW" |
|
0x11 "DVD-R sequential recording" |
|
0x12 "DVD-RAM" |
|
0x13 "DVD-RW restricted overwrite" |
|
0x14 "DVD-RW sequential recording", |
|
0x15 "DVD-R/DL sequential recording", |
|
0x1a "DVD+RW" |
|
0x1b "DVD+R", |
|
0x2b "DVD+R/DL", |
|
0x41 "BD-R sequential recording", |
|
0x43 "BD-RE", |
|
0xffff "stdio file" |
|
Note: 0xffff is not a MMC profile but a libburn invention. |
|
Read-only are the profiles |
|
0x08 "CD-ROM", |
|
0x10 "DVD-ROM", |
|
0x40 "BD-ROM", |
|
Read-only for now is this BD-R profile (testers wanted) |
|
0x42 "BD-R random recording" |
|
Empty drives are supposed to report |
|
0x00 "" |
|
@param d The drive where the media is inserted. |
|
@param pno Profile Number. See also mmc5r03c.pdf, table 89 |
|
@param name Profile Name (see above list, unknown profiles have empty name) |
|
@return 1 profile is valid, 0 no profile info available |
|
@since 0.3.0 |
|
*/ |
|
int burn_disc_get_profile(struct burn_drive *d, int *pno, char name[80]); |
|
|
|
|
|
/* ts A90903 : API */ |
|
/** Obtain product id and standards defined media codes. |
|
The product id is a printable string which is supposed to be the same |
|
for identical media but should vary with non-identical media. Some media |
|
cannot provide such an id at all. |
|
The pair (profile_number, product_id) should be the best id to identify |
|
media with identical product specifications. |
|
The reply parameters media_code1 and media_code2 can be used with |
|
burn_guess_manufacturer() |
|
The reply parameters have to be disposed by free() when no longer needed. |
|
@param d The drive where the media is inserted. |
|
@param product_id Reply: Printable text depicting manufacturer and |
|
eventually media id. |
|
@param media_code1 Reply: The eventual manufacturer identification as read |
|
from DVD/BD media or a text "XXmYYsZZf" from CD media |
|
ATIP lead-in. |
|
@param media_code2 The eventual media id as read from DVD+/BD media or a |
|
text "XXmYYsZZf" from CD ATIP lead-out. |
|
@param book_type Book type text for DVD and BD. |
|
Caution: is NULL with CD, even if return value says ok. |
|
@param flag Bitfield for control purposes |
|
bit0= do not escape " _/" (not suitable for |
|
burn_guess_manufacturer()) |
|
@return 1= ok, product_id and media codes are valid, |
|
0= no product id_available, reply parameters are NULL |
|
<0= error |
|
@since 0.7.2 |
|
*/ |
|
int burn_disc_get_media_id(struct burn_drive *d, |
|
char **product_id, char **media_code1, char **media_code2, |
|
char **book_type, int flag); |
|
|
|
|
|
/* ts A90904 */ |
|
/** Guess the name of a manufacturer by profile number, manufacturer code |
|
and media code. The profile number can be obtained by |
|
burn_disc_get_profile(), the other two parameters can be obtained as |
|
media_code1 and media_code2 by burn_disc_get_media_id(). |
|
@param profile_no Profile number (submit -1 if not known) |
|
@param manuf_code Manufacturer code from media (e.g. "RICOHJPN") |
|
@param media_code Media ID code from media (e.g. "W11") |
|
@param flag Bitfield for control purposes, submit 0 |
|
@return Printable text or NULL on memory shortage. |
|
If the text begins with "Unknown " then no item of the |
|
manufacturer list matched the codes. |
|
Dispose by free() when no longer needed. |
|
@since 0.7.2 |
|
*/ |
|
char *burn_guess_manufacturer(int profile_no, |
|
char *manuf_code, char *media_code, int flag); |
|
|
|
|
|
/** Tells whether a disc can be erased or not |
|
@param d The drive to inquire. |
|
@return Non-zero means erasable |
|
*/ |
|
int burn_disc_erasable(struct burn_drive *d); |
|
|
|
/** Returns the progress and status of a drive. |
|
@param drive The drive to query busy state for. |
|
@param p Returns the progress of the operation, NULL if you don't care |
|
@return the current status of the drive. See also burn_drive_status. |
|
*/ |
|
enum burn_drive_status burn_drive_get_status(struct burn_drive *drive, |
|
struct burn_progress *p); |
|
|
|
/** Creates a write_opts struct for burning to the specified drive. |
|
The returned object must later be freed with burn_write_opts_free(). |
|
@param drive The drive to write with |
|
@return The write_opts, NULL on error |
|
*/ |
|
struct burn_write_opts *burn_write_opts_new(struct burn_drive *drive); |
|
|
|
|
|
/* ts A70901 */ |
|
/** Inquires the drive associated with a burn_write_opts object. |
|
@param opts object to inquire |
|
@return pointer to drive |
|
@since 0.4.0 |
|
*/ |
|
struct burn_drive *burn_write_opts_get_drive(struct burn_write_opts *opts); |
|
|
|
|
|
/** Frees a write_opts struct created with burn_write_opts_new |
|
@param opts write_opts to free |
|
*/ |
|
void burn_write_opts_free(struct burn_write_opts *opts); |
|
|
|
/** Creates a read_opts struct for reading from the specified drive |
|
must be freed with burn_read_opts_free |
|
@param drive The drive to read from |
|
@return The read_opts |
|
*/ |
|
struct burn_read_opts *burn_read_opts_new(struct burn_drive *drive); |
|
|
|
/** Frees a read_opts struct created with burn_read_opts_new |
|
@param opts write_opts to free |
|
*/ |
|
void burn_read_opts_free(struct burn_read_opts *opts); |
|
|
|
/** Erase a disc in the drive. The drive must be grabbed successfully BEFORE |
|
calling this functions. Always ensure that the drive reports a status of |
|
BURN_DISC_FULL before calling this function. An erase operation is not |
|
cancellable, as control of the operation is passed wholly to the drive and |
|
there is no way to interrupt it safely. |
|
@param drive The drive with which to erase a disc. |
|
Only drive roles 1 (MMC) and 5 (stdio random write-only) |
|
support erasing. |
|
@param fast Nonzero to do a fast erase, where only the disc's headers are |
|
erased; zero to erase the entire disc. |
|
With DVD-RW, fast blanking yields media capable only of DAO. |
|
*/ |
|
void burn_disc_erase(struct burn_drive *drive, int fast); |
|
|
|
|
|
/* ts A70101 - A70417 */ |
|
/** Format media for use with libburn. This currently applies to DVD-RW |
|
in state "Sequential Recording" (profile 0014h) which get formatted to |
|
state "Restricted Overwrite" (profile 0013h). DVD+RW can be "de-iced" |
|
by setting bit4 of flag. DVD-RAM and BD-RE may get formatted initially |
|
or re-formatted to adjust their Defect Management. |
|
This function usually returns while the drive is still in the process |
|
of formatting. The formatting is done, when burn_drive_get_status() |
|
returns BURN_DRIVE_IDLE. This may be immediately after return or may |
|
need several thousand seconds to occur. |
|
@param drive The drive with the disc to format. |
|
@param size The size in bytes to be used with the format command. It should |
|
be divisible by 32*1024. The effect of this parameter may |
|
depend on the media profile and on parameter flag. |
|
@param flag Bitfield for control purposes: |
|
bit0= after formatting, write the given number of zero-bytes |
|
to the media and eventually perform preliminary closing. |
|
bit1+2: size mode |
|
0 = use parameter size as far as it makes sense |
|
1 = insist in size 0 even if there is a better default known |
|
(on DVD-RAM or BD-R identical to size mode 0, |
|
i.e. they never get formatted with payload size 0) |
|
2 = without bit7: format to maximum available size |
|
with bit7 : take size from indexed format descriptor |
|
3 = without bit7: format to default size |
|
with bit7 : take size from indexed format descriptor |
|
bit3= -reserved- |
|
bit4= enforce re-format of (partly) formatted media |
|
bit5= try to disable eventual defect management |
|
bit6= try to avoid lengthy media certification |
|
bit7, bit8 to bit15 = |
|
bit7 enables MMC expert application mode (else libburn |
|
tries to choose a suitable format type): |
|
If it is set then bit8 to bit15 contain the index of |
|
the format to use. See burn_disc_get_formats(), |
|
burn_disc_get_format_descr(). |
|
Acceptable types are: 0x00, 0x01, 0x10, 0x11, 0x13, |
|
0x15, 0x26, 0x30, 0x31, 0x32. |
|
If bit7 is set, then bit4 is set automatically. |
|
bit16= enable POW on blank BD-R |
|
@since 0.3.0 |
|
*/ |
|
void burn_disc_format(struct burn_drive *drive, off_t size, int flag); |
|
|
|
|
|
/* ts A70112 */ |
|
/* @since 0.3.0 */ |
|
/** Possible formatting status values */ |
|
#define BURN_FORMAT_IS_UNFORMATTED 1 |
|
#define BURN_FORMAT_IS_FORMATTED 2 |
|
#define BURN_FORMAT_IS_UNKNOWN 3 |
|
|
|
/* ts A70112 */ |
|
/** Inquire the formatting status, the associated sizes and the number of |
|
available formats. The info is media specific and stems from MMC command |
|
23h READ FORMAT CAPACITY. See mmc5r03c.pdf 6.24 for background details. |
|
Media type can be determined via burn_disc_get_profile(). |
|
@param drive The drive with the disc to format. |
|
@param status The current formatting status of the inserted media. |
|
See BURN_FORMAT_IS_* macros. Note: "unknown" is the |
|
legal status for quick formatted, yet unwritten DVD-RW. |
|
@param size The size in bytes associated with status. |
|
unformatted: the maximum achievable size of the media |
|
formatted: the currently formatted capacity |
|
unknown: maximum capacity of drive or of media |
|
@param bl_sas Additional info "Block Length/Spare Area Size". |
|
Expected to be constantly 2048 for non-BD media. |
|
@param num_formats The number of available formats. To be used with |
|
burn_disc_get_format_descr() to obtain such a format |
|
and eventually with burn_disc_format() to select one. |
|
@return 1 reply is valid , <=0 failure |
|
@since 0.3.0 |
|
*/ |
|
int burn_disc_get_formats(struct burn_drive *drive, int *status, off_t *size, |
|
unsigned *bl_sas, int *num_formats); |
|
|
|
/* ts A70112 */ |
|
/** Inquire parameters of an available media format. |
|
@param drive The drive with the disc to format. |
|
@param index The index of the format item. Beginning with 0 up to reply |
|
parameter from burn_disc_get_formats() : num_formats - 1 |
|
@param type The format type. See mmc5r03c.pdf, 6.5, 04h FORMAT UNIT. |
|
0x00=full, 0x10=CD-RW/DVD-RW full, 0x11=CD-RW/DVD-RW grow, |
|
0x15=DVD-RW quick, 0x13=DVD-RW quick grow, |
|
0x26=DVD+RW background, 0x30=BD-RE with spare areas, |
|
0x31=BD-RE without spare areas |
|
@param size The maximum size in bytes achievable with this format. |
|
@param tdp Type Dependent Parameter. See mmc5r03c.pdf. |
|
@return 1 reply is valid , <=0 failure |
|
@since 0.3.0 |
|
*/ |
|
int burn_disc_get_format_descr(struct burn_drive *drive, int index, |
|
int *type, off_t *size, unsigned *tdp); |
|
|
|
|
|
|
|
/* ts A61109 : this was and is defunct */ |
|
/** Read a disc from the drive and write it to an fd pair. The drive must be |
|
grabbed successfully BEFORE calling this function. Always ensure that the |
|
drive reports a status of BURN_DISC_FULL before calling this function. |
|
@param drive The drive from which to read a disc. |
|
@param o The options for the read operation. |
|
*/ |
|
void burn_disc_read(struct burn_drive *drive, const struct burn_read_opts *o); |
|
|
|
|
|
|
|
/* ts A70222 */ |
|
/* @since 0.3.4 */ |
|
/** The length of a rejection reasons string for burn_precheck_write() and |
|
burn_write_opts_auto_write_type() . |
|
*/ |
|
#define BURN_REASONS_LEN 4096 |
|
|
|
|
|
/* ts A70219 */ |
|
/** Examines a completed setup for burn_disc_write() whether it is permissible |
|
with drive and media. This function is called by burn_disc_write() but |
|
an application might be interested in this check in advance. |
|
@param o The options for the writing operation. |
|
@param disc The descrition of the disc to be created |
|
@param reasons Eventually returns a list of rejection reason statements |
|
@param silent 1= do not issue error messages , 0= report problems |
|
@return 1 ok, -1= no recordable media detected, 0= other failure |
|
@since 0.3.4 |
|
*/ |
|
int burn_precheck_write(struct burn_write_opts *o, struct burn_disc *disc, |
|
char reasons[BURN_REASONS_LEN], int silent); |
|
|
|
|
|
/** Write a disc in the drive. The drive must be grabbed successfully before |
|
calling this function. Always ensure that the drive reports a status of |
|
BURN_DISC_BLANK ot BURN_DISC_APPENDABLE before calling this function. |
|
Note: write_type BURN_WRITE_SAO is currently not capable of writing a mix |
|
of data and audio tracks. You must use BURN_WRITE_TAO for such sessions. |
|
To be set by burn_write_opts_set_write_type(). |
|
Note: This function is not suitable for overwriting data in the middle of |
|
a valid data area because it is allowed to append trailing data. |
|
For exact random access overwriting use burn_random_access_write(). |
|
Note: After writing it is advised to give up the drive and to grab it again |
|
in order to learn about its view on the new media state. |
|
Note: Before mounting the written media it might be necessary to eject |
|
and reload in order to allow the operating system to notice the new |
|
media state. |
|
@param o The options for the writing operation. |
|
@param disc The struct burn_disc * that described the disc to be created |
|
*/ |
|
void burn_disc_write(struct burn_write_opts *o, struct burn_disc *disc); |
|
|
|
|
|
/* ts A90227 */ |
|
/** Control stream recording during the write run and eventually set the start |
|
LBA for stream recording. |
|
Stream recording is set from struct burn_write_opts when the write run |
|
gets started. See burn_write_opts_set_stream_recording(). |
|
The call described here can be used later to override this setting and |
|
to program automatic switching at a given LBA. It also affects subsequent |
|
calls to burn_random_access_write(). |
|
@param drive The drive which performs the write operation. |
|
@param recmode -1= disable stream recording |
|
0= leave setting as is |
|
1= enable stream recording |
|
@param start The LBA where actual stream recording shall start. |
|
(0 means unconditional stream recording) |
|
@param flag Bitfield for control purposes (unused yet, submit 0). |
|
@return 1=success , <=0 failure |
|
@since 0.6.4 |
|
*/ |
|
int burn_drive_set_stream_recording(struct burn_drive *drive, int recmode, |
|
int start, int flag); |
|
|
|
|
|
/* ts B60730 */ |
|
/** Enable or disable use of the Immed bit with long running SCSI commands. |
|
If the Immed bit is used, then those SCSI commands end early and leave |
|
the drive in not-ready state. libburn then tries periodically whether |
|
the drive became ready again. Only then it assumes the command to be |
|
completely done. |
|
The default setting may depend on the operating system on which libburn |
|
was compiled. |
|
@param drive The drive which will be affected. |
|
@param enable 1= use Immed bit. |
|
0= use no Immed bit. Affected commands can last very long. |
|
@return 1=success , <=0 failure |
|
@since 1.4.6 |
|
*/ |
|
int burn_drive_set_immed(struct burn_drive *drive, int enable); |
|
|
|
|
|
/* ts B60730 */ |
|
/** Inquire the current setting of usage of the Immed bit. Either the still set |
|
system dependent default or the value set by call burn_drive_set_immed(). |
|
@return The current value. |
|
@since 1.4.6 |
|
*/ |
|
int burn_drive_get_immed(struct burn_drive *drive); |
|
|
|
|
|
/** Cancel an operation on a drive. |
|
This will only work when the drive's busy state is BURN_DRIVE_READING or |
|
BURN_DRIVE_WRITING. |
|
@param drive The drive on which to cancel the current operation. |
|
*/ |
|
void burn_drive_cancel(struct burn_drive *drive); |
|
|
|
|
|
/* ts A61223 */ |
|
/** Inquire whether the most recent asynchronous media job was successful. |
|
This applies to burn_disc_erase(), burn_disc_format(), burn_disc_write(). |
|
Reasons for non-success may be: rejection of burn parameters, abort due to |
|
fatal errors during write, blank or format, a call to burn_drive_cancel() |
|
by the application thread. |
|
@param d The drive to inquire. |
|
@return 1=burn seems to have went well, 0=burn failed |
|
@since 0.2.6 |
|
*/ |
|
int burn_drive_wrote_well(struct burn_drive *d); |
|
|
|
|
|
/* ts B31023 */ |
|
/** Inquire whether a write error occurred which is suspected to have happened |
|
due to a false report about DVD-RW capability to be written in write type |
|
BURN_WRITE_TAO. |
|
@param d The drive to inquire. |
|
@return 1= it seems that BURN_WRITE_TAO on DVD-RW caused error, |
|
0= it does not seem so |
|
@since 1.3.4 |
|
*/ |
|
int burn_drive_was_feat21_failure(struct burn_drive *d); |
|
|
|
|
|
/** Convert a minute-second-frame (MSF) value to sector count |
|
@param m Minute component |
|
@param s Second component |
|
@param f Frame component |
|
@return The sector count |
|
*/ |
|
int burn_msf_to_sectors(int m, int s, int f); |
|
|
|
/** Convert a sector count to minute-second-frame (MSF) |
|
@param sectors The sector count |
|
@param m Returns the minute component |
|
@param s Returns the second component |
|
@param f Returns the frame component |
|
*/ |
|
void burn_sectors_to_msf(int sectors, int *m, int *s, int *f); |
|
|
|
/** Convert a minute-second-frame (MSF) value to an lba |
|
@param m Minute component |
|
@param s Second component |
|
@param f Frame component |
|
@return The lba |
|
*/ |
|
int burn_msf_to_lba(int m, int s, int f); |
|
|
|
/** Convert an lba to minute-second-frame (MSF) |
|
@param lba The lba |
|
@param m Returns the minute component |
|
@param s Returns the second component |
|
@param f Returns the frame component |
|
*/ |
|
void burn_lba_to_msf(int lba, int *m, int *s, int *f); |
|
|
|
/** Create a new disc |
|
@return Pointer to a burn_disc object or NULL on failure. |
|
*/ |
|
struct burn_disc *burn_disc_create(void); |
|
|
|
/** Delete disc and decrease the reference count on all its sessions |
|
@param d The disc to be freed |
|
*/ |
|
void burn_disc_free(struct burn_disc *d); |
|
|
|
/** Create a new session |
|
@return Pointer to a burn_session object or NULL on failure. |
|
*/ |
|
struct burn_session *burn_session_create(void); |
|
|
|
/** Free a session (and decrease reference count on all tracks inside) |
|
@param s Session to be freed |
|
*/ |
|
void burn_session_free(struct burn_session *s); |
|
|
|
/** Add a session to a disc at a specific position, increasing the |
|
sessions's reference count. |
|
@param d Disc to add the session to |
|
@param s Session to add to the disc |
|
@param pos position to add at (BURN_POS_END is "at the end") |
|
@return 0 for failure, 1 for success |
|
*/ |
|
int burn_disc_add_session(struct burn_disc *d, struct burn_session *s, |
|
unsigned int pos); |
|
|
|
/** Remove a session from a disc |
|
@param d Disc to remove session from |
|
@param s Session pointer to find and remove |
|
*/ |
|
int burn_disc_remove_session(struct burn_disc *d, struct burn_session *s); |
|
|
|
|
|
/* ts B11219 */ |
|
/** Read a CDRWIN cue sheet file and equip the session object by tracks and |
|
CD-TEXT according to the content of the file. |
|
For a description of CDRWIN file format see |
|
http://digitalx.org/cue-sheet/syntax/ |
|
Fully supported commands are: |
|
CATALOG , CDTEXTFILE , FLAGS , INDEX , ISRC , PERFORMER , |
|
POSTGAP , PREGAP , REM , SONGWRITER , TITLE |
|
Further supported commands introduced by cdrecord (usage like PERFORMER): |
|
ARRANGER , COMPOSER , MESSAGE |
|
Partly supported commands are: |
|
FILE which supports only types BINARY , MOTOROLA , WAVE |
|
TRACK which supports only datatypes AUDIO , MODE1/2048 |
|
Unsupported types of FILE or TRACK lead to failure of the call. |
|
libburn does not yet support mixing of AUDIO and MODE1/2048. So this call |
|
will fail if such a mix is found. |
|
CD-TEXT information is allowed only if all tracks are of datatype AUDIO. |
|
Empty lines and lines which start by '#' are ignored. |
|
@param session Session where to attach tracks. It must not yet have |
|
tracks or else this call will fail. |
|
@param path Filesystem address of the CDRWIN cue sheet file. |
|
Normally with suffix .cue |
|
@param fifo_size Number of bytes in fifo. This will be rounded up by |
|
the block size of the track mode. <= 0 means no fifo. |
|
@param fifo Returns a reference to the burn_source object that |
|
was installed as fifo between FILE and the track |
|
burn sources. One may use this to inquire the fifo |
|
state. Dispose it by burn_source_free() when no longer |
|
needed. It is permissible to pass this parameter to |
|
libburn as NULL, in order to immediately drop ownership |
|
on the fifo. |
|
@param text_packs Returns pre-formatted CD-TEXT packs resulting from |
|
cue sheet command CDTEXTFILE. To be used with call |
|
burn_write_opts_set_leadin_text(). |
|
It is permissible to pass this parameter to libburn |
|
as NULL, in order to disable CDTEXTFILE. |
|
@param num_packs Returns the number of 18 byte records in text_packs. |
|
@param flag Bitfield for control purposes. |
|
bit0= Do not attach CD-TEXT information to session and |
|
tracks. Do not load text_packs. |
|
bit1= Do not use media catalog string of session or ISRC |
|
strings of tracks for writing to Q sub-channel. |
|
@return > 0 indicates success, <= 0 indicates failure |
|
@since 1.2.0 |
|
*/ |
|
int burn_session_by_cue_file(struct burn_session *session, |
|
char *path, int fifo_size, struct burn_source **fifo, |
|
unsigned char **text_packs, int *num_packs, int flag); |
|
|
|
|
|
/** Create a track */ |
|
struct burn_track *burn_track_create(void); |
|
|
|
/** Free a track |
|
@param t Track to free |
|
*/ |
|
void burn_track_free(struct burn_track *t); |
|
|
|
/** Add a track to a session at specified position |
|
@param s Session to add to |
|
@param t Track to insert in session |
|
@param pos position to add at (BURN_POS_END is "at the end") |
|
@return 0 for failure, 1 for success |
|
*/ |
|
int burn_session_add_track(struct burn_session *s, struct burn_track *t, |
|
unsigned int pos); |
|
|
|
/** Remove a track from a session |
|
@param s Session to remove track from |
|
@param t Track pointer to find and remove |
|
@return 0 for failure, 1 for success |
|
*/ |
|
int burn_session_remove_track(struct burn_session *s, struct burn_track *t); |
|
|
|
|
|
/* ts B20107 */ |
|
/** Set the number which shall be written as CD track number with the first |
|
track of the session. The following tracks will then get written with |
|
consecutive CD track numbers. The resulting number of the last track |
|
must not exceed 99. The lowest possible start number is 1, which is also |
|
the default. This setting applies only to CD SAO writing. |
|
@param session The session to be manipulated |
|
@param tno A number between 1 and 99 |
|
@param flag Bitfield for control purposes. Unused yet. Submit 0. |
|
@return > 0 indicates success, <= 0 indicates failure |
|
@since 1.2.0 |
|
*/ |
|
int burn_session_set_start_tno(struct burn_session *session, int tno, |
|
int flag); |
|
|
|
/* ts B20108 */ |
|
/** Inquire the CD track start number, as set by default or by |
|
burn_session_set_start_tno(). |
|
@param session The session to be inquired |
|
@param flag Bitfield for control purposes. Unused yet. Submit 0. |
|
@return > 0 is the currently set CD track start number |
|
<= 0 indicates failure |
|
@since 1.2.0 |
|
*/ |
|
int burn_session_get_start_tno(struct burn_session *session, int flag); |
|
|
|
|
|
|
|
/* ts B11206 */ |
|
/** Set the Character Codes, the Copyright bytes, and the Language Codes |
|
for CD-TEXT blocks 0 to 7. They will be used in the block summaries |
|
of text packs which get generated from text or binary data submitted |
|
by burn_session_set_cdtext() and burn_track_set_cdtext(). |
|
Character Code value can be |
|
0x00 = ISO-8859-1 |
|
0x01 = 7 bit ASCII |
|
0x80 = MS-JIS (japanesei Kanji, double byte characters) |
|
Copyright byte value can be |
|
0x00 = not copyrighted |
|
0x03 = copyrighted |
|
Language Code value will typically be 0x09 = English or 0x69 = Japanese. |
|
See below macros BURN_CDTEXT_LANGUAGES_0X00 and BURN_CDTEXT_LANGUAGES_0X45, |
|
but be aware that many of these codes have never been seen on CD, and that |
|
many of them do not have a character representation among the above |
|
Character Codes. |
|
Default is 0x09 = English for block 0 and 0x00 = Unknown for block 1 to 7. |
|
Copyright and Character Code are 0x00 for all blocks by default. |
|
See also file doc/cdtext.txt, "Format of a CD-TEXT packs array", |
|
"Pack type 0x8f". |
|
|
|
Parameter value -1 leaves the current setting of the session parameter |
|
unchanged. |
|
@param s Session where to change settings |
|
@param char_codes Character Codes for block 0 to 7 |
|
@param copyrights Copyright bytes for block 0 to 7 |
|
@param languages Language Codes for block 0 to 7 |
|
@param flag Bitfiled for control purposes. Unused yet. Submit 0. |
|
@return <=0 failure, > 0 success |
|
@since 1.2.0 |
|
*/ |
|
int burn_session_set_cdtext_par(struct burn_session *s, |
|
int char_codes[8], int copyrights[8], |
|
int languages[8], int flag); |
|
|
|
/** This is the first list of languages sorted by their Language codes, |
|
which start at 0x00. They stem from from EBU Tech 3264, appendix 3. |
|
E.g. language 0x00 is "Unknown", 0x08 is "German", 0x10 is "Frisian", |
|
0x18 is "Latvian", 0x20 is "Polish", 0x28 is "Swedish", 0x2b is "Wallon". |
|
See also file doc/cdtext.txt. |
|
@since 1.2.0 |
|
*/ |
|
#define BURN_CDTEXT_LANGUAGES_0X00 \ |
|
"Unknown", "Albanian", "Breton", "Catalan", \ |
|
"Croatian", "Welsh", "Czech", "Danish", \ |
|
"German", "English", "Spanish", "Esperanto", \ |
|
"Estonian", "Basque", "Faroese", "French", \ |
|
"Frisian", "Irish", "Gaelic", "Galician", \ |
|
"Icelandic", "Italian", "Lappish", "Latin", \ |
|
"Latvian", "Luxembourgian", "Lithuanian", "Hungarian", \ |
|
"Maltese", "Dutch", "Norwegian", "Occitan", \ |
|
"Polish", "Portuguese", "Romanian", "Romansh", \ |
|
"Serbian", "Slovak", "Slovenian", "Finnish", \ |
|
"Swedish", "Turkish", "Flemish", "Wallon" |
|
|
|
/** This is the second list of languages sorted by their Language codes, |
|
which start at 0x45. They stem from from EBU Tech 3264, appendix 3. |
|
E.g. language 0x45 is "Zulu", 0x50 is "Sranan Tongo", 0x58 is "Pushtu", |
|
0x60 is "Moldavian", 0x68 is "Kannada", 0x70 is "Greek", 0x78 is "Bengali", |
|
0x7f is "Amharic". |
|
See also file doc/cdtext.txt. |
|
@since 1.2.0 |
|
*/ |
|
#define BURN_CDTEXT_LANGUAGES_0X45 \ |
|
"Zulu", "Vietnamese", "Uzbek", \ |
|
"Urdu", "Ukrainian", "Thai", "Telugu", \ |
|
"Tatar", "Tamil", "Tadzhik", "Swahili", \ |
|
"Sranan Tongo", "Somali", "Sinhalese", "Shona", \ |
|
"Serbo-croat", "Ruthenian", "Russian", "Quechua", \ |
|
"Pushtu", "Punjabi", "Persian", "Papamiento", \ |
|
"Oriya", "Nepali", "Ndebele", "Marathi", \ |
|
"Moldavian", "Malaysian", "Malagasay", "Macedonian", \ |
|
"Laotian", "Korean", "Khmer", "Kazakh", \ |
|
"Kannada", "Japanese", "Indonesian", "Hindi", \ |
|
"Hebrew", "Hausa", "Gurani", "Gujurati", \ |
|
"Greek", "Georgian", "Fulani", "Dari", \ |
|
"Churash", "Chinese", "Burmese", "Bulgarian", \ |
|
"Bengali", "Bielorussian", "Bambora", "Azerbaijani", \ |
|
"Assamese", "Armenian", "Arabic", "Amharic" |
|
|
|
/* This is the list of empty languages names between 0x30 and 0x44. |
|
Together the three macros fill an array of 128 char pointers. |
|
static char *languages[] = { |
|
BURN_CDTEXT_LANGUAGES_0X00, |
|
BURN_CDTEXT_FILLER, |
|
BURN_CDTEXT_LANGUAGES_0X45 |
|
}; |
|
*/ |
|
#define BURN_CDTEXT_FILLER \ |
|
"", "", "", "", \ |
|
"", "", "", "", \ |
|
"", "", "", "", \ |
|
"", "", "", "", \ |
|
"", "", "", "", \ |
|
"", "", "", "", \ |
|
"" |
|
|
|
/* ts B11206 */ |
|
/** Obtain the current settings as of burn_session_set_cdtext_par() |
|
@param s Session which to inquire |
|
@param char_codes Will return Character Codes for block 0 to 7 |
|
@param copyrights Will return Copyright bytes for block 0 to 7 |
|
@param block_languages Will return Language Codes for block 0 to 7 |
|
@param flag Bitfiled for control purposes. Unused yet. Submit 0. |
|
@return <=0 failure, reply invalid, > 0 success, reply valid |
|
@since 1.2.0 |
|
*/ |
|
int burn_session_get_cdtext_par(struct burn_session *s, |
|
int char_codes[8], int copyrights[8], |
|
int block_languages[8], int flag); |
|
|
|
|
|
/* ts B11206 */ |
|
/** Attach text or binary data as CD-TEXT attributes to a session. |
|
They can be used to generate CD-TEXT packs by burn_cdtext_from_session() |
|
or to write CD-TEXT packs into the lead-in of a CD SAO session. |
|
The latter happens only if no array of CD-TEXT packs is attached to |
|
the write options by burn_write_opts_set_leadin_text(). |
|
For details of the CD-TEXT format and of the payload content, see file |
|
doc/cdtext.txt . |
|
@param s Session where to attach CD-TEXT attribute |
|
@param block Number of the language block in which the attribute |
|
shall appear. Possible values: 0 to 7. |
|
@param pack_type Pack type number. 0x80 to 0x8e. Used if pack_type_name |
|
is NULL or empty text. Else submit 0 and a name. |
|
Pack type 0x8f is generated automatically and may not |
|
be set by applications. |
|
@param pack_type_name The pack type by name. Defined names are: |
|
0x80 = "TITLE" 0x81 = "PERFORMER" |
|
0x82 = "SONGWRITER" 0x83 = "COMPOSER" |
|
0x84 = "ARRANGER" 0x85 = "MESSAGE" |
|
0x86 = "DISCID" 0x87 = "GENRE" |
|
0x88 = "TOC" 0x89 = "TOC2" |
|
0x8d = "CLOSED" 0x8e = "UPC_ISRC" |
|
Names are recognized uppercase and lowercase. |
|
@param payload Text or binary bytes. The data will be copied to |
|
session-internal memory. |
|
Pack types 0x80 to 0x85 contain 0-terminated cleartext |
|
encoded according to the block's Character Code. |
|
If double byte characters are used, then two 0-bytes |
|
terminate the cleartext. |
|
Pack type 0x86 is 0-terminated ASCII cleartext. |
|
Pack type 0x87 consists of two byte big-endian |
|
Genre code (see below BURN_CDTEXT_GENRE_LIST), and |
|
0-terminated ASCII cleartext of genre description. |
|
Pack type 0x88 mirrors the session table-of-content. |
|
Pack type 0x89 is not understood yet. |
|
Pack types 0x8a to 0x8c are reserved. |
|
Pack type 0x8d contains ISO-8859-1 cleartext which is |
|
not to be shown by commercial audio CD players. |
|
Pack type 0x8e is ASCII cleartext with UPC/EAN code. |
|
@param length Number of bytes in payload. Including terminating |
|
0-bytes. |
|
@param flag Bitfield for control purposes. |
|
bit0= payload contains double byte characters |
|
(with character code 0x80 MS-JIS japanese Kanji) |
|
@return > 0 indicates success , <= 0 is failure |
|
@since 1.2.0 |
|
*/ |
|
int burn_session_set_cdtext(struct burn_session *s, int block, |
|
int pack_type, char *pack_type_name, |
|
unsigned char *payload, int length, int flag); |
|
|
|
|
|
/** This is the list of Genres sorted by their Genre codes. |
|
E.g. genre code 0x0000 is "No Used", 0x0008 is "Dance, 0x0010 is "Musical", |
|
0x0018 is "Rhythm & Blues", 0x001b is "World Music". |
|
See also file doc/cdtext.txt. |
|
@since 1.2.0 |
|
*/ |
|
#define BURN_CDTEXT_GENRE_LIST \ |
|
"Not Used", "Not Defined", "Adult Contemporary", "Alternative Rock", \ |
|
"Childrens Music", "Classical", "Contemporary Christian", "Country", \ |
|
"Dance", "Easy Listening", "Erotic", "Folk", \ |
|
"Gospel", "Hip Hop", "Jazz", "Latin", \ |
|
"Musical", "New Age", "Opera", "Operetta", \ |
|
"Pop Music", "Rap", "Reggae", "Rock Music", \ |
|
"Rhythm & Blues", "Sound Effects", "Spoken Word", "World Music" |
|
|
|
/* The number of genre names in BURN_CDTEXT_GENRE_LIST. |
|
*/ |
|
#define BURN_CDTEXT_NUM_GENRES 28 |
|
|
|
|
|
/* ts B11206 */ |
|
/** Obtain a CD-TEXT attribute that was set by burn_session_set_cdtext() |
|
@param s Session to inquire |
|
@param block Number of the language block to inquire. |
|
@param pack_type Pack type number to inquire. Used if pack_type_name |
|
is NULL or empty text. Else submit 0 and a name. |
|
Pack type 0x8f is generated automatically and may not |
|
be inquire in advance. Use burn_cdtext_from_session() |
|
to generate all packs including type 0x8f packs. |
|
@param pack_type_name The pack type by name. |
|
See above burn_session_set_cdtext(). |
|
@param payload Will return a pointer to text or binary bytes. |
|
Not a copy of data. Do not free() this address. |
|
If no text attribute is attached for pack type and |
|
block, then payload is returned as NULL. The return |
|
value will not indicate error in this case. |
|
@param length Will return the number of bytes pointed to by payload. |
|
Including terminating 0-bytes. |
|
@param flag Bitfield for control purposes. Unused yet. Submit 0. |
|
@return 1 single byte char, 2 double byte char, <=0 error |
|
@since 1.2.0 |
|
*/ |
|
int burn_session_get_cdtext(struct burn_session *s, int block, |
|
int pack_type, char *pack_type_name, |
|
unsigned char **payload, int *length, int flag); |
|
|
|
|
|
/* ts B11215 */ |
|
/** Read a Sony CD-TEXT Input Sheet Version 0.7T file and attach its text |
|
attributes to the given session and its tracks for the given CD-TEXT |
|
block number. This overrides previous settings made by |
|
burn_session_set_cdtext(), burn_track_set_cdtext(), burn_track_set_isrc(), |
|
burn_session_set_start_tno(). It can later be overridden by said function |
|
calls. |
|
The media catalog number from purpose specifier "UPC / EAN" gets into |
|
effect only if burn_write_opts_set_has_mediacatalog() is set to 0. |
|
The format of a v07t sheet file is documented in doc/cdtext.txt. |
|
@param session Session where to attach CD-TEXT attributes |
|
@param path Local filesystem address of the sheet file which |
|
shall be read and interpreted. |
|
@param block Number of the language block in which the attributes |
|
shall appear. Possible values: 0 to 7. |
|
@param flag Bitfield for control purposes. |
|
bit0= Permission to read multiple blocks from the |
|
given sheet file. Each block is supposed to begin |
|
by a line "Input Sheet Version = 0.7T". Therefore |
|
this permission is only valid if the input file |
|
begins by such a line. |
|
@since 1.3.2 |
|
bit1= Do not use media catalog string of session or ISRC |
|
strings of tracks for writing to Q sub-channel. |
|
@since 1.2.0 |
|
@return > 0 indicates success and the number of interpreted |
|
blocks (1 if not flag bit0 is set). |
|
<= 0 indicates failure |
|
@since 1.2.0 |
|
*/ |
|
int burn_session_input_sheet_v07t(struct burn_session *session, |
|
char *path, int block, int flag); |
|
|
|
|
|
/* ts B11210 */ |
|
/** Produce an array of CD-TEXT packs that could be submitted to |
|
burn_write_opts_set_leadin_text(), or stored as *.cdt file, |
|
or submitted to burn_make_input_sheet_v07t(). |
|
For a description of the format of the array, see file doc/cdtext.txt. |
|
The input data stem from burn_session_set_cdtext_par(), |
|
burn_session_set_cdtext(), and burn_track_set_cdtext(). |
|
@param s Session from which to produce CD-TEXT packs. |
|
@param text_packs Will return the buffer with the CD-TEXT packs. |
|
Dispose by free() when no longer needed. |
|
@param num_packs Will return the number of 18 byte text packs. |
|
@param flag Bitfield for control purposes. |
|
bit0= do not return generated CD-TEXT packs, |
|
but check whether production would work and |
|
indicate the number of packs by the call return |
|
value. This happens also if |
|
(text_packs == NULL || num_packs == NULL). |
|
@return Without flag bit0: > 0 is success, <= 0 failure |
|
With flag bit0: > 0 is number of packs, |
|
0 means no packs will be generated, |
|
< 0 means failure |
|
@since 1.2.0 |
|
*/ |
|
int burn_cdtext_from_session(struct burn_session *s, |
|
unsigned char **text_packs, int *num_packs, |
|
int flag); |
|
|
|
|
|
/* ts B30519 */ |
|
/** Convert an array of CD-TEXT packs into the text format of |
|
Sony CD-TEXT Input Sheet Version 0.7T . |
|
|
|
@param text_packs Array of bytes which form CD-TEXT packs of 18 bytes |
|
each. For a description of the format of the array, |
|
see file doc/cdtext.txt. |
|
No header of 4 bytes must be prepended which would |
|
tell the number of pack bytes + 2. |
|
This parameter may be NULL if the currently attached |
|
array of packs shall be removed. |
|
@param num_packs The number of 18 byte packs in text_packs. |
|
@param start_tno The start number of track counting, if known from |
|
CD table-of-content or other sources. |
|
Submit 0 to enable the attempt to read it and the |
|
track_count from pack type 0x8f. |
|
@param track_count The number of tracks, if known from CD table-of-content |
|
or orther sources. |
|
@param result Will return the buffer with Sheet text. |
|
Dispose by free() when no longer needed. |
|
It will be filled by the text for the v07t sheet file |
|
plus a trailing 0-byte. (Be aware that double-byte |
|
characters might contain 0-bytes, too.) |
|
Each CD-TEXT language block starts by the line |
|
"Input Sheet Version = 0.7T" |
|
and a "Remarks" line that tells the block number. |
|
@param char_code Returns the character code of the pack array: |
|
0x00 = ISO-8859-1 |
|
0x01 = 7 bit ASCII |
|
0x80 = MS-JIS (japanese Kanji, double byte characters) |
|
The presence of a code value that is not in this list |
|
will cause this function to fail. |
|
@param flag Bitfield for control purposes. Unused yet. Submit 0. |
|
@return > 0 tells the number of valid text bytes in result. |
|
This does not include the trailing 0-byte. |
|
<= 0 indicates failure. |
|
@since 1.3.2 |
|
*/ |
|
int burn_make_input_sheet_v07t(unsigned char *text_packs, int num_packs, |
|
int start_tno, int track_count, |
|
char **result, int *char_code, int flag); |
|
|
|
|
|
/* ts B11206 */ |
|
/** Remove all CD-TEXT attributes of the given block from the session. |
|
They were attached by burn_session_set_cdtext(). |
|
@param s Session where to remove the CD-TEXT attribute |
|
@param block Number of the language block in which the attribute |
|
shall appear. Possible values: 0 to 7. |
|
-1 causes text packs of all blocks to be removed. |
|
@return > 0 is success, <= 0 failure |
|
@since 1.2.0 |
|
*/ |
|
int burn_session_dispose_cdtext(struct burn_session *s, int block); |
|
|
|
|
|
/* ts B11221*/ |
|
/** Read an array of CD-TEXT packs from a file. This array should be suitable |
|
for burn_write_opts_set_leadin_text(). |
|
The function tolerates and removes 4-byte headers as produced by |
|
cdrecord -vv -toc, if this header tells the correct number of bytes which |
|
matches the file size. If no 4-byte header is present, then the function |
|
tolerates and removes a trailing 0-byte as of Sony specs. |
|
@param path Filesystem address of the CD-TEXT pack file. |
|
Normally with suffix .cdt or .dat |
|
@param text_packs Will return the buffer with the CD-TEXT packs. |
|
Dispose by free() when no longer needed. |
|
@param num_packs Will return the number of 18 byte text packs. |
|
@param flag Bitfield for control purposes. Unused yet.Submit 0. |
|
@return 0 is success, <= 0 failure |
|
@since 1.2.0 |
|
*/ |
|
int burn_cdtext_from_packfile(char *path, unsigned char **text_packs, |
|
int *num_packs, int flag); |
|
|
|
|
|
/** Define the data in a track |
|
@param t the track to define |
|
@param offset The lib will write this many 0s before start of data |
|
@param tail The number of extra 0s to write after data |
|
@param pad 1 means the lib should pad the last sector with 0s if the |
|
track isn't exactly sector sized. (otherwise the lib will |
|
begin reading from the next track) |
|
@param mode data format (bitfield) |
|
*/ |
|
void burn_track_define_data(struct burn_track *t, int offset, int tail, |
|
int pad, int mode); |
|
|
|
|
|
/* ts B11206 */ |
|
/** Attach text or binary data as CD-TEXT attributes to a track. |
|
The payload will be used to generate CD-TEXT packs by |
|
burn_cdtext_from_session() or to write CD-TEXT packs into the lead-in |
|
of a CD SAO session. This happens if the CD-TEXT attribute of the session |
|
gets generated, which has the same block number and pack type. In this |
|
case, each track should have such a CD-TEXT attribute, too. |
|
See burn_session_set_cdtext(). |
|
Be cautious not to exceed the maximum number of 253 payload packs per |
|
language block. Use burn_cdtext_from_session() to learn whether a valid |
|
array of CD-TEXT packs can be generated from your attributes. |
|
@param t Track where to attach CD-TEXT attribute. |
|
@param block Number of the language block in which the attribute |
|
shall appear. Possible values: 0 to 7. |
|
@param pack_type Pack type number. 0x80 to 0x85 or 0x8e. Used if |
|
pack_type_name is NULL or empty text. Else submit 0 |
|
and a name. |
|
@param pack_type_name The pack type by name. Applicable names are: |
|
0x80 = "TITLE" 0x81 = "PERFORMER" |
|
0x82 = "SONGWRITER" 0x83 = "COMPOSER" |
|
0x84 = "ARRANGER" 0x85 = "MESSAGE" |
|
0x8e = "UPC_ISRC" |
|
@param payload 0-terminated cleartext. If double byte characters |
|
are used, then two 0-bytes terminate the cleartext. |
|
@param length Number of bytes in payload. Including terminating |
|
0-bytes. |
|
@param flag Bitfield for control purposes. |
|
bit0= payload contains double byte characters |
|
(with character code 0x80 MS-JIS japanese Kanji) |
|
@return > 0 indicates success , <= 0 is failure |
|
@since 1.2.0 |
|
*/ |
|
int burn_track_set_cdtext(struct burn_track *t, int block, |
|
int pack_type, char *pack_type_name, |
|
unsigned char *payload, int length, int flag); |
|
|
|
/* ts B11206 */ |
|
/** Obtain a CD-TEXT attribute that was set by burn_track_set_cdtext(). |
|
@param t Track to inquire |
|
@param block Number of the language block to inquire. |
|
@param pack_type Pack type number to inquire. Used if pack_type_name |
|
is NULL or empty text. Else submit 0 and a name. |
|
@param pack_type_name The pack type by name. |
|
See above burn_track_set_cdtext(). |
|
@param payload Will return a pointer to text bytes. |
|
Not a copy of data. Do not free() this address. |
|
If no text attribute is attached for pack type and |
|
block, then payload is returned as NULL. The return |
|
value will not indicate error in this case. |
|
@param length Will return the number of bytes pointed to by payload. |
|
Including terminating 0-bytes. |
|
@param flag Bitfield for control purposes. Unused yet. Submit 0. |
|
@return 1=single byte char , 2= double byte char , <=0 error |
|
@since 1.2.0 |
|
*/ |
|
int burn_track_get_cdtext(struct burn_track *t, int block, |
|
int pack_type, char *pack_type_name, |
|
unsigned char **payload, int *length, int flag); |
|
|
|
/* ts B11206 */ |
|
/** Remove all CD-TEXT attributes of the given block from the track. |
|
They were attached by burn_track_set_cdtext(). |
|
@param t Track where to remove the CD-TEXT attribute. |
|
@param block Number of the language block in which the attribute |
|
shall appear. Possible values: 0 to 7. |
|
-1 causes text packs of all blocks to be removed. |
|
@return > 0 is success, <= 0 failure |
|
@since 1.2.0 |
|
*/ |
|
int burn_track_dispose_cdtext(struct burn_track *t, int block); |
|
|
|
|
|
/* ts A90910 */ |
|
/** Activates CD XA compatibility modes. |
|
libburn currently writes data only in CD mode 1. Some programs insist in |
|
sending data with additional management bytes. These bytes have to be |
|
stripped in order to make the input suitable for BURN_MODE1. |
|
@param t The track to manipulate |
|
@param value 0= no conversion |
|
1= strip 8 byte sector headers of CD-ROM XA mode 2 form 1 |
|
see MMC-5 4.2.3.8.5.3 Block Format for Mode 2 form 1 Data |
|
all other values are reserved |
|
@return 1=success , 0=unacceptable value |
|
@since 0.7.2 |
|
*/ |
|
int burn_track_set_cdxa_conv(struct burn_track *t, int value); |
|
|
|
|
|
/** Set the ISRC details for a track. When writing to CD media, ISRC will get |
|
written into the Q sub-channel. |
|
@param t The track to change |
|
@param country the 2 char country code. Each character must be |
|
only numbers or letters. |
|
@param owner 3 char owner code. Each character must be only numbers |
|
or letters. |
|
@param year 2 digit year. A number in 0-99 (Yep, not Y2K friendly). |
|
@param serial 5 digit serial number. A number in 0-99999. |
|
*/ |
|
void burn_track_set_isrc(struct burn_track *t, char *country, char *owner, |
|
unsigned char year, unsigned int serial); |
|
|
|
/* ts B11226 */ |
|
/** Set the composed ISRC string for a track. This is an alternative to |
|
burn_track_set_isrc(). |
|
@param t The track to be manipulated |
|
@param isrc 12 characters which are composed from ISRC details. |
|
Format is CCOOOYYSSSSS, terminated by a 0-byte: |
|
Country, Owner, Year(decimal digits), Serial(decimal digits). |
|
@param flag Bitfield for control purposes. Unused yet. Submit 0. |
|
@return > 0 indicates success, <= 0 means failure |
|
@since 1.2.0 |
|
*/ |
|
int burn_track_set_isrc_string(struct burn_track *t, char isrc[13], int flag); |
|
|
|
/** Disable ISRC parameters for a track |
|
@param t The track to change |
|
*/ |
|
void burn_track_clear_isrc(struct burn_track *t); |
|
|
|
|
|
/* ts B20103 */ |
|
/** Define an index start address within a track. The index numbers inside a |
|
track have to form sequence starting at 0 or 1 with no gaps up to the |
|
highest number used. They affect only writing of CD SAO sessions. |
|
The first index start address of a track must be 0. |
|
Blocks between index 0 and index 1 are considered to be located before the |
|
track start as of the table-of-content. |
|
@param t The track to be manipulated |
|
@param index_number A number between 0 and 99 |
|
@param relative_lba The start address relative to the start of the |
|
burn_source of the track. It will get mapped to the |
|
appropriate absolute block address. |
|
@param flag Bitfield for control purposes. Unused yet. Submit 0. |
|
@return > 0 indicates success, <= 0 means failure |
|
@since 1.2.0 |
|
*/ |
|
int burn_track_set_index(struct burn_track *t, int index_number, |
|
unsigned int relative_lba, int flag); |
|
|
|
/* ts B20103 */ |
|
/** Remove all index start addresses and reset to the default indexing of |
|
CD SAO sessions. This means index 0 of track 1 reaches from LBA -150 |
|
to LBA -1. Index 1 of track 1 reaches from LBA 0 to track end. Index 1 |
|
of track 2 follows immediately. The same happens for all further tracks |
|
after the end of their predecessor. |
|
@param t The track to be manipulated |
|
@param flag Bitfield for control purposes. Unused yet. Submit 0. |
|
@return > 0 indicates success, <= 0 means failure |
|
@since 1.2.0 |
|
*/ |
|
int burn_track_clear_indice(struct burn_track *t, int flag); |
|
|
|
|
|
/* ts B20110 */ |
|
/** Define whether a pre-gap shall be written before the track and how many |
|
sectors this pre-gap shall have. A pre-gap is written in the range of track |
|
index 0 and contains zeros (audio silence). No bytes from the track source |
|
will be read for writing the pre-gap. |
|
This setting affects only CD SAO write runs. |
|
The first track automatically gets a pre-gap of at least 150 sectors. Its |
|
size may be enlarged by this call. Further pre-gaps are demanded by MMC |
|
for tracks which follow tracks of a different mode. (But Mode mixing in |
|
CD SAO sessions is currently not supported by libburn.) |
|
@param t The track to change |
|
@param size Number of sectors in the pre-gap. |
|
-1 disables pre-gap, except for the first track. |
|
libburn allows 0, but MMC does not propose this. |
|
@param flag Bitfield for control purposes. Unused yet. Submit 0. |
|
@return > 0 indicates success, <= 0 means failure |
|
@since 1.2.0 |
|
*/ |
|
int burn_track_set_pregap_size(struct burn_track *t, int size, int flag); |
|
|
|
/* ts B20111 */ |
|
/** Define whether a post-gap shall be written at the end of the track and |
|
how many sectors this gap shall have. A post-gap occupies the range of |
|
an additional index of the track. It contains zeros. No bytes from the |
|
track source will be read for writing the post-gap. |
|
This setting affects only CD SAO write runs. |
|
MMC prescribes to add a post-gap to a data track which is followed by |
|
a non-data track. (But libburn does not yet support mixed mode CD SAO |
|
sessions.) |
|
@param t The track to change |
|
@param size Number of sectors in the post-gap. |
|
-1 disables post-gap. |
|
libburn allows 0, but MMC does not propose this. |
|
@param flag Bitfield for control purposes. Unused yet. Submit 0. |
|
@return > 0 indicates success, <= 0 means failure |
|
@since 1.2.0 |
|
*/ |
|
int burn_track_set_postgap_size(struct burn_track *t, int size, int flag); |
|
|
|
|
|
/* ts A61024 */ |
|
/** Define whether a track shall swap bytes of its input stream. |
|
@param t The track to change |
|
@param swap_source_bytes 0=do not swap, 1=swap byte pairs |
|
@return 1=success , 0=unacceptable value |
|
@since 0.2.6 |
|
*/ |
|
int burn_track_set_byte_swap(struct burn_track *t, int swap_source_bytes); |
|
|
|
|
|
/** Hide the first track in the "pre gap" of the disc |
|
@param s session to change |
|
@param onoff 1 to enable hiding, 0 to disable |
|
*/ |
|
void burn_session_hide_first_track(struct burn_session *s, int onoff); |
|
|
|
/** Get the drive's disc struct - free when done |
|
@param d drive to query |
|
@return the disc struct or NULL on failure |
|
*/ |
|
struct burn_disc *burn_drive_get_disc(struct burn_drive *d); |
|
|
|
/** Set the track's data source |
|
@param t The track to set the data source for |
|
@param s The data source to use for the contents of the track |
|
@return An error code stating if the source is ready for use for |
|
writing the track, or if an error occurred |
|
|
|
*/ |
|
enum burn_source_status burn_track_set_source(struct burn_track *t, |
|
struct burn_source *s); |
|
|
|
|
|
/* ts A70218 */ |
|
/** Set a default track size to be used only if the track turns out to be of |
|
unpredictable length and if the effective write type demands a fixed size. |
|
This can be useful to enable write types CD SAO or DVD DAO together with |
|
a track source like stdin. If the track source delivers fewer bytes than |
|
announced then the track will be padded up with zeros. |
|
@param t The track to change |
|
@param size The size to set |
|
@return 0=failure 1=success |
|
@since 0.3.4 |
|
*/ |
|
int burn_track_set_default_size(struct burn_track *t, off_t size); |
|
|
|
/** Free a burn_source (decrease its refcount and maybe free it) |
|
@param s Source to free |
|
*/ |
|
void burn_source_free(struct burn_source *s); |
|
|
|
/** Creates a data source for an image file (and maybe subcode file) |
|
@param path The file address for the main channel payload. |
|
@param subpath Eventual address for subchannel data. Only used in exotic |
|
raw write modes. Submit NULL for normal tasks. |
|
@return Pointer to a burn_source object, NULL indicates failure |
|
*/ |
|
struct burn_source *burn_file_source_new(const char *path, |
|
const char *subpath); |
|
|
|
|
|
/* ts A91122 : An interface to open(O_DIRECT) or similar OS tricks. */ |
|
|
|
/** Opens a file with eventual acceleration preparations which may depend |
|
on the operating system and on compile time options of libburn. |
|
You may use this call instead of open(2) for opening file descriptors |
|
which shall be handed to burn_fd_source_new(). |
|
This should only be done for tracks with BURN_BLOCK_MODE1 (2048 bytes |
|
per block). |
|
|
|
If you use this call then you MUST allocate the buffers which you use |
|
with read(2) by call burn_os_alloc_buffer(). Read sizes MUST be a multiple |
|
of a safe buffer amount. Else you risk that track data get altered during |
|
transmission. |
|
burn_disk_write() will allocate a suitable read/write buffer for its own |
|
operations. A fifo created by burn_fifo_source_new() will allocate |
|
suitable memory for its buffer if called with flag bit0 and a multiple |
|
of a safe buffer amount. |
|
@param path The file address to open |
|
@param open_flags The flags as of man 2 open. Normally just O_RDONLY. |
|
@param flag Bitfield for control purposes (unused yet, submit 0). |
|
@return A file descriptor as of open(2). Finally to be disposed |
|
by close(2). |
|
-1 indicates failure. |
|
@since 0.7.4 |
|
*/ |
|
int burn_os_open_track_src(char *path, int open_flags, int flag); |
|
|
|
/** Allocate a memory area that is suitable for reading with a file descriptor |
|
opened by burn_os_open_track_src(). |
|
@param amount Number of bytes to allocate. This should be a multiple |
|
of the operating system's i/o block size. 32 KB is |
|
guaranteed by libburn to be safe. |
|
@param flag Bitfield for control purposes (unused yet, submit 0). |
|
@return The address of the allocated memory, or NULL on failure. |
|
A non-NULL return value has finally to be disposed via |
|
burn_os_free_buffer(). |
|
@since 0.7.4 |
|
*/ |
|
void *burn_os_alloc_buffer(size_t amount, int flag); |
|
|
|
/** Dispose a memory area which was obtained by burn_os_alloc_buffer(), |
|
@param buffer Memory address to be freed. |
|
@param amount The number of bytes which was allocated at that |
|
address. |
|
@param flag Bitfield for control purposes (unused yet, submit 0). |
|
@return 1 success , <=0 failure |
|
@since 0.7.4 |
|
*/ |
|
int burn_os_free_buffer(void *buffer, size_t amount, int flag); |
|
|
|
|
|
/** Creates a data source for an image file (a track) from an open |
|
readable filedescriptor, an eventually open readable subcodes file |
|
descriptor and eventually a fixed size in bytes. |
|
@param datafd The source of data. |
|
@param subfd The eventual source of subchannel data. Only used in exotic |
|
raw write modes. Submit -1 for normal tasks. |
|
@param size The eventual fixed size of eventually both fds. |
|
If this value is 0, the size will be determined from datafd. |
|
@return Pointer to a burn_source object, NULL indicates failure |
|
*/ |
|
struct burn_source *burn_fd_source_new(int datafd, int subfd, off_t size); |
|
|
|
|
|
/* ts B00922 */ |
|
/** Creates an offset source which shall provide a byte interval of a stream |
|
to its consumer. It is supposed to be chain-linked with other offset |
|
sources which serve neighboring consumers. The chronological sequence |
|
of consumers and the sequence of offset sources must match. The intervals |
|
of the sources must not overlap. |
|
|
|
A chain of these burn_source objects may be used to feed multiple tracks |
|
from one single stream of input bytes. |
|
Each of the offset sources will skip the bytes up to its start address and |
|
provide the prescribed number of bytes to the track. Skipping takes into |
|
respect the bytes which have been processed by eventual predecessors in the |
|
chain. |
|
Important: It is not allowed to free an offset source before its successor |
|
has ended its work. Best is to keep them all until all tracks |
|
are done. |
|
|
|
@param inp The burn_source object from which to read stream data. |
|
E.g. created by burn_file_source_new(). |
|
@param prev The eventual offset source object which shall read data from |
|
inp before the new offset source will begin its own work. |
|
This must either be a result of burn_offst_source_new() or |
|
it must be NULL. |
|
@param start The byte address where to start reading bytes for the |
|
consumer. inp bytes may get skipped to reach this address. |
|
@param size The number of bytes to be delivered to the consumer. |
|
If size is <= 0 then it may be set later by a call of method |
|
set_size(). If it is >= 0, then it can only be changed if |
|
flag bit0 was set with burn_offst_source_new(). |
|
@param flag Bitfield for control purposes |
|
bit0 = Prevent set_size() from overriding interval sizes > 0. |
|
If such a size is already set, then the new one will |
|
only affect the reply of get_size(). |
|
See also above struct burn_source. |
|
@since 1.2.0 |
|
@return Pointer to a burn_source object, later to be freed by |
|
burn_source_free(). NULL indicates failure. |
|
@since 0.8.8 |
|
*/ |
|
struct burn_source *burn_offst_source_new( |
|
struct burn_source *inp, struct burn_source *prev, |
|
off_t start, off_t size, int flag); |
|
|
|
/* ts A70930 */ |
|
/** Creates a fifo which acts as proxy for an already existing data source. |
|
The fifo provides a ring buffer which shall smoothen the data stream |
|
between burn_source and writer thread. Each fifo serves only for one |
|
data source. It may be attached to one track as its only data source |
|
by burn_track_set_source(), or it may be used as input for other burn |
|
sources. |
|
A fifo starts its life in "standby" mode with no buffer space allocated. |
|
As soon as its consumer requires bytes, the fifo establishes a worker |
|
thread and allocates its buffer. After input has ended and all buffer |
|
content is consumed, the buffer space gets freed and the worker thread |
|
ends. This happens asynchronously. So expect two buffers and worker threads |
|
to exist for a short time between tracks. Be modest in your size demands if |
|
multiple tracks are to be expected. |
|
@param inp The burn_source for which the fifo shall act as proxy. |
|
It can be disposed by burn_source_free() immediately |
|
after this call. |
|
@param chunksize The size in bytes of a chunk. |
|
Use 2048 for sources suitable for BURN_BLOCK_MODE1, |
|
2352 for sources which deliver for BURN_BLOCK_AUDIO, |
|
2056 for sources which shall get treated by |
|
burn_track_set_cdxa_conv(track, 1). |
|
|