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
59extern "C" {
60#endif
61
62/**
63 * Opaque type that is used as a handle for one instance of an opened DVD.
64 */
65typedef 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 */
70typedef struct dvd_file_s dvd_file_t;
71
72/**
73 * Public type that is used to provide statistics on a handle.
74 */
75typedef 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 */
103dvd_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 */
114void DVDClose( dvd_reader_t * );
115
116/**
117 *
118 */
119typedef 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 */
153int 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); */
168dvd_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 */
177void 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 */
194ssize_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 */
208int32_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 */
222ssize_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 */
232ssize_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 */
247int 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 */
267int DVDUDFVolumeInfo( dvd_reader_t *, char *, unsigned int,
268 unsigned char *, unsigned int );
269
270int 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 */
293int 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 */
308int DVDUDFCacheLevel( dvd_reader_t *, int );
309
310#ifdef __cplusplus
311};
312#endif
313#endif /* LIBDVDREAD_DVD_READER_H */
314