API documentation for libmpg123, libout123, and libsyn123
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;-).
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
| enum 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. |
Function Documentation
◆ mpg123_plain_strerror()
| MPG123_EXPORT const char* mpg123_plain_strerror | ( | int | errcode | ) |
Look up error strings given integer code.
- Parameters
-
errcode integer 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
-
mh handle
- Returns
- error message
◆ mpg123_errcode()
| MPG123_EXPORT int mpg123_errcode | ( | mpg123_handle * | mh | ) |
Return the plain errcode intead of a string.
- Parameters
-
mh handle
- Returns
- error code recorded in handle or MPG123_BAD_HANDLE
