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