Commit ff2d31c7 authored by conrad's avatar conrad

update API docs for callback return values


git-svn-id: http://svn.annodex.net/liboggz/trunk@2028 8158c8cd-e7e1-0310-9fa4-c5954c97daef
parent 560daffd
...@@ -477,27 +477,37 @@ OGGZ * oggz_open_stdio (FILE * file, int flags); ...@@ -477,27 +477,37 @@ OGGZ * oggz_open_stdio (FILE * file, int flags);
int oggz_flush (OGGZ * oggz); int oggz_flush (OGGZ * oggz);
/** /**
* Set the blocksize to use internally for oggz_run() * Run an OGGZ until completion, or error.
* This is a convenience function which repeatedly calls oggz_read() or
* oggz_write() as appropriate.
* For an OGGZ opened for reading, an OggzReadPacket or OggzReadPage callback
* should have been set before calling this function.
* For an OGGZ opened for writing, either an OggzHungry callback should have
* been set before calling this function, or you can use this function to
* write out all unwritten Ogg pages which are pending.
* \param oggz An OGGZ handle previously opened for either reading or writing * \param oggz An OGGZ handle previously opened for either reading or writing
* \param blocksize The blocksize to use within oggz_run()
* \retval 0 Success * \retval 0 Success
* \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ * \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
* \retval OGGZ_ERR_INVALID Invalid blocksize (\a run_blocksize <= 0) * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
* \retval OGGZ_ERR_SYSTEM System error; check errno for details
* \retval OGGZ_ERR_STOP_OK Operation was stopped by a user callback
* returning OGGZ_STOP_OK
* \retval OGGZ_ERR_STOP_ERR Operation was stopped by a user callback
* returning OGGZ_STOP_ERR
* \retval OGGZ_ERR_RECURSIVE_WRITE Attempt to initiate writing from
* within an OggzHungry callback
*/ */
int oggz_run_set_blocksize (OGGZ * oggz, long blocksize); long oggz_run (OGGZ * oggz);
/** /**
* Run an OGGZ until completion, or error * Set the blocksize to use internally for oggz_run()
* \param oggz An OGGZ handle previously opened for either reading or writing * \param oggz An OGGZ handle previously opened for either reading or writing
* \param blocksize The blocksize to use within oggz_run()
* \retval 0 Success * \retval 0 Success
* \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing 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 * \retval OGGZ_ERR_INVALID Invalid blocksize (\a run_blocksize <= 0)
* \retval OGGZ_ERR_SYSTEM System error; check errno for details
* \retval OGGZ_ERR_RECURSIVE_WRITE Attempt to initiate writing from
* within an OggzHungry callback
*/ */
long oggz_run (OGGZ * oggz); int oggz_run_set_blocksize (OGGZ * oggz, long blocksize);
/** /**
* Close an OGGZ handle * Close an OGGZ handle
......
...@@ -144,10 +144,10 @@ int oggz_set_read_page (OGGZ * oggz, long serialno, ...@@ -144,10 +144,10 @@ int oggz_set_read_page (OGGZ * oggz, long serialno,
* \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing 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 * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
* \retval OGGZ_ERR_SYSTEM System error; check errno for details * \retval OGGZ_ERR_SYSTEM System error; check errno for details
* \retval OGGZ_ERR_USER_STOPPED Reading was stopped by a user callback * \retval OGGZ_ERR_STOP_OK Reading was stopped by a user callback
* returning OGGZ_STOP_OK or OGGZ_STOP_ERR before any input bytes were * returning OGGZ_STOP_OK
* consumed. This will occur when a packet is read from a previously * \retval OGGZ_ERR_STOP_ERR Reading was stopped by a user callback
* buffered page of input data, and stopping is immediately requested. * returning OGGZ_STOP_ERR
*/ */
long oggz_read (OGGZ * oggz, long n); long oggz_read (OGGZ * oggz, long n);
...@@ -159,10 +159,10 @@ long oggz_read (OGGZ * oggz, long n); ...@@ -159,10 +159,10 @@ long oggz_read (OGGZ * oggz, long n);
* \retval "> 0" The number of bytes successfully ingested. * \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_BAD_OGGZ \a oggz does not refer to an existing OGGZ
* \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
* \retval OGGZ_ERR_USER_STOPPED Reading was stopped by a user callback * \retval OGGZ_ERR_STOP_OK Reading was stopped by a user callback
* returning OGGZ_STOP_OK or OGGZ_STOP_ERR before any input bytes were * returning OGGZ_STOP_OK
* consumed. This will occur when a packet is read from a previously * \retval OGGZ_ERR_STOP_ERR Reading was stopped by a user callback
* buffered page of input data, and stopping is immediately requested. * returning OGGZ_STOP_ERR
*/ */
long oggz_read_input (OGGZ * oggz, unsigned char * buf, long n); long oggz_read_input (OGGZ * oggz, unsigned char * buf, long n);
......
...@@ -196,6 +196,10 @@ int oggz_write_feed (OGGZ * oggz, ogg_packet * op, long serialno, int flush, ...@@ -196,6 +196,10 @@ int oggz_write_feed (OGGZ * oggz, ogg_packet * op, long serialno, int flush,
* within an OggzHungry callback * within an OggzHungry callback
* \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing 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 * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
* \retval OGGZ_ERR_STOP_OK Writing was stopped by an OggzHungry callback
* returning OGGZ_STOP_OK
* \retval OGGZ_ERR_STOP_ERR Reading was stopped by an OggzHungry callback
* returning OGGZ_STOP_ERR
*/ */
long oggz_write_output (OGGZ * oggz, unsigned char * buf, long n); long oggz_write_output (OGGZ * oggz, unsigned char * buf, long n);
...@@ -211,6 +215,10 @@ long oggz_write_output (OGGZ * oggz, unsigned char * buf, long n); ...@@ -211,6 +215,10 @@ long oggz_write_output (OGGZ * oggz, unsigned char * buf, long n);
* within an OggzHungry callback * within an OggzHungry callback
* \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing 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 * \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
* \retval OGGZ_ERR_STOP_OK Writing was stopped by an OggzHungry callback
* returning OGGZ_STOP_OK
* \retval OGGZ_ERR_STOP_ERR Reading was stopped by an OggzHungry callback
* returning OGGZ_STOP_ERR
*/ */
long oggz_write (OGGZ * oggz, long n); long oggz_write (OGGZ * oggz, long n);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment