download : svn :: features :: sf.net project - bug tracker :: news archive

libmpg123 API :: testing :: benchmarking :: faq :: links :: contact

Note: This API doc is automatically generated from the current development version that you can get via Subversion or as a daily snapshot from http://mpg123.org/snapshot. There may be differences (additions) compared to the latest stable release. See NEWS.libmpg123 and the overall NEWS file on libmpg123 versions and important changes between them.
Let me emphasize that the policy for libmpg123 is to always stay backwards compatible -- only additions are planned (and it's not yet planned to change the plans;-).

mpg123 error handling

Enumerations
enum	mpg123_errors {   MPG123_DONE = -12, MPG123_NEW_FORMAT = -11,   MPG123_NEED_MORE = -10, MPG123_ERR = -1,   MPG123_OK = 0, MPG123_BAD_OUTFORMAT,   MPG123_BAD_CHANNEL, MPG123_BAD_RATE,   MPG123_ERR_16TO8TABLE, MPG123_BAD_PARAM,   MPG123_BAD_BUFFER, MPG123_OUT_OF_MEM,   MPG123_NOT_INITIALIZED, MPG123_BAD_DECODER,   MPG123_BAD_HANDLE, MPG123_NO_BUFFERS,   MPG123_BAD_RVA, MPG123_NO_GAPLESS,   MPG123_NO_SPACE, MPG123_BAD_TYPES,   MPG123_BAD_BAND, MPG123_ERR_NULL,   MPG123_ERR_READER, MPG123_NO_SEEK_FROM_END,   MPG123_BAD_WHENCE, MPG123_NO_TIMEOUT,   MPG123_BAD_FILE, MPG123_NO_SEEK,   MPG123_NO_READER, MPG123_BAD_PARS,   MPG123_BAD_INDEX_PAR, MPG123_OUT_OF_SYNC,   MPG123_RESYNC_FAIL, MPG123_NO_8BIT,   MPG123_BAD_ALIGN, MPG123_NULL_BUFFER,   MPG123_NO_RELSEEK, MPG123_NULL_POINTER,   MPG123_BAD_KEY, MPG123_NO_INDEX,   MPG123_INDEX_FAIL, MPG123_BAD_DECODER_SETUP,   MPG123_MISSING_FEATURE }
Functions
const char *	mpg123_plain_strerror (int errcode)
const char *	mpg123_strerror (mpg123_handle *mh)
int	mpg123_errcode (mpg123_handle *mh)

---

Detailed Description

Functions to get text version of the error numbers and an enumeration of the error codes returned by libmpg123.

Most functions operating on a mpg123_handle simply return MPG123_OK on success and MPG123_ERR on failure (setting the internal error variable of the handle to the specific error code). Decoding/seek functions may also return message codes MPG123_DONE, MPG123_NEW_FORMAT and MPG123_NEED_MORE. The positive range of return values is used for "useful" values when appropriate.

---

Enumeration Type Documentation

enum mpg123_errors

Enumeration of the message and error codes and returned by libmpg123 functions.

Enumerator:

MPG123_DONE	Message: Track ended.
MPG123_NEW_FORMAT	Message: Output format will be different on next call.
MPG123_NEED_MORE	Message: For feed reader: "Feed me more!"
MPG123_ERR	Generic Error
MPG123_OK	Success
MPG123_BAD_OUTFORMAT	Unable to set up output format!
MPG123_BAD_CHANNEL	Invalid channel number specified.
MPG123_BAD_RATE	Invalid sample rate specified.
MPG123_ERR_16TO8TABLE	Unable to allocate memory for 16 to 8 converter table!
MPG123_BAD_PARAM	Bad parameter id!
MPG123_BAD_BUFFER	Bad buffer given -- invalid pointer or too small size.
MPG123_OUT_OF_MEM	Out of memory -- some malloc() failed.
MPG123_NOT_INITIALIZED	You didn't initialize the library!
MPG123_BAD_DECODER	Invalid decoder choice.
MPG123_BAD_HANDLE	Invalid mpg123 handle.
MPG123_NO_BUFFERS	Unable to initialize frame buffers (out of memory?).
MPG123_BAD_RVA	Invalid RVA mode.
MPG123_NO_GAPLESS	This build doesn't support gapless decoding.
MPG123_NO_SPACE	Not enough buffer space.
MPG123_BAD_TYPES	Incompatible numeric data types.
MPG123_BAD_BAND	Bad equalizer band.
MPG123_ERR_NULL	Null pointer given where valid storage address needed.
MPG123_ERR_READER	Error reading the stream.
MPG123_NO_SEEK_FROM_END	Cannot seek from end (end is not known).
MPG123_BAD_WHENCE	Invalid 'whence' for seek function.
MPG123_NO_TIMEOUT	Build does not support stream timeouts.
MPG123_BAD_FILE	File access error.
MPG123_NO_SEEK	Seek not supported by stream.
MPG123_NO_READER	No stream opened.
MPG123_BAD_PARS	Bad parameter handle.
MPG123_BAD_INDEX_PAR	Bad parameters to mpg123_index()
MPG123_OUT_OF_SYNC	Lost track in bytestream and did not try to resync.
MPG123_RESYNC_FAIL	Resync failed to find valid MPEG data.
MPG123_NO_8BIT	No 8bit encoding possible.
MPG123_BAD_ALIGN	Stack aligmnent error
MPG123_NULL_BUFFER	NULL input buffer with non-zero size...
MPG123_NO_RELSEEK	Relative seek not possible (screwed up file offset)
MPG123_NULL_POINTER	You gave a null pointer somewhere where you shouldn't have.
MPG123_BAD_KEY	Bad key value given.
MPG123_NO_INDEX	No frame index in this build.
MPG123_INDEX_FAIL	Something with frame index went wrong.
MPG123_BAD_DECODER_SETUP	Something prevents a proper decoder setup
MPG123_MISSING_FEATURE	This feature has not been built into libmpg123.

Definition at line 175 of file mpg123.h.

---

Function Documentation

const char* mpg123_plain_strerror

(

int

errcode

)

Return a string describing that error errcode means.

const char* mpg123_strerror

(

mpg123_handle *

mh

)

Give string describing what error has occured in the context of handle mh. When a function operating on an mpg123 handle returns MPG123_ERR, you should check for the actual reason via char *errmsg = mpg123_strerror(mh) This function will catch mh == NULL and return the message for MPG123_BAD_HANDLE.

int mpg123_errcode

(

mpg123_handle *

mh

)

Return the plain errcode intead of a string.

---