split oggz.h into smaller header files

git-svn-id: http://svn.annodex.net/liboggz/trunk@560 8158c8cd-e7e1-0310-9fa4-c5954c97daef

include/oggz/Makefile.am

@@ -2,6 +2,6 @@
 
 # Include files to install
 includedir = $(prefix)/include/oggz
-include_HEADERS = oggz.h oggz_constants.h oggz_io.h oggz_table.h\
-	oggz_deprecated.h
+include_HEADERS = oggz.h oggz_constants.h oggz_read.h oggz_seek.h \
+	oggz_write.h oggz_io.h oggz_table.h oggz_deprecated.h
 

include/oggz/oggz_read.h

+/*
+   Copyright (C) 2003 Commonwealth Scientific and Industrial Research
+   Organisation (CSIRO) Australia
+
+   Redistribution and use in source and binary forms, with or without
+   modification, are permitted provided that the following conditions
+   are met:
+
+   - Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+
+   - Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+   - Neither the name of CSIRO Australia nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+   ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+   PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE ORGANISATION OR
+   CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+   EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+   PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+   PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+   LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+   NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+   SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/
+
+#ifndef __OGGZ_READ_H__
+#define __OGGZ_READ_H__
+
+/** \defgroup read_api OGGZ Read API
+ *
+ * OGGZ parses Ogg bitstreams, forming ogg_packet structures, and calling
+ * your OggzReadPacket callback(s).
+ *
+ * You provide Ogg data to OGGZ with oggz_read() or oggz_read_input(), and
+ * independently process it in OggzReadPacket callbacks.
+ * It is possible to set a different callback per \a serialno (ie. for each
+ * logical bitstream in the Ogg bitstream - see the \ref basics section for
+ * more detail).
+ *
+ * See \ref seek_api for information on seeking on interleaved Ogg data.
+ *
+ * \{
+ */
+
+/**
+ * This is the signature of a callback which you must provide for Oggz
+ * to call whenever it finds a new packet in the Ogg stream associated
+ * with \a oggz.
+ *
+ * \param oggz The OGGZ handle
+ * \param op The full ogg_packet (see <ogg/ogg.h>)
+ * \param serialno Identify the logical bistream in \a oggz that contains
+ *                 \a op
+ * \param user_data A generic pointer you have provided earlier
+ * \returns 0 to continue, non-zero to instruct OGGZ to stop.
+ *
+ * \note It is possible to provide different callbacks per logical
+ * bitstream -- see oggz_set_read_callback() for more information.
+ */
+typedef int (*OggzReadPacket) (OGGZ * oggz, ogg_packet * op, long serialno,
+			       void * user_data);
+
+/**
+ * Set a callback for Oggz to call when a new Ogg packet is found in the
+ * stream.
+ *
+ * \param oggz An OGGZ handle previously opened for reading
+ * \param serialno Identify the logical bitstream in \a oggz to attach
+ * this callback to, or -1 to attach this callback to all unattached
+ * logical bitstreams in \a oggz.
+ * \param read_packet Your callback function
+ * \param user_data Arbitrary data you wish to pass to your callback
+ * \retval 0 Success
+ * \retval OGGZ_ERR_BAD_SERIALNO \a serialno does not identify an existing
+ * logical bitstream in \a oggz.
+ * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
+ * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
+ *
+ * \note Values of \a serialno other than -1 allows you to specify different
+ * callback functions for each logical bitstream.
+ *
+ * \note It is safe to call this callback from within an OggzReadPacket
+ * function, in order to specify that subsequent packets should be handled
+ * by a different OggzReadPacket function.
+ */
+int oggz_set_read_callback (OGGZ * oggz, long serialno,
+			    OggzReadPacket read_packet, void * user_data);
+
+/**
+ * Read n bytes into \a oggz, calling any read callbacks on the fly.
+ * \param oggz An OGGZ handle previously opened for reading
+ * \param n A count of bytes to ingest
+ * \retval ">  0" The number of bytes successfully ingested.
+ * \retval 0 End of file
+ * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
+ * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
+ * \retval OGGZ_ERR_SYSTEM System error; check errno for details
+ * \retval OGGZ_ERR_USER_STOPPED Reading was stopped by a user callback
+ * returning OGGZ_STOP_OK or OGGZ_STOP_ERR before any input bytes were
+ * consumed. This will occur when a packet is read from a previously
+ * buffered page of input data, and stopping is immediately requested.
+ */
+long oggz_read (OGGZ * oggz, long n);
+
+/**
+ * Input data into \a oggz.
+ * \param oggz An OGGZ handle previously opened for reading
+ * \param buf A memory buffer
+ * \param n A count of bytes to input
+ * \retval ">  0" The number of bytes successfully ingested.
+ * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
+ * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
+ * \retval OGGZ_ERR_USER_STOPPED Reading was stopped by a user callback
+ * returning OGGZ_STOP_OK or OGGZ_STOP_ERR before any input bytes were
+ * consumed. This will occur when a packet is read from a previously
+ * buffered page of input data, and stopping is immediately requested.
+ */
+long oggz_read_input (OGGZ * oggz, unsigned char * buf, long n);
+
+/** \}
+ */
+
+#endif /* __OGGZ_READ_H__ */

include/oggz/oggz_write.h

+/*
+   Copyright (C) 2003 Commonwealth Scientific and Industrial Research
+   Organisation (CSIRO) Australia
+
+   Redistribution and use in source and binary forms, with or without
+   modification, are permitted provided that the following conditions
+   are met:
+
+   - Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+
+   - Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+   - Neither the name of CSIRO Australia nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+   ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+   PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE ORGANISATION OR
+   CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+   EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+   PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+   PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+   LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+   NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+   SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/
+
+#ifndef __OGGZ_WRITE_H__
+#define __OGGZ_WRITE_H__
+
+/** \defgroup force_feed Writing by force feeding OGGZ
+ *
+ * Force feeding involves synchronously:
+ * - Creating an \a ogg_packet structure
+ * - Adding it to the packet queue with oggz_write_feed()
+ * - Calling oggz_write() or oggz_write_output(), repeatedly as necessary,
+ *   to generate the Ogg bitstream.
+ *
+ * This process is illustrated in the following diagram:
+ *
+ * \image html forcefeed.png
+ * \image latex forcefeed.eps "Force Feeding OGGZ" width=10cm
+ *
+ * The following example code generates a stream of ten packets, each
+ * containing a single byte ('A', 'B', ... , 'J'):
+ *
+ * \include write-feed.c
+ */
+
+/** \defgroup hungry Writing with OggzHungry callbacks
+ *
+ * You can add packets to the OGGZ packet queue only when it is "hungry"
+ * by providing an OggzHungry callback.
+ *
+ * An OggzHungry callback will:
+ * - Create an \a ogg_packet structure
+ * - Add it to the packet queue with oggz_write_feed()
+ *
+ * Once you have set such a callback with oggz_write_set_hungry_callback(),
+ * simply call oggz_write() or oggz_write_output() repeatedly, and OGGZ
+ * will call your callback to provide packets when it is hungry.
+ *
+ * This process is illustrated in the following diagram:
+ *
+ * \image html hungry.png
+ * \image latex hungry.eps "Using OggzHungry" width=10cm
+ *
+ * The following example code generates a stream of ten packets, each
+ * containing a single byte ('A', 'B', ... , 'J'):
+ *
+ * \include write-hungry.c
+ */
+
+/** \defgroup write_api OGGZ Write API
+ *
+ * OGGZ maintains a packet queue, such that you can independently add
+ * packets to the queue and write an Ogg bitstream.
+ * There are two complementary methods for adding packets to the
+ * packet queue.
+ *
+ * - by \link force_feed force feeding OGGZ \endlink
+ * - by using \link hungry OggzHungry \endlink callbacks
+ *
+ * As each packet is enqueued, its validity is checked against the framing
+ * constraints outlined in the \link basics Ogg basics \endlink section.
+ * If it does not pass these constraints, oggz_write_feed() will fail with
+ * an appropriate error code.
+ *
+ * \note
+ * - When writing, you can ensure that a packet starts on a new page
+ *   by setting the \a flush parameter of oggz_write_feed() to
+ *   \a OGGZ_FLUSH_BEFORE when enqueuing it.
+ *   Similarly you can ensure that the last page a packet is written into
+ *   won't contain any following packets by setting the \a flush parameter
+ *   of oggz_write_feed() to \a OGGZ_FLUSH_AFTER.
+ * - The \a OGGZ_FLUSH_BEFORE and \a OGGZ_FLUSH_AFTER flags can be bitwise
+ *   OR'd together to ensure that the packet will not share any pages with
+ *   any other packets, either before or after.
+ *
+ * \{
+ */
+
+/**
+ * This is the signature of a callback which Oggz will call when \a oggz
+ * is \link hungry hungry \endlink.
+ *
+ * \param oggz The OGGZ handle
+ * \param empty A value of 1 indicates that the packet queue is currently
+ *        empty. A value of 0 indicates that the packet queue is not empty.
+ * \param user_data A generic pointer you have provided earlier
+ * \retval 0 Continue
+ * \retval non-zero Instruct OGGZ to stop.
+ */
+typedef int (*OggzWriteHungry) (OGGZ * oggz, int empty, void * user_data);
+
+/**
+ * Set a callback for Oggz to call when \a oggz
+ * is \link hungry hungry \endlink.
+ *
+ * \param oggz An OGGZ handle previously opened for writing
+ * \param hungry Your callback function
+ * \param only_when_empty When to call: a value of 0 indicates that
+ * OGGZ should call \a hungry() after each and every packet is written;
+ * a value of 1 indicates that OGGZ should call \a hungry() only when
+ * its packet queue is empty
+ * \param user_data Arbitrary data you wish to pass to your callback
+ * \retval 0 Success
+ * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
+ * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
+ * \note Passing a value of 0 for \a only_when_empty allows you to feed
+ * new packets into \a oggz's packet queue on the fly.
+ */
+int oggz_write_set_hungry_callback (OGGZ * oggz,
+				    OggzWriteHungry hungry,
+				    int only_when_empty,
+				    void * user_data);
+/**
+ * Add a packet to \a oggz's packet queue.
+ * \param oggz An OGGZ handle previously opened for writing
+ * \param op An ogg_packet with all fields filled in
+ * \param serialno Identify the logical bitstream in \a oggz to add the
+ * packet to
+ * \param flush Bitmask of OGGZ_FLUSH_BEFORE, OGGZ_FLUSH_AFTER
+ * \param guard A guard for nocopy, NULL otherwise
+ * \retval 0 Success
+ * \retval OGGZ_ERR_BAD_GUARD \a guard specified has non-zero initialization
+ * \retval OGGZ_ERR_BOS Packet would be bos packet of a new logical bitstream,
+ *         but oggz has already written one or more non-bos packets in
+ *         other logical bitstreams,
+ *         and \a oggz is not flagged OGGZ_NONSTRICT
+ * \retval OGGZ_ERR_EOS The logical bitstream identified by \a serialno is
+ *         already at eos,
+ *         and \a oggz is not flagged OGGZ_NONSTRICT
+ * \retval OGGZ_ERR_BAD_BYTES \a op->bytes is invalid,
+ *         and \a oggz is not flagged OGGZ_NONSTRICT
+ * \retval OGGZ_ERR_BAD_B_O_S \a op->b_o_s is invalid,
+ *         and \a oggz is not flagged OGGZ_NONSTRICT
+ * \retval OGGZ_ERR_BAD_GRANULEPOS \a op->granulepos is less than that of
+ *         an earlier packet within this logical bitstream,
+ *         and \a oggz is not flagged OGGZ_NONSTRICT
+ * \retval OGGZ_ERR_BAD_PACKETNO \a op->packetno is less than that of an
+ *         earlier packet within this logical bitstream,
+ *         and \a oggz is not flagged OGGZ_NONSTRICT
+ * \retval OGGZ_ERR_BAD_SERIALNO \a serialno does not identify an existing
+ *         logical bitstream in \a oggz,
+ *         and \a oggz is not flagged OGGZ_NONSTRICT
+ * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
+ * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
+ *
+ * \note If \a op->b_o_s is initialized to \a -1 before calling
+ *       oggz_write_feed(), Oggz will fill it in with the appropriate
+ *       value; ie. 1 for the first packet of a new stream, and 0 otherwise.
+ */
+int oggz_write_feed (OGGZ * oggz, ogg_packet * op, long serialno, int flush,
+		     int * guard);
+
+/**
+ * Output data from an OGGZ handle. Oggz will call your write callback
+ * as needed.
+ *
+ * \param oggz An OGGZ handle previously opened for writing
+ * \param buf A memory buffer
+ * \param n A count of bytes to output
+ * \retval "> 0" The number of bytes successfully output
+ * \retval 0 End of stream
+ * \retval OGGZ_ERR_RECURSIVE_WRITE Attempt to initiate writing from
+ * within an OggzHungry callback
+ * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
+ * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
+ */
+long oggz_write_output (OGGZ * oggz, unsigned char * buf, long n);
+
+/**
+ * Write n bytes from an OGGZ handle. Oggz will call your write callback
+ * as needed.
+ *
+ * \param oggz An OGGZ handle previously opened for writing
+ * \param n A count of bytes to be written
+ * \retval "> 0" The number of bytes successfully output
+ * \retval 0 End of stream
+ * \retval OGGZ_ERR_RECURSIVE_WRITE Attempt to initiate writing from
+ * within an OggzHungry callback
+ * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
+ * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
+ */
+long oggz_write (OGGZ * oggz, long n);
+
+/**
+ * Query the number of bytes in the next page to be written.
+ *
+ * \param oggz An OGGZ handle previously opened for writing
+ * \retval ">= 0" The number of bytes in the next page
+ * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
+ * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
+ */
+long oggz_write_get_next_page_size (OGGZ * oggz);
+
+/** \}
+ */
+
+#endif /* __OGGZ_WRITE_H__ */