media/liboggz/include/oggz/oggz_read.h

   1 /*
   2    Copyright (C) 2003 Commonwealth Scientific and Industrial Research
   3    Organisation (CSIRO) Australia
   4
   5    Redistribution and use in source and binary forms, with or without
   6    modification, are permitted provided that the following conditions
   7    are met:
   8
   9    - Redistributions of source code must retain the above copyright
  10    notice, this list of conditions and the following disclaimer.
  11
  12    - Redistributions in binary form must reproduce the above copyright
  13    notice, this list of conditions and the following disclaimer in the
  14    documentation and/or other materials provided with the distribution.
  15
  16    - Neither the name of CSIRO Australia nor the names of its
  17    contributors may be used to endorse or promote products derived from
  18    this software without specific prior written permission.
  19
  20    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  23    PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE ORGANISATION OR
  24    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  25    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  26    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  27    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  28    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  29    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  30    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31 */
  32
  33 #ifndef __OGGZ_READ_H__
  34 #define __OGGZ_READ_H__
  35
  36 /** \file
  37  * Interfaces for reading Ogg files and streams
  38  */
  39
  40 /** \defgroup read_api Oggz Read API
  41  *
  42  * Oggz parses Ogg bitstreams, forming ogg_packet structures, and calling
  43  * your OggzReadPacket callback(s).
  44  *
  45  * You provide Ogg data to Oggz with oggz_read() or oggz_read_input(), and
  46  * independently process it in OggzReadPacket callbacks.
  47  * It is possible to set a different callback per \a serialno (ie. for each
  48  * logical bitstream in the Ogg bitstream - see the \ref basics section for
  49  * more detail).
  50  *
  51  * When using an OGGZ* opened with the OGGZ_AUTO flag set, Oggz will
  52  * internally calculate the granulepos for each packet, even though these
  53  * are not all recorded in the file: only the last packet ending on a page
  54  * will have its granulepos recorded in the page header.
  55  * Within a OggzReadPacket callback, calling oggz_tell_granulepos() will
  56  * retrieve the calculated granulepos.
  57  *
  58  * See \ref seek_api for information on seeking on interleaved Ogg data,
  59  * and for working with calculated granulepos values.
  60  *
  61  * \{
  62  */
  63
  64 /**
  65  * This is the signature of a callback which you must provide for Oggz
  66  * to call whenever it finds a new packet in the Ogg stream associated
  67  * with \a oggz.
  68  *
  69  * \param oggz The OGGZ handle
  70  * \param op The full ogg_packet (see <ogg/ogg.h>)
  71  * \param serialno Identify the logical bistream in \a oggz that contains
  72  *                 \a op
  73  * \param user_data A generic pointer you have provided earlier
  74  * \returns 0 to continue, non-zero to instruct Oggz to stop.
  75  *
  76  * \note It is possible to provide different callbacks per logical
  77  * bitstream -- see oggz_set_read_callback() for more information.
  78  */
  79 typedef int (*OggzReadPacket) (OGGZ * oggz, ogg_packet * op, long serialno,
  80                                void * user_data);
  81
  82 /**
  83  * Set a callback for Oggz to call when a new Ogg packet is found in the
  84  * stream.
  85  *
  86  * \param oggz An OGGZ handle previously opened for reading
  87  * \param serialno Identify the logical bitstream in \a oggz to attach
  88  * this callback to, or -1 to attach this callback to all unattached
  89  * logical bitstreams in \a oggz.
  90  * \param read_packet Your callback function
  91  * \param user_data Arbitrary data you wish to pass to your callback
  92  * \retval 0 Success
  93  * \retval OGGZ_ERR_BAD_SERIALNO \a serialno does not identify an existing
  94  * logical bitstream in \a oggz.
  95  * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
  96  * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
  97  *
  98  * \note Values of \a serialno other than -1 allows you to specify different
  99  * callback functions for each logical bitstream.
 100  *
 101  * \note It is safe to call this callback from within an OggzReadPacket
 102  * function, in order to specify that subsequent packets should be handled
 103  * by a different OggzReadPacket function.
 104  */
 105 int oggz_set_read_callback (OGGZ * oggz, long serialno,
 106                             OggzReadPacket read_packet, void * user_data);
 107
 108 /**
 109  * This is the signature of a callback which you must provide for Oggz
 110  * to call whenever it finds a new page in the Ogg stream associated
 111  * with \a oggz.
 112  *
 113  * \param oggz The OGGZ handle
 114  * \param op The full ogg_page (see <ogg/ogg.h>)
 115  * \param user_data A generic pointer you have provided earlier
 116  * \returns 0 to continue, non-zero to instruct Oggz to stop.
 117  */
 118 typedef int (*OggzReadPage) (OGGZ * oggz, const ogg_page * og,
 119                              long serialno, void * user_data);
 120
 121 /**
 122  * Set a callback for Oggz to call when a new Ogg page is found in the
 123  * stream.
 124  *
 125  * \param oggz An OGGZ handle previously opened for reading
 126  * \param serialno Identify the logical bitstream in \a oggz to attach
 127  * this callback to, or -1 to attach this callback to all unattached
 128  * logical bitstreams in \a oggz.
 129  * \param read_page Your OggzReadPage callback function
 130  * \param user_data Arbitrary data you wish to pass to your callback
 131  * \retval 0 Success
 132  * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
 133  * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
 134  *
 135  * \note Values of \a serialno other than -1 allows you to specify different
 136  * callback functions for each logical bitstream.
 137  *
 138  * \note It is safe to call this callback from within an OggzReadPage
 139  * function, in order to specify that subsequent pages should be handled
 140  * by a different OggzReadPage function.
 141  */
 142 int oggz_set_read_page (OGGZ * oggz, long serialno,
 143                         OggzReadPage read_page, void * user_data);
 144
 145
 146 /**
 147  * Read n bytes into \a oggz, calling any read callbacks on the fly.
 148  * \param oggz An OGGZ handle previously opened for reading
 149  * \param n A count of bytes to ingest
 150  * \retval ">  0" The number of bytes successfully ingested.
 151  * \retval 0 End of file
 152  * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
 153  * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
 154  * \retval OGGZ_ERR_SYSTEM System error; check errno for details
 155  * \retval OGGZ_ERR_STOP_OK Reading was stopped by a user callback
 156  * returning OGGZ_STOP_OK
 157  * \retval OGGZ_ERR_STOP_ERR Reading was stopped by a user callback
 158  * returning OGGZ_STOP_ERR
 159  */
 160 long oggz_read (OGGZ * oggz, long n);
 161
 162 /**
 163  * Input data into \a oggz.
 164  * \param oggz An OGGZ handle previously opened for reading
 165  * \param buf A memory buffer
 166  * \param n A count of bytes to input
 167  * \retval ">  0" The number of bytes successfully ingested.
 168  * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
 169  * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
 170  * \retval OGGZ_ERR_STOP_OK Reading was stopped by a user callback
 171  * returning OGGZ_STOP_OK
 172  * \retval OGGZ_ERR_STOP_ERR Reading was stopped by a user callback
 173  * returning OGGZ_STOP_ERR
 174  */
 175 long oggz_read_input (OGGZ * oggz, unsigned char * buf, long n);
 176
 177 /** \}
 178  */
 179
 180 /**
 181  * Erase any input buffered in Oggz. This discards any input read from the
 182  * underlying IO system but not yet delivered as ogg_packets.
 183  *
 184  * \param oggz An OGGZ handle
 185  * \retval 0 Success
 186  * \retval OGGZ_ERR_SYSTEM Error seeking on underlying IO.
 187  * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
 188  * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
 189  */
 190 int oggz_purge (OGGZ * oggz);
 191
 192 /**
 193  * Determine the content type of the oggz stream referred to by \a serialno
 194  *
 195  * \param oggz An OGGZ handle
 196  * \param serialno An ogg stream serialno
 197  * \retval OGGZ_CONTENT_THEORA..OGGZ_CONTENT_UNKNOWN content successfully
 198  *          identified
 199  * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
 200  * \retval OGGZ_ERR_BAD_SERIALNO \a serialno does not refer to an existing
 201  *          stream
 202  */
 203 OggzStreamContent oggz_stream_get_content (OGGZ * oggz, long serialno);
 204
 205 /**
 206  * Return human-readable string representation of content type of oggz stream
 207  * referred to by \a serialno
 208  *
 209  * \param oggz An OGGZ handle
 210  * \param serialno An ogg stream serialno
 211  * \retval string the name of the content type
 212  * \retval NULL \a oggz or \a serialno invalid
 213  */
 214 const char * oggz_stream_get_content_type (OGGZ *oggz, long serialno);
 215
 216 /**
 217  * Determine the number of headers of the oggz stream referred to by
 218  * \a serialno
 219  *
 220  * \param oggz An OGGZ handle
 221  * \param serialno An ogg stream serialno
 222  * \retval OGGZ_CONTENT_THEORA..OGGZ_CONTENT_UNKNOWN content successfully
 223  *          identified
 224  * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
 225  * \retval OGGZ_ERR_BAD_SERIALNO \a serialno does not refer to an existing
 226  *          stream
 227  */
 228 int oggz_stream_get_numheaders (OGGZ * oggz, long serialno);
 229
 230 #endif /* __OGGZ_READ_H__ */