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);
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 blocksize The blocksize to use within oggz_run()
* \retval 0 Success
* \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 blocksize The blocksize to use within oggz_run()
* \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
* \retval OGGZ_ERR_SYSTEM System error; check errno for details
* \retval OGGZ_ERR_RECURSIVE_WRITE Attempt to initiate writing from
* within an OggzHungry callback
* \retval OGGZ_ERR_INVALID Invalid blocksize (\a run_blocksize <= 0)
*/
long oggz_run (OGGZ * oggz);
int oggz_run_set_blocksize (OGGZ * oggz, long blocksize);
/**
* Close an OGGZ handle
......
......@@ -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_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.
* \retval OGGZ_ERR_STOP_OK Reading was stopped by a user callback
* returning OGGZ_STOP_OK
* \retval OGGZ_ERR_STOP_ERR Reading was stopped by a user callback
* returning OGGZ_STOP_ERR
*/
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 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.
* \retval OGGZ_ERR_STOP_OK Reading was stopped by a user callback
* returning OGGZ_STOP_OK
* \retval OGGZ_ERR_STOP_ERR Reading was stopped by a user callback
* returning OGGZ_STOP_ERR
*/
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,
* 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
* \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);
......@@ -211,6 +215,10 @@ long oggz_write_output (OGGZ * oggz, unsigned char * buf, long n);
* 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
* \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);
......
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