Commit 01-ov_read_filter patch from #381; closes feature request #1352. Also updates...
[platform/upstream/libvorbis.git] / doc / vorbis-errors.txt
1 Error return codes possible from libvorbis and libvorbisfile:
2
3 All 'failure' style returns are <0; this either indicates a generic
4 'false' value (eg, ready?  T or F) or an error condition.  Code can
5 safely just test for < 0, or look at the specific return code for more
6 detail.
7
8 *** Return codes:
9
10 OV_FALSE        The call returned a 'false' status (eg, ov_bitrate_instant 
11                 can return OV_FALSE if playback is not in progress, and thus 
12                 there is no instantaneous bitrate information to report.
13
14 OV_HOLE         libvorbis/libvorbisfile is alerting the application that 
15                 there was an interruption in the data (one of: garbage 
16                 between pages, loss of sync followed by recapture, or a 
17                 corrupt page)
18
19 OV_EREAD        A read from media returned an error.
20
21 OV_EFAULT       Internal logic fault; indicates a bug or heap/stack 
22                 corruption.
23
24 OV_EIMPL        The bitstream makes use of a feature not implemented in this 
25                 library version.
26
27 OV_EINVAL       Invalid argument value.
28
29 OV_ENOTVORBIS   Bitstream/page/packet is not Vorbis data.
30
31 OV_EBADHEADER   Invalid Vorbis bitstream header.
32
33 OV_EVERSION     Vorbis version mismatch.
34
35 OV_ENOTAUDIO    Packet data submitted to vorbis_synthesis is not audio data.
36
37 OV_EBADPACKET   Invalid packet submitted to vorbis_synthesis.
38
39 OV_EBADLINK     Invalid stream section supplied to libvorbis/libvorbisfile, 
40                 or the requested link is corrupt. 
41
42 OV_ENOSEEK      Bitstream is not seekable.
43
44
45 ****************************************************************
46 *** Libvorbis functions that can return failure/error codes:
47
48 int vorbis_analysis_headerout()
49     OV_EIMPL
50
51 int vorbis_analysis_wrote()
52     OV_EINVAL
53
54 int vorbis_synthesis_headerin()
55     OV_ENOTVORBIS, OV_EVERSION, OV_EBADHEADER
56
57 int vorbis_synthesis()
58     OV_ENOTAUDIO, OV_EBADPACKET
59
60 int vorbis_synthesis_read()
61     OV_EINVAL
62
63 ****************************************************************
64 *** Libvorbisfile functions that can return failure/error codes:
65
66 int ov_open_callbacks()   
67     OV_EREAD, OV_ENOTVORBIS, OV_EVERSION, OV_EBADHEADER, OV_FAULT
68
69 int ov_open()
70     OV_EREAD, OV_ENOTVORBIS, OV_EVERSION, OV_EBADHEADER, OV_FAULT
71
72 long ov_bitrate()
73     OV_EINVAL, OV_FALSE
74
75 long ov_bitrate_instant()
76     OV_FALSE
77
78 ogg_int64_t ov_raw_total()
79     OV_EINVAL
80
81 ogg_int64_t ov_pcm_total()
82     OV_EINVAL
83
84 double ov_time_total()
85     OV_EINVAL
86
87 int ov_raw_seek()
88     OV_ENOSEEK, OV_EINVAL, OV_BADLINK
89
90 int ov_pcm_seek_page()
91     OV_ENOSEEK, OV_EINVAL, OV_EREAD, OV_BADLINK, OV_FAULT
92
93 int ov_pcm_seek()
94     OV_ENOSEEK, OV_EINVAL, OV_EREAD, OV_BADLINK, OV_FAULT
95
96 int ov_time_seek()
97     OV_ENOSEEK, OV_EINVAL, OV_EREAD, OV_BADLINK, OV_FAULT
98
99 int ov_time_seek_page()
100     OV_ENOSEEK, OV_EINVAL, OV_EREAD, OV_BADLINK, OV_FAULT
101
102 long ov_read()
103     OV_HOLE, OV_EBADLINK