API documentation for libmpg123, libout123, and libsyn123

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, NEWS.libout123, NEWS.libsyn123, and the overall NEWS file on libmpg123 versions and important changes between them.
Let me emphasize that the policy for the lib*123 family 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 , MPG123_BAD_VALUE ,
  MPG123_LSEEK_FAILED , MPG123_BAD_CUSTOM_IO ,
  MPG123_LFS_OVERFLOW , MPG123_INT_OVERFLOW ,
  MPG123_BAD_FLOAT
}
 

Functions

MPG123_EXPORT const char * mpg123_plain_strerror (int errcode)
 
MPG123_EXPORT const char * mpg123_strerror (mpg123_handle *mh)
 
MPG123_EXPORT 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 (0) on success and MPG123_ERR (-1) on failure, setting the internal error variable of the handle to the specific error code. If there was not a valid (non-NULL) handle provided to a function operating on one, MPG123_BAD_HANDLE may be returned if this can not be confused with a valid positive return value. Meaning: A function expected to return positive integers on success will always indicate error or a special condition by returning a negative one.

Decoding/seek functions may also return message codes MPG123_DONE, MPG123_NEW_FORMAT and MPG123_NEED_MORE (all negative, see below on how to react). Note that calls to those can be nested, so generally watch out for these codes after initial handle setup. Especially any function that needs information about the current stream to work will try to at least parse the beginning if that did not happen yet.

On a function that is supposed to return MPG123_OK on success and MPG123_ERR on failure, make sure you check for != MPG123_OK, not == MPG123_ERR, as the error code could get more specific in future, or there is just a special message from a decoding routine as indicated above.

Enumeration Type Documentation

◆ mpg123_errors

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

Enumerator
MPG123_DONE 

Message: Track ended. Stop decoding.

MPG123_NEW_FORMAT 

Message: Output format will be different on next call. Note that some libmpg123 versions between 1.4.3 and 1.8.0 insist on you calling mpg123_getformat() after getting this message code. Newer verisons behave like advertised: You have the chance to call mpg123_getformat(), but you can also just continue decoding and get your data.

MPG123_NEED_MORE 

Message: For feed reader: "Feed me more!" (call mpg123_feed() or mpg123_decode() with some new input data).

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 or no reader callback setup.

MPG123_BAD_PARS 

Bad parameter handle.

MPG123_BAD_INDEX_PAR 

Bad parameters to mpg123_index() and mpg123_set_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.

MPG123_BAD_VALUE 

A bad value has been given, somewhere.

MPG123_LSEEK_FAILED 

Low-level seek failed.

MPG123_BAD_CUSTOM_IO 

Custom I/O not prepared.

MPG123_LFS_OVERFLOW 

Offset value overflow during translation of large file API calls – your client program cannot handle that large file.

MPG123_INT_OVERFLOW 

Some integer overflow.

MPG123_BAD_FLOAT 

Floating-point computations work not as expected.

Definition at line 465 of file mpg123.h.

Function Documentation

◆ mpg123_plain_strerror()

MPG123_EXPORT const char* mpg123_plain_strerror ( int  errcode)

Look up error strings given integer code.

Parameters
errcodeinteger error code
Returns
string describing what that error error code means

◆ mpg123_strerror()

MPG123_EXPORT 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.

Parameters
mhhandle
Returns
error message

◆ mpg123_errcode()

MPG123_EXPORT int mpg123_errcode ( mpg123_handle mh)

Return the plain errcode intead of a string.

Parameters
mhhandle
Returns
error code recorded in handle or MPG123_BAD_HANDLE
Hopefully valid HTML! Valid CSS!