Update documentation to reflect new API calls, and extended error return behavior.

svn path=/trunk/ogg/; revision=16017
author: Monty <xiphmont@xiph.org> 2009-05-20 00:18:35 +0000
committer: Monty <xiphmont@xiph.org> 2009-05-20 00:18:35 +0000
commit: 0abcbbfac5e066858445f75f83007996a3195f99 (patch)
tree: 99ca341fe3fe5c622cff8bf1ef2612971dd52865 /doc/libogg
parent: 76f4809e46bd2af58b6efd7cc0ccb616d45b176a (diff)
download: ogg-git-0abcbbfac5e066858445f75f83007996a3195f99.tar.gz
10 files changed, 242 insertions, 5 deletions
diff --git a/doc/libogg/bitpacking.html b/doc/libogg/bitpacking.html
index 0b8e1b8..a285644 100644
--- a/doc/libogg/bitpacking.html
+++ b/doc/libogg/bitpacking.html
@@ -29,6 +29,10 @@ All the <b>libogg</b> specific functions are declared in "ogg/ogg.h".
 	<td>Initializes a buffer for writing using this bitpacking library.</td>
 </tr>
 <tr valign=top>
+<td><a href="oggpack_writecheck.html">oggpack_writecheck</a></td>
+	<td>Asynchronously checks error status of bitpacker write buffer.</td>
+</tr>
+<tr valign=top>
 <td><a href="oggpack_reset.html">oggpack_reset</a></td>
 	<td>Clears and resets the buffer to the initial position.</td>
 </tr>
diff --git a/doc/libogg/encoding.html b/doc/libogg/encoding.html
index 32fa766..9485248 100644
--- a/doc/libogg/encoding.html
+++ b/doc/libogg/encoding.html
@@ -38,6 +38,10 @@ All the <b>libogg</b> specific functions are declared in "ogg/ogg.h".
 	<td>Submits a raw packet to the streaming layer, so that it can be formed into a page.</td>
 </tr>
 <tr valign=top>
+<td><a href="ogg_stream_iovecin.html">ogg_stream_iovecin</a></td>
+	<td>iovec version of ogg_stream_packetin() above.</td>
+</tr>
+<tr valign=top>
 <td><a href="ogg_stream_pageout.html">ogg_stream_pageout</a></td>
 	<td>Outputs a completed page if the stream contains enough packets to form a full page.<td>
 </tr>
diff --git a/doc/libogg/general.html b/doc/libogg/general.html
index 550ff0c..43788e5 100644
--- a/doc/libogg/general.html
+++ b/doc/libogg/general.html
@@ -79,7 +79,7 @@ All the <b>libogg</b> specific functions are declared in "ogg/ogg.h".
 	<td>Returns the sequential page number for this page.</td>
 </tr>
 <tr valign=top>
-<td><a href="ogg_packet_clear.html">ogg_packet_clear</a><td>
+<td><a href="ogg_packet_clear.html">ogg_packet_clear</a></td>
         <td>Clears the ogg_packet structure.</td>
 </tr>
 <tr valign=top>
diff --git a/doc/libogg/ogg_iovec_t.html b/doc/libogg/ogg_iovec_t.html
new file mode 100644
index 0000000..4b3c32f
--- /dev/null
+++ b/doc/libogg/ogg_iovec_t.html
@@ -0,0 +1,62 @@
+<html>
+
+<head>
+<title>libogg - datatype - ogg_iovec_t</title>
+<link rel=stylesheet href="style.css" type="text/css">
+</head>
+
+<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
+<table border=0 width=100%>
+<tr>
+<td><p class=tiny>libogg documentation</p></td>
+<td align=right><p class=tiny>libogg - 20011015</p></td>
+</tr>
+</table>
+
+<h1>ogg_iovec_t</h1>
+
+<p><i>declared in "ogg/ogg.h"</i></p>
+
+<p>
+The ogg_iovec_t struct encapsulates a length-encoded buffer.  An array
+of ogg_iovec_t is used to pass a list of buffers to functions that
+accept data in ogg_iovec_t* form.
+<p>
+
+<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
+<tr bgcolor=#cccccc>
+	<td>
+<pre><b>
+typedef struct {
+  void *iov_base;
+  size_t iov_len;
+} ogg_iovec_t;
+</b></pre>
+	</td>
+</tr>
+</table>
+
+<h3>Relevant Struct Members</h3>
+<dl>
+<dt><i>iov_base</i></dt>
+<dd>Pointer to the buffer data.</dd>
+<dt><i>iov_len</i></dt>
+<dd>Length of buffer data in bytes.</dd>
+</dl>
+
+
+<br><br>
+<hr noshade>
+<table border=0 width=100%>
+<tr valign=top>
+<td><p class=tiny>copyright &copy; 2001 xiph.org foundation</p></td>
+<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/">Ogg Container Format</a></p></td>
+</tr><tr>
+<td><p class=tiny>libogg documentation</p></td>
+<td align=right><p class=tiny>libogg - 20011015</p></td>
+</tr>
+</table>
+
+</body>
+
+</html>
diff --git a/doc/libogg/ogg_stream_init.html b/doc/libogg/ogg_stream_init.html
index 8285493..e0e58f4 100644
--- a/doc/libogg/ogg_stream_init.html
+++ b/doc/libogg/ogg_stream_init.html
@@ -44,7 +44,7 @@ int ogg_stream_init(<a href="ogg_stream_state.html">ogg_stream_state</a> *os,int
 <li>
 0 if successful</li>
 <li>
--1 if unsuccessful.  If this fails, the ogg_stream_state was not properly declared before calling this function.</li>
+-1 if unsuccessful.</li>
 </blockquote>
 <p>
 
diff --git a/doc/libogg/ogg_stream_iovecin.html b/doc/libogg/ogg_stream_iovecin.html
new file mode 100644
index 0000000..d07d345
--- /dev/null
+++ b/doc/libogg/ogg_stream_iovecin.html
@@ -0,0 +1,83 @@
+<html>
+
+<head>
+<title>libogg - function - ogg_stream_iovecin</title>
+<link rel=stylesheet href="style.css" type="text/css">
+</head>
+
+<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
+<table border=0 width=100%>
+<tr>
+<td><p class=tiny>libogg documentation</p></td>
+<td align=right><p class=tiny>libogg release 1.0 - 20000615</p></td>
+</tr>
+</table>
+
+<h1>ogg_stream_iovecin</h1>
+
+<p><i>declared in "ogg/ogg.h";</i></p>
+
+<p>This function submits packet data (in the form of
+an array of <a href="ogg_iovec_t.html">ogg_iovec_t</a>, rather than using
+an <a href="ogg_packet.html">ogg_packet</a> structure) to the
+bitstream for page encapsulation. After this is called, more packets
+can be submitted, or pages can be written out.</p>
+
+<p>In a typical encoding situation, this should be used after filling a 
+packet with data.
+The data in the packet is copied into the internal storage managed by 
+the <a href="ogg_stream_state.html">ogg_stream_state</a>, so the caller
+is free to alter the contents of <i>os</i> after this call has returned.
+
+<br><br>
+<table border=0 color=black cellspacing=0 cellpadding=7>
+<tr bgcolor=#cccccc>
+	<td>
+<pre><b>
+int ogg_stream_iovecin(ogg_stream_state *os, ogg_iovec_t *iov, int count, long e_o_s, ogg_int64_t granulepos);
+</b></pre>
+	</td>
+</tr>
+</table>
+
+<h3>Parameters</h3>
+<dl>
+<dt><i>os</i></dt>
+<dd>Pointer to a previously declared <a href="ogg_stream_state.html">ogg_stream_state</a> struct.</dd>
+<dt><i>iov</i></dt>
+<dd>Length-encoded buffers held in an array of <a href="ogg_iovec_t.html">ogg_iovec_t</a>.
+<dt><i>count</i></dt>
+<dd>Length of the iov array.
+<dt><i>e_o_s</i></dt>
+<dd>End of stream flag, analagous to the e_o_s field in an <a href="ogg_packet.html">ogg_packet</a>.
+<dt><i>granulepos</i></dt>
+<dd>Granule position value, analagous to the granpos field in an <a href="ogg_packet.html">ogg_packet</a>.
+</dl>
+
+
+<h3>Return Values</h3>
+<blockquote>
+<li>
+0 returned on success.  -1 returned in the event of internal error
+(currently only caused by a failed memory allocation, a case that can
+only occur on embedded systems.  It is reasonable to ignore the return
+value innormal desktop applications).</li>
+</blockquote>
+<p>
+
+<br><br>
+<hr noshade>
+<table border=0 width=100%>
+<tr valign=top>
+<td><p class=tiny>copyright &copy; 2000 xiph.org</p></td>
+<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/">Ogg Container Format</a></p></td>
+</tr><tr>
+<td><p class=tiny>libogg documentation</p></td>
+<td align=right><p class=tiny>libogg release 1.0 - 20000615</p></td>
+</tr>
+</table>
+
+
+</body>
+
+</html>
diff --git a/doc/libogg/ogg_stream_packetin.html b/doc/libogg/ogg_stream_packetin.html
index 0e88afb..b8c8d02 100644
--- a/doc/libogg/ogg_stream_packetin.html
+++ b/doc/libogg/ogg_stream_packetin.html
@@ -50,7 +50,10 @@ int ogg_stream_packetin(ogg_stream_state *os,ogg_packet *op);
 <h3>Return Values</h3>
 <blockquote>
 <li>
-0 is always returned.</li>
+0 returned on success.  -1 returned in the event of internal error
+(currently only caused by a failed memory allocation, a case that can
+only occur on embedded systems.  It is reasonable to ignore the return
+value innormal desktop applications).</li>
 </blockquote>
 <p>
 
diff --git a/doc/libogg/ogg_stream_pagein.html b/doc/libogg/ogg_stream_pagein.html
index 88d7a9b..a6ebb2a 100644
--- a/doc/libogg/ogg_stream_pagein.html
+++ b/doc/libogg/ogg_stream_pagein.html
@@ -43,7 +43,7 @@ int ogg_stream_pagein(<a href="ogg_stream_state.html">ogg_stream_state</a> *os,
 
 <h3>Return Values</h3>
 <blockquote>
-<li>-1 indicates failure.  This means that the serial number of the page did not match the serial number of the bitstream, or that the page version was incorrect.</li>
+<li>-1 indicates failure.  This means that the serial number of the page did not match the serial number of the bitstream, the page version was incorrect, or a memory allocation failed.</li>
 <li>
 0 means that the page was successfully submitted to the bitstream.</li>
 </blockquote>
diff --git a/doc/libogg/ogg_sync_buffer.html b/doc/libogg/ogg_sync_buffer.html
index 6f77133..8001d81 100644
--- a/doc/libogg/ogg_sync_buffer.html
+++ b/doc/libogg/ogg_sync_buffer.html
@@ -45,7 +45,7 @@ char *ogg_sync_buffer(ogg_sync_state *oy, long size);
 <h3>Return Values</h3>
 <blockquote>
 <li>
-Returns a pointer to the newly allocated buffer.</li>
+Returns a pointer to the newly allocated buffer or NULL on error</li>
 </blockquote>
 <p>
 
diff --git a/doc/libogg/oggpack_writecheck.html b/doc/libogg/oggpack_writecheck.html
new file mode 100644
index 0000000..e53dbac
--- /dev/null
+++ b/doc/libogg/oggpack_writecheck.html
@@ -0,0 +1,81 @@
+<html>
+
+<head>
+<title>libogg - function - oggpack_writecheck</title>
+<link rel=stylesheet href="style.css" type="text/css">
+</head>
+
+<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
+<table border=0 width=100%>
+<tr>
+<td><p class=tiny>libogg documentation</p></td>
+<td align=right><p class=tiny>libogg release 1.0 - 20000615</p></td>
+</tr>
+</table>
+
+<h1>oggpack_writecheck</h1>
+
+<p><i>declared in "ogg/ogg.h";</i></p>
+
+<p>This function checks the readiness status of
+an <a href="oggpack_buffer.html">oggpack_buffer</a> previously
+initialized for writing using the
+Ogg <a href="bitpacking.html">bitpacking</a> functions.  A write
+buffer that encounters an error (such as a failed malloc) will clear
+its internal state and release any in-use memory, flagging itself as
+'not ready'.  Subsequent attempts to write using the buffer will
+silently fail. This error state may be detected at any later time by
+using oggpack_writecheck().  It is safe but not necessary to
+call <a href="oggpack_clear.html">oggpack_clear()</a> on a buffer that
+has flagged an error and released its resources. 
+
+<p><em>Important note to developers: Although libogg checks the
+results of memory allocations, these checks are only useful on a
+narrow range of embedded platforms. Allocation checks perform no
+useful service on a general purpose desktop OS where pages are
+routinely overallocated and all allocations succeed whether memory is
+available or not.  The only way to detect an out of memory condition
+on the vast majority of OSes is to watch for and capture segmentation
+faults.  This function is useful only to embedded developers.</em>
+ 
+<br><br>
+<table border=0 color=black cellspacing=0 cellpadding=7>
+<tr bgcolor=#cccccc>
+	<td>
+<pre><b>
+int  oggpack_writecheck(<a href="oggpack_buffer.html">oggpack_buffer</a> *b);
+</b></pre>
+	</td>
+</tr>
+</table>
+
+<h3>Parameters</h3>
+<dl>
+<dt><i>b</i></dt>
+<dd>An <a href="oggpack_buffer.html">oggpack_buffer</a> previously initialized for writing.</dd>
+</dl>
+
+
+<h3>Return Values</h3>
+<blockquote>
+<li><i>zero</i>: buffer is ready for writing</li>
+<li><i>nonzero</i>: buffer is not ready or encountered an error</li>
+</blockquote>
+<p>
+
+<br><br>
+<hr noshade>
+<table border=0 width=100%>
+<tr valign=top>
+<td><p class=tiny>copyright &copy; 2000 xiph.org</p></td>
+<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/">Ogg Container Format</a></p></td>
+</tr><tr>
+<td><p class=tiny>libogg documentation</p></td>
+<td align=right><p class=tiny>libogg release 1.0 - 20000615</p></td>
+</tr>
+</table>
+
+
+</body>
+
+</html>
author	Monty <xiphmont@xiph.org>	2009-05-20 00:18:35 +0000
committer	Monty <xiphmont@xiph.org>	2009-05-20 00:18:35 +0000
commit	0abcbbfac5e066858445f75f83007996a3195f99 (patch)
tree	99ca341fe3fe5c622cff8bf1ef2612971dd52865 /doc/libogg
parent	76f4809e46bd2af58b6efd7cc0ccb616d45b176a (diff)
download	ogg-git-0abcbbfac5e066858445f75f83007996a3195f99.tar.gz