libmpdvdkit2/dvd_reader.h

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