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;-).
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;-).
Macros | |
| #define | MPG123_API_VERSION 49 |
| #define | MPG123_PATCHLEVEL 3 |
| #define | MPG123_EXPORT |
Typedefs | |
| typedef ssize_t | mpg123_ssize_t |
Detailed Description
About enum API
Earlier versions of libmpg123 put enums into public API calls, which is not exactly safe. There are ABI rules, but you can use compiler switches to change the sizes of enums. It is safer not to have them in API calls. Thus, the default is to remap calls and structs to variants that use plain ints. Define MPG123_ENUM_API to prevent that remapping.You might want to define this to increase the chance of your binary working with an older version of the library. But if that is your goal, you should better build with an older version to begin with.You can avoid renamed symbols by using the non-enum names directly:
Handling of large file offsets
When client code defines _FILE_OFFSET_BITS, it wants non-default large file support, and thus functions with added suffix (mpg123_open_64). The default library build provides wrapper and alias functions to accomodate client code variations (dual-mode library like glibc).Client code can definie MPG123_NO_LARGENAME and MPG123_LARGESUFFIX, respectively, for disabling or enforcing the suffixes. You should not do this, though, unless you really want to deal with symbol ABI yourself. If explicit usage of 64 bit offsets is desired, the int64_t API consisting of functions with 64 suffix without underscore, notably mpg123_reader64(), can be used since API version 48 (mpg123 1.32). A matching mpg123_open64(), stripped-down mpg123_open_handle_64() is present since API version 49 (mpg123 1.33).When in doubt, use the explicit 64 bit functions and avoid off_t in the API. You can define MPG123_PORTABLE_API to ensure that. That being said, if you and your compiler do not have problems with the concept of off_t, just use the normal AP like the I/O API of the standard C library. Both 32 and 64 bit versions of functions will be present where appropriate.If your toolchain enforces _FILE_OFFSET_BITS also during build of libmpg123, only that setting will be supported for client code.
Renaming of functions for largefile support
Now, the renaming of large file aware functions. By default, it appends underscore _FILE_OFFSET_BITS (so, mpg123_seek_64() for mpg123_seek()), if _FILE_OFFSET_BITS is defined. These are the affected API functions:
- mpg123_open_fixed()
- mpg123_open()
- mpg123_open_fd()
- mpg123_open_handle()
- mpg123_framebyframe_decode()
- mpg123_decode_frame()
- mpg123_tell()
- mpg123_tellframe()
- mpg123_tell_stream()
- mpg123_seek()
- mpg123_feedseek()
- mpg123_seek_frame()
- mpg123_timeframe()
- mpg123_index()
- mpg123_set_index()
- mpg123_position()
- mpg123_length()
- mpg123_framelength()
- mpg123_set_filesize()
- mpg123_replace_reader()
- mpg123_replace_reader_handle()
- mpg123_framepos()
Macro Definition Documentation
◆ MPG123_API_VERSION
| #define MPG123_API_VERSION 49 |
◆ MPG123_PATCHLEVEL
| #define MPG123_PATCHLEVEL 3 |
◆ MPG123_EXPORT
| #define MPG123_EXPORT |
Defines needed for MS Visual Studio(tm) DLL builds. Every public function must be prefixed with MPG123_EXPORT. When building the DLL ensure to define BUILD_MPG123_DLL. This makes the function accessible for clients and includes it in the import library which is created together with the DLL. When consuming the DLL ensure to define LINK_MPG123_DLL which imports the functions from the DLL.
Typedef Documentation
◆ mpg123_ssize_t
| typedef ssize_t mpg123_ssize_t |
