/*
libmpg123: MPEG Audio Decoder library (version 1.26.3)
copyright 1995-2015 by the mpg123 project
free software under the terms of the LGPL 2.1
see COPYING and AUTHORS files in distribution or http://mpg123.org
*/
#ifndef MPG123_LIB_H
#define MPG123_LIB_H
#include <fmt123.h>
/** \file mpg123.h The header file for the libmpg123 MPEG Audio decoder */
/** A macro to check at compile time which set of API functions to expect.
* This should be incremented at least each time a new symbol is added
* to the header.
*/
#define MPG123_API_VERSION 45
#ifndef 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.
*/
#ifdef BUILD_MPG123_DLL
/* The dll exports. */
#define MPG123_EXPORT __declspec(dllexport)
#else
#ifdef LINK_MPG123_DLL
/* The exe imports. */
#define MPG123_EXPORT __declspec(dllimport)
#else
/* Nothing on normal/UNIX builds */
#define MPG123_EXPORT
#endif
#endif
#endif
/* This is for Visual Studio, so this header works as distributed in the binary downloads */
#if defined(_MSC_VER) && !defined(MPG123_DEF_SSIZE_T)
#define MPG123_DEF_SSIZE_T
#include <stddef.h>
typedef ptrdiff_t ssize_t;
#endif
#ifndef MPG123_NO_CONFIGURE /* Enable use of this file without configure. */
#include <stdlib.h>
#include <sys/types.h>
/* Simplified large file handling.
I used to have a check here that prevents building for a library with conflicting large file setup
(application that uses 32 bit offsets with library that uses 64 bits).
While that was perfectly fine in an environment where there is one incarnation of the library,
it hurt GNU/Linux and Solaris systems with multilib where the distribution fails to provide the
correct header matching the 32 bit library (where large files need explicit support) or
the 64 bit library (where there is no distinction).
New approach: When the app defines _FILE_OFFSET_BITS, it wants non-default large file support,
and thus functions with added suffix (mpg123_open_64).
Any mismatch will be caught at link time because of the _FILE_OFFSET_BITS setting used when
building libmpg123. Plus, there's dual mode large file support in mpg123 since 1.12 now.
Link failure is not the expected outcome of any half-sane usage anymore.
More complication: What about client code defining _LARGEFILE64_SOURCE? It might want direct access to the _64 functions, along with the ones without suffix. Well, that's possible now via defining MPG123_NO_LARGENAME and MPG123_LARGESUFFIX, respectively, for disabling or enforcing the suffix names.
*/
/*
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. You can force a different suffix via MPG123_LARGESUFFIX (that must include the underscore), or you can just disable the whole mess by defining MPG123_NO_LARGENAME.
*/
#if (!defined MPG123_NO_LARGENAME) && ((defined _FILE_OFFSET_BITS) || (defined MPG123_LARGESUFFIX))
/* Need some trickery to concatenate the value(s) of the given macro(s). */
#define MPG123_MACROCAT_REALLY(a, b) a ## b
#define MPG123_MACROCAT(a, b) MPG123_MACROCAT_REALLY(a, b)
#ifndef MPG123_LARGESUFFIX
#define MPG123_LARGESUFFIX MPG123_MACROCAT(_, _FILE_OFFSET_BITS)
#endif
#define MPG123_LARGENAME(func) MPG123_MACROCAT(func, MPG123_LARGESUFFIX)
#define mpg123_open_fixed MPG123_LARGENAME(mpg123_open_fixed)
#define mpg123_open MPG123_LARGENAME(mpg123_open)
#define mpg123_open_fd MPG123_LARGENAME(mpg123_open_fd)
#define mpg123_open_handle MPG123_LARGENAME(mpg123_open_handle)
#define mpg123_framebyframe_decode MPG123_LARGENAME(mpg123_framebyframe_decode)
#define mpg123_decode_frame MPG123_LARGENAME(mpg123_decode_frame)
#define mpg123_tell MPG123_LARGENAME(mpg123_tell)
#define mpg123_tellframe MPG123_LARGENAME(mpg123_tellframe)
#define mpg123_tell_stream MPG123_LARGENAME(mpg123_tell_stream)
#define mpg123_seek MPG123_LARGENAME(mpg123_seek)
#define mpg123_feedseek MPG123_LARGENAME(mpg123_feedseek)
#define mpg123_seek_frame MPG123_LARGENAME(mpg123_seek_frame)
#define mpg123_timeframe MPG123_LARGENAME(mpg123_timeframe)
#define mpg123_index MPG123_LARGENAME(mpg123_index)
#define mpg123_set_index MPG123_LARGENAME(mpg123_set_index)
#define mpg123_position MPG123_LARGENAME(mpg123_position)
#define mpg123_length MPG123_LARGENAME(mpg123_length)
#define mpg123_framelength MPG123_LARGENAME(mpg123_framelength)
#define mpg123_set_filesize MPG123_LARGENAME(mpg123_set_filesize)
#define mpg123_replace_reader MPG123_LARGENAME(mpg123_replace_reader)
#define mpg123_replace_reader_handle MPG123_LARGENAME(mpg123_replace_reader_handle)
#define mpg123_framepos MPG123_LARGENAME(mpg123_framepos)
#endif /* largefile hackery */
#endif /* MPG123_NO_CONFIGURE */
#ifdef __cplusplus
extern "C" {
#endif
/** \defgroup mpg123_init mpg123 library and handle setup
*
* Functions to initialise and shutdown the mpg123 library and handles.
* The parameters of handles have workable defaults, you only have to tune them when you want to tune something;-)
* Tip: Use a RVA setting...
*
* @{
*/
/** Opaque structure for the libmpg123 decoder handle. */
struct mpg123_handle_struct;
/** Opaque structure for the libmpg123 decoder handle.
* Most functions take a pointer to a mpg123_handle as first argument and operate on its data in an object-oriented manner.
*/
typedef struct mpg123_handle_struct mpg123_handle;
/** Function to initialise the mpg123 library.
* This should be called once in a non-parallel context. It is not explicitly
* thread-safe, but repeated/concurrent calls still _should_ be safe as static
* tables are filled with the same values anyway.
*
* \return MPG123_OK if successful, otherwise an error number.
*/
MPG123_EXPORT int mpg123_init(void);
/** Superfluous Function to close down the mpg123 library.
* This was created with the thought that there sometime will be cleanup code
* to be run after library use. This never materialized. You can forget about
* this function and it is only here for old programs that do call it.
*/
MPG123_EXPORT void mpg123_exit(void);
/** Create a handle with optional choice of decoder (named by a string, see mpg123_decoders() or mpg123_supported_decoders()).
* and optional retrieval of an error code to feed to mpg123_plain_strerror().
* Optional means: Any of or both the parameters may be NULL.
*
* \param decoder optional choice of decoder variant (NULL for default)
* \param error optional address to store error codes
* \return Non-NULL pointer to fresh handle when successful.
*/
MPG123_EXPORT mpg123_handle *mpg123_new(const char* decoder, int *error);
/** Delete handle, mh is either a valid mpg123 handle or NULL.
* \param mh handle
*/
MPG123_EXPORT void mpg123_delete(mpg123_handle *mh);
/** Free plain memory allocated within libmpg123.
* This is for library users that are not sure to use the same underlying
* memory allocator as libmpg123. It is just a wrapper over free() in
* the underlying C library.
*/
MPG123_EXPORT void mpg123_free(void *ptr);
/** Enumeration of the parameters types that it is possible to set/get. */
enum mpg123_parms
{
MPG123_VERBOSE = 0, /**< set verbosity value for enabling messages to stderr, >= 0 makes sense (integer) */
MPG123_FLAGS, /**< set all flags, p.ex val = MPG123_GAPLESS|MPG123_MONO_MIX (integer) */
MPG123_ADD_FLAGS, /**< add some flags (integer) */
MPG123_FORCE_RATE, /**< when value > 0, force output rate to that value (integer) */
MPG123_DOWN_SAMPLE, /**< 0=native rate, 1=half rate, 2=quarter rate (integer)