diff --git a/src/lib.rs b/src/lib.rs index 606b8c6..07a95d9 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -244,9 +244,11 @@ pub const burn_write_types_BURN_WRITE_SAO: burn_write_types = 2; /// 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 pub const burn_write_types_BURN_WRITE_RAW: burn_write_types = 3; /// In replies this indicates that not any writing will work. @@ -1252,6 +1254,7 @@ unsafe extern "C" { /// 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. pub fn burn_initialize() -> ::std::os::raw::c_int; @@ -1271,17 +1274,23 @@ unsafe extern "C" { /// 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 pub fn burn_abort( patience: ::std::os::raw::c_int, @@ -1297,8 +1306,11 @@ unsafe extern "C" { } unsafe extern "C" { /// 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 pub fn burn_abort_pacifier( handle: *mut ::std::os::raw::c_void, @@ -1311,6 +1323,7 @@ unsafe extern "C" { /// 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. pub fn burn_set_verbosity(level: ::std::os::raw::c_int); @@ -1320,10 +1333,12 @@ unsafe extern "C" { /// 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 pub fn burn_set_scsi_logging(flag: ::std::os::raw::c_int); } @@ -1332,6 +1347,7 @@ unsafe extern "C" { /// 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 @@ -1347,12 +1363,15 @@ unsafe extern "C" { /// 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 pub fn burn_preset_device_open( exclusive: ::std::os::raw::c_int, @@ -1368,7 +1387,9 @@ unsafe extern "C" { /// 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 pub fn burn_allow_untested_profiles(yes: ::std::os::raw::c_int); } @@ -1438,6 +1459,7 @@ unsafe extern "C" { /// 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. @@ -1445,13 +1467,17 @@ unsafe extern "C" { /// 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 pub fn burn_drive_scan_and_grab( drive_infos: *mut *mut burn_drive_info, @@ -1462,7 +1488,9 @@ unsafe extern "C" { unsafe extern "C" { /// 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 pub fn burn_drive_add_whitelist( device_address: *mut ::std::os::raw::c_char, @@ -1487,11 +1515,14 @@ unsafe extern "C" { /// 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. @@ -1503,16 +1534,20 @@ unsafe extern "C" { unsafe extern "C" { /// 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 pub fn burn_drive_info_forget( drive_info: *mut burn_drive_info, @@ -1527,10 +1562,14 @@ unsafe extern "C" { } unsafe extern "C" { /// 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 pub fn burn_drive_d_get_adr( drive: *mut burn_drive, @@ -1540,10 +1579,14 @@ unsafe extern "C" { unsafe extern "C" { /// 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 pub fn burn_drive_get_adr( drive_info: *mut burn_drive_info, @@ -1555,7 +1598,9 @@ unsafe extern "C" { /// 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 pub fn burn_drive_is_enumerable_adr(adr: *mut ::std::os::raw::c_char) -> ::std::os::raw::c_int; } @@ -1564,10 +1609,14 @@ unsafe extern "C" { /// 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 pub fn burn_drive_convert_fs_adr( path: *mut ::std::os::raw::c_char, @@ -1580,14 +1629,22 @@ unsafe extern "C" { /// 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 pub fn burn_drive_convert_scsi_adr( bus_no: ::std::os::raw::c_int, @@ -1605,13 +1662,17 @@ unsafe extern "C" { /// 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. @@ -1622,10 +1683,14 @@ unsafe extern "C" { /// 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 pub fn burn_lookup_device_link( dev_adr: *mut ::std::os::raw::c_char, @@ -1641,7 +1706,9 @@ unsafe extern "C" { /// 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 pub fn burn_drive_obtain_scsi_adr( path: *mut ::std::os::raw::c_char, @@ -1655,10 +1722,13 @@ unsafe extern "C" { unsafe extern "C" { /// 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 pub fn burn_drive_grab( drive: *mut burn_drive, @@ -1677,11 +1747,15 @@ unsafe extern "C" { /// 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 pub fn burn_drive_snooze( d: *mut burn_drive, @@ -1692,9 +1766,13 @@ unsafe extern "C" { /// 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 pub fn burn_drive_re_assess( d: *mut burn_drive, @@ -1704,7 +1782,9 @@ unsafe extern "C" { unsafe extern "C" { /// 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. pub fn burn_drive_release(drive: *mut burn_drive, eject: ::std::os::raw::c_int); } @@ -1713,9 +1793,13 @@ unsafe extern "C" { /// 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 pub fn burn_drive_leave_locked( d: *mut burn_drive, @@ -1726,7 +1810,9 @@ unsafe extern "C" { /// 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 pub fn burn_disc_get_status(drive: *mut burn_drive) -> burn_disc_status; @@ -1736,7 +1822,9 @@ unsafe extern "C" { /// 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 pub fn burn_disc_pretend_blank(drive: *mut burn_drive) -> ::std::os::raw::c_int; } @@ -1745,18 +1833,22 @@ unsafe extern "C" { /// 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 pub fn burn_disc_pretend_full(drive: *mut burn_drive) -> ::std::os::raw::c_int; } unsafe extern "C" { /// WARNING: This overrides the safety measures against unsuitable media. /// Sets the drive status to BURN_DISC_FULL unconditionally. + /// /// @since 1.3.4 pub fn burn_disc_pretend_full_uncond(drive: *mut burn_drive) -> ::std::os::raw::c_int; } unsafe extern "C" { /// 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 @@ -1764,9 +1856,12 @@ unsafe extern "C" { /// 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 pub fn burn_drive_get_serial_no( d: *mut burn_drive, @@ -1787,15 +1882,20 @@ unsafe extern "C" { /// 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 pub fn burn_drive_get_media_sno( d: *mut burn_drive, @@ -1807,8 +1907,11 @@ unsafe extern "C" { /// 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 pub fn burn_disc_read_atip(drive: *mut burn_drive) -> ::std::os::raw::c_int; } @@ -1817,8 +1920,11 @@ unsafe extern "C" { /// 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 pub fn burn_drive_get_bd_r_pow(drive: *mut burn_drive) -> ::std::os::raw::c_int; } @@ -1827,11 +1933,17 @@ unsafe extern "C" { /// in the given drive. The drive has to be grabbed to have hope for reply. /// Shortcoming (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 pub fn burn_drive_get_start_end_lba( drive: *mut burn_drive, @@ -1848,17 +1960,26 @@ unsafe extern "C" { /// 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 pub fn burn_guess_cd_manufacturer( m_li: ::std::os::raw::c_int, @@ -1873,14 +1994,20 @@ unsafe extern "C" { unsafe extern "C" { /// 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 @@ -1893,7 +2020,9 @@ unsafe extern "C" { /// bit5= Disc is nominally erasable (Erasable bit) /// This will be set with overwritable media which /// libburn normally considers to be unerasable blank. + /// /// @return 1 success, <= 0 an error occurred + /// /// @since 0.7.2 pub fn burn_disc_get_cd_info( d: *mut burn_drive, @@ -1909,7 +2038,9 @@ unsafe extern "C" { /// 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 @@ -1917,11 +2048,15 @@ unsafe extern "C" { /// 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 pub fn burn_disc_get_leadin_text( d: *mut burn_drive, @@ -1936,12 +2071,18 @@ unsafe extern "C" { /// 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 pub fn burn_disc_get_bd_spare_info( d: *mut burn_drive, @@ -1954,17 +2095,26 @@ unsafe extern "C" { /// 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 pub fn burn_disc_get_phys_format_info( d: *mut burn_drive, @@ -1983,15 +2133,22 @@ unsafe extern "C" { /// 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 pub fn burn_disc_track_lba_nwa( d: *mut burn_drive, @@ -2006,12 +2163,16 @@ unsafe extern "C" { /// 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 pub fn burn_disc_next_track_is_damaged( d: *mut burn_drive, @@ -2027,16 +2188,20 @@ unsafe extern "C" { /// 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 pub fn burn_disc_close_damaged( o: *mut burn_write_opts, @@ -2047,9 +2212,13 @@ unsafe extern "C" { /// 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 pub fn burn_disc_get_msc1( d: *mut burn_drive, @@ -2068,9 +2237,13 @@ unsafe extern "C" { /// 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 pub fn burn_disc_available_space(d: *mut burn_drive, o: *mut burn_write_opts) -> off_t; } @@ -2100,10 +2273,15 @@ unsafe extern "C" { /// 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 pub fn burn_disc_get_profile( d: *mut burn_drive, @@ -2121,22 +2299,30 @@ unsafe extern "C" { /// 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 pub fn burn_disc_get_media_id( d: *mut burn_drive, @@ -2152,14 +2338,20 @@ unsafe extern "C" { /// 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 pub fn burn_guess_manufacturer( profile_no: ::std::os::raw::c_int, @@ -2170,14 +2362,19 @@ unsafe extern "C" { } unsafe extern "C" { /// Tells whether a disc can be erased or not + /// /// @param d The drive to inquire. + /// /// @return Non-zero means erasable pub fn burn_disc_erasable(d: *mut burn_drive) -> ::std::os::raw::c_int; } unsafe extern "C" { /// 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. pub fn burn_drive_get_status( drive: *mut burn_drive, @@ -2187,19 +2384,25 @@ unsafe extern "C" { unsafe extern "C" { /// 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 pub fn burn_write_opts_new(drive: *mut burn_drive) -> *mut burn_write_opts; } unsafe extern "C" { /// Inquires the drive associated with a burn_write_opts object. + /// /// @param opts object to inquire + /// /// @return pointer to drive + /// /// @since 0.4.0 pub fn burn_write_opts_get_drive(opts: *mut burn_write_opts) -> *mut burn_drive; } unsafe extern "C" { /// Frees a write_opts struct created with burn_write_opts_new + /// /// @param opts write_opts to free pub fn burn_write_opts_free(opts: *mut burn_write_opts); } @@ -2211,12 +2414,15 @@ pub struct burn_read_opts { unsafe extern "C" { /// 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 pub fn burn_read_opts_new(drive: *mut burn_drive) -> *mut burn_read_opts; } unsafe extern "C" { /// Frees a read_opts struct created with burn_read_opts_new + /// /// @param opts write_opts to free pub fn burn_read_opts_free(opts: *mut burn_read_opts); } @@ -2226,9 +2432,11 @@ unsafe extern "C" { /// 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. @@ -2244,10 +2452,13 @@ unsafe extern "C" { /// 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. @@ -2274,6 +2485,7 @@ unsafe extern "C" { /// 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 pub fn burn_disc_format(drive: *mut burn_drive, size: off_t, flag: ::std::os::raw::c_int); } @@ -2282,20 +2494,27 @@ unsafe extern "C" { /// 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 pub fn burn_disc_get_formats( drive: *mut burn_drive, @@ -2307,17 +2526,24 @@ unsafe extern "C" { } unsafe extern "C" { /// 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 pub fn burn_disc_get_format_descr( drive: *mut burn_drive, @@ -2331,7 +2557,9 @@ unsafe extern "C" { /// 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. pub fn burn_disc_read(drive: *mut burn_drive, o: *const burn_read_opts); } @@ -2339,11 +2567,17 @@ unsafe extern "C" { /// 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 description 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 pub fn burn_precheck_write( o: *mut burn_write_opts, @@ -2367,7 +2601,9 @@ unsafe extern "C" { /// 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 pub fn burn_disc_write(o: *mut burn_write_opts, disc: *mut burn_disc); } @@ -2379,14 +2615,20 @@ unsafe extern "C" { /// 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 pub fn burn_drive_set_stream_recording( drive: *mut burn_drive, @@ -2403,10 +2645,14 @@ unsafe extern "C" { /// 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 pub fn burn_drive_set_immed( drive: *mut burn_drive, @@ -2416,7 +2662,9 @@ unsafe extern "C" { unsafe extern "C" { /// 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 pub fn burn_drive_get_immed(drive: *mut burn_drive) -> ::std::os::raw::c_int; } @@ -2424,6 +2672,7 @@ unsafe extern "C" { /// 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. pub fn burn_drive_cancel(drive: *mut burn_drive); } @@ -2433,8 +2682,11 @@ unsafe extern "C" { /// 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 pub fn burn_drive_wrote_well(d: *mut burn_drive) -> ::std::os::raw::c_int; } @@ -2442,17 +2694,24 @@ unsafe extern "C" { /// 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 pub fn burn_drive_was_feat21_failure(d: *mut burn_drive) -> ::std::os::raw::c_int; } unsafe extern "C" { /// 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 pub fn burn_msf_to_sectors( m: ::std::os::raw::c_int, @@ -2462,9 +2721,13 @@ unsafe extern "C" { } unsafe extern "C" { /// 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 pub fn burn_sectors_to_msf( sectors: ::std::os::raw::c_int, @@ -2475,9 +2738,13 @@ unsafe extern "C" { } unsafe extern "C" { /// 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 pub fn burn_msf_to_lba( m: ::std::os::raw::c_int, @@ -2487,9 +2754,13 @@ unsafe extern "C" { } unsafe extern "C" { /// 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 pub fn burn_lba_to_msf( lba: ::std::os::raw::c_int, @@ -2500,30 +2771,38 @@ unsafe extern "C" { } unsafe extern "C" { /// Create a new disc + /// /// @return Pointer to a burn_disc object or NULL on failure. pub fn burn_disc_create() -> *mut burn_disc; } unsafe extern "C" { /// Delete disc and decrease the reference count on all its sessions + /// /// @param d The disc to be freed pub fn burn_disc_free(d: *mut burn_disc); } unsafe extern "C" { /// Create a new session + /// /// @return Pointer to a burn_session object or NULL on failure. pub fn burn_session_create() -> *mut burn_session; } unsafe extern "C" { /// Free a session (and decrease reference count on all tracks inside) + /// /// @param s Session to be freed pub fn burn_session_free(s: *mut burn_session); } unsafe extern "C" { /// 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 pub fn burn_disc_add_session( d: *mut burn_disc, @@ -2533,7 +2812,9 @@ unsafe extern "C" { } unsafe extern "C" { /// Remove a session from a disc + /// /// @param d Disc to remove session from + /// /// @param s Session pointer to find and remove pub fn burn_disc_remove_session( d: *mut burn_disc, @@ -2558,12 +2839,16 @@ unsafe extern "C" { /// 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 @@ -2571,18 +2856,23 @@ unsafe extern "C" { /// 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 pub fn burn_session_by_cue_file( session: *mut burn_session, @@ -2600,14 +2890,19 @@ unsafe extern "C" { } unsafe extern "C" { /// Free a track + /// /// @param t Track to free pub fn burn_track_free(t: *mut burn_track); } unsafe extern "C" { /// 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 pub fn burn_session_add_track( s: *mut burn_session, @@ -2617,8 +2912,11 @@ unsafe extern "C" { } unsafe extern "C" { /// 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 pub fn burn_session_remove_track( s: *mut burn_session, @@ -2631,10 +2929,15 @@ unsafe extern "C" { /// 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 pub fn burn_session_set_start_tno( session: *mut burn_session, @@ -2645,10 +2948,14 @@ unsafe extern "C" { unsafe extern "C" { /// 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 pub fn burn_session_get_start_tno( session: *mut burn_session, @@ -2679,12 +2986,19 @@ unsafe extern "C" { /// /// 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 pub fn burn_session_set_cdtext_par( s: *mut burn_session, @@ -2696,12 +3010,19 @@ unsafe extern "C" { } unsafe extern "C" { /// 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 pub fn burn_session_get_cdtext_par( s: *mut burn_session, @@ -2719,13 +3040,17 @@ unsafe extern "C" { /// 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\" @@ -2734,6 +3059,7 @@ unsafe extern "C" { /// 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 @@ -2750,12 +3076,16 @@ unsafe extern "C" { /// 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 pub fn burn_session_set_cdtext( s: *mut burn_session, @@ -2769,24 +3099,33 @@ unsafe extern "C" { } unsafe extern "C" { /// 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 pub fn burn_session_get_cdtext( s: *mut burn_session, @@ -2808,24 +3147,32 @@ unsafe extern "C" { /// 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 pub fn burn_session_input_sheet_v07t( session: *mut burn_session, @@ -2841,20 +3188,26 @@ unsafe extern "C" { /// 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 pub fn burn_cdtext_from_session( s: *mut burn_session, @@ -2867,6 +3220,7 @@ unsafe extern "C" { /// 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. @@ -2874,13 +3228,17 @@ unsafe extern "C" { /// 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 @@ -2889,16 +3247,20 @@ unsafe extern "C" { /// 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 pub fn burn_make_input_sheet_v07t( text_packs: *mut ::std::os::raw::c_uchar, @@ -2913,11 +3275,15 @@ unsafe extern "C" { unsafe extern "C" { /// 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 pub fn burn_session_dispose_cdtext( s: *mut burn_session, @@ -2931,13 +3297,19 @@ unsafe extern "C" { /// 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 pub fn burn_cdtext_from_packfile( path: *mut ::std::os::raw::c_char, @@ -2948,12 +3320,17 @@ unsafe extern "C" { } unsafe extern "C" { /// 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) pub fn burn_track_define_data( t: *mut burn_track, @@ -2974,25 +3351,34 @@ unsafe extern "C" { /// 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 pub fn burn_track_set_cdtext( t: *mut burn_track, @@ -3006,21 +3392,30 @@ unsafe extern "C" { } unsafe extern "C" { /// 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 pub fn burn_track_get_cdtext( t: *mut burn_track, @@ -3035,11 +3430,15 @@ unsafe extern "C" { unsafe extern "C" { /// 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 pub fn burn_track_dispose_cdtext( t: *mut burn_track, @@ -3051,12 +3450,16 @@ unsafe extern "C" { /// 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 pub fn burn_track_set_cdxa_conv( t: *mut burn_track, @@ -3066,12 +3469,17 @@ unsafe extern "C" { unsafe extern "C" { /// 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. pub fn burn_track_set_isrc( t: *mut burn_track, @@ -3084,12 +3492,17 @@ unsafe extern "C" { unsafe extern "C" { /// 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 pub fn burn_track_set_isrc_string( t: *mut burn_track, @@ -3099,6 +3512,7 @@ unsafe extern "C" { } unsafe extern "C" { /// Disable ISRC parameters for a track + /// /// @param t The track to change pub fn burn_track_clear_isrc(t: *mut burn_track); } @@ -3109,13 +3523,19 @@ unsafe extern "C" { /// 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 pub fn burn_track_set_index( t: *mut burn_track, @@ -3130,9 +3550,13 @@ unsafe extern "C" { /// 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 pub fn burn_track_clear_indice( t: *mut burn_track, @@ -3149,12 +3573,17 @@ unsafe extern "C" { /// 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 pub fn burn_track_set_pregap_size( t: *mut burn_track, @@ -3171,12 +3600,17 @@ unsafe extern "C" { /// 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 pub fn burn_track_set_postgap_size( t: *mut burn_track, @@ -3186,9 +3620,13 @@ unsafe extern "C" { } unsafe extern "C" { /// 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 pub fn burn_track_set_byte_swap( t: *mut burn_track, @@ -3197,20 +3635,27 @@ unsafe extern "C" { } unsafe extern "C" { /// 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 pub fn burn_session_hide_first_track(s: *mut burn_session, onoff: ::std::os::raw::c_int); } unsafe extern "C" { /// Get the drive's disc struct - free when done + /// /// @param d drive to query + /// /// @return the disc struct or NULL on failure pub fn burn_drive_get_disc(d: *mut burn_drive) -> *mut burn_disc; } unsafe extern "C" { /// 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 pub fn burn_track_set_source(t: *mut burn_track, s: *mut burn_source) -> burn_source_status; @@ -3221,22 +3666,30 @@ unsafe extern "C" { /// 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 pub fn burn_track_set_default_size(t: *mut burn_track, size: off_t) -> ::std::os::raw::c_int; } unsafe extern "C" { /// Free a burn_source (decrease its refcount and maybe free it) + /// /// @param s Source to free pub fn burn_source_free(s: *mut burn_source); } unsafe extern "C" { /// 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 pub fn burn_file_source_new( path: *const ::std::os::raw::c_char, @@ -3259,12 +3712,17 @@ unsafe extern "C" { /// 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 pub fn burn_os_open_track_src( path: *mut ::std::os::raw::c_char, @@ -3275,13 +3733,17 @@ unsafe extern "C" { unsafe extern "C" { /// 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 pub fn burn_os_alloc_buffer( amount: usize, @@ -3290,11 +3752,16 @@ unsafe extern "C" { } unsafe extern "C" { /// 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 pub fn burn_os_free_buffer( buffer: *mut ::std::os::raw::c_void, @@ -3306,11 +3773,15 @@ unsafe extern "C" { /// 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 pub fn burn_fd_source_new( datafd: ::std::os::raw::c_int, @@ -3335,26 +3806,34 @@ unsafe extern "C" { /// 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 pub fn burn_offst_source_new( inp: *mut burn_source, @@ -3378,9 +3857,11 @@ unsafe extern "C" { /// 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, @@ -3388,8 +3869,10 @@ unsafe extern "C" { /// burn_track_set_cdxa_conv(track, 1). /// Some variations of burn_source might work only with /// a particular chunksize. E.g. libisofs demands 2048. + /// /// @param chunks The number of chunks to be allocated in ring buffer. /// This value must be >= 2. + /// /// @param flag Bitfield for control purposes: /// bit0= The read method of inp is capable of delivering /// arbitrary amounts of data per call. Not only one @@ -3400,12 +3883,15 @@ unsafe extern "C" { /// You MUST use this on inp which uses an fd opened /// with burn_os_open_track_src(). /// Better do not use with other inp types. + /// /// @since 0.7.4 + /// /// @return A pointer to the newly created burn_source. /// Later both burn_sources, inp and the returned fifo, have /// to be disposed by calling burn_source_free() for each. /// inp can be freed immediately, the returned fifo may be /// kept as handle for burn_fifo_inquire_status(). + /// /// @since 0.4.0 pub fn burn_fifo_source_new( inp: *mut burn_source, @@ -3417,10 +3903,15 @@ unsafe extern "C" { unsafe extern "C" { /// Inquires state and fill parameters of a fifo burn_source which was created /// by burn_fifo_source_new() . Do not use with other burn_source variants. + /// /// @param fifo The fifo object to inquire + /// /// @param size The total size of the fifo + /// /// @param free_bytes The current free capacity of the fifo + /// /// @param status_text Returns a pointer to a constant text, see below + /// /// @return <0 reply invalid, >=0 fifo status code: /// bit0+1=input status, bit2=consumption status, i.e: /// 0=\"standby\" : data processing not started yet @@ -3431,6 +3922,7 @@ unsafe extern "C" { /// 5=\"abandoned\" : consumption has ended prematurely /// 6=\"ended\" : consumption has ended without input error /// 7=\"aborted\" : consumption has ended after input error + /// /// @since 0.4.0 pub fn burn_fifo_inquire_status( fifo: *mut burn_source, @@ -3441,17 +3933,25 @@ unsafe extern "C" { } unsafe extern "C" { /// Inquire various counters which reflect the fifo operation. + /// /// @param fifo The fifo object to inquire + /// /// @param total_min_fill The minimum number of bytes in the fifo. Beginning /// from the moment when fifo consumption is enabled. + /// /// @param interval_min_fill The minimum byte number beginning from the moment /// when fifo consumption is enabled or from the /// most recent moment when burn_fifo_next_interval() /// was called. + /// /// @param put_counter The number of data transactions into the fifo. + /// /// @param get_counter The number of data transactions out of the fifo. + /// /// @param empty_counter The number of times the fifo was empty. + /// /// @param full_counter The number of times the fifo was full. + /// /// @since 0.7.4 pub fn burn_fifo_get_statistics( fifo: *mut burn_source, @@ -3465,11 +3965,14 @@ unsafe extern "C" { } unsafe extern "C" { /// Inquire the fifo minimum fill counter for intervals and reset that counter. + /// /// @param fifo The fifo object to inquire + /// /// @param interval_min_fill The minimum number of bytes in the fifo. Beginning /// from the moment when fifo consumption is enabled /// or from the most recent moment when /// burn_fifo_next_interval() was called. + /// /// @since 0.7.4 pub fn burn_fifo_next_interval( fifo: *mut burn_source, @@ -3488,12 +3991,18 @@ unsafe extern "C" { /// data have arrived or until it becomes clear that this will not happen. /// The call may be repeated with increased bufsize. It will always yield /// the bytes beginning from the first one in the fifo. + /// /// @param fifo The fifo object to start and to inquire + /// /// @param buf Pointer to memory of at least bufsize bytes where to /// deliver the peeked data. + /// /// @param bufsize Number of bytes to peek from the start of the fifo data + /// /// @param flag Bitfield for control purposes (unused yet, submit 0). + /// /// @return <0 on severe error, 0 if not enough data, 1 if bufsize bytes read + /// /// @since 0.5.0 pub fn burn_fifo_peek_data( fifo: *mut burn_source, @@ -3507,13 +4016,18 @@ unsafe extern "C" { /// of bytes have arrived or until it becomes clear that this will not happen. /// Filling will go on asynchronously after burn_fifo_fill() returned. /// This call and burn_fifo_peek_data() do not disturb each other. + /// /// @param fifo The fifo object to start + /// /// @param fill Number of bytes desired. Expect to get return 1 if /// at least fifo size - 32k were read. + /// /// @param flag Bitfield for control purposes. /// bit0= fill fifo to maximum size + /// /// @return <0 on severe error, 0 if not enough data, /// 1 if desired amount or fifo full + /// /// @since 0.7.4 pub fn burn_fifo_fill( fifo: *mut burn_source, @@ -3524,9 +4038,13 @@ unsafe extern "C" { unsafe extern "C" { /// Sets a fixed track size after the data source object has already been /// created. + /// /// @param t The track to operate on + /// /// @param size the number of bytes to use as track size + /// /// @return <=0 indicates failure , >0 success + /// /// @since 0.3.6 pub fn burn_track_set_size(t: *mut burn_track, size: off_t) -> ::std::os::raw::c_int; } @@ -3539,9 +4057,13 @@ unsafe extern "C" { unsafe extern "C" { /// Tells how many source bytes have been read and how many data bytes have /// been written by the track during burn. + /// /// @param t The track to inquire + /// /// @param read_bytes Number of bytes read from the track source + /// /// @param written_bytes Number of bytes written to track + /// /// @since 0.2.6 pub fn burn_track_get_counters( t: *mut burn_track, @@ -3554,8 +4076,11 @@ unsafe extern "C" { /// Note: \"k\" is 1000, not 1024. /// 1xCD = 176.4 k/s, 1xDVD = 1385 k/s, 1xBD = 4496 k/s. /// Fractional speeds should be rounded up. Like 4xCD = 706. + /// /// @param d The drive to set speed for + /// /// @param read Read speed in k/s (0 is max, -1 is min). + /// /// @param write Write speed in k/s (0 is max, -1 is min). pub fn burn_drive_set_speed( d: *mut burn_drive, @@ -3573,10 +4098,15 @@ unsafe extern "C" { /// only coarsly or ignore the setting after a few MB of fast read attempts. /// /// The call parameters have the same meaning as with burn_drive_set_speed(). + /// /// @param d The drive to set speed for. It must be a role 1 drive. + /// /// @param read Read speed in k/s (0 is max, -1 is min). + /// /// @param write Write speed in k/s (0 is max, -1 is min). + /// /// @return 1=success , 0=failure + /// /// @since 1.5.4 pub fn burn_drive_set_speed_exact( d: *mut burn_drive, @@ -3598,23 +4128,31 @@ unsafe extern "C" { /// been necessary. The next call will reduce or enlarge its own sleeping /// period by this value. /// + /// /// @param kb_per_second the desired speed in 1000 bytes per second. /// Supplied by the caller. + /// /// @max_corr the maximum backlog in microseconds which shall /// be compensated by the next call. Supplied by the /// caller. Not more than 1 billion = 1000 seconds. + /// /// @param prev_time time keeper updated by burn_nominal_slowdown(). /// The caller provides the memory and elsewise should /// carry it unchanged from call to call. + /// /// @param us_corr updated by burn_nominal_slowdown(). See above. /// The caller provides the memory and elsewise should /// carry it unchanged from call to call. + /// /// @param b_since_prev byte count since the previous call. This number /// has to be counted and supplied by the caller. + /// /// @param flag Bitfield for control purposes: /// bit0= initialize *prev_time and *us_corr, /// ignore other parameters, do not wait + /// /// @return 2=no wait because no usable kb_per_second , 1=success , 0=failure + /// /// @since 1.5.4 pub fn burn_nominal_slowdown( kb_per_second: ::std::os::raw::c_int, @@ -3647,16 +4185,25 @@ unsafe extern "C" { /// they report their buffer fill with delay. Some do not go to full speed /// unless their buffer is full. /// + /// /// @param d The drive to control + /// /// @param enable 0= disable , 1= enable waiting , (-1 = do not change setting) + /// /// @param min_usec Shortest possible sleeping period (given in micro seconds) + /// /// @param max_usec Longest possible sleeping period (given in micro seconds) + /// /// @param timeout_sec If a single write has to wait longer than this number /// of seconds, then waiting gets disabled and mindless /// writing starts. A value of 0 disables this timeout. + /// /// @param min_percent Minimum of desired buffer oscillation: 25 to 100 + /// /// @param max_percent Maximum of desired buffer oscillation: 25 to 100 + /// /// @return 1=success , 0=failure + /// /// @since 0.3.8 pub fn burn_drive_set_buffer_waiting( d: *mut burn_drive, @@ -3679,9 +4226,13 @@ unsafe extern "C" { /// This call may only be made when burn_drive_get_status() returns /// BURN_DRIVE_IDLE. /// + /// /// @param d The drive to control + /// /// @param simulate 1 enables simulation, 0 enables real writing + /// /// @return 1=success , 0=failure + /// /// @since 1.4.8 pub fn burn_drive_reset_simulate( d: *mut burn_drive, @@ -3701,9 +4252,13 @@ unsafe extern "C" { /// Sets the write type for the write_opts struct. /// 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. + /// /// @param opts The write opts to change + /// /// @param write_type The write type to use + /// /// @param block_type The block type to use + /// /// @return Returns 1 on success and 0 on failure. pub fn burn_write_opts_set_write_type( opts: *mut burn_write_opts, @@ -3716,14 +4271,20 @@ unsafe extern "C" { /// to find a suitable write type and block type for a given write job /// described by opts and disc. To be used after all other setups have been /// made, i.e. immediately before burn_disc_write(). + /// /// @param opts The nearly complete write opts to change + /// /// @param disc The already composed session and track model + /// /// @param reasons This text string collects reasons for decision or failure + /// /// @param flag Bitfield for control purposes: /// bit0= do not choose type but check the one that is already set /// bit1= do not issue error messages via burn_msgs queue /// (is automatically set with bit0) + /// /// @return Chosen write type. BURN_WRITE_NONE on failure. + /// /// @since 0.3.2 pub fn burn_write_opts_auto_write_type( opts: *mut burn_write_opts, @@ -3734,8 +4295,11 @@ unsafe extern "C" { } unsafe extern "C" { /// Supplies toc entries for writing - not normally required for cd mastering + /// /// @param opts The write opts to change + /// /// @param count The number of entries + /// /// @param toc_entries pub fn burn_write_opts_set_toc_entries( opts: *mut burn_write_opts, @@ -3745,7 +4309,9 @@ unsafe extern "C" { } unsafe extern "C" { /// Sets the session format for a disc + /// /// @param opts The write opts to change + /// /// @param format The session format to set pub fn burn_write_opts_set_format(opts: *mut burn_write_opts, format: ::std::os::raw::c_int); } @@ -3766,8 +4332,11 @@ unsafe extern "C" { /// a simulated burn run. /// Use burn_drive_reset_simulate(drive, 0) if you really want to end /// simulation before you call burn_disc_write() with new write options. + /// /// @param opts The write opts to change + /// /// @param sim Non-zero enables simulation, 0 enables real writing + /// /// @return Returns 1 on success and 0 on failure. pub fn burn_write_opts_set_simulate( opts: *mut burn_write_opts, @@ -3778,8 +4347,11 @@ unsafe extern "C" { /// Controls buffer underrun prevention. This is only needed with CD media /// and possibly with old DVD-R drives. All other media types are not /// vulnerable to burn failure due to buffer underrun. + /// /// @param opts The write opts to change + /// /// @param underrun_proof if non-zero, buffer underrun protection is enabled + /// /// @return Returns 1 if the drive announces to be capable of underrun /// prevention, /// Returns 0 if not. @@ -3790,7 +4362,9 @@ unsafe extern "C" { } unsafe extern "C" { /// Sets whether to use opc or not with the write_opts struct + /// /// @param opts The write opts to change + /// /// @param opc If non-zero, optical power calibration will be performed at /// start of burn pub fn burn_write_opts_set_perform_opc(opts: *mut burn_write_opts, opc: ::std::os::raw::c_int); @@ -3799,7 +4373,9 @@ unsafe extern "C" { /// The Q sub-channel of a CD may contain a Media Catalog Number of 13 decimal /// digits. This call sets the string of digits, but does not yet activate it /// for writing. + /// /// @param opts The write opts to change + /// /// @param mediacatalog The 13 decimal digits as ASCII bytes. I.e. '0' = 0x30. pub fn burn_write_opts_set_mediacatalog( opts: *mut burn_write_opts, @@ -3809,7 +4385,9 @@ unsafe extern "C" { unsafe extern "C" { /// This call activates the Media Catalog Number for writing. The digits of /// that number have to be set by call burn_write_opts_set_mediacatalog(). + /// /// @param opts The write opts to change + /// /// @param has_mediacatalog 1= activate writing of catalog to Q sub-channel /// 0= deactivate it pub fn burn_write_opts_set_has_mediacatalog( @@ -3824,8 +4402,11 @@ unsafe extern "C" { /// DVD-R DL are not capable of this at all. /// libburn will refuse to write if burn_write_opts_set_multi() is /// enabled under such conditions. + /// /// @param opts The option object to be manipulated + /// /// @param multi 1=media will be appendable, 0=media will be closed (default) + /// /// @since 0.2.6 pub fn burn_write_opts_set_multi(opts: *mut burn_write_opts, multi: ::std::os::raw::c_int); } @@ -3843,7 +4424,9 @@ unsafe extern "C" { /// burn attempt with BURN_WRITE_SAO, then set the severity of the error /// message low enough, so that the application does not see reason to abort. /// + /// /// @param opts The option object to be manipulated + /// /// @param severity Severity as with burn_msgs_set_severities(). /// \"ALL\" or empty text means the default severity that /// is attributed to other kinds of write errors. @@ -3855,7 +4438,9 @@ unsafe extern "C" { unsafe extern "C" { /// Submit an array of CD-TEXT packs which shall be written to the Lead-in /// of a SAO write run on CD. + /// /// @param opts The option object to be manipulated + /// /// @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. @@ -3863,14 +4448,18 @@ unsafe extern "C" { /// 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. /// This parameter may be 0 if the currently attached /// array of packs shall be removed. + /// /// @param flag Bitfield for control purposes. /// bit0= do not verify checksums /// bit1= repair mismatching checksums /// bit2= repair checksums if they are 00 00 with each pack + /// /// @return 1 on success, <= 0 on failure + /// /// @since 1.2.0 pub fn burn_write_opts_set_leadin_text( opts: *mut burn_write_opts, @@ -3889,8 +4478,11 @@ unsafe extern "C" { /// Call burn_disc_get_multi_caps() can obtain the necessary media info. See /// resulting struct burn_multi_caps elements .start_adr , .start_alignment , /// .start_range_low , .start_range_high . + /// /// @param opts The write opts to change + /// /// @param value The address in bytes (-1 = start at default address) + /// /// @since 0.3.0 pub fn burn_write_opts_set_start_byte(opts: *mut burn_write_opts, value: off_t); } @@ -3900,8 +4492,11 @@ unsafe extern "C" { /// /// Controls whether the whole available space of the media shall be filled up /// by the last track of the last session. + /// /// @param opts The write opts to change + /// /// @param fill_up_media If 1 : fill up by last track, if 0 = do not fill up + /// /// @since 0.3.4 pub fn burn_write_opts_set_fillup( opts: *mut burn_write_opts, @@ -3916,8 +4511,11 @@ unsafe extern "C" { /// The check whether a write operation exceeds the size of the medium /// as announced by the drive. This is known as \"overburn\" and may work /// for a few thousand additional blocks on CD media with write type SAO. + /// /// @param opts The write opts to change + /// /// @param use_force 1=ignore above checks, 0=refuse work on failed check + /// /// @since 0.3.4 pub fn burn_write_opts_set_force(opts: *mut burn_write_opts, use_force: ::std::os::raw::c_int); } @@ -3928,10 +4526,14 @@ unsafe extern "C" { /// then it also disables error management and correction. Weigh your /// priorities. This affects the write operations of burn_disc_write() /// and subsequent calls of burn_random_access_write(). + /// /// @param opts The write opts to change + /// /// @param value 0=use 2Ah WRITE10, 1=use AAh WRITE12 with Streaming bit + /// /// @since 0.6.4: /// >=16 use WRITE12 but not before the LBA given by value + /// /// @since 0.4.6 pub fn burn_write_opts_set_stream_recording( opts: *mut burn_write_opts, @@ -3943,10 +4545,13 @@ unsafe extern "C" { /// determined according to media type and setting of stream recording. /// A chunk size of 64 KB may improve throughput with bus systems which show /// latency problems. + /// /// @param opts The write opts to change + /// /// @param obs Number of bytes which shall be sent by a single write command. /// 0 means automatic size, 32768 and 65336 are the only other /// accepted sizes for now. + /// /// @since 0.7.4 pub fn burn_write_opts_set_dvd_obs(opts: *mut burn_write_opts, obs: ::std::os::raw::c_int); } @@ -3955,8 +4560,11 @@ unsafe extern "C" { /// its full size. This applies to DVD, BD and stdio: pseudo-drives. /// Note: This override may get enabled fixely already at compile time by /// defining macro Libburn_dvd_always_obs_paD . + /// /// @param opts The write opts to change + /// /// @param pad 1 means to pad up in any case, 0 means automatic decision. + /// /// @since 1.2.4 pub fn burn_write_opts_set_obs_pad(opts: *mut burn_write_opts, pad: ::std::os::raw::c_int); } @@ -3965,10 +4573,13 @@ unsafe extern "C" { /// last write chunk to its full size. /// Even if this exempt is granted it gets into effect only if stream recording /// is disabled and burn_write_opts_set_obs_pad() is set to 0. + /// /// @param opts The write opts to change + /// /// @param value 1= possibly exempt BD-R from end chunk padding. /// 0= always act on BD-R as if /// burn_write_opts_set_obs_pad(opts, 1) is in effect. + /// /// @since 1.5.6 pub fn burn_write_opts_set_bdr_obs_exempt( opts: *mut burn_write_opts, @@ -3979,7 +4590,9 @@ unsafe extern "C" { /// Sets the rhythm by which stdio pseudo drives force their output data to /// be consumed by the receiving storage device. This forcing keeps the memory /// from being clogged with lots of pending data for slow devices. + /// /// @param opts The write opts to change + /// /// @param rhythm Number of 2KB output blocks after which fsync(2) is /// performed. /// -1 means no fsync() @@ -3987,6 +4600,7 @@ unsafe extern "C" { /// 1 means fsync() only at end, @since 1.3.8 (noop before 1.3.8) /// elsewise the value must be >= 32. /// Default is currently 8192 = 16 MB. + /// /// @since 0.7.4 pub fn burn_write_opts_set_stdio_fsync( opts: *mut burn_write_opts, @@ -3995,20 +4609,26 @@ unsafe extern "C" { } unsafe extern "C" { /// Sets whether to read in raw mode or not + /// /// @param opts The read opts to change + /// /// @param raw_mode If non-zero, reading will be done in raw mode, so that everything in the data tracks on the /// disc is read, including headers. pub fn burn_read_opts_set_raw(opts: *mut burn_read_opts, raw_mode: ::std::os::raw::c_int); } unsafe extern "C" { /// Sets whether to report c2 errors or not + /// /// @param opts The read opts to change + /// /// @param c2errors If non-zero, report c2 errors. pub fn burn_read_opts_set_c2errors(opts: *mut burn_read_opts, c2errors: ::std::os::raw::c_int); } unsafe extern "C" { /// Sets whether to read subcodes from audio tracks or not + /// /// @param opts The read opts to change + /// /// @param subcodes_audio If non-zero, read subcodes from audio tracks on the disc. pub fn burn_read_opts_read_subcodes_audio( opts: *mut burn_read_opts, @@ -4017,7 +4637,9 @@ unsafe extern "C" { } unsafe extern "C" { /// Sets whether to read subcodes from data tracks or not + /// /// @param opts The read opts to change + /// /// @param subcodes_data If non-zero, read subcodes from data tracks on the disc. pub fn burn_read_opts_read_subcodes_data( opts: *mut burn_read_opts, @@ -4026,7 +4648,9 @@ unsafe extern "C" { } unsafe extern "C" { /// Sets whether to recover errors if possible + /// /// @param opts The read opts to change + /// /// @param hardware_error_recovery If non-zero, attempt to recover errors if possible. pub fn burn_read_opts_set_hardware_error_recovery( opts: *mut burn_read_opts, @@ -4035,7 +4659,9 @@ unsafe extern "C" { } unsafe extern "C" { /// Sets whether to report recovered errors or not + /// /// @param opts The read opts to change + /// /// @param report_recovered_errors If non-zero, recovered errors will be reported. pub fn burn_read_opts_report_recovered_errors( opts: *mut burn_read_opts, @@ -4044,7 +4670,9 @@ unsafe extern "C" { } unsafe extern "C" { /// Sets whether blocks with unrecoverable errors should be read or not + /// /// @param opts The read opts to change + /// /// @param transfer_damaged_blocks If non-zero, blocks with unrecoverable errors will still be read. pub fn burn_read_opts_transfer_damaged_blocks( opts: *mut burn_read_opts, @@ -4053,7 +4681,9 @@ unsafe extern "C" { } unsafe extern "C" { /// Sets the number of retries to attempt when trying to correct an error + /// /// @param opts The read opts to change + /// /// @param hardware_error_retries The number of retries to attempt when correcting an error. pub fn burn_read_opts_set_hardware_error_retries( opts: *mut burn_read_opts, @@ -4064,13 +4694,19 @@ unsafe extern "C" { /// Gets the list of profile codes supported by the drive. /// Profiles depict the feature sets which constitute media types. For /// known profile codes and names see burn_disc_get_profile(). + /// /// @param d is the drive to query + /// /// @param num_profiles returns the number of supported profiles + /// /// @param profiles returns the profile codes + /// /// @param is_current returns the status of the corresponding profile code: /// 1= current, i.e. the matching media is loaded /// 0= not current, i.e. the matching media is not loaded + /// /// @return always 1 for now + /// /// @since 0.7.0 pub fn burn_drive_get_all_profiles( d: *mut burn_drive, @@ -4081,9 +4717,13 @@ unsafe extern "C" { } unsafe extern "C" { /// Obtains the profile name associated with a profile code. + /// /// @param profile_code the profile code to be translated + /// /// @param name returns the profile name (e.g. \"DVD+RW\") + /// /// @return 1= known profile code , 0= unknown profile code + /// /// @since 0.7.0 pub fn burn_obtain_profile_name( profile_code: ::std::os::raw::c_int, @@ -4094,11 +4734,15 @@ unsafe extern "C" { /// Obtains the list of SCSI Feature Codes from feature descriptors which /// were obtained from the drive when it was most recently acquired or /// re-assessed. + /// /// @param d Drive to query + /// /// @param count Returns the number of allocated elements in feature_codes + /// /// @param feature_codes Returns the allocated array of feature codes. /// If returned *feature_codes is not NULL, dispose it /// by free() when it is no longer needed. + /// /// @since 1.5.2 pub fn burn_drive_get_feature_codes( d: *mut burn_drive, @@ -4110,17 +4754,23 @@ unsafe extern "C" { /// Obtains the fields and data of a particular feature which were obtained /// from the drive when it was last acquired or re-assessed. See MMC specs /// for full detail. + /// /// @param d Drive to query + /// /// @param feature_code A number as learned by burn_drive_get_feature_codes() + /// /// @param flags Returns byte 2 of the feature descriptor: /// bit0= Current /// bit1= Persistent /// bit2-5= Version + /// /// @param additional_length Returns byte 3 of descriptor. /// This is the size of feature_data. + /// /// @param feature_data Returns further bytes of descriptor. /// If returned *feature_data is not NULL, dispose it /// by free() when it is no longer needed. + /// /// @param feature_text Returns text representation of the feature descriptor: /// Code +/- : Name : Version,P/N : Hex bytes : Parsed info /// Current features are marked by \"+\", others by \"-\". @@ -4129,9 +4779,11 @@ unsafe extern "C" { /// no text is generated and returned. /// If returned *feature_text is not NULL, dispose it /// by free() when it is no longer needed. + /// /// @return 0 feature descriptor is not present /// -1 out of memory /// >0 success + /// /// @since 1.5.2 pub fn burn_drive_get_feature( d: *mut burn_drive, @@ -4146,7 +4798,9 @@ unsafe extern "C" { /// Gets the maximum write speed for a drive and eventually loaded media. /// The return value might change by the media type of already loaded media, /// again by call burn_drive_grab() and again by call burn_disc_read_atip(). + /// /// @param d Drive to query + /// /// @return Maximum write speed in K/s pub fn burn_drive_get_write_speed(d: *mut burn_drive) -> ::std::os::raw::c_int; } @@ -4154,14 +4808,19 @@ unsafe extern "C" { /// Gets the minimum write speed for a drive and eventually loaded media. /// The return value might change by the media type of already loaded media, /// again by call burn_drive_grab() and again by call burn_disc_read_atip(). + /// /// @param d Drive to query + /// /// @return Minimum write speed in K/s + /// /// @since 0.2.6 pub fn burn_drive_get_min_write_speed(d: *mut burn_drive) -> ::std::os::raw::c_int; } unsafe extern "C" { /// Gets the maximum read speed for a drive + /// /// @param d Drive to query + /// /// @return Maximum read speed in K/s pub fn burn_drive_get_read_speed(d: *mut burn_drive) -> ::std::os::raw::c_int; } @@ -4173,9 +4832,13 @@ unsafe extern "C" { /// may appear several times in the list. The list content depends much on /// drive and media type. It seems that .source == 1 applies mostly to CD media /// whereas .source == 2 applies to any media. + /// /// @param d Drive to query + /// /// @param speed_list The copy. If empty, *speed_list gets returned as NULL. + /// /// @return 1=success , 0=list empty , <0 severe error + /// /// @since 0.3.0 pub fn burn_drive_get_speedlist( d: *mut burn_drive, @@ -4188,15 +4851,21 @@ unsafe extern "C" { /// descriptors with the highest end_lba. If it is -1 then the slowest speed /// descriptor is chosen regardless of end_lba. Parameter flag decides whether /// the speed goal means write speed or read speed. + /// /// @param d Drive to query + /// /// @param speed_goal Upper limit for speed, /// 0=search for maximum speed , -1 search for minimum speed + /// /// @param best_descr Result of the search, NULL if no match + /// /// @param flag Bitfield for control purposes /// bit0= look for best read speed rather than write speed /// bit1= look for any source type (else look for source==2 first /// and for any other source type only with CD media) + /// /// @return >0 indicates a valid best_descr, 0 = no valid best_descr + /// /// @since 0.3.8 pub fn burn_drive_get_best_speed( d: *mut burn_drive, @@ -4208,8 +4877,11 @@ unsafe extern "C" { unsafe extern "C" { /// Dispose a speed descriptor list copy which was obtained by /// burn_drive_get_speedlist(). + /// /// @param speed_list The list copy. *speed_list gets set to NULL. + /// /// @return 1=list disposed , 0= *speedlist was already NULL + /// /// @since 0.3.0 pub fn burn_drive_free_speedlist( speed_list: *mut *mut burn_speed_descriptor, @@ -4291,14 +4963,20 @@ unsafe extern "C" { /// which are appropriate for the drive and the loaded media. The drive /// must be grabbed for this call. The returned structure has to be disposed /// via burn_disc_free_multi_caps() when no longer needed. + /// /// @param d The drive to inquire + /// /// @param wt With BURN_WRITE_NONE the best capabilities of all write modes /// get returned. If set to a write mode like BURN_WRITE_SAO the /// capabilities with that particular mode are returned and the /// return value is 0 if the desired mode is not possible. + /// /// @param caps returns the info structure + /// /// @param flag Bitfield for control purposes (unused yet, submit 0) + /// /// @return < 0 : error , 0 : writing seems impossible , 1 : writing possible + /// /// @since 0.3.2 pub fn burn_disc_get_multi_caps( d: *mut burn_drive, @@ -4310,20 +4988,27 @@ unsafe extern "C" { unsafe extern "C" { /// Removes from memory a multi session info structure which was returned by /// burn_disc_get_multi_caps(). The pointer *caps gets set to NULL. + /// /// @param caps the info structure to dispose (note: pointer to pointer) + /// /// @return 0 : *caps was already NULL, 1 : memory object was disposed + /// /// @since 0.3.2 pub fn burn_disc_free_multi_caps(caps: *mut *mut burn_multi_caps) -> ::std::os::raw::c_int; } unsafe extern "C" { /// Gets a copy of the toc_entry structure associated with a track + /// /// @param t Track to get the entry from + /// /// @param entry Struct for the library to fill out pub fn burn_track_get_entry(t: *mut burn_track, entry: *mut burn_toc_entry); } unsafe extern "C" { /// Gets a copy of the toc_entry structure associated with a session's lead out + /// /// @param s Session to get the entry from + /// /// @param entry Struct for the library to fill out pub fn burn_session_get_leadout_entry(s: *mut burn_session, entry: *mut burn_toc_entry); } @@ -4334,8 +5019,11 @@ unsafe extern "C" { /// elements. All above *num are incomplete sessions. /// Typically there is at most one incomplete session with one empty track. /// DVD+R and BD-R seem support more than one track with even readable data. + /// /// @param d Disc to get session array for + /// /// @param num Returns the number of sessions in the array + /// /// @return array of sessions pub fn burn_disc_get_sessions( d: *mut burn_disc, @@ -4346,7 +5034,9 @@ unsafe extern "C" { /// Obtains the number of incomplete sessions which are recorded in the /// result array of burn_disc_get_sessions() after the complete sessions. /// See above. + /// /// @param d Disc object to inquire + /// /// @return Number of incomplete sessions pub fn burn_disc_get_incomplete_sessions(d: *mut burn_disc) -> ::std::os::raw::c_int; } @@ -4356,8 +5046,11 @@ unsafe extern "C" { unsafe extern "C" { /// Gets an array of all the tracks for a session /// THIS IS NO LONGER VALID AFTER YOU ADD OR REMOVE A TRACK + /// /// @param s session to get track array for + /// /// @param num Returns the number of tracks in the array + /// /// @return array of tracks pub fn burn_session_get_tracks( s: *mut burn_session, @@ -4369,13 +5062,17 @@ unsafe extern "C" { } unsafe extern "C" { /// Gets the mode of a track + /// /// @param track the track to query + /// /// @return the track's mode pub fn burn_track_get_mode(track: *mut burn_track) -> ::std::os::raw::c_int; } unsafe extern "C" { /// Returns whether the first track of a session is hidden in the pregap + /// /// @param session the session to query + /// /// @return non-zero means the first track is hidden pub fn burn_session_get_hidefirst(session: *mut burn_session) -> ::std::os::raw::c_int; } @@ -4383,8 +5080,11 @@ unsafe extern "C" { /// Returns the library's version in its parts. /// This is the runtime counterpart of the three build time macros /// burn_header_version_* below. + /// /// @param major The major version number + /// /// @param minor The minor version number + /// /// @param micro The micro version number pub fn burn_version( major: *mut ::std::os::raw::c_int, @@ -4396,8 +5096,11 @@ unsafe extern "C" { /// Obtain the id string of the SCSI transport interface. /// This interface may be a system specific adapter module of libburn or /// an adapter to a supporting library like libcdio. + /// /// @param flag Bitfield for control puposes, submit 0 for now + /// /// @return A pointer to the id string. Do not alter the string content. + /// /// @since 0.7.6 pub fn burn_scsi_transport_id(flag: ::std::os::raw::c_int) -> *mut ::std::os::raw::c_char; } @@ -4405,13 +5108,18 @@ unsafe extern "C" { /// Control queueing and stderr printing of messages from libburn. /// Severity may be one of \"NEVER\", \"ABORT\", \"FATAL\", \"FAILURE\", \"SORRY\", /// \"WARNING\", \"HINT\", \"NOTE\", \"UPDATE\", \"DEBUG\", \"ALL\". + /// /// @param queue_severity Gives the minimum limit for messages to be queued. /// Default: \"NEVER\". If you queue messages then you /// must consume them by burn_msgs_obtain(). + /// /// @param print_severity Does the same for messages to be printed directly /// to stderr. Default: \"FATAL\". + /// /// @param print_id A text prefix to be printed before the message. + /// /// @return >0 for success, <=0 for error + /// /// @since 0.2.6 pub fn burn_msgs_set_severities( queue_severity: *mut ::std::os::raw::c_char, @@ -4423,18 +5131,25 @@ unsafe extern "C" { /// Obtain the oldest pending libburn message from the queue which has at /// least the given minimum_severity. This message and any older message of /// lower severity will get discarded from the queue and is then lost forever. + /// /// @param minimum_severity may be one of \"NEVER\", \"ABORT\", \"FATAL\", /// \"FAILURE\", \"SORRY\", \"WARNING\", \"HINT\", \"NOTE\", \"UPDATE\", /// \"DEBUG\", \"ALL\". /// To call with minimum_severity \"NEVER\" will discard the /// whole queue. + /// /// @param error_code Will become a unique error code as listed in /// libburn/libdax_msgs.h + /// /// @param msg_text Must provide at least BURN_MSGS_MESSAGE_LEN bytes. + /// /// @param os_errno Will become the eventual errno related to the message + /// /// @param severity Will become the severity related to the message and /// should provide at least 80 bytes. + /// /// @return 1 if a matching item was found, 0 if not, <0 for severe errors + /// /// @since 0.2.6 pub fn burn_msgs_obtain( minimum_severity: *mut ::std::os::raw::c_char, @@ -4447,19 +5162,26 @@ unsafe extern "C" { unsafe extern "C" { /// Submit a message to the libburn queueing system. It will be queued or /// printed as if it was generated by libburn itself. + /// /// @param error_code The unique error code of your message. /// Submit 0 if you do not have reserved error codes within /// the libburnia project. + /// /// @param msg_text Not more than BURN_MSGS_MESSAGE_LEN characters of /// message text. + /// /// @param os_errno Eventual errno related to the message. Submit 0 if /// the message is not related to a operating system error. + /// /// @param severity One of \"ABORT\", \"FATAL\", \"FAILURE\", \"SORRY\", \"WARNING\", /// \"HINT\", \"NOTE\", \"UPDATE\", \"DEBUG\". Defaults to \"FATAL\". + /// /// @param d An eventual drive to which the message shall be related. /// Submit NULL if the message is not specific to a /// particular drive object. + /// /// @return 1 if message was delivered, <=0 if failure + /// /// @since 0.4.0 pub fn burn_msgs_submit( error_code: ::std::os::raw::c_int, @@ -4472,10 +5194,15 @@ unsafe extern "C" { unsafe extern "C" { /// Convert a severity name into a severity number, which gives the severity /// rank of the name. + /// /// @param severity_name A name as with burn_msgs_submit(), e.g. \"SORRY\". + /// /// @param severity_number The rank number: the higher, the more severe. + /// /// @param flag Bitfield for control purposes (unused yet, submit 0) + /// /// @return >0 success, <=0 failure + /// /// @since 0.4.0 pub fn burn_text_to_sev( severity_name: *mut ::std::os::raw::c_char, @@ -4485,10 +5212,15 @@ unsafe extern "C" { } unsafe extern "C" { /// Convert a severity number into a severity name + /// /// @param severity_number The rank number: the higher, the more severe. + /// /// @param severity_name A name as with burn_msgs_submit(), e.g. \"SORRY\". + /// /// @param flag Bitfield for control purposes (unused yet, submit 0) + /// /// @return >0 success, <=0 failure + /// /// @since 0.4.4 pub fn burn_sev_to_text( severity_number: ::std::os::raw::c_int, @@ -4499,8 +5231,11 @@ unsafe extern "C" { unsafe extern "C" { /// Return a blank separated list of severity names. Sorted from low /// to high severity. + /// /// @param flag Bitfield for control purposes (unused yet, submit 0) + /// /// @return A constant string with the severity names + /// /// @since 1.2.6 pub fn burn_list_sev_texts(flag: ::std::os::raw::c_int) -> *mut ::std::os::raw::c_char; } @@ -4508,8 +5243,11 @@ unsafe extern "C" { /// Replace the messenger object handle of libburn by a compatible handle /// obtained from a related library. /// See also: libisofs, API function iso_get_messenger(). + /// /// @param messenger The foreign but compatible message handle. + /// /// @return 1 : success, <=0 : failure + /// /// @since 0.4.0 pub fn burn_set_messenger(messenger: *mut ::std::os::raw::c_void) -> ::std::os::raw::c_int; } @@ -4545,8 +5283,10 @@ unsafe extern "C" { /// and to call burn_is_aborting(0) when the drive is BURN_DRIVE_IDLE. /// If burn_is_aborting(0) returns 1, then call burn_abort() and exit(1). /// + /// /// @param handle Opaque handle eventually pointing to an application /// provided memory object + /// /// @param handler A function to be called on signals, if the handling bits /// in parameter mode are set 0. /// It will get parameter handle as argument. flag will be 0. @@ -4555,6 +5295,7 @@ unsafe extern "C" { /// signal handler of libburn will return and let the program /// continue its operations. Any other return value causes /// exit(1). + /// /// @param mode : bit0 - bit3: Handling of received signals: /// 0 Install libburn wrapping signal handler, which will call /// handler(handle, signum, 0) on nearly all signals @@ -4567,6 +5308,7 @@ unsafe extern "C" { /// All actions activate receive mode 2 to ignore further /// signals. /// 0 Same as 1 (for pre-0.7.8 backward compatibility) + /// /// @since 0.7.8 /// 1 Catch the control thread in abort handler, call /// burn_abort() with a patience value > 0 and @@ -4586,6 +5328,7 @@ unsafe extern "C" { /// bit8: @since 1.3.2 /// try to ignore SIGPIPE (regardless of bit0 - bit3) /// + /// /// @since 0.2.6 pub fn burn_set_signal_handling( handle: *mut ::std::os::raw::c_void, @@ -4618,16 +5361,23 @@ unsafe extern "C" { /// operation or synchronization of the drive buffer will happen. /// See burn_drive_reset_simulate(). /// + /// /// @param d The drive to which to write + /// /// @param byte_address The start address of the write in byte /// (1 LBA unit = 2048 bytes) (do respect media alignment) + /// /// @param data The bytes to be written + /// /// @param data_count The number of those bytes (do respect media alignment) /// data_count == 0 is permitted (e.g. to flush the /// drive buffer without further data transfer). + /// /// @param flag Bitfield for control purposes: /// bit0 = flush the drive buffer after eventual writing + /// /// @return 1=successful , <=0 : number of transferred bytes * -1 + /// /// @since 0.4.0 pub fn burn_random_access_write( d: *mut burn_drive, @@ -4648,10 +5398,15 @@ unsafe extern "C" { /// of each track which might be TAO Run-out blocks. /// If the drive is actually a large file or block device, then the capacity /// is curbed to a maximum of 0x7ffffff0 blocks = 4 TB - 32 KB. + /// /// @param d The drive from which to read + /// /// @param capacity Will return the result if valid + /// /// @param flag Bitfield for control purposes: Unused yet, submit 0. + /// /// @return 1=successful , <=0 an error occurred + /// /// @since 0.6.0 pub fn burn_get_read_capacity( d: *mut burn_drive, @@ -4668,21 +5423,29 @@ unsafe extern "C" { /// This is a synchronous call which returns only after the full read job /// has ended (successfully or not). So it is wise not to read giant amounts /// of data in a single call. + /// /// @param d The drive from which to read + /// /// @param byte_address The start address of the read in byte (aligned to 2048) + /// /// @param data A memory buffer capable of taking data_size bytes + /// /// @param data_size The amount of data to be read. This does not have to /// be aligned to any block size. + /// /// @param data_count The amount of data actually read (interesting on error) /// The counted bytes are supposed to be valid. + /// /// @param flag Bitfield for control purposes: /// bit0= - reserved - /// bit1= do not submit error message if read error /// bit2= on error do not try to read a second time /// with single block steps. + /// /// @since 0.5.2 /// bit3= return -2 on permission denied error rather than /// issuing a warning message. + /// /// @since 1.0.6 /// bit4= return -3 on SCSI error /// 5 64 00 ILLEGAL MODE FOR THIS TRACK @@ -4690,12 +5453,16 @@ unsafe extern "C" { /// event message. Do not retry reading in this case. /// (Useful to try the last two blocks of a CD /// track which might be non-data because of TAO.) + /// /// @since 1.2.6 /// bit5= issue messages with severity DEBUG if they would /// be suppressed by bit1. + /// /// @since 1.4.0 + /// /// @return 1=successful , <=0 an error occurred /// with bit3: -2= permission denied error + /// /// @since 0.4.0 pub fn burn_read_data( d: *mut burn_drive, @@ -4719,16 +5486,22 @@ unsafe extern "C" { /// CD and individual drive. /// Expect leading and trailing zeros, as well as slight truncation. /// + /// /// @param d The drive from which to read. /// It must be a real MMC drive (i.e. not a stdio file) /// and it must have a CD loaded (i.e. not DVD or BD). + /// /// @param sector_no The sector number (Logical Block Address) /// It may be slightly below 0, depending on drive and /// medium. -150 is a lower limit. + /// /// @param data A memory buffer capable of taking data_size bytes + /// /// @param data_size The amount of data to be read. This must be aligned /// to full multiples of 2352. + /// /// @param data_count The amount of data actually read (interesting on error) + /// /// @param flag Bitfield for control purposes: /// bit0= - reserved - /// bit1= do not submit error message if read error @@ -4744,9 +5517,12 @@ unsafe extern "C" { /// track which might be non-audio because of TAO.) /// bit5= issue messages with severity DEBUG if they would /// be suppressed by bit1. + /// /// @since 1.4.0 + /// /// @return 1=successful , <=0 an error occurred /// with bit3: -2= permission denied error + /// /// @since 1.2.6 pub fn burn_read_audio( d: *mut burn_drive, @@ -4761,18 +5537,24 @@ unsafe extern "C" { /// Extract an interval of audio sectors from CD and store it as a WAVE /// audio file on hard disk. /// + /// /// @param drive The drive from which to read. + /// /// @param start_sector The logical block address of the first audio sector /// which shall be read. + /// /// @param sector_count The number of audio sectors to be read. /// Each sector consists of 2352 bytes. + /// /// @param target_path The address of the file where to store the extracted /// audio data. Will be opened O_WRONLY | O_CREAT. /// The file name should have suffix \".wav\". + /// /// @param flag Bitfield for control purposes: /// bit0= Report about progress by UPDATE messages /// bit3= Enable DAP : \"flaw obscuring mechanisms like /// audio data mute and interpolate\" + /// /// @since 1.3.2 pub fn burn_drive_extract_audio( drive: *mut burn_drive, @@ -4786,15 +5568,20 @@ unsafe extern "C" { /// Extract all audio sectors of a track from CD and store them as a WAVE /// audio file on hard disk. /// + /// /// @param drive The drive from which to read. + /// /// @param track The track which shall be extracted. + /// /// @param target_path The address of the file where to store the extracted /// audio data. Will be opened O_WRONLY | O_CREAT. /// The file name should have suffix \".wav\". + /// /// @param flag Bitfield for control purposes: /// bit0= Report about progress by UPDATE messages /// bit3= Enable DAP : \"flaw obscuring mechanisms like /// audio data mute and interpolate\" + /// /// @since 1.3.2 pub fn burn_drive_extract_audio_track( drive: *mut burn_drive, @@ -4806,7 +5593,9 @@ unsafe extern "C" { unsafe extern "C" { /// Inquire whether the drive object is a real MMC drive or a pseudo-drive /// created by a stdio: address. + /// /// @param d The drive to inquire + /// /// @return 0= null-drive /// 1= real MMC drive /// 2= stdio-drive, random access, read-write @@ -4815,6 +5604,7 @@ unsafe extern "C" { /// (only if enabled by burn_allow_drive_role_4()) /// 5= stdio-drive, random access, write-only /// (only if enabled by burn_allow_drive_role_4()) + /// /// @since 0.4.0 pub fn burn_drive_get_drive_role(d: *mut burn_drive) -> ::std::os::raw::c_int; } @@ -4832,6 +5622,7 @@ unsafe extern "C" { /// respectively. /// Other paths may get tested by an attempt to open them for read-write /// (role 2) or read-only (role 4) or write-only (role 5). See bit1. + /// /// @param allowed Bitfield for control purposes: /// bit0= Enable roles 4 and 5 for drives which get /// acquired after this call @@ -4848,6 +5639,7 @@ unsafe extern "C" { /// after the end of the file. It is nevertheless /// possible to change this address by call /// burn_write_opts_set_start_byte(). + /// /// @since 1.0.6 pub fn burn_allow_drive_role_4(allowed: ::std::os::raw::c_int); } @@ -4862,17 +5654,22 @@ unsafe extern "C" { /// if (burn_drive_equals_adr(d1, adr2, burn_drive_get_drive_role(d2))) /// ... Both drive objects point to the same storage facility ... /// + /// /// @param d1 Existing drive object + /// /// @param adr2 Address string to be tested. Prefix \"stdio:\" overrides /// parameter drive_role2 by either 0 or 2 as appropriate. /// The string must be shorter than BURN_DRIVE_ADR_LEN. + /// /// @param drive_role2 Role as burn_drive_get_drive_role() would attribute /// to adr2 if it was a drive. Use value 2 for checking track /// sources or pseudo-drive addresses without \"stdio:\". /// Use 1 for checking drive addresses including those with /// prefix \"stdio:\". + /// /// @return 1= adr2 leads to d1 , 0= adr2 seems not to lead to d1, /// -1 = adr2 is bad + /// /// @since 0.4.0 pub fn burn_drive_equals_adr( d1: *mut burn_drive, @@ -4891,14 +5688,19 @@ pub struct libdax_audioxtr { } unsafe extern "C" { /// Open an audio file, check whether suitable, create extractor object. + /// /// @param xtr Opaque handle to extractor. Gets attached extractor object. + /// /// @param path Address of the audio file to extract. \"-\" is stdin (but might /// be not suitable for all futurely supported formats). + /// /// @param flag Bitfield for control purposes (unused yet, submit 0) + /// /// @return >0 success /// 0 unsuitable format /// -1 severe error /// -2 path not found + /// /// @since 0.2.4 pub fn libdax_audioxtr_new( xtr: *mut *mut libdax_audioxtr, @@ -4908,16 +5710,26 @@ unsafe extern "C" { } unsafe extern "C" { /// Obtain identification parameters of opened audio source. + /// /// @param xtr Opaque handle to extractor + /// /// @param fmt Gets pointed to the audio file format id text: \".wav\" , \".au\" + /// /// @param fmt_info Gets pointed to a format info text telling parameters + /// /// @param num_channels e.g. 1=mono, 2=stereo, etc + /// /// @param sample_rate e.g. 11025, 44100 + /// /// @param bits_per_sample e.g. 8= 8 bits per sample, 16= 16 bits ... + /// /// @param msb_first Byte order of samples: 0= Intel = Little Endian /// 1= Motorola = Big Endian + /// /// @param flag Bitfield for control purposes (unused yet, submit 0) + /// /// @return >0 success, <=0 failure + /// /// @since 0.2.4 pub fn libdax_audioxtr_get_id( xtr: *mut libdax_audioxtr, @@ -4933,10 +5745,15 @@ unsafe extern "C" { unsafe extern "C" { /// Obtain a prediction about the extracted size based on internal information /// of the formatted file. + /// /// @param o Opaque handle to extractor + /// /// @param size Gets filled with the predicted size + /// /// @param flag Bitfield for control purposes (unused yet, submit 0) + /// /// @return 1 prediction was possible , 0 no prediction could be made + /// /// @since 0.2.4 pub fn libdax_audioxtr_get_size( o: *mut libdax_audioxtr, @@ -4947,15 +5764,21 @@ unsafe extern "C" { unsafe extern "C" { /// Obtain next buffer full of extracted data in desired format (only raw audio /// for now). + /// /// @param xtr Opaque handle to extractor + /// /// @param buffer Gets filled with extracted data + /// /// @param buffer_size Maximum number of bytes to be filled into buffer + /// /// @param flag Bitfield for control purposes /// bit0= do not stop at predicted end of data + /// /// @return >0 number of valid buffer bytes, /// 0 End of file /// -1 operating system reports error /// -2 usage error by application + /// /// @since 0.2.4 pub fn libdax_audioxtr_read( xtr: *mut libdax_audioxtr, @@ -4971,11 +5794,16 @@ unsafe extern "C" { /// object will have forgotten its file descriptor and libdax_audioxtr_read() /// will return a usage error. One may use *fd after libdax_audioxtr_destroy() /// and will have to close it via close(2) when done with it. + /// /// @param o Opaque handle to extractor + /// /// @param fd Returns the file descriptor number + /// /// @param flag Bitfield for control purposes /// bit0= do not dup(2) and close(2) but hand out original fd + /// /// @return 1 success, 0 cannot hand out fd , -1 severe error + /// /// @since 0.2.4 pub fn libdax_audioxtr_detach_fd( o: *mut libdax_audioxtr, @@ -4985,10 +5813,14 @@ unsafe extern "C" { } unsafe extern "C" { /// Clean up after extraction and destroy extractor object. + /// /// @param xtr Opaque handle to extractor, *xtr is allowed to be NULL, /// xtr is set to NULL by this function + /// /// @param flag Bitfield for control purposes (unused yet, submit 0) + /// /// @return 1 = destroyed object, 0 = was already destroyed + /// /// @since 0.2.4 pub fn libdax_audioxtr_destroy( xtr: *mut *mut libdax_audioxtr,