libdvdread/dvd_reader.h

   1 /* -*- c-basic-offset: 2; indent-tabs-mode: nil -*- */
   2 #ifndef DVD_READER_H_INCLUDED
   3 #define DVD_READER_H_INCLUDED
   4
   5 /*
   6  * Copyright (C) 2001, 2002 Billy Biggs <vektor@dumbterm.net>,
   7  *                          Håkan Hjort <d95hjort@dtek.chalmers.se>,
   8  *                          Björn Englund <d4bjorn@dtek.chalmers.se>
   9  *
  10  * This program is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License as published by
  12  * the Free Software Foundation; either version 2 of the License, or (at
  13  * your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful, but
  16  * WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program; if not, write to the Free Software
  22  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  23  */
  24
  25 #include <sys/types.h>
  26
  27 /**
  28  * The DVD access interface.
  29  *
  30  * This file contains the functions that form the interface to to
  31  * reading files located on a DVD.
  32  */
  33
  34 /**
  35  * The current version. (0.9.4 => 904, 1.2.3 => 10203)
  36  */
  37 #define DVDREAD_VERSION 907
  38
  39
  40 /**
  41  * The length of one Logical Block of a DVD.
  42  */
  43 #define DVD_VIDEO_LB_LEN 2048
  44
  45 /**
  46  * Maximum length of filenames allowed in UDF.
  47  */
  48 #define MAX_UDF_FILE_NAME_LEN 2048
  49
  50 #ifdef __cplusplus
  51 extern "C" {
  52 #endif
  53
  54 /**
  55  * Opaque type that is used as a handle for one instance of an opened DVD.
  56  */
  57 typedef struct dvd_reader_s dvd_reader_t;
  58
  59 /**
  60  * Opaque type for a file read handle, much like a normal fd or FILE *.
  61  */
  62 typedef struct dvd_file_s dvd_file_t;
  63
  64 /**
  65  * Returns the compiled version. (DVDREAD_VERSION as an int)
  66  */
  67 int DVDVersion(void);
  68
  69
  70 /**
  71  * Opens a block device of a DVD-ROM file, or an image file, or a directory
  72  * name for a mounted DVD or HD copy of a DVD.
  73  *
  74  * If the given file is a block device, or is the mountpoint for a block
  75  * device, then that device is used for CSS authentication using libdvdcss.
  76  * If no device is available, then no CSS authentication is performed,
  77  * and we hope that the image is decrypted.
  78  *
  79  * If the path given is a directory, then the files in that directory may be
  80  * in any one of these formats:
  81  *
  82  *   path/VIDEO_TS/VTS_01_1.VOB
  83  *   path/video_ts/vts_01_1.vob
  84  *   path/VTS_01_1.VOB
  85  *   path/vts_01_1.vob
  86  *
  87  * @param path Specifies the the device, file or directory to be used.
  88  * @return If successful a a read handle is returned. Otherwise 0 is returned.
  89  *
  90  * dvd = DVDOpen(path);
  91  *
  92  * Threads: this function uses chdir() and getcwd().
  93  * The current working directory is global to all threads,
  94  * so using chdir/getcwd in another thread could give unexpected results.
  95  */
  96 dvd_reader_t *DVDOpen( const char * );
  97
  98 /**
  99  * Closes and cleans up the DVD reader object.
 100  *
 101  * You must close all open files before calling this function.
 102  *
 103  * @param dvd A read handle that should be closed.
 104  *
 105  * DVDClose(dvd);
 106  */
 107 void DVDClose( dvd_reader_t * );
 108
 109 /**
 110  * Initializes libdvdread to be used with multithreading apps.
 111  *
 112  * You must call this function before using any other functions of libdvdread
 113  * if you are going to use libdvdread in multiple threads in your program.
 114  * If you are not using threads, or using libdvdread from just one thread,
 115  * you do not need to call this, but you are allowed to do so anyway.
 116  *
 117  * There are several restrictions on how you can use libdvdread in
 118  * multithreading apps, see further documentation.
 119  *
 120  * If you have called DVDFinish() you need to call DVDInit again to use
 121  * libdvdread in multiple threads.
 122  *
 123  * DVDInit(void);
 124  */
 125 void DVDInit(void);
 126
 127 /**
 128  * frees any dlopened objects.
 129  *
 130  * You must DVDClose all handles opened with DVDOpen before calling this.
 131  * Use this function if you need to close the dlopened libs and any other
 132  * objects that have been dynamically allocated by libdvdread.
 133  *
 134  * DVDFinish(void);
 135  */
 136 void DVDFinish(void);
 137
 138 /**
 139  *
 140  */
 141 typedef enum {
 142   DVD_READ_INFO_FILE,        /**< VIDEO_TS.IFO  or VTS_XX_0.IFO (title) */
 143   DVD_READ_INFO_BACKUP_FILE, /**< VIDEO_TS.BUP  or VTS_XX_0.BUP (title) */
 144   DVD_READ_MENU_VOBS,        /**< VIDEO_TS.VOB  or VTS_XX_0.VOB (title) */
 145   DVD_READ_TITLE_VOBS        /**< VTS_XX_[1-9].VOB (title).  All files in
 146                                 the title set are opened and read as a
 147                                 single file. */
 148 } dvd_read_domain_t;
 149
 150 /**
 151  *
 152  */
 153 typedef struct {
 154   off_t size;          /**< Total size of file in bytes */
 155   int nr_parts;           /**< Number of file parts */
 156   off_t parts_size[9]; /**< Size of each part in bytes */
 157 } dvd_stat_t;
 158
 159 /**
 160  * Stats a file on the DVD given the title number and domain.
 161  * The information about the file is stored in a dvd_stat_t
 162  * which contains information about the size of the file and
 163  * the number of parts in case of a multipart file and the respective
 164  * sizes of the parts.
 165  * A multipart file is for instance VTS_02_1.VOB, VTS_02_2.VOB, VTS_02_3.VOB
 166  * The size of VTS_02_1.VOB will be stored in stat->parts_size[0],
 167  * VTS_02_2.VOB in stat->parts_size[1], ...
 168  * The total size (sum of all parts) is stored in stat->size and
 169  * stat->nr_parts will hold the number of parts.
 170  * Only DVD_READ_TITLE_VOBS (VTS_??_[1-9].VOB) can be multipart files.
 171  *
 172  * This function is only of use if you want to get the size of each file
 173  * in the filesystem. These sizes are not needed to use any other
 174  * functions in libdvdread.
 175  *
 176  * @param dvd  A dvd read handle.
 177  * @param titlenum Which Video Title Set should be used, VIDEO_TS is 0.
 178  * @param domain Which domain.
 179  * @param stat Pointer to where the result is stored.
 180  * @return If successful 0, otherwise -1.
 181  *
 182  * int DVDFileStat(dvd, titlenum, domain, stat);
 183  */
 184 int DVDFileStat(dvd_reader_t *, int, dvd_read_domain_t, dvd_stat_t *);
 185
 186 /**
 187  * Opens a file on the DVD given the title number and domain.
 188  *
 189  * If the title number is 0, the video manager information is opened
 190  * (VIDEO_TS.[IFO,BUP,VOB]).  Returns a file structure which may be
 191  * used for reads, or 0 if the file was not found.
 192  *
 193  * @param dvd  A dvd read handle.
 194  * @param titlenum Which Video Title Set should be used, VIDEO_TS is 0.
 195  * @param domain Which domain.
 196  * @return If successful a a file read handle is returned, otherwise 0.
 197  *
 198  * dvd_file = DVDOpenFile(dvd, titlenum, domain); */
 199 dvd_file_t *DVDOpenFile( dvd_reader_t *, int, dvd_read_domain_t );
 200
 201 /**
 202  * Closes a file and frees the associated structure.
 203  *
 204  * @param dvd_file  The file read handle to be closed.
 205  *
 206  * DVDCloseFile(dvd_file);
 207  */
 208 void DVDCloseFile( dvd_file_t * );
 209
 210 /**
 211  * Reads block_count number of blocks from the file at the given block offset.
 212  * Returns number of blocks read on success, -1 on error.  This call is only
 213  * for reading VOB data, and should not be used when reading the IFO files.
 214  * When reading from an encrypted drive, blocks are decrypted using libdvdcss
 215  * where required.
 216  *
 217  * @param dvd_file  A file read handle.
 218  * @param offset Block offset from the start of the file to start reading at.
 219  * @param block_count Number of block to read.
 220  * @param data Pointer to a buffer to write the data into.
 221  *             It must be aligned to the logical block size of the device when
 222  *             reading from a raw/O_DIRECT device (2048 bytes for DVD)
 223  * @return Returns number of blocks read on success, -1 on error.
 224  *
 225  * blocks_read = DVDReadBlocks(dvd_file, offset, block_count, data);
 226  */
 227 ssize_t DVDReadBlocks( dvd_file_t *, int, size_t, unsigned char * );
 228
 229 /**
 230  * Seek to the given position in the file.  Returns the resulting position in
 231  * bytes from the beginning of the file.  The seek position is only used for
 232  * byte reads from the file, the block read call always reads from the given
 233  * offset.
 234  *
 235  * @param dvd_file  A file read handle.
 236  * @param seek_offset Byte offset from the start of the file to seek to.
 237  * @return The resulting position in bytes from the beginning of the file.
 238  *
 239  * offset_set = DVDFileSeek(dvd_file, seek_offset);
 240  */
 241 int DVDFileSeek( dvd_file_t *, int );
 242
 243 /**
 244  * Reads the given number of bytes from the file.  This call can only be used
 245  * on the information files, and may not be used for reading from a VOB.  This
 246  * reads from and increments the currrent seek position for the file.
 247  *
 248  * @param dvd_file  A file read handle.
 249  * @param data Pointer to a buffer to write the data into.
 250  * @param bytes Number of bytes to read.
 251  * @return Returns number of bytes read on success, -1 on error.
 252  *
 253  * bytes_read = DVDReadBytes(dvd_file, data, bytes);
 254  */
 255 ssize_t DVDReadBytes( dvd_file_t *, void *, size_t );
 256
 257 /**
 258  * Returns the file size in blocks.
 259  *
 260  * @param dvd_file  A file read handle.
 261  * @return The size of the file in blocks, -1 on error.
 262  *
 263  * blocks = DVDFileSize(dvd_file);
 264  */
 265 ssize_t DVDFileSize( dvd_file_t * );
 266
 267 /**
 268  * Get a unique 128 bit disc ID.
 269  * This is the MD5 sum of VIDEO_TS.IFO and the VTS_0?_0.IFO files
 270  * in title order (those that exist).
 271  * If you need a 'text' representation of the id, print it as a
 272  * hexadecimal number, using lowercase letters, discid[0] first.
 273  * I.e. the same format as the command-line 'md5sum' program uses.
 274  *
 275  * @param dvd A read handle to get the disc ID from
 276  * @param discid The buffer to put the disc ID into. The buffer must
 277  *               have room for 128 bits (16 chars).
 278  * @return 0 on success, -1 on error.
 279  */
 280 int DVDDiscID( dvd_reader_t *, unsigned char * );
 281
 282 /**
 283  * Get the UDF VolumeIdentifier and VolumeSetIdentifier
 284  * from the PrimaryVolumeDescriptor.
 285  *
 286  * @param dvd A read handle to get the disc ID from
 287  * @param volid The buffer to put the VolumeIdentifier into.
 288  *              The VolumeIdentifier is latin-1 encoded (8bit unicode)
 289  *              null terminated and max 32 bytes (including '\0')
 290  * @param volid_size No more than volid_size bytes will be copied to volid.
 291  *                   If the VolumeIdentifier is truncated because of this
 292  *                   it will still be null terminated.
 293  * @param volsetid The buffer to put the VolumeSetIdentifier into.
 294  *                 The VolumeIdentifier is 128 bytes as
 295  *                 stored in the UDF PrimaryVolumeDescriptor.
 296  *                 Note that this is not a null terminated string.
 297  * @param volsetid_size At most volsetid_size bytes will be copied to volsetid.
 298  * @return 0 on success, -1 on error.
 299  */
 300 int DVDUDFVolumeInfo( dvd_reader_t *, char *, unsigned int,
 301                       unsigned char *, unsigned int );
 302
 303 /**
 304  * Get the ISO9660 VolumeIdentifier and VolumeSetIdentifier
 305  *
 306  * * Only use this function as fallback if DVDUDFVolumeInfo returns 0   *
 307  * * this will happen on a disc mastered only with a iso9660 filesystem *
 308  * * All video DVD discs have UDF filesystem                            *
 309  *
 310  * @param dvd A read handle to get the disc ID from
 311  * @param volid The buffer to put the VolumeIdentifier into.
 312  *              The VolumeIdentifier is coded with '0-9','A-Z','_'
 313  *              null terminated and max 33 bytes (including '\0')
 314  * @param volid_size No more than volid_size bytes will be copied to volid.
 315  *                   If the VolumeIdentifier is truncated because of this
 316  *                   it will still be null terminated.
 317  * @param volsetid The buffer to put the VolumeSetIdentifier into.
 318  *                 The VolumeIdentifier is 128 bytes as
 319  *                 stored in the ISO9660 PrimaryVolumeDescriptor.
 320  *                 Note that this is not a null terminated string.
 321  * @param volsetid_size At most volsetid_size bytes will be copied to volsetid.
 322  * @return 0 on success, -1 on error.
 323  */
 324 int DVDISOVolumeInfo( dvd_reader_t *, char *, unsigned int,
 325                       unsigned char *, unsigned int );
 326
 327 /**
 328  * Sets the level of caching that is done when reading from a device
 329  *
 330  * @param dvd A read handle to get the disc ID from
 331  * @param level The level of caching wanted.
 332  *             -1 - returns the current setting.
 333  *              0 - UDF Cache turned off.
 334  *              1 - (default level) Pointers to IFO files and some data from
 335  *                  PrimaryVolumeDescriptor are cached.
 336  *
 337  * @return The level of caching.
 338  */
 339 int DVDUDFCacheLevel( dvd_reader_t *, int );
 340
 341 #ifdef __cplusplus
 342 };
 343 #endif
 344 #endif /* DVD_READER_H_INCLUDED */