1 /* 2 * PortBurn 3 * 4 * Dominic Mazzoni, Leland Lucius 5 * License: LGPL 6 * 7 * A library for cross-platform audio CD burning 8 * 9 * All functions return 0 on success and nonzero when there's an error, 10 * unless otherwise specified. The error codes will come from the enum 11 * below. When one of the CD burning or filesystem errors was returned, 12 * you might be able to call PortBurn_LastError to get operating-system 13 * specific information about what went wrong. If PortBurn_LastError 14 * returns no error, no additional information was available. 15 */ 16 17 #ifndef __PORTBURN__ 18 #define __PORTBURN__ 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 typedef enum { 25 pbOptTest, 26 pbOptVerify, 27 pbOptUnderrun, 28 pbOptEject, 29 pbOptGapless, 30 pbOptSpeed 31 } PortBurn_Options; 32 33 typedef enum { 34 pbTestOff = 0, 35 pbTestOn = 1, 36 pbTestDefault = pbTestOff 37 } PortBurn_Test; 38 39 typedef enum { 40 pbVerifyOff = 0, 41 pbVerifyOn = 1, 42 pbVerifyDefault = pbVerifyOff 43 } PortBurn_Verify; 44 45 typedef enum { 46 pbUnderrunOff = 0, 47 pbUnderrunOn = 1, 48 pbUnderrunDefault = pbUnderrunOff 49 } PortBurn_Underrun; 50 51 typedef enum { 52 pbEjectOff = 0, 53 pbEjectOn = 1, 54 pbEjectDefault = pbEjectOff 55 } PortBurn_Eject; 56 57 typedef enum { 58 pbGaplessOff = 0, 59 pbGapelessOn = 1, 60 pbGaplessDefault = pbGaplessOff 61 } PortBurn_Gap; 62 63 typedef enum { 64 pbSpeedDefault = -1, 65 pbSpeedMax = -1 66 } PortBurn_Speed; 67 68 #define pbMediaNotWritable 0x00 69 #define pbMediaNone 0xff 70 71 #define pbMediaAppendable 0x01 72 #define pbMediaBlank 0x02 73 #define pbMediaErasable 0x04 74 #define pbMediaOverwritable 0x08 75 76 typedef enum { 77 pbEraseQuick, 78 pbEraseFull 79 } PortBurn_EraseTypes; 80 81 typedef enum { 82 pbSuccess = 0, 83 84 /* CD burning errors */ 85 pbErrCannotEject = -1, 86 pbErrCannotAccessDevice = -2, 87 pbErrNoMediaInDrive = -3, 88 pbErrMediaIsNotWritable = -4, 89 pbErrMediaIsNotBlank = -5, 90 pbErrCannotReserveDevice = -6, 91 pbErrCannotPrepareToBurn = -7, 92 pbErrCannotStartBurning = -8, 93 pbErrCannotGetBurnStatus = -9, 94 pbErrBurnFailed = -10, 95 pbErrCannotCloseDevice = -11, 96 97 /* Erase errors */ 98 pbErrCannotPrepareToErase = -201, 99 pbErrCannotStartErasing = -202, 100 pbErrCannotGetEraseStatus = -203, 101 pbErrEraseFailed = -204, 102 103 /* Filesystem errors */ 104 pbErrCannotCreateStagingDirectory = -401, 105 pbErrCannotCreateStagingFile = -402, 106 pbErrCannotWriteToStagingFile = -403, 107 pbErrCannotStageTrack = -404, 108 pbErrCannotAccessStagedFile = -405, 109 pbErrCannotUseStagedFileForBurning = -406, 110 111 /* API errors: if these happen, you are not using PortBurn correctly */ 112 pbErrNoHandle = -501, 113 pbErrMustCallGetNumDevices = -502, 114 pbErrDeviceNotOpen = -503, 115 pbErrAlreadyStagingOrBurning = -504, 116 pbErrMustCallStartStaging = -505, 117 pbErrMustCallStartTrack = -506, 118 pbErrNotCurrentlyBurning = -507, 119 pbErrNotCurrentlyErasing = -508, 120 pbErrInvalidOption = -509, 121 pbErrInvalidOptValue = -510, 122 pbErrDeviceAlreadyOpen = -511, 123 pbErrInvalidDeviceIndex = -512 124 125 } PortBurn_Result; 126 127 /* Returns a handle if burning capability is available on this system, 128 and NULL otherwise */ 129 void *PortBurn_Open(); 130 131 /* Cleanup */ 132 void PortBurn_Close(void *handle); 133 134 /* Return a human-readable error string for the last operating system 135 specific error (NOT human readable strings for the PortBurn error 136 codes). Caller should dispose of the returned string using free(). */ 137 char *PortBurn_LastError(void *handle); 138 139 /* Get the number of devices capable of burning audio CDs. 140 If the result is N, then calls to GetDeviceName and OpenDevice 141 are guaranteed to be valid for indices from 0 up to N-1, until 142 the next time you call GetNumDevices. At that point, the list of 143 devices will be rescanned, and may be different. */ 144 int PortBurn_GetNumDevices(void *handle); 145 146 /* Get the name of the device with a given index. Only valid 147 after a call to GetNumDevices. */ 148 char *PortBurn_GetDeviceName(void *handle, int index); 149 150 /* Open a particular device by index number. You can open a device 151 even before you're sure if you're going to go through with the 152 burn, for example to make Eject available. */ 153 int PortBurn_OpenDevice(void *handle, int index); 154 155 /* Close a device */ 156 int PortBurn_CloseDevice(void *handle); 157 158 /* Eject the media in the currently opened device */ 159 int PortBurn_EjectDevice(void *handle); 160 161 /* Erase the media in the currently opened device */ 162 int PortBurn_StartErasing(void *handle, int type); 163 164 /* During erase, returns the fraction complete in the given 165 float pointer, from 0.0 to 1.0. If this function returns 166 nonzero, the disc burning has failed and should be aborted. 167 If *out_fraction_complete is equal to 1.0, the burning is done; 168 you can call PortBurn_CloseDevice. 169 */ 170 int PortBurn_GetEraseStatus(void *handle, float *out_fraction_complete); 171 172 /* This indicates you're ready to start staging audio data for the 173 currently opened device. At this point you are committing to 174 exclusive access to the CD burner, and this is the function that 175 will fail if another program is using the device, or if there is 176 no writable CD media in the device at this point. 177 You should pass in the path to a temporary directory that has at 178 least 700 MB of free space, to stage the audio, although note that 179 not all implementations will make use of this directory. */ 180 int PortBurn_StartStaging(void *handle, const char *tmpdir); 181 182 /* Start a new audio track. Pass the name of the track */ 183 int PortBurn_StartTrack(void *handle, const char *name); 184 185 /* Add one frame of audio to the current track. The buffer must be exactly 186 1176 elements long, containing interleaved left and right audio samples. 187 The values should be signed 16-bit numbers in the native endianness of 188 this computer. */ 189 int PortBurn_AddFrame(void *handle, short *buffer); 190 191 /* Finish the current audio track. */ 192 int PortBurn_EndTrack(void *handle); 193 194 /* Begin burning the disc. */ 195 int PortBurn_StartBurning(void *handle); 196 197 /* Cancel if burning was in progress. It might take a while for 198 this to take effect; wait until GetStatus says 1.0 to close 199 the device. */ 200 int PortBurn_CancelBurning(void *handle); 201 202 /* During burning, returns the fraction complete in the given 203 float pointer, from 0.0 to 1.0. If this function returns 204 nonzero, the disc burning has failed and should be aborted. 205 If *out_fraction_complete is equal to 1.0, the burning is done; 206 you can call PortBurn_CloseDevice. 207 */ 208 int PortBurn_GetStatus(void *handle, float *out_fraction_complete); 209 210 /* Retrieve the current value of the specified option. */ 211 int PortBurn_GetOption(void *handle, int option, int *value); 212 213 /* Changes the value of the specifed option. */ 214 int PortBurn_SetOption(void *handle, int option, int value); 215 216 /* */ 217 int PortBurn_GetSupportedSpeeds(void *handle, int *cnt, int *option[]); 218 219 /* */ 220 int PortBurn_GetMediaState(void *handle, int *state); 221 222 #ifdef __cplusplus 223 } 224 #endif 225 226 #endif /* __PORTBURN__ */ 227