libopenmpt: libopenmpt C

libopenmpt 0.9.0-pre.12+r25552 cross-platform C++ and C library to decode tracked music files

Loading...
Searching...
No Matches
libopenmpt C

## Topics
| Render param indices
| Parameter index to use with openmpt_module_get_render_param() and openmpt_module_set_render_param().
| Pattern cell indices
| Parameter index to use with openmpt_module_get_pattern_row_channel_command(), openmpt_module_format_pattern_row_channel_command() and openmpt_module_highlight_pattern_row_channel_command().

## Classes
struct | openmpt_stream_callbacks
| Stream callbacks. More...
struct | openmpt_module_initial_ctl
struct | openmpt_stream_buffer
struct | openmpt_stream_buffer2

## Macros
#define | OPENMPT_STRING_LIBRARY_VERSION LIBOPENMPT_DEPRECATED_STRING( "library_version" )
#define | OPENMPT_STRING_LIBRARY_FEATURES LIBOPENMPT_DEPRECATED_STRING( "library_features" )
#define | OPENMPT_STRING_CORE_VERSION LIBOPENMPT_DEPRECATED_STRING( "core_version" )
#define | OPENMPT_STRING_BUILD LIBOPENMPT_DEPRECATED_STRING( "build" )
#define | OPENMPT_STRING_CREDITS LIBOPENMPT_DEPRECATED_STRING( "credits" )
#define | OPENMPT_STRING_CONTACT LIBOPENMPT_DEPRECATED_STRING( "contact" )
#define | OPENMPT_STRING_LICENSE LIBOPENMPT_DEPRECATED_STRING( "license" )
#define | OPENMPT_STREAM_SEEK_SET 0
#define | OPENMPT_STREAM_SEEK_CUR 1
#define | OPENMPT_STREAM_SEEK_END 2
#define | OPENMPT_ERROR_OK 0
#define | OPENMPT_ERROR_BASE 256
#define | OPENMPT_ERROR_UNKNOWN ( OPENMPT_ERROR_BASE + 1 )
#define | OPENMPT_ERROR_EXCEPTION ( OPENMPT_ERROR_BASE + 11 )
#define | OPENMPT_ERROR_OUT_OF_MEMORY ( OPENMPT_ERROR_BASE + 21 )
#define | OPENMPT_ERROR_RUNTIME ( OPENMPT_ERROR_BASE + 30 )
#define | OPENMPT_ERROR_RANGE ( OPENMPT_ERROR_BASE + 31 )
#define | OPENMPT_ERROR_OVERFLOW ( OPENMPT_ERROR_BASE + 32 )
#define | OPENMPT_ERROR_UNDERFLOW ( OPENMPT_ERROR_BASE + 33 )
#define | OPENMPT_ERROR_LOGIC ( OPENMPT_ERROR_BASE + 40 )
#define | OPENMPT_ERROR_DOMAIN ( OPENMPT_ERROR_BASE + 41 )
#define | OPENMPT_ERROR_LENGTH ( OPENMPT_ERROR_BASE + 42 )
#define | OPENMPT_ERROR_OUT_OF_RANGE ( OPENMPT_ERROR_BASE + 43 )
#define | OPENMPT_ERROR_INVALID_ARGUMENT ( OPENMPT_ERROR_BASE + 44 )
#define | OPENMPT_ERROR_GENERAL ( OPENMPT_ERROR_BASE + 101 )
#define | OPENMPT_ERROR_INVALID_MODULE_POINTER ( OPENMPT_ERROR_BASE + 102 )
#define | OPENMPT_ERROR_ARGUMENT_NULL_POINTER ( OPENMPT_ERROR_BASE + 103 )
#define | OPENMPT_ERROR_FUNC_RESULT_NONE 0
#define | OPENMPT_ERROR_FUNC_RESULT_LOG ( 1 << 0 )
#define | OPENMPT_ERROR_FUNC_RESULT_STORE ( 1 << 1 )
#define | OPENMPT_ERROR_FUNC_RESULT_DEFAULT ( OPENMPT_ERROR_FUNC_RESULT_LOG | OPENMPT_ERROR_FUNC_RESULT_STORE )
#define | OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES 0x1ull
#define | OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS 0x2ull
#define | OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT ( OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES | OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS )
#define | OPENMPT_PROBE_FILE_HEADER_FLAGS_NONE 0x0ull
#define | OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESS 1
#define | OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE 0
#define | OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATA (-1)
#define | OPENMPT_PROBE_FILE_HEADER_RESULT_ERROR (-255)
#define | openmpt_stream_buffer_init_prefix_only(buffer_, prefix_data_, prefix_size_, file_size_)
#define | openmpt_stream_buffer_overflowed(buffer_)
#define | LIBOPENMPT_STREAM_CALLBACKS_BUFFER
| Defined if libopenmpt/libopenmpt_stream_callbacks_buffer.h exists.
#define | LIBOPENMPT_STREAM_CALLBACKS_FD
| Defined if libopenmpt/libopenmpt_stream_callbacks_fd.h exists.
#define | LIBOPENMPT_STREAM_CALLBACKS_FILE
| Defined if libopenmpt/libopenmpt_stream_callbacks_file.h exists.
#define | LIBOPENMPT_STREAM_CALLBACKS_FILE_MINGW
| Defined if libopenmpt/libopenmpt_stream_callbacks_file_mingw.h exists.
#define | LIBOPENMPT_STREAM_CALLBACKS_FILE_MSVCRT
| Defined if libopenmpt/libopenmpt_stream_callbacks_file_msvcrt.h exists.
#define | LIBOPENMPT_STREAM_CALLBACKS_FILE_POSIX
| Defined if libopenmpt/libopenmpt_stream_callbacks_file_posix.h exists.
#define | LIBOPENMPT_STREAM_CALLBACKS_FILE_POSIX_LFS64
| Defined if libopenmpt/libopenmpt_stream_callbacks_file_posix_lfs64.h exists.

## Typedefs
typedef size_t(* | openmpt_stream_read_func) (void *stream, void *dst, size_t bytes)
| Read bytes from stream.
typedef int(* | openmpt_stream_seek_func) (void *stream, int64_t offset, int whence)
| Seek stream position.
typedef int64_t(* | openmpt_stream_tell_func) (void *stream)
| Tell stream position.
typedef struct openmpt_stream_callbacks | openmpt_stream_callbacks
| Stream callbacks.
typedef void(* | openmpt_log_func) (const char *message, void *user)
| Logging function.
typedef int(* | openmpt_error_func) (int error, void *user)
| Error function.
typedef struct openmpt_module | openmpt_module
| Opaque type representing a libopenmpt module.
typedef struct openmpt_module_initial_ctl | openmpt_module_initial_ctl
typedef struct openmpt_stream_buffer | openmpt_stream_buffer
typedef struct openmpt_stream_buffer2 | openmpt_stream_buffer2

## Functions
uint32_t | openmpt_get_library_version (void)
| Get the libopenmpt version number.
uint32_t | openmpt_get_core_version (void)
| Get the core version number.
void | openmpt_free_string (const char *str)
| Free a string returned by libopenmpt.
const char * | openmpt_get_string (const char *key)
| Get library related metadata.
const char * | openmpt_get_supported_extensions (void)
| Get a list of supported file extensions.
int | openmpt_is_extension_supported (const char *extension)
| Query whether a file extension is supported.
void | openmpt_log_func_default (const char *message, void *user)
| Default logging function.
void | openmpt_log_func_silent (const char *message, void *user)
| Silent logging function.
int | openmpt_error_is_transient (int error)
| Check whether the error is transient.
const char * | openmpt_error_string (int error)
| Convert error code to text.
int | openmpt_error_func_default (int error, void *user)
| Default error function.
int | openmpt_error_func_log (int error, void *user)
| Log error function.
int | openmpt_error_func_store (int error, void *user)
| Store error function.
int | openmpt_error_func_ignore (int error, void *user)
| Ignore error function.
int | openmpt_error_func_errno (int error, void *user)
| Errno error function.
void * | openmpt_error_func_errno_userdata (int *error)
| User pointer for openmpt_error_func_errno.
double | openmpt_could_open_probability (openmpt_stream_callbacks stream_callbacks, void *stream, double effort, openmpt_log_func logfunc, void *user)
| Roughly scan the input stream to find out whether libopenmpt might be able to open it.
double | openmpt_could_open_propability (openmpt_stream_callbacks stream_callbacks, void *stream, double effort, openmpt_log_func logfunc, void *user)
| Roughly scan the input stream to find out whether libopenmpt might be able to open it.
double | openmpt_could_open_probability2 (openmpt_stream_callbacks stream_callbacks, void *stream, double effort, openmpt_log_func logfunc, void *loguser, openmpt_error_func errfunc, void *erruser, int *error, const char **error_message)
| Roughly scan the input stream to find out whether libopenmpt might be able to open it.
size_t | openmpt_probe_file_header_get_recommended_size (void)
| Get recommended header size for successfull format probing.
int | openmpt_probe_file_header (uint64_t flags, const void *data, size_t size, uint64_t filesize, openmpt_log_func logfunc, void *loguser, openmpt_error_func errfunc, void *erruser, int *error, const char **error_message)
| Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it.
int | openmpt_probe_file_header_without_filesize (uint64_t flags, const void *data, size_t size, openmpt_log_func logfunc, void *loguser, openmpt_error_func errfunc, void *erruser, int *error, const char **error_message)
| Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it.
int | openmpt_probe_file_header_from_stream (uint64_t flags, openmpt_stream_callbacks stream_callbacks, void *stream, openmpt_log_func logfunc, void *loguser, openmpt_error_func errfunc, void *erruser, int *error, const char **error_message)
| Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it.
openmpt_module * | openmpt_module_create (openmpt_stream_callbacks stream_callbacks, void *stream, openmpt_log_func logfunc, void *loguser, const openmpt_module_initial_ctl *ctls)
| Construct an openmpt_module.
openmpt_module * | openmpt_module_create2 (openmpt_stream_callbacks stream_callbacks, void *stream, openmpt_log_func logfunc, void *loguser, openmpt_error_func errfunc, void *erruser, int *error, const char **error_message, const openmpt_module_initial_ctl *ctls)
| Construct an openmpt_module.
openmpt_module * | openmpt_module_create_from_memory (const void *filedata, size_t filesize, openmpt_log_func logfunc, void *loguser, const openmpt_module_initial_ctl *ctls)
| Construct an openmpt_module.
openmpt_module * | openmpt_module_create_from_memory2 (const void *filedata, size_t filesize, openmpt_log_func logfunc, void *loguser, openmpt_error_func errfunc, void *erruser, int *error, const char **error_message, const openmpt_module_initial_ctl *ctls)
| Construct an openmpt_module.
void | openmpt_module_destroy (openmpt_module *mod)
| Unload a previously created openmpt_module from memory.
void | openmpt_module_set_log_func (openmpt_module *mod, openmpt_log_func logfunc, void *loguser)
| Set logging function.
void | openmpt_module_set_error_func (openmpt_module *mod, openmpt_error_func errfunc, void *erruser)
| Set error function.
int | openmpt_module_error_get_last (openmpt_module *mod)
| Get last error.
const char * | openmpt_module_error_get_last_message (openmpt_module *mod)
| Get last error message.
void | openmpt_module_error_set_last (openmpt_module *mod, int error)
| Set last error.
void | openmpt_module_error_clear (openmpt_module *mod)
| Clear last error.
int | openmpt_module_select_subsong (openmpt_module *mod, int32_t subsong)
| Select a sub-song from a multi-song module.
int32_t | openmpt_module_get_selected_subsong (openmpt_module *mod)
| Get currently selected sub-song from a multi-song module.
int32_t | openmpt_module_get_restart_order (openmpt_module *mod, int32_t subsong)
| Get the restart order of the specified sub-song.
int32_t | openmpt_module_get_restart_row (openmpt_module *mod, int32_t subsong)
| Get the restart row of the specified sub-song.
int | openmpt_module_set_repeat_count (openmpt_module *mod, int32_t repeat_count)
| Set Repeat Count.
int32_t | openmpt_module_get_repeat_count (openmpt_module *mod)
| Get Repeat Count.
double | openmpt_module_get_duration_seconds (openmpt_module *mod)
| approximate song duration
double | openmpt_module_get_time_at_position (openmpt_module *mod, int32_t order, int32_t row)
| Get approximate playback time in seconds at given position.
double | openmpt_module_set_position_seconds (openmpt_module *mod, double seconds)
| Set approximate current song position.
double | openmpt_module_get_position_seconds (openmpt_module *mod)
| Get current song position.
double | openmpt_module_set_position_order_row (openmpt_module *mod, int32_t order, int32_t row)
| Set approximate current song position.
int | openmpt_module_get_render_param (openmpt_module *mod, int param, int32_t *value)
| Get render parameter.
int | openmpt_module_set_render_param (openmpt_module *mod, int param, int32_t value)
| Set render parameter.
size_t | openmpt_module_read_mono (openmpt_module *mod, int32_t samplerate, size_t count, int16_t *mono)
| Render audio data.
size_t | openmpt_module_read_stereo (openmpt_module *mod, int32_t samplerate, size_t count, int16_t *left, int16_t *right)
| Render audio data.
size_t | openmpt_module_read_quad (openmpt_module *mod, int32_t samplerate, size_t count, int16_t *left, int16_t *right, int16_t *rear_left, int16_t *rear_right)
| Render audio data.
size_t | openmpt_module_read_float_mono (openmpt_module *mod, int32_t samplerate, size_t count, float *mono)
| Render audio data.
size_t | openmpt_module_read_float_stereo (openmpt_module *mod, int32_t samplerate, size_t count, float *left, float *right)
| Render audio data.
size_t | openmpt_module_read_float_quad (openmpt_module *mod, int32_t samplerate, size_t count, float *left, float *right, float *rear_left, float *rear_right)
| Render audio data.
size_t | openmpt_module_read_interleaved_stereo (openmpt_module *mod, int32_t samplerate, size_t count, int16_t *interleaved_stereo)
| Render audio data.
size_t | openmpt_module_read_interleaved_quad (openmpt_module *mod, int32_t samplerate, size_t count, int16_t *interleaved_quad)
| Render audio data.
size_t | openmpt_module_read_interleaved_float_stereo (openmpt_module *mod, int32_t samplerate, size_t count, float *interleaved_stereo)
| Render audio data.
size_t | openmpt_module_read_interleaved_float_quad (openmpt_module *mod, int32_t samplerate, size_t count, float *interleaved_quad)
| Render audio data.
const char * | openmpt_module_get_metadata_keys (openmpt_module *mod)
| Get the list of supported metadata item keys.
const char * | openmpt_module_get_metadata (openmpt_module *mod, const char *key)
| Get a metadata item value.
double | openmpt_module_get_current_estimated_bpm (openmpt_module *mod)
int32_t | openmpt_module_get_current_speed (openmpt_module *mod)
| Get the current speed.
int32_t | openmpt_module_get_current_tempo (openmpt_module *mod)
| Get the current tempo.
double | openmpt_module_get_current_tempo2 (openmpt_module *mod)
| Get the current tempo.
int32_t | openmpt_module_get_current_sequence (openmpt_module *mod)
| Get the current sequence.
int32_t | openmpt_module_get_current_order (openmpt_module *mod)
| Get the current order.
int32_t | openmpt_module_get_current_pattern (openmpt_module *mod)
| Get the current pattern.
int32_t | openmpt_module_get_current_row (openmpt_module *mod)
| Get the current row.
int32_t | openmpt_module_get_current_playing_channels (openmpt_module *mod)
| Get the current amount of playing channels.
float | openmpt_module_get_current_channel_vu_mono (openmpt_module *mod, int32_t channel)
| Get an approximate indication of the channel volume.
float | openmpt_module_get_current_channel_vu_left (openmpt_module *mod, int32_t channel)
| Get an approximate indication of the channel volume on the front-left speaker.
float | openmpt_module_get_current_channel_vu_right (openmpt_module *mod, int32_t channel)
| Get an approximate indication of the channel volume on the front-right speaker.
float | openmpt_module_get_current_channel_vu_rear_left (openmpt_module *mod, int32_t channel)
| Get an approximate indication of the channel volume on the rear-left speaker.
float | openmpt_module_get_current_channel_vu_rear_right (openmpt_module *mod, int32_t channel)
| Get an approximate indication of the channel volume on the rear-right speaker.
int32_t | openmpt_module_get_num_subsongs (openmpt_module *mod)
| Get the number of sub-songs.
int32_t | openmpt_module_get_num_channels (openmpt_module *mod)
| Get the number of pattern channels.
int32_t | openmpt_module_get_num_orders (openmpt_module *mod)
| Get the number of orders.
int32_t | openmpt_module_get_num_patterns (openmpt_module *mod)
| Get the number of patterns.
int32_t | openmpt_module_get_num_instruments (openmpt_module *mod)
| Get the number of instruments.
int32_t | openmpt_module_get_num_samples (openmpt_module *mod)
| Get the number of samples.
const char * | openmpt_module_get_subsong_name (openmpt_module *mod, int32_t index)
| Get a sub-song name.
const char * | openmpt_module_get_channel_name (openmpt_module *mod, int32_t index)
| Get a channel name.
const char * | openmpt_module_get_order_name (openmpt_module *mod, int32_t index)
| Get an order name.
const char * | openmpt_module_get_pattern_name (openmpt_module *mod, int32_t index)
| Get a pattern name.
const char * | openmpt_module_get_instrument_name (openmpt_module *mod, int32_t index)
| Get an instrument name.
const char * | openmpt_module_get_sample_name (openmpt_module *mod, int32_t index)
| Get a sample name.
int32_t | openmpt_module_get_order_pattern (openmpt_module *mod, int32_t order)
| Get pattern at order position.
int | openmpt_module_is_order_skip_entry (openmpt_module *mod, int32_t order)
| Check if specified order is a skip ("+++") item.
int | openmpt_module_is_pattern_skip_item (openmpt_module *mod, int32_t pattern)
| Check if specified pattern index is a skip ("+++") item.
int | openmpt_module_is_order_stop_entry (openmpt_module *mod, int32_t order)
| Check if specified order is a stop ("---") item.
int | openmpt_module_is_pattern_stop_item (openmpt_module *mod, int32_t pattern)
| Check if specified pattern index is a stop ("---") item.
int32_t | openmpt_module_get_pattern_num_rows (openmpt_module *mod, int32_t pattern)
| Get the number of rows in a pattern.
int32_t | openmpt_module_get_pattern_rows_per_beat (openmpt_module *mod, int32_t pattern)
| Get the rows per beat of a pattern.
int32_t | openmpt_module_get_pattern_rows_per_measure (openmpt_module *mod, int32_t pattern)
| Get the rows per measure of a pattern.
uint8_t | openmpt_module_get_pattern_row_channel_command (openmpt_module *mod, int32_t pattern, int32_t row, int32_t channel, int command)
| Get raw pattern content.
const char * | openmpt_module_format_pattern_row_channel_command (openmpt_module *mod, int32_t pattern, int32_t row, int32_t channel, int command)
| Get formatted (human-readable) pattern content.
const char * | openmpt_module_highlight_pattern_row_channel_command (openmpt_module *mod, int32_t pattern, int32_t row, int32_t channel, int command)
| Get highlighting information for formatted pattern content.
const char * | openmpt_module_format_pattern_row_channel (openmpt_module *mod, int32_t pattern, int32_t row, int32_t channel, size_t width, int pad)
| Get formatted (human-readable) pattern content.
const char * | openmpt_module_highlight_pattern_row_channel (openmpt_module *mod, int32_t pattern, int32_t row, int32_t channel, size_t width, int pad)
| Get highlighting information for formatted pattern content.
const char * | openmpt_module_get_ctls (openmpt_module *mod)
| Retrieve supported ctl keys.
const char * | openmpt_module_ctl_get (openmpt_module *mod, const char *ctl)
| Get current ctl value.
int | openmpt_module_ctl_get_boolean (openmpt_module *mod, const char *ctl)
| Get current ctl boolean value.
int64_t | openmpt_module_ctl_get_integer (openmpt_module *mod, const char *ctl)
| Get current ctl integer value.
double | openmpt_module_ctl_get_floatingpoint (openmpt_module *mod, const char *ctl)
| Get current ctl floatingpoint value.
const char * | openmpt_module_ctl_get_text (openmpt_module *mod, const char *ctl)
| Get current ctl string value.
int | openmpt_module_ctl_set (openmpt_module *mod, const char *ctl, const char *value)
| Set ctl value.
int | openmpt_module_ctl_set_boolean (openmpt_module *mod, const char *ctl, int value)
| Set ctl boolean value.
int | openmpt_module_ctl_set_integer (openmpt_module *mod, const char *ctl, int64_t value)
| Set ctl integer value.
int | openmpt_module_ctl_set_floatingpoint (openmpt_module *mod, const char *ctl, double value)
| Set ctl floatingpoint value.
int | openmpt_module_ctl_set_text (openmpt_module *mod, const char *ctl, const char *value)
| Set ctl string value.
static size_t | openmpt_stream_buffer_read_func (void *stream, void *dst, size_t bytes)
static int | openmpt_stream_buffer_seek_func (void *stream, int64_t offset, int whence)
static int64_t | openmpt_stream_buffer_tell_func (void *stream)
static void | openmpt_stream_buffer_init (openmpt_stream_buffer *buffer, const void *file_data, int64_t file_size)
static openmpt_stream_callbacks | openmpt_stream_get_buffer_callbacks (void)
| Provide openmpt_stream_callbacks for in-memoy buffers.
static size_t | openmpt_stream_buffer_read_func2 (void *stream, void *dst, size_t bytes)
static int | openmpt_stream_buffer_seek_func2 (void *stream, int64_t offset, int whence)
static int64_t | openmpt_stream_buffer_tell_func2 (void *stream)
static void | openmpt_stream_buffer_init2 (openmpt_stream_buffer2 *buffer, const void *file_data, int64_t file_size)
static openmpt_stream_callbacks | openmpt_stream_get_buffer_callbacks2 (void)
| Provide openmpt_stream_callbacks for in-memoy buffers.
static size_t | openmpt_stream_fd_read_func (void *stream, void *dst, size_t bytes)
static openmpt_stream_callbacks | openmpt_stream_get_fd_callbacks (void)
| Provide openmpt_stream_callbacks for standard POSIX file descriptors.
static size_t | openmpt_stream_file_read_func (void *stream, void *dst, size_t bytes)
static int | openmpt_stream_file_seek_func (void *stream, int64_t offset, int whence)
static int64_t | openmpt_stream_file_tell_func (void *stream)
static openmpt_stream_callbacks | openmpt_stream_get_file_callbacks (void)
| Provide openmpt_stream_callbacks for standard C FILE objects.
static openmpt_stream_callbacks | openmpt_stream_get_file_callbacks2 (void)
| Provide openmpt_stream_callbacks for standard C FILE objects.
static size_t | openmpt_stream_file_mingw_read_func (void *stream, void *dst, size_t bytes)
static int | openmpt_stream_file_mingw_seek_func (void *stream, int64_t offset, int whence)
static int64_t | openmpt_stream_file_mingw_tell_func (void *stream)
static openmpt_stream_callbacks | openmpt_stream_get_file_mingw_callbacks (void)
| Provide openmpt_stream_callbacks for standard C FILE objects.
static size_t | openmpt_stream_file_msvcrt_read_func (void *stream, void *dst, size_t bytes)
static int | openmpt_stream_file_msvcrt_seek_func (void *stream, int64_t offset, int whence)
static int64_t | openmpt_stream_file_msvcrt_tell_func (void *stream)
static openmpt_stream_callbacks | openmpt_stream_get_file_msvcrt_callbacks (void)
| Provide openmpt_stream_callbacks for standard C FILE objects.
static size_t | openmpt_stream_file_posix_read_func (void *stream, void *dst, size_t bytes)
static int | openmpt_stream_file_posix_seek_func (void *stream, int64_t offset, int whence)
static int64_t | openmpt_stream_file_posix_tell_func (void *stream)
static openmpt_stream_callbacks | openmpt_stream_get_file_posix_callbacks (void)
| Provide openmpt_stream_callbacks for standard C FILE objects.
static size_t | openmpt_stream_file_posix_lfs64_read_func (void *stream, void *dst, size_t bytes)
static int | openmpt_stream_file_posix_lfs64_seek_func (void *stream, int64_t offset, int whence)
static int64_t | openmpt_stream_file_posix_lfs64_tell_func (void *stream)
static openmpt_stream_callbacks | openmpt_stream_get_file_posix_lfs64_callbacks (void)
| Provide openmpt_stream_callbacks for standard C FILE objects.

## Detailed Description

## Macro Definition Documentation

## ◆ LIBOPENMPT_STREAM_CALLBACKS_BUFFER

#define LIBOPENMPT_STREAM_CALLBACKS_BUFFER

Defined if libopenmpt/libopenmpt_stream_callbacks_buffer.h exists.

Remarks
  Use the following to check for availability:
  #include <libopenmpt/libopenmpt.h>
  #if defined(LIBOPENMPT_STREAM_CALLBACKS_BUFFER)
  #include <libopenmpt/libopenmpt_stream_callbacks_buffer.h>
  #endif
  libopenmpt.h
  libopenmpt_stream_callbacks_buffer.h

## ◆ LIBOPENMPT_STREAM_CALLBACKS_FD

#define LIBOPENMPT_STREAM_CALLBACKS_FD

Defined if libopenmpt/libopenmpt_stream_callbacks_fd.h exists.

Since
  0.3.0

Remarks
  Use the following to check for availability:
  #include <libopenmpt/libopenmpt.h>
  #if defined(LIBOPENMPT_STREAM_CALLBACKS_FD) || ((OPENMPT_API_VERSION_MAJOR == 0) && ((OPENMPT_API_VERSION_MINOR == 2) || (OPENMPT_API_VERSION_MINOR == 1)))
  #include <libopenmpt/libopenmpt_stream_callbacks_fd.h>
  #endif
  libopenmpt_stream_callbacks_fd.h

## ◆ LIBOPENMPT_STREAM_CALLBACKS_FILE

#define LIBOPENMPT_STREAM_CALLBACKS_FILE

Defined if libopenmpt/libopenmpt_stream_callbacks_file.h exists.

Since
  0.3.0

Remarks
  Use the following to check for availability:
  #include <libopenmpt/libopenmpt.h>
  #if defined(LIBOPENMPT_STREAM_CALLBACKS_FILE) || ((OPENMPT_API_VERSION_MAJOR == 0) && ((OPENMPT_API_VERSION_MINOR == 2) || (OPENMPT_API_VERSION_MINOR == 1)))
  #include <libopenmpt/libopenmpt_stream_callbacks_file.h>
  #endif
  libopenmpt_stream_callbacks_file.h

## ◆ LIBOPENMPT_STREAM_CALLBACKS_FILE_MINGW

#define LIBOPENMPT_STREAM_CALLBACKS_FILE_MINGW

Defined if libopenmpt/libopenmpt_stream_callbacks_file_mingw.h exists.

Since
  0.7.0

Remarks
  This macro does not determine if the interfaces required to use libopenmpt/libopenmpt_stream_callbacks_file_posix_lfs64.h are available. It is the libopenmpt user's responsibility to check for availability of the _off64_t, _ftelli64(), and _fseeki64(). Use the following to check for availability:
  #include <libopenmpt/libopenmpt.h>
  #if defined(LIBOPENMPT_STREAM_CALLBACKS_FILE_MINGW)
  #include <libopenmpt/libopenmpt_stream_callbacks_file_mingw.h>
  #endif
  libopenmpt_stream_callbacks_file_mingw.h

## ◆ LIBOPENMPT_STREAM_CALLBACKS_FILE_MSVCRT

#define LIBOPENMPT_STREAM_CALLBACKS_FILE_MSVCRT

Defined if libopenmpt/libopenmpt_stream_callbacks_file_msvcrt.h exists.

Since
  0.7.0

Remarks
  This macro does not determine if the interfaces required to use libopenmpt/libopenmpt_stream_callbacks_file_posix_lfs64.h are available. It is the libopenmpt user's responsibility to check for availability of the __int64, _ftelli64(), and _fseeki64(). Use the following to check for availability:
  #include <libopenmpt/libopenmpt.h>
  #if defined(LIBOPENMPT_STREAM_CALLBACKS_FILE_MSVCRT)
  #include <libopenmpt/libopenmpt_stream_callbacks_file_msvcrt.h>
  #endif
  libopenmpt_stream_callbacks_file_msvcrt.h

## ◆ LIBOPENMPT_STREAM_CALLBACKS_FILE_POSIX

#define LIBOPENMPT_STREAM_CALLBACKS_FILE_POSIX

Defined if libopenmpt/libopenmpt_stream_callbacks_file_posix.h exists.

Since
  0.7.0

Remarks
  This macro does not determine if the interfaces required to use libopenmpt/libopenmpt_stream_callbacks_file_posix_lfs64.h are available. It is the libopenmpt user's responsibility to check for availability of the _off_t, ftello(), and fseeko(). Use the following to check for availability:
  #include <libopenmpt/libopenmpt.h>
  #if defined(LIBOPENMPT_STREAM_CALLBACKS_FILE_MINGW)
  #include <libopenmpt/libopenmpt_stream_callbacks_file_mingw.h>
  #endif

## ◆ LIBOPENMPT_STREAM_CALLBACKS_FILE_POSIX_LFS64

#define LIBOPENMPT_STREAM_CALLBACKS_FILE_POSIX_LFS64

Defined if libopenmpt/libopenmpt_stream_callbacks_file_posix_lfs64.h exists.

Since
  0.7.0

Remarks
  This macro does not determine if the interfaces required to use libopenmpt/libopenmpt_stream_callbacks_file_posix_lfs64.h are available. It is the libopenmpt user's responsibility to check for availability of the off64_t, ftello64(), and fseeko64(). Use the following to check for availability:
  #include <libopenmpt/libopenmpt.h>
  #if defined(LIBOPENMPT_STREAM_CALLBACKS_FILE_POSIX_LFS64)
  #include <libopenmpt/libopenmpt_stream_callbacks_file_posix_lfs64.h>
  #endif
  libopenmpt_stream_callbacks_file_posix_lfs64.h

## ◆ OPENMPT_ERROR_ARGUMENT_NULL_POINTER

#define OPENMPT_ERROR_ARGUMENT_NULL_POINTER ( OPENMPT_ERROR_BASE + 103 )

NULL pointer argument.

Since
  0.3.0

## ◆ OPENMPT_ERROR_BASE

#define OPENMPT_ERROR_BASE 256

Lowest value libopenmpt will use for any of its own error codes.

Since
  0.3.0

## ◆ OPENMPT_ERROR_DOMAIN

#define OPENMPT_ERROR_DOMAIN ( OPENMPT_ERROR_BASE + 41 )

Value domain error.

Since
  0.3.0

## ◆ OPENMPT_ERROR_EXCEPTION

#define OPENMPT_ERROR_EXCEPTION ( OPENMPT_ERROR_BASE + 11 )

Unknown internal C++ exception.

Since
  0.3.0

## ◆ OPENMPT_ERROR_FUNC_RESULT_DEFAULT

#define OPENMPT_ERROR_FUNC_RESULT_DEFAULT ( OPENMPT_ERROR_FUNC_RESULT_LOG | OPENMPT_ERROR_FUNC_RESULT_STORE )

Log and store the error.

Since
  0.3.0

## ◆ OPENMPT_ERROR_FUNC_RESULT_LOG

#define OPENMPT_ERROR_FUNC_RESULT_LOG ( 1 << 0 )

Log the error.

Since
  0.3.0

## ◆ OPENMPT_ERROR_FUNC_RESULT_NONE

#define OPENMPT_ERROR_FUNC_RESULT_NONE 0

Do not log or store the error.

Since
  0.3.0

## ◆ OPENMPT_ERROR_FUNC_RESULT_STORE

#define OPENMPT_ERROR_FUNC_RESULT_STORE ( 1 << 1 )

Store the error.

Since
  0.3.0

## ◆ OPENMPT_ERROR_GENERAL

#define OPENMPT_ERROR_GENERAL ( OPENMPT_ERROR_BASE + 101 )

General libopenmpt error.

Since
  0.3.0

## ◆ OPENMPT_ERROR_INVALID_ARGUMENT

#define OPENMPT_ERROR_INVALID_ARGUMENT ( OPENMPT_ERROR_BASE + 44 )

Invalid argument.

Since
  0.3.0

## ◆ OPENMPT_ERROR_INVALID_MODULE_POINTER

#define OPENMPT_ERROR_INVALID_MODULE_POINTER ( OPENMPT_ERROR_BASE + 102 )

openmpt_module * is invalid.

Since
  0.3.0

## ◆ OPENMPT_ERROR_LENGTH

#define OPENMPT_ERROR_LENGTH ( OPENMPT_ERROR_BASE + 42 )

Maximum supported size exceeded.

Since
  0.3.0

## ◆ OPENMPT_ERROR_LOGIC

#define OPENMPT_ERROR_LOGIC ( OPENMPT_ERROR_BASE + 40 )

Logic error.

Since
  0.3.0

## ◆ OPENMPT_ERROR_OK

#define OPENMPT_ERROR_OK 0

No error.

Since
  0.3.0

## ◆ OPENMPT_ERROR_OUT_OF_MEMORY

#define OPENMPT_ERROR_OUT_OF_MEMORY ( OPENMPT_ERROR_BASE + 21 )

Out of memory.

Since
  0.3.0

## ◆ OPENMPT_ERROR_OUT_OF_RANGE

#define OPENMPT_ERROR_OUT_OF_RANGE ( OPENMPT_ERROR_BASE + 43 )

Argument out of range.

Since
  0.3.0

## ◆ OPENMPT_ERROR_OVERFLOW

#define OPENMPT_ERROR_OVERFLOW ( OPENMPT_ERROR_BASE + 32 )

Arithmetic overflow.

Since
  0.3.0

## ◆ OPENMPT_ERROR_RANGE

#define OPENMPT_ERROR_RANGE ( OPENMPT_ERROR_BASE + 31 )

Range error.

Since
  0.3.0

## ◆ OPENMPT_ERROR_RUNTIME

#define OPENMPT_ERROR_RUNTIME ( OPENMPT_ERROR_BASE + 30 )

Runtime error.

Since
  0.3.0

## ◆ OPENMPT_ERROR_UNDERFLOW

#define OPENMPT_ERROR_UNDERFLOW ( OPENMPT_ERROR_BASE + 33 )

Arithmetic underflow.

Since
  0.3.0

## ◆ OPENMPT_ERROR_UNKNOWN

#define OPENMPT_ERROR_UNKNOWN ( OPENMPT_ERROR_BASE + 1 )

Unknown internal error.

Since
  0.3.0

## ◆ OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS

#define OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS 0x2ull

Probe for module-specific container formats in openmpt_probe_file_header() or openmpt_probe_file_header_without_filesize().

Since
  0.3.0

## ◆ OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT

#define OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT ( OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES | OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS )

Probe for the default set of formats in openmpt_probe_file_header() or openmpt_probe_file_header_without_filesize().

Since
  0.3.0

## ◆ OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES

#define OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES 0x1ull

Probe for module formats in openmpt_probe_file_header() or openmpt_probe_file_header_without_filesize().

Since
  0.3.0

## ◆ OPENMPT_PROBE_FILE_HEADER_FLAGS_NONE

#define OPENMPT_PROBE_FILE_HEADER_FLAGS_NONE 0x0ull

Probe for no formats in openmpt_probe_file_header() or openmpt_probe_file_header_without_filesize().

Since
  0.3.0

## ◆ OPENMPT_PROBE_FILE_HEADER_RESULT_ERROR

#define OPENMPT_PROBE_FILE_HEADER_RESULT_ERROR (-255)

Possible return values for openmpt_probe_file_header() and openmpt_probe_file_header_without_filesize(): An internal error occurred.

Since
  0.3.0

## ◆ OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE

#define OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE 0

Possible return values for openmpt_probe_file_header() and openmpt_probe_file_header_without_filesize(): The file is not supported by libopenmpt.

Since
  0.3.0

## ◆ OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESS

#define OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESS 1

Possible return values for openmpt_probe_file_header() and openmpt_probe_file_header_without_filesize(): The file will most likely be supported by libopenmpt.

Since
  0.3.0

## ◆ OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATA

#define OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATA (-1)

Possible return values for openmpt_probe_file_header() and openmpt_probe_file_header_without_filesize(): An answer could not be determined with the amount of data provided.

Since
  0.3.0

## ◆ openmpt_stream_buffer_init_prefix_only

#define openmpt_stream_buffer_init_prefix_only | ( |  | buffer_,
|  |  | prefix_data_,
|  |  | prefix_size_,
|  |  | file_size_ )

Value:
do { \
openmpt_stream_buffer_init( (buffer_), (prefix_data_), (file_size_) ); \
(buffer_)->prefix_size = (prefix_size_); \
} while(0)

## ◆ openmpt_stream_buffer_overflowed

#define openmpt_stream_buffer_overflowed | ( |  | buffer_ | ) |

Value:
( (buffer_)->overflow )

## ◆ OPENMPT_STREAM_SEEK_CUR

#define OPENMPT_STREAM_SEEK_CUR 1

Seek to the given offset relative to the current position in the file.

## ◆ OPENMPT_STREAM_SEEK_END

#define OPENMPT_STREAM_SEEK_END 2

Seek to the given offset relative to the end of the file.

## ◆ OPENMPT_STREAM_SEEK_SET

#define OPENMPT_STREAM_SEEK_SET 0

Seek to the given offset relative to the beginning of the file.

## ◆ OPENMPT_STRING_BUILD

#define OPENMPT_STRING_BUILD LIBOPENMPT_DEPRECATED_STRING( "build" )

Return information about the current build (e.g. the build date or compiler used) from openmpt_get_string().

Deprecated
  Please use "build" directly.

## ◆ OPENMPT_STRING_CONTACT

#define OPENMPT_STRING_CONTACT LIBOPENMPT_DEPRECATED_STRING( "contact" )

Return contact information about libopenmpt from openmpt_get_string().

Deprecated
  Please use "contact" directly.

## ◆ OPENMPT_STRING_CORE_VERSION

#define OPENMPT_STRING_CORE_VERSION LIBOPENMPT_DEPRECATED_STRING( "core_version" )

Return a verbose OpenMPT core version string from openmpt_get_string().

Deprecated
  Please use "core_version" directly.

## ◆ OPENMPT_STRING_CREDITS

#define OPENMPT_STRING_CREDITS LIBOPENMPT_DEPRECATED_STRING( "credits" )

Return all contributors from openmpt_get_string().

Deprecated
  Please use "credits" directly.

## ◆ OPENMPT_STRING_LIBRARY_FEATURES

#define OPENMPT_STRING_LIBRARY_FEATURES LIBOPENMPT_DEPRECATED_STRING( "library_features" )

Return a verbose library features string from openmpt_get_string().

Deprecated
  Please use "library_features" directly.

## ◆ OPENMPT_STRING_LIBRARY_VERSION

#define OPENMPT_STRING_LIBRARY_VERSION LIBOPENMPT_DEPRECATED_STRING( "library_version" )

Return a verbose library version string from openmpt_get_string().

Deprecated
  Please use "library_version" directly.

## ◆ OPENMPT_STRING_LICENSE

#define OPENMPT_STRING_LICENSE LIBOPENMPT_DEPRECATED_STRING( "license" )

Return the libopenmpt license from openmpt_get_string().

Deprecated
  Please use "license" directly.

## Typedef Documentation

## ◆ openmpt_error_func

typedef int(* openmpt_error_func) (int error, void *user)

Error function.

Parameters

  error | Error code.
  user | User context that was passed to openmpt_module_create2(), openmpt_module_create_from_memory2() or openmpt_could_open_probability2().

Returns
  Mask of OPENMPT_ERROR_FUNC_RESULT_LOG and OPENMPT_ERROR_FUNC_RESULT_STORE.

Return values

  OPENMPT_ERROR_FUNC_RESULT_NONE | Do not log or store the error.
  OPENMPT_ERROR_FUNC_RESULT_LOG | Log the error.
  OPENMPT_ERROR_FUNC_RESULT_STORE | Store the error.
  OPENMPT_ERROR_FUNC_RESULT_DEFAULT | Log and store the error.

See also
  OPENMPT_ERROR_FUNC_RESULT_NONE
  OPENMPT_ERROR_FUNC_RESULT_LOG
  OPENMPT_ERROR_FUNC_RESULT_STORE
  OPENMPT_ERROR_FUNC_RESULT_DEFAULT
  openmpt_error_func_default
  openmpt_error_func_log
  openmpt_error_func_store
  openmpt_error_func_ignore
  openmpt_error_func_errno

Since
  0.3.0

## ◆ openmpt_log_func

typedef void(* openmpt_log_func) (const char *message, void *user)

Logging function.

Parameters

  message | UTF-8 encoded log message.
  user | User context that was passed to openmpt_module_create2(), openmpt_module_create_from_memory2() or openmpt_could_open_probability2().

## ◆ openmpt_module

typedef struct openmpt_module openmpt_module

Opaque type representing a libopenmpt module.

## ◆ openmpt_module_initial_ctl

typedef struct openmpt_module_initial_ctl openmpt_module_initial_ctl

## ◆ openmpt_stream_buffer

typedef struct openmpt_stream_buffer openmpt_stream_buffer

## ◆ openmpt_stream_buffer2

typedef struct openmpt_stream_buffer2 openmpt_stream_buffer2

## ◆ openmpt_stream_callbacks

typedef struct openmpt_stream_callbacks openmpt_stream_callbacks

Stream callbacks.

Stream callbacks used by libopenmpt for stream operations.

See also
  openmpt_stream_get_file_callbacks
  openmpt_stream_get_fd_callbacks
  openmpt_stream_get_buffer_callbacks

## ◆ openmpt_stream_read_func

typedef size_t(* openmpt_stream_read_func) (void *stream, void *dst, size_t bytes)

Read bytes from stream.

Read bytes data from stream to dst.

Parameters

  stream | Stream to read data from
  dst | Target where to copy data.
  bytes | Number of bytes to read.

Returns
  Number of bytes actually read and written to dst.

Return values

  0 | End of stream or error.

Remarks
  Short reads are allowed as long as they return at least 1 byte if EOF is not reached.

## ◆ openmpt_stream_seek_func

typedef int(* openmpt_stream_seek_func) (void *stream, int64_t offset, int whence)

Seek stream position.

Seek to stream position offset at whence.

Parameters

  stream | Stream to operate on.
  offset | Offset to seek to.
  whence | OPENMPT_STREAM_SEEK_SET, OPENMPT_STREAM_SEEK_CUR, OPENMPT_STREAM_SEEK_END. See C89 documentation.

Returns
  Returns 0 on success.

Return values

  0 | Success.
  -1 | Failure. Position does not get updated.

Remarks
  libopenmpt will not try to seek beyond the file size, thus it is not important whether you allow for virtual positioning after the file end, or return an error in that case. The position equal to the file size needs to be seekable to.

## ◆ openmpt_stream_tell_func

typedef int64_t(* openmpt_stream_tell_func) (void *stream)

Tell stream position.

Tell position of stream.

Parameters

  stream | Stream to operate on.

Returns
  Current position in stream.

Return values

  -1 | Failure.

## Function Documentation

## ◆ openmpt_could_open_probability()

double openmpt_could_open_probability | ( | openmpt_stream_callbacks | stream_callbacks,
|  | void * | stream,
|  | double | effort,
|  | openmpt_log_func | logfunc,
|  | void * | user )

Roughly scan the input stream to find out whether libopenmpt might be able to open it.

Parameters

  stream_callbacks | Input stream callback operations.
  stream | Input stream to scan.
  effort | Effort to make when validating stream. Effort 0.0 does not even look at stream at all and effort 1.0 completely loads the file from stream. A lower effort requires less data to be loaded but only gives a rough estimate answer. Use an effort of 0.25 to only verify the header data of the module file.
  logfunc | Logging function where warning and errors are written. May be NULL.
  user | Logging function user context. Used to pass any user-defined data associated with this module to the logging function.

Returns
  Probability between 0.0 and 1.0.

Remarks
  openmpt_could_open_probability() can return any value between 0.0 and 1.0. Only 0.0 and 1.0 are definitive answers, all values in between are just estimates. In general, any return value >0.0 means that you should try loading the file, and any value below 1.0 means that loading may fail. If you want a threshold above which you can be reasonably sure that libopenmpt will be able to load the file, use >=0.5. If you see the need for a threshold below which you could reasonably outright reject a file, use <0.25 (Note: Such a threshold for rejecting on the lower end is not recommended, but may be required for better integration into some other framework's probe scoring.).
  openmpt_could_open_probability() expects the complete file data to be eventually available to it, even if it is asked to just parse the header. Verification will be unreliable (both false positives and false negatives), if you pretend that the file is just some few bytes of initial data threshold in size. In order to really just access the first bytes of a file, check in your callback functions whether data or seeking is requested beyond your initial data threshold, and in that case, return an error. openmpt_could_open_probability() will treat this as any other I/O error and return 0.0. You must not expect the correct result in this case. You instead must remember that it asked for more data than you currently want to provide to it and treat this situation as if openmpt_could_open_probability() returned 0.5.

See also
  File I/O
  openmpt_stream_callbacks

Deprecated
  Please use openmpt_could_open_probability2().

Since
  0.3.0

## ◆ openmpt_could_open_probability2()

double openmpt_could_open_probability2 | ( | openmpt_stream_callbacks | stream_callbacks,
|  | void * | stream,
|  | double | effort,
|  | openmpt_log_func | logfunc,
|  | void * | loguser,
|  | openmpt_error_func | errfunc,
|  | void * | erruser,
|  | int * | error,
|  | const char ** | error_message )

Roughly scan the input stream to find out whether libopenmpt might be able to open it.

Parameters

  stream_callbacks | Input stream callback operations.
  stream | Input stream to scan.
  effort | Effort to make when validating stream. Effort 0.0 does not even look at stream at all and effort 1.0 completely loads the file from stream. A lower effort requires less data to be loaded but only gives a rough estimate answer. Use an effort of 0.25 to only verify the header data of the module file.
  logfunc | Logging function where warning and errors are written. May be NULL.
  loguser | Logging function user context. Used to pass any user-defined data associated with this module to the logging function.
  errfunc | Error function to define error behaviour. May be NULL.
  erruser | Error function user context. Used to pass any user-defined data associated with this module to the logging function.
  error | Pointer to an integer where an error may get stored. May be NULL.
  error_message | Pointer to a string pointer where an error message may get stored. May be NULL.

Returns
  Probability between 0.0 and 1.0.

Remarks
  openmpt_probe_file_header() or openmpt_probe_file_header_without_filesize() provide a simpler and faster interface that fits almost all use cases better. It is recommended to use openmpt_probe_file_header() or openmpt_probe_file_header_without_filesize() instead of openmpt_could_open_probability().
  openmpt_could_open_probability2() can return any value between 0.0 and 1.0. Only 0.0 and 1.0 are definitive answers, all values in between are just estimates. In general, any return value >0.0 means that you should try loading the file, and any value below 1.0 means that loading may fail. If you want a threshold above which you can be reasonably sure that libopenmpt will be able to load the file, use >=0.5. If you see the need for a threshold below which you could reasonably outright reject a file, use <0.25 (Note: Such a threshold for rejecting on the lower end is not recommended, but may be required for better integration into some other framework's probe scoring.).
  openmpt_could_open_probability2() expects the complete file data to be eventually available to it, even if it is asked to just parse the header. Verification will be unreliable (both false positives and false negatives), if you pretend that the file is just some few bytes of initial data threshold in size. In order to really just access the first bytes of a file, check in your callback functions whether data or seeking is requested beyond your initial data threshold, and in that case, return an error. openmpt_could_open_probability2() will treat this as any other I/O error and return 0.0. You must not expect the correct result in this case. You instead must remember that it asked for more data than you currently want to provide to it and treat this situation as if openmpt_could_open_probability2() returned 0.5.
  /*
  * libopenmpt_example_c_probe.c
  * ----------------------------
  * Purpose: libopenmpt C API probing example
  * Notes : (currently none)
  * Authors: OpenMPT Devs
  * The OpenMPT source code is released under the BSD license. Read LICENSE for more details.
  */
  /*
  * Usage: libopenmpt_example_c_probe SOMEMODULE ...
  * Returns 0 on successful probing for all files.
  * Returns 1 on failed probing for 1 or more files.
  * Returns 2 on error.
  */
  #define LIBOPENMPT_EXAMPLE_PROBE_RESULT_BINARY 1
  #define LIBOPENMPT_EXAMPLE_PROBE_RESULT_FLOAT 2
  #define LIBOPENMPT_EXAMPLE_PROBE_RESULT LIBOPENMPT_EXAMPLE_PROBE_RESULT_BINARY
  #if defined( __MINGW32__ ) && !defined( __MINGW64__ )
  #include <sys/types.h>
  #endif
  #include <memory.h>
  #include <stdint.h>
  #include <stdio.h>
  #include <stdlib.h>
  #include <string.h>
  #include <libopenmpt/libopenmpt.h>
  #include <libopenmpt/libopenmpt_stream_callbacks_file.h>
  #if defined( __DJGPP__ )
  #include <crt0.h>
  #endif /* __DJGPP__ */
  static void libopenmpt_example_logfunc( const char * message, void * userdata ) {
  (void)userdata;
  if ( message ) {
  fprintf( stderr, "%s\n", message );
  }
  }
  #if ( defined( _WIN32 ) || defined( WIN32 ) ) && ( defined( _UNICODE ) || defined( UNICODE ) )
  static int probe_file( const wchar_t * filename ) {
  #else
  static int probe_file( const char * filename ) {
  #endif
  int result = 0;
  int mod_err = OPENMPT_ERROR_OK;
  FILE * file = NULL;
  #if ( LIBOPENMPT_EXAMPLE_PROBE_RESULT == LIBOPENMPT_EXAMPLE_PROBE_RESULT_BINARY )
  int result_binary = 0;
  int probe_file_header_result = OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE;
  const char * probe_file_header_result_str = NULL;
  #endif
  #if ( LIBOPENMPT_EXAMPLE_PROBE_RESULT == LIBOPENMPT_EXAMPLE_PROBE_RESULT_FLOAT )
  double probability = 0.0;
  #endif
  #if ( defined( _WIN32 ) || defined( WIN32 ) ) && ( defined( _UNICODE ) || defined( UNICODE ) )
  if ( wcslen( filename ) == 0 ) {
  fprintf( stderr, "Error: %s\n", "Wrong invocation. Use 'libopenmpt_example_c_probe SOMEMODULE'." );
  goto fail;
  }
  #else
  if ( strlen( filename ) == 0 ) {
  fprintf( stderr, "Error: %s\n", "Wrong invocation. Use 'libopenmpt_example_c_probe SOMEMODULE'." );
  goto fail;
  }
  #endif
  #if ( defined( _WIN32 ) || defined( WIN32 ) ) && ( defined( _UNICODE ) || defined( UNICODE ) )
  file = _wfopen( filename, L"rb" );
  #else
  file = fopen( filename, "rb" );
  #endif
  if ( !file ) {
  fprintf( stderr, "Error: %s\n", "fopen() failed." );
  goto fail;
  }
  #if ( LIBOPENMPT_EXAMPLE_PROBE_RESULT == LIBOPENMPT_EXAMPLE_PROBE_RESULT_BINARY )
  probe_file_header_result = openmpt_probe_file_header_from_stream( OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT, openmpt_stream_get_file_callbacks2(), file, &libopenmpt_example_logfunc, NULL, &openmpt_error_func_default, NULL, &mod_err, NULL );
  probe_file_header_result_str = NULL;
  switch ( probe_file_header_result ) {
  case OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESS:
  probe_file_header_result_str = "Success ";
  result_binary = 1;
  break;
  case OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE:
  probe_file_header_result_str = "Failure ";
  result_binary = 0;
  break;
  case OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATA:
  probe_file_header_result_str = "WantMoreData";
  result_binary = 0;
  break;
  case OPENMPT_PROBE_FILE_HEADER_RESULT_ERROR:
  result_binary = 0;
  (void)result_binary;
  fprintf( stderr, "Error: %s\n", "openmpt_probe_file_header() failed." );
  goto fail;
  break;
  default:
  result_binary = 0;
  (void)result_binary;
  fprintf( stderr, "Error: %s\n", "openmpt_probe_file_header() failed." );
  goto fail;
  break;
  }
  #if ( defined( _WIN32 ) || defined( WIN32 ) ) && ( defined( _UNICODE ) || defined( UNICODE ) )
  fprintf( stdout, "%s - %ls\n", probe_file_header_result_str, filename );
  #else
  fprintf( stdout, "%s - %s\n", probe_file_header_result_str, filename );
  #endif
  if ( result_binary ) {
  result = 0;
  } else {
  result = 1;
  }
  #elif ( LIBOPENMPT_EXAMPLE_PROBE_RESULT == LIBOPENMPT_EXAMPLE_PROBE_RESULT_FLOAT )
  probability = openmpt_could_open_probability2( openmpt_stream_get_file_callbacks2(), file, 0.25, &libopenmpt_example_logfunc, NULL, &openmpt_error_func_default, NULL, &mod_err, NULL );
  #if ( defined( _WIN32 ) || defined( WIN32 ) ) && ( defined( _UNICODE ) || defined( UNICODE ) )
  fprintf( stdout, "%s: %f - %ls\n", "Result", probability, filename );
  #else
  fprintf( stdout, "%s: %f - %s\n", "Result", probability, filename );
  #endif
  if ( probability >= 0.5 ) {
  result = 0;
  } else {
  result = 1;
  }
  #else
  #error "LIBOPENMPT_EXAMPLE_PROBE_RESULT is wrong"
  #endif
  goto cleanup;
  fail:
  result = 2;
  cleanup:
  if ( file ) {
  fclose( file );
  file = 0;
  }
  return result;
  }
  #if defined( __DJGPP__ )
  /* clang-format off */
  int _crt0_startup_flags = 0
  | _CRT0_FLAG_NONMOVE_SBRK /* force interrupt compatible allocation */
  | _CRT0_DISABLE_SBRK_ADDRESS_WRAP /* force NT compatible allocation */
  | _CRT0_FLAG_LOCK_MEMORY /* lock all code and data at program startup */
  | 0;
  /* clang-format on */
  #endif /* __DJGPP__ */
  #if ( defined( _WIN32 ) || defined( WIN32 ) ) && ( defined( _UNICODE ) || defined( UNICODE ) )
  #if defined( __clang__ ) && !defined( _MSC_VER )
  int wmain( int argc, wchar_t * argv[] );
  #endif
  int wmain( int argc, wchar_t * argv[] ) {
  #else
  int main( int argc, char * argv[] ) {
  #endif
  #if defined( __DJGPP__ )
  /* clang-format off */
  _crt0_startup_flags &= ~_CRT0_FLAG_LOCK_MEMORY; /* disable automatic locking for all further memory allocations */
  /* clang-format on */
  #endif /* __DJGPP__ */
  int global_result = 0;
  if ( argc <= 1 ) {
  fprintf( stderr, "Error: %s\n", "Wrong invocation. Use 'libopenmpt_example_c_probe SOMEMODULE ...'." );
  goto fail;
  }
  for ( int i = 1; i < argc; ++i ) {
  int result = probe_file( argv[i] );
  if ( result > global_result ) {
  global_result = result;
  }
  }
  goto cleanup;
  fail:
  global_result = 2;
  cleanup:
  return global_result;
  }
  OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATA
  #define OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATA
  Definition libopenmpt.h:576
  openmpt_stream_get_file_callbacks2
  static openmpt_stream_callbacks openmpt_stream_get_file_callbacks2(void)
  Provide openmpt_stream_callbacks for standard C FILE objects.
  Definition libopenmpt_stream_callbacks_file.h:132
  OPENMPT_ERROR_OK
  #define OPENMPT_ERROR_OK
  Definition libopenmpt.h:344
  openmpt_could_open_probability2
  double openmpt_could_open_probability2(openmpt_stream_callbacks stream_callbacks, void *stream, double effort, openmpt_log_func logfunc, void *loguser, openmpt_error_func errfunc, void *erruser, int *error, const char **error_message)
  Roughly scan the input stream to find out whether libopenmpt might be able to open it.
  openmpt_probe_file_header_from_stream
  int openmpt_probe_file_header_from_stream(uint64_t flags, openmpt_stream_callbacks stream_callbacks, void *stream, openmpt_log_func logfunc, void *loguser, openmpt_error_func errfunc, void *erruser, int *error, const char **error_message)
  Probe the provided bytes from the beginning of a file for supported file format headers to find out w...
  OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESS
  #define OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESS
  Definition libopenmpt.h:572
  openmpt_error_func_default
  int openmpt_error_func_default(int error, void *user)
  Default error function.
  OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT
  #define OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT
  Definition libopenmpt.h:567
  OPENMPT_PROBE_FILE_HEADER_RESULT_ERROR
  #define OPENMPT_PROBE_FILE_HEADER_RESULT_ERROR
  Definition libopenmpt.h:578
  OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE
  #define OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE
  Definition libopenmpt.h:574
  openmpt::probe_file_header_result
  probe_file_header_result
  Possible return values for openmpt::probe_file_header().
  Definition libopenmpt.hpp:300

See also
  File I/O
  openmpt_stream_callbacks
  openmpt_probe_file_header
  openmpt_probe_file_header_without_filesize

Since
  0.3.0

## ◆ openmpt_could_open_propability()

double openmpt_could_open_propability | ( | openmpt_stream_callbacks | stream_callbacks,
|  | void * | stream,
|  | double | effort,
|  | openmpt_log_func | logfunc,
|  | void * | user )

Roughly scan the input stream to find out whether libopenmpt might be able to open it.

Parameters

  stream_callbacks | Input stream callback operations.
  stream | Input stream to scan.
  effort | Effort to make when validating stream. Effort 0.0 does not even look at stream at all and effort 1.0 completely loads the file from stream. A lower effort requires less data to be loaded but only gives a rough estimate answer. Use an effort of 0.25 to only verify the header data of the module file.
  logfunc | Logging function where warning and errors are written. May be NULL.
  user | Logging function user context. Used to pass any user-defined data associated with this module to the logging function.

Returns
  Probability between 0.0 and 1.0.

Remarks
  openmpt_could_open_probability() can return any value between 0.0 and 1.0. Only 0.0 and 1.0 are definitive answers, all values in between are just estimates. In general, any return value >0.0 means that you should try loading the file, and any value below 1.0 means that loading may fail. If you want a threshold above which you can be reasonably sure that libopenmpt will be able to load the file, use >=0.5. If you see the need for a threshold below which you could reasonably outright reject a file, use <0.25 (Note: Such a threshold for rejecting on the lower end is not recommended, but may be required for better integration into some other framework's probe scoring.).
  openmpt_could_open_probability() expects the complete file data to be eventually available to it, even if it is asked to just parse the header. Verification will be unreliable (both false positives and false negatives), if you pretend that the file is just some few bytes of initial data threshold in size. In order to really just access the first bytes of a file, check in your callback functions whether data or seeking is requested beyond your initial data threshold, and in that case, return an error. openmpt_could_open_probability() will treat this as any other I/O error and return 0.0. You must not expect the correct result in this case. You instead must remember that it asked for more data than you currently want to provide to it and treat this situation as if openmpt_could_open_probability() returned 0.5.

See also
  File I/O
  openmpt_stream_callbacks

Deprecated
  Please use openmpt_could_open_probability2().

## ◆ openmpt_error_func_default()

int openmpt_error_func_default | ( | int | error,
|  | void * | user )

Default error function.

Causes all errors to be logged and stored.

Parameters

  error | Error code.
  user | Ignored.

Return values

  OPENMPT_ERROR_FUNC_RESULT_DEFAULT | Always.

Since
  0.3.0

## ◆ openmpt_error_func_errno()

int openmpt_error_func_errno | ( | int | error,
|  | void * | user )

Errno error function.

Causes all errors to be stored in the pointer passed in as user.

Parameters

  error | Error code.
  user | Pointer to an int as generated by openmpt_error_func_errno_userdata.

Return values

  OPENMPT_ERROR_FUNC_RESULT_NONE | user is not NULL.
  OPENMPT_ERROR_FUNC_RESULT_DEFAULT | user is NULL.

Since
  0.3.0

## ◆ openmpt_error_func_errno_userdata()

void * openmpt_error_func_errno_userdata | ( | int * | error | ) |

User pointer for openmpt_error_func_errno.

Provides a suitable user pointer argument for openmpt_error_func_errno.

Parameters

  error | Pointer to an integer value to be used as output by openmpt_error_func_errno.

Return values

  (void*)error. |

Since
  0.3.0

## ◆ openmpt_error_func_ignore()

int openmpt_error_func_ignore | ( | int | error,
|  | void * | user )

Ignore error function.

Causes all errors to be neither logged nor stored.

Parameters

  error | Error code.
  user | Ignored.

Return values

  OPENMPT_ERROR_FUNC_RESULT_NONE | Always.

Since
  0.3.0

## ◆ openmpt_error_func_log()

int openmpt_error_func_log | ( | int | error,
|  | void * | user )

Log error function.

Causes all errors to be logged.

Parameters

  error | Error code.
  user | Ignored.

Return values

  OPENMPT_ERROR_FUNC_RESULT_LOG | Always.

Since
  0.3.0

## ◆ openmpt_error_func_store()

int openmpt_error_func_store | ( | int | error,
|  | void * | user )

Store error function.

Causes all errors to be stored.

Parameters

  error | Error code.
  user | Ignored.

Return values

  OPENMPT_ERROR_FUNC_RESULT_STORE | Always.

Since
  0.3.0

## ◆ openmpt_error_is_transient()

int openmpt_error_is_transient | ( | int | error | ) |

Check whether the error is transient.

Checks whether an error code represents a transient error which may not occur again in a later try if for example memory has been freed up after an out-of-memory error.

Parameters

  error | Error code.

Return values

  0 | Error is not transient.
  1 | Error is transient.

See also
  OPENMPT_ERROR_OUT_OF_MEMORY

Since
  0.3.0

## ◆ openmpt_error_string()

const char * openmpt_error_string | ( | int | error | ) |

Convert error code to text.

Converts an error code into a text string describing the error.

Parameters

  error | Error code.

Returns
  Allocated string describing the error.

Return values

  NULL | Not enough memory to allocate the string.

Since
  0.3.0

## ◆ openmpt_free_string()

void openmpt_free_string | ( | const char * | str | ) |

Free a string returned by libopenmpt.

Frees any string that got returned by libopenmpt.

## ◆ openmpt_get_core_version()

uint32_t openmpt_get_core_version | ( | void |  | ) |

Get the core version number.

Return the OpenMPT core version number.

Returns
  The value represents (majormajor << 24 + major << 16 + minor << 8 + minorminor).

## ◆ openmpt_get_library_version()

uint32_t openmpt_get_library_version | ( | void |  | ) |

Get the libopenmpt version number.

Returns the libopenmpt version number.

Returns
  The value represents (major << 24 + minor << 16 + patch << 0).

Remarks
  libopenmpt < 0.3.0-pre used the following scheme: (major << 24 + minor << 16 + revision).

## ◆ openmpt_get_string()

const char * openmpt_get_string | ( | const char * | key | ) |

Get library related metadata.

Parameters

  key | Key to query. Possible keys are: "library_version": verbose library version string "library_version_is_release": "1" if the version is an officially released version "library_features": verbose library features string "core_version": verbose OpenMPT core version string "source_url": original source code URL "source_date": original source code date "source_revision": original source code revision "source_is_modified": "1" if the original source has been modified "source_has_mixed_revisions": "1" if the original source has been compiled from different various revision "source_is_package": "1" if the original source has been obtained from a source pacakge instead of source code version control "build": information about the current build (e.g. the build date or compiler used) "build_compiler": information about the compiler used to build libopenmpt "credits": all contributors "contact": contact information about libopenmpt "license": the libopenmpt license "url": libopenmpt website URL "support_forum_url": libopenmpt support and discussions forum URL "bugtracker_url": libopenmpt bug and issue tracker URL

Returns
  A (possibly multi-line) string containing the queried information. If no information is available, the string is empty.

## ◆ openmpt_get_supported_extensions()

const char * openmpt_get_supported_extensions | ( | void |  | ) |

Get a list of supported file extensions.

Returns
  The semicolon-separated list of extensions supported by this libopenmpt build. The extensions are returned lower-case without a leading dot.

## ◆ openmpt_is_extension_supported()

int openmpt_is_extension_supported | ( | const char * | extension | ) |

Query whether a file extension is supported.

Parameters

  extension | file extension to query without a leading dot. The case is ignored.

Returns
  1 if the extension is supported by libopenmpt, 0 otherwise.

## ◆ openmpt_log_func_default()

void openmpt_log_func_default | ( | const char * | message,
|  | void * | user )

Default logging function.

Default logging function that logs anything to stderr.

## ◆ openmpt_log_func_silent()

void openmpt_log_func_silent | ( | const char * | message,
|  | void * | user )

Silent logging function.

Silent logging function that throws any log message away.

## ◆ openmpt_module_create()

openmpt_module * openmpt_module_create | ( | openmpt_stream_callbacks | stream_callbacks,
|  | void * | stream,
|  | openmpt_log_func | logfunc,
|  | void * | loguser,
|  | const openmpt_module_initial_ctl * | ctls )

Construct an openmpt_module.

Parameters

  stream_callbacks | Input stream callback operations.
  stream | Input stream to load the module from.
  logfunc | Logging function where warning and errors are written. The logging function may be called throughout the lifetime of openmpt_module. May be NULL.
  loguser | User-defined data associated with this module. This value will be passed to the logging callback function (logfunc)
  ctls | An array of initial ctl and value pairs stored in openmpt_module_initial_ctl, terminated by a pair of NULL and NULL. See openmpt_module_get_ctls and openmpt_module_ctl_set.

Returns
  A pointer to the constructed openmpt_module, or NULL on failure.

Remarks
  The input data can be discarded after an openmpt_module has been constructed successfully.

See also
  openmpt_stream_callbacks
  File I/O

Deprecated
  Please use openmpt_module_create2().

## ◆ openmpt_module_create2()

openmpt_module * openmpt_module_create2 | ( | openmpt_stream_callbacks | stream_callbacks,
|  | void * | stream,
|  | openmpt_log_func | logfunc,
|  | void * | loguser,
|  | openmpt_error_func | errfunc,
|  | void * | erruser,
|  | int * | error,
|  | const char ** | error_message,
|  | const openmpt_module_initial_ctl * | ctls )

Construct an openmpt_module.

Parameters

  stream_callbacks | Input stream callback operations.
  stream | Input stream to load the module from.
  logfunc | Logging function where warning and errors are written. The logging function may be called throughout the lifetime of openmpt_module. May be NULL.
  loguser | User-defined data associated with this module. This value will be passed to the logging callback function (logfunc)
  errfunc | Error function to define error behaviour. May be NULL.
  erruser | Error function user context. Used to pass any user-defined data associated with this module to the logging function.
  error | Pointer to an integer where an error may get stored. May be NULL.
  error_message | Pointer to a string pointer where an error message may get stored. May be NULL.
  ctls | An array of initial ctl and value pairs stored in openmpt_module_initial_ctl, terminated by a pair of NULL and NULL. See openmpt_module_get_ctls and openmpt_module_ctl_set.

Returns
  A pointer to the constructed openmpt_module, or NULL on failure.

Remarks
  The input data can be discarded after an openmpt_module has been constructed successfully.

See also
  openmpt_stream_callbacks
  File I/O

Since
  0.3.0

## ◆ openmpt_module_create_from_memory()

openmpt_module * openmpt_module_create_from_memory | ( | const void * | filedata,
|  | size_t | filesize,
|  | openmpt_log_func | logfunc,
|  | void * | loguser,
|  | const openmpt_module_initial_ctl * | ctls )

Construct an openmpt_module.

Parameters

  filedata | Data to load the module from.
  filesize | Amount of data available.
  logfunc | Logging function where warning and errors are written. The logging function may be called throughout the lifetime of openmpt_module.
  loguser | User-defined data associated with this module. This value will be passed to the logging callback function (logfunc)
  ctls | An array of initial ctl and value pairs stored in openmpt_module_initial_ctl, terminated by a pair of NULL and NULL. See openmpt_module_get_ctls and openmpt_module_ctl_set.

Returns
  A pointer to the constructed openmpt_module, or NULL on failure.

Remarks
  The input data can be discarded after an openmpt_module has been constructed successfully.

See also
  File I/O

Deprecated
  Please use openmpt_module_create_from_memory2().

## ◆ openmpt_module_create_from_memory2()

openmpt_module * openmpt_module_create_from_memory2 | ( | const void * | filedata,
|  | size_t | filesize,
|  | openmpt_log_func | logfunc,
|  | void * | loguser,
|  | openmpt_error_func | errfunc,
|  | void * | erruser,
|  | int * | error,
|  | const char ** | error_message,
|  | const openmpt_module_initial_ctl * | ctls )

Construct an openmpt_module.

Parameters

  filedata | Data to load the module from.
  filesize | Amount of data available.
  logfunc | Logging function where warning and errors are written. The logging function may be called throughout the lifetime of openmpt_module.
  loguser | User-defined data associated with this module. This value will be passed to the logging callback function (logfunc)
  errfunc | Error function to define error behaviour. May be NULL.
  erruser | Error function user context. Used to pass any user-defined data associated with this module to the logging function.
  error | Pointer to an integer where an error may get stored. May be NULL.
  error_message | Pointer to a string pointer where an error message may get stored. May be NULL.
  ctls | An array of initial ctl and value pairs stored in openmpt_module_initial_ctl, terminated by a pair of NULL and NULL. See openmpt_module_get_ctls and openmpt_module_ctl_set.

Returns
  A pointer to the constructed openmpt_module, or NULL on failure.

Remarks
  The input data can be discarded after an openmpt_module has been constructed successfully.

See also
  File I/O

Since
  0.3.0

## ◆ openmpt_module_ctl_get()

const char * openmpt_module_ctl_get | ( | openmpt_module * | mod,
|  | const char * | ctl )

Get current ctl value.

Parameters

  mod | The module handle to work on.
  ctl | The ctl key whose value should be retrieved.

Returns
  The associated ctl value, or NULL on failure.

See also
  openmpt_module_get_ctls

Deprecated
  Please use openmpt_module_ctl_get_boolean(), openmpt_module_ctl_get_integer(), openmpt_module_ctl_get_floatingpoint(), or openmpt_module_ctl_get_text().

## ◆ openmpt_module_ctl_get_boolean()

int openmpt_module_ctl_get_boolean | ( | openmpt_module * | mod,
|  | const char * | ctl )

Get current ctl boolean value.

Parameters

  mod | The module handle to work on.
  ctl | The ctl key whose value should be retrieved.

Returns
  The associated ctl value, or NULL on failure.

See also
  openmpt_module_get_ctls

Since
  0.5.0

## ◆ openmpt_module_ctl_get_floatingpoint()

double openmpt_module_ctl_get_floatingpoint | ( | openmpt_module * | mod,
|  | const char * | ctl )

Get current ctl floatingpoint value.

Parameters

  mod | The module handle to work on.
  ctl | The ctl key whose value should be retrieved.

Returns
  The associated ctl value, or NULL on failure.

See also
  openmpt_module_get_ctls

Since
  0.5.0

## ◆ openmpt_module_ctl_get_integer()

int64_t openmpt_module_ctl_get_integer | ( | openmpt_module * | mod,
|  | const char * | ctl )

Get current ctl integer value.

Parameters

  mod | The module handle to work on.
  ctl | The ctl key whose value should be retrieved.

Returns
  The associated ctl value, or NULL on failure.

See also
  openmpt_module_get_ctls

Since
  0.5.0

## ◆ openmpt_module_ctl_get_text()

const char * openmpt_module_ctl_get_text | ( | openmpt_module * | mod,
|  | const char * | ctl )

Get current ctl string value.

Parameters

  mod | The module handle to work on.
  ctl | The ctl key whose value should be retrieved.

Returns
  The associated ctl value, or NULL on failure.

See also
  openmpt_module_get_ctls

Since
  0.5.0

## ◆ openmpt_module_ctl_set()

int openmpt_module_ctl_set | ( | openmpt_module * | mod,
|  | const char * | ctl,
|  | const char * | value )

Set ctl value.

Parameters

  mod | The module handle to work on.
  ctl | The ctl key whose value should be set.
  value | The value that should be set.

Returns
  1 if successful, 0 in case the value is not sensible (e.g. negative tempo factor) or the ctl is not recognized.

See also
  openmpt_module_get_ctls

Deprecated
  Please use openmpt_module_ctl_set_boolean(), openmpt_module_ctl_set_integer(), openmpt_module_ctl_set_floatingpoint(), or openmpt_module_ctl_set_text().

## ◆ openmpt_module_ctl_set_boolean()

int openmpt_module_ctl_set_boolean | ( | openmpt_module * | mod,
|  | const char * | ctl,
|  | int | value )

Set ctl boolean value.

Parameters

  mod | The module handle to work on.
  ctl | The ctl key whose value should be set.
  value | The value that should be set.

Returns
  1 if successful, 0 in case the value is not sensible (e.g. negative tempo factor) or the ctl is not recognized.

See also
  openmpt_module_get_ctls

Since
  0.5.0

## ◆ openmpt_module_ctl_set_floatingpoint()

int openmpt_module_ctl_set_floatingpoint | ( | openmpt_module * | mod,
|  | const char * | ctl,
|  | double | value )

Set ctl floatingpoint value.

Parameters

  mod | The module handle to work on.
  ctl | The ctl key whose value should be set.
  value | The value that should be set.

Returns
  1 if successful, 0 in case the value is not sensible (e.g. negative tempo factor) or the ctl is not recognized.

See also
  openmpt_module_get_ctls

Since
  0.5.0

## ◆ openmpt_module_ctl_set_integer()

int openmpt_module_ctl_set_integer | ( | openmpt_module * | mod,
|  | const char * | ctl,
|  | int64_t | value )

Set ctl integer value.

Parameters

  mod | The module handle to work on.
  ctl | The ctl key whose value should be set.
  value | The value that should be set.

Returns
  1 if successful, 0 in case the value is not sensible (e.g. negative tempo factor) or the ctl is not recognized.

See also
  openmpt_module_get_ctls

Since
  0.5.0

## ◆ openmpt_module_ctl_set_text()

int openmpt_module_ctl_set_text | ( | openmpt_module * | mod,
|  | const char * | ctl,
|  | const char * | value )

Set ctl string value.

Parameters

  mod | The module handle to work on.
  ctl | The ctl key whose value should be set.
  value | The value that should be set.

Returns
  1 if successful, 0 in case the value is not sensible (e.g. negative tempo factor) or the ctl is not recognized.

See also
  openmpt_module_get_ctls

Since
  0.5.0

## ◆ openmpt_module_destroy()

void openmpt_module_destroy | ( | openmpt_module * | mod | ) |

Unload a previously created openmpt_module from memory.

Parameters

  mod | The module to unload.

## ◆ openmpt_module_error_clear()

void openmpt_module_error_clear | ( | openmpt_module * | mod | ) |

Clear last error.

Set the error currently stored in an openmpt_module to OPPENMPT_ERROR_OK.

Parameters

  mod | The module handle to work on.

See also
  openmpt_module_error_get_last
  openmpt_module_error_set_last

Since
  0.3.0

## ◆ openmpt_module_error_get_last()

int openmpt_module_error_get_last | ( | openmpt_module * | mod | ) |

Get last error.

Return the error currently stored in an openmpt_module. The stored error is not cleared.

Parameters

  mod | The module handle to work on.

Returns
  The error currently stored.

See also
  openmpt_module_error_get_last_message
  openmpt_module_error_set_last
  openmpt_module_error_clear

Since
  0.3.0

## ◆ openmpt_module_error_get_last_message()

const char * openmpt_module_error_get_last_message | ( | openmpt_module * | mod | ) |

Get last error message.

Return the error message currently stored in an openmpt_module. The stored error is not cleared.

Parameters

  mod | The module handle to work on.

Returns
  The error message currently stored.

See also
  openmpt_module_error_set_last
  openmpt_module_error_clear

Since
  0.3.0

## ◆ openmpt_module_error_set_last()

void openmpt_module_error_set_last | ( | openmpt_module * | mod,
|  | int | error )

Set last error.

Set the error currently stored in an openmpt_module.

Parameters

  mod | The module handle to work on.
  error | Error to be stored.

See also
  openmpt_module_error_get_last
  openmpt_module_error_clear

Since
  0.3.0

## ◆ openmpt_module_format_pattern_row_channel()

const char * openmpt_module_format_pattern_row_channel | ( | openmpt_module * | mod,
|  | int32_t | pattern,
|  | int32_t | row,
|  | int32_t | channel,
|  | size_t | width,
|  | int | pad )

Get formatted (human-readable) pattern content.

Parameters

  mod | The module handle to work on.
  pattern | The pattern whose data should be retrieved.
  row | The row from which the data should be retrieved.
  channel | The channel from which the data should be retrieved.
  width | The maximum number of characters the string should contain. 0 means no limit.
  pad | If true, the string will be resized to the exact length provided in the width parameter.

Returns
  The formatted pattern data at the given pattern position.

See also
  openmpt_module_highlight_pattern_row_channel

## ◆ openmpt_module_format_pattern_row_channel_command()

const char * openmpt_module_format_pattern_row_channel_command | ( | openmpt_module * | mod,
|  | int32_t | pattern,
|  | int32_t | row,
|  | int32_t | channel,
|  | int | command )

Get formatted (human-readable) pattern content.

Parameters

  mod | The module handle to work on.
  pattern | The pattern whose data should be retrieved.
  row | The row from which the data should be retrieved.
  channel | The channel from which the data should be retrieved.
  command | The cell index at which the data should be retrieved.

Returns
  The formatted pattern data at the given pattern position. See Pattern cell indices

See also
  openmpt_module_highlight_pattern_row_channel_command

## ◆ openmpt_module_get_channel_name()

const char * openmpt_module_get_channel_name | ( | openmpt_module * | mod,
|  | int32_t | index )

Get a channel name.

Parameters

  mod | The module handle to work on.
  index | The channel whose name should be retrieved

Returns
  The channel name.

See also
  openmpt_module_get_num_channels

## ◆ openmpt_module_get_ctls()

const char * openmpt_module_get_ctls | ( | openmpt_module * | mod | ) |

Retrieve supported ctl keys.

Parameters

  mod | The module handle to work on.

Returns
  A semicolon-separated list containing all supported ctl keys.

Remarks
  Currently supported ctl values are:
  - load.skip_samples (boolean): Set to "1" to avoid loading samples into memory
  - load.skip_patterns (boolean): Set to "1" to avoid loading patterns into memory
  - load.skip_plugins (boolean): Set to "1" to avoid loading plugins
  - load.skip_subsongs_init (boolean): Set to "1" to avoid pre-initializing sub-songs. Skipping results in faster module loading but slower seeking.
  - seek.sync_samples (boolean): Set to "0" to not sync sample playback when using openmpt_module_set_position_seconds or openmpt_module_set_position_order_row.
  - subsong (integer): The current subsong. Setting it has identical semantics as openmpt_module_select_subsong(), getting it returns the currently selected subsong.
  - play.at_end (text): Chooses the behaviour when the end of song is reached. The song end is considered to be reached after the number of reptitions set by openmpt_module_set_repeat_count was played, so if the song is set to repeat infinitely, its end is never considered to be reached.
    - "fadeout": Fades the module out for a short while. Subsequent reads after the fadeout will return 0 rendered frames.
    - "continue": Returns 0 rendered frames when the song end is reached. Subsequent reads will continue playing from the loop start (if the song is not programmed to loop, playback resumed from the song start).
    - "stop": Returns 0 rendered frames when the song end is reached. Subsequent reads will return 0 rendered frames.
  - play.tempo_factor (floatingpoint): Set a floating point tempo factor. "1.0" is the default tempo.
  - play.pitch_factor (floatingpoint): Set a floating point pitch factor. "1.0" is the default pitch.
  - render.resampler.emulate_amiga (boolean): Set to "1" to enable the Amiga resampler for Amiga modules. This emulates the sound characteristics of the Paula chip and overrides the selected interpolation filter. Non-Amiga module formats are not affected by this setting.
  - render.resampler.emulate_amiga_type (string): Configures the filter type to use for the Amiga resampler. Supported values are:
    - "auto": Filter type is chosen by the library and might change. This is the default.
    - "a500": Amiga A500 filter.
    - "a1200": Amiga A1200 filter.
    - "unfiltered": BLEP synthesis without model-specific filters. The LED filter is ignored by this setting. This filter mode is considered to be experimental and might change in the future.
  - render.opl.volume_factor (floatingpoint): Set volume factor applied to synthesized OPL sounds, relative to the default OPL volume.
  - dither (integer): Set the dither algorithm that is used for the 16 bit versions of openmpt_module_read. Supported values are:
    - 0: No dithering.
    - 1: Default mode. Chosen by OpenMPT code, might change.
    - 2: Rectangular, 0.5 bit depth, no noise shaping (original ModPlug Tracker).
    - 3: Rectangular, 1 bit depth, simple 1st order noise shaping

## ◆ openmpt_module_get_current_channel_vu_left()

float openmpt_module_get_current_channel_vu_left | ( | openmpt_module * | mod,
|  | int32_t | channel )

Get an approximate indication of the channel volume on the front-left speaker.

Parameters

  mod | The module handle to work on.
  channel | The channel whose volume should be retrieved.

Returns
  The approximate channel volume.

Remarks
  The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account.

## ◆ openmpt_module_get_current_channel_vu_mono()

float openmpt_module_get_current_channel_vu_mono | ( | openmpt_module * | mod,
|  | int32_t | channel )

Get an approximate indication of the channel volume.

Parameters

  mod | The module handle to work on.
  channel | The channel whose volume should be retrieved.

Returns
  The approximate channel volume.

Remarks
  The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account.

## ◆ openmpt_module_get_current_channel_vu_rear_left()

float openmpt_module_get_current_channel_vu_rear_left | ( | openmpt_module * | mod,
|  | int32_t | channel )

Get an approximate indication of the channel volume on the rear-left speaker.

Parameters

  mod | The module handle to work on.
  channel | The channel whose volume should be retrieved.

Returns
  The approximate channel volume.

Remarks
  The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account.

## ◆ openmpt_module_get_current_channel_vu_rear_right()

float openmpt_module_get_current_channel_vu_rear_right | ( | openmpt_module * | mod,
|  | int32_t | channel )

Get an approximate indication of the channel volume on the rear-right speaker.

Parameters

  mod | The module handle to work on.
  channel | The channel whose volume should be retrieved.

Returns
  The approximate channel volume.

Remarks
  The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account.

## ◆ openmpt_module_get_current_channel_vu_right()

float openmpt_module_get_current_channel_vu_right | ( | openmpt_module * | mod,
|  | int32_t | channel )

Get an approximate indication of the channel volume on the front-right speaker.

Parameters

  mod | The module handle to work on.
  channel | The channel whose volume should be retrieved.

Returns
  The approximate channel volume.

Remarks
  The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account.

## ◆ openmpt_module_get_current_estimated_bpm()

double openmpt_module_get_current_estimated_bpm | ( | openmpt_module * | mod | ) |

Get the current estimated beats per minute (BPM).

Parameters

  mod | The module handle to work on.

Remarks
  Many module formats lack time signature metadata. It is common that this estimate is off by a factor of two, but other multipliers are also possible.
  Due to the nature of how module tempo works, the estimate may change slightly after switching libopenmpt's output to a different sample rate.

Returns
  The current estimated BPM.

## ◆ openmpt_module_get_current_order()

int32_t openmpt_module_get_current_order | ( | openmpt_module * | mod | ) |

Get the current order.

Parameters

  mod | The module handle to work on.

Returns
  The current order at which the module is being played back.

## ◆ openmpt_module_get_current_pattern()

int32_t openmpt_module_get_current_pattern | ( | openmpt_module * | mod | ) |

Get the current pattern.

Parameters

  mod | The module handle to work on.

Returns
  The current pattern that is being played.

## ◆ openmpt_module_get_current_playing_channels()

int32_t openmpt_module_get_current_playing_channels | ( | openmpt_module * | mod | ) |

Get the current amount of playing channels.

Parameters

  mod | The module handle to work on.

Returns
  The amount of sample channels that are currently being rendered.

## ◆ openmpt_module_get_current_row()

int32_t openmpt_module_get_current_row | ( | openmpt_module * | mod | ) |

Get the current row.

Parameters

  mod | The module handle to work on.

Returns
  The current row at which the current pattern is being played.

## ◆ openmpt_module_get_current_sequence()

int32_t openmpt_module_get_current_sequence | ( | openmpt_module * | mod | ) |

Get the current sequence.

Parameters

  mod | The module handle to work on.

Returns
  The sequence (order list) in which the currently playing subsong is located.

Remarks
  There is no corresponding setter function. The current sequence is adjusted automatically by selecting a different subsong.
  One sequence can contain multiple subsongs. Most module formats only support a single sequence, hence the return value of this function will often be 0 even in modules that contain multiple subsongs.

Since
  0.9.0

## ◆ openmpt_module_get_current_speed()

int32_t openmpt_module_get_current_speed | ( | openmpt_module * | mod | ) |

Get the current speed.

Parameters

  mod | The module handle to work on.

Returns
  The current speed in ticks per row.

## ◆ openmpt_module_get_current_tempo()

int32_t openmpt_module_get_current_tempo | ( | openmpt_module * | mod | ) |

Get the current tempo.

Parameters

  mod | The module handle to work on.

Returns
  The current tempo in tracker units. The exact meaning of this value depends on the tempo mode being used.

Deprecated
  Please use openmpt_module_get_current_tempo2().

## ◆ openmpt_module_get_current_tempo2()

double openmpt_module_get_current_tempo2 | ( | openmpt_module * | mod | ) |

Get the current tempo.

Parameters

  mod | The module handle to work on.

Returns
  The current tempo in tracker units. The exact meaning of this value depends on the tempo mode being used.

Since
  0.7.0

## ◆ openmpt_module_get_duration_seconds()

double openmpt_module_get_duration_seconds | ( | openmpt_module * | mod | ) |

approximate song duration

Parameters

  mod | The module handle to work on.

Returns
  Approximate duration of current sub-song in seconds.

Remarks
  The function may return infinity if the pattern data is too complex to evaluate.

## ◆ openmpt_module_get_instrument_name()

const char * openmpt_module_get_instrument_name | ( | openmpt_module * | mod,
|  | int32_t | index )

Get an instrument name.

Parameters

  mod | The module handle to work on.
  index | The instrument whose name should be retrieved

Returns
  The instrument name.

See also
  openmpt_module_get_num_instruments

## ◆ openmpt_module_get_metadata()

const char * openmpt_module_get_metadata | ( | openmpt_module * | mod,
|  | const char * | key )

Get a metadata item value.

Parameters

  mod | The module handle to work on.
  key | Metadata item key to query. Use openmpt_module_get_metadata_keys to check for available keys. Possible keys are: type: Module format extension (e.g. it) or another similar identifier for modules formats that typically do not use a file extension type_long: Format name associated with the module format (e.g. Impulse Tracker) originaltype: Module format extension (e.g. it) of the original module in case the actual type is a converted format (e.g. mo3 or gdm) originaltype_long: Format name associated with the module format (e.g. Impulse Tracker) of the original module in case the actual type is a converted format (e.g. mo3 or gdm) container: Container format the module file is embedded in, if any (e.g. umx) container_long: Full container name if the module is embedded in a container (e.g. Unreal Music) tracker: Tracker that was (most likely) used to save the module file, if known artist: Author of the module title: Module title date: Date the module was last saved, in ISO-8601 format. message: Song message. If the song message is empty or the module format does not support song messages, a list of instrument and sample names is returned instead. message_raw: Song message. If the song message is empty or the module format does not support song messages, an empty string is returned. warnings: A list of warnings that were generated while loading the module.

Returns
  The associated value for key.

See also
  openmpt_module_get_metadata_keys

## ◆ openmpt_module_get_metadata_keys()

const char * openmpt_module_get_metadata_keys | ( | openmpt_module * | mod | ) |

Get the list of supported metadata item keys.

Parameters

  mod | The module handle to work on.

Returns
  Metadata item keys supported by openmpt_module_get_metadata, as a semicolon-separated list.

See also
  openmpt_module_get_metadata

## ◆ openmpt_module_get_num_channels()

int32_t openmpt_module_get_num_channels | ( | openmpt_module * | mod | ) |

Get the number of pattern channels.

Parameters

  mod | The module handle to work on.

Returns
  The number of pattern channels in the module. Not all channels do necessarily contain data.

Remarks
  The number of pattern channels is completely independent of the number of output channels. libopenmpt can render modules in mono, stereo or quad surround, but the choice of which of the three modes to use must not be made based on the return value of this function, which may be any positive integer amount. Only use this function for informational purposes.

## ◆ openmpt_module_get_num_instruments()

int32_t openmpt_module_get_num_instruments | ( | openmpt_module * | mod | ) |

Get the number of instruments.

Parameters

  mod | The module handle to work on.

Returns
  The number of instrument slots in the module. Instruments are a layer on top of samples, and are not supported by all module formats.

## ◆ openmpt_module_get_num_orders()

int32_t openmpt_module_get_num_orders | ( | openmpt_module * | mod | ) |

Get the number of orders.

Parameters

  mod | The module handle to work on.

Returns
  The number of orders in the current sequence of the module.

## ◆ openmpt_module_get_num_patterns()

int32_t openmpt_module_get_num_patterns | ( | openmpt_module * | mod | ) |

Get the number of patterns.

Parameters

  mod | The module handle to work on.

Returns
  The number of distinct patterns in the module.

## ◆ openmpt_module_get_num_samples()

int32_t openmpt_module_get_num_samples | ( | openmpt_module * | mod | ) |

Get the number of samples.

Parameters

  mod | The module handle to work on.

Returns
  The number of sample slots in the module.

## ◆ openmpt_module_get_num_subsongs()

int32_t openmpt_module_get_num_subsongs | ( | openmpt_module * | mod | ) |

Get the number of sub-songs.

Parameters

  mod | The module handle to work on.

Returns
  The number of sub-songs in the module. This includes any "hidden" songs (songs that share the same sequence, but start at different order indices) and "normal" sub-songs or "sequences" (if the format supports them).

See also
  openmpt_module_get_subsong_name, openmpt_module_select_subsong, openmpt_module_get_selected_subsong

## ◆ openmpt_module_get_order_name()

const char * openmpt_module_get_order_name | ( | openmpt_module * | mod,
|  | int32_t | index )

Get an order name.

Parameters

  mod | The module handle to work on.
  index | The order whose name should be retrieved

Returns
  The order name.

See also
  openmpt_module_get_num_orders

## ◆ openmpt_module_get_order_pattern()

int32_t openmpt_module_get_order_pattern | ( | openmpt_module * | mod,
|  | int32_t | order )

Get pattern at order position.

Parameters

  mod | The module handle to work on.
  order | The order item whose pattern index should be retrieved.

Returns
  The pattern index found at the given order position of the current sequence.

## ◆ openmpt_module_get_pattern_name()

const char * openmpt_module_get_pattern_name | ( | openmpt_module * | mod,
|  | int32_t | index )

Get a pattern name.

Parameters

  mod | The module handle to work on.
  index | The pattern whose name should be retrieved

Returns
  The pattern name.

See also
  openmpt_module_get_num_patterns

## ◆ openmpt_module_get_pattern_num_rows()

int32_t openmpt_module_get_pattern_num_rows | ( | openmpt_module * | mod,
|  | int32_t | pattern )

Get the number of rows in a pattern.

Parameters

  mod | The module handle to work on.
  pattern | The pattern whose row count should be retrieved.

Returns
  The number of rows in the given pattern. If the pattern does not exist, 0 is returned.

## ◆ openmpt_module_get_pattern_row_channel_command()

uint8_t openmpt_module_get_pattern_row_channel_command | ( | openmpt_module * | mod,
|  | int32_t | pattern,
|  | int32_t | row,
|  | int32_t | channel,
|  | int | command )

Get raw pattern content.

Parameters

  mod | The module handle to work on.
  pattern | The pattern whose data should be retrieved.
  row | The row from which the data should be retrieved.
  channel | The channel from which the data should be retrieved.
  command | The cell index at which the data should be retrieved. See Pattern cell indices

Returns
  The internal, raw pattern data at the given pattern position.

## ◆ openmpt_module_get_pattern_rows_per_beat()

int32_t openmpt_module_get_pattern_rows_per_beat | ( | openmpt_module * | mod,
|  | int32_t | pattern )

Get the rows per beat of a pattern.

Parameters

  mod | The module handle to work on.
  pattern | The pattern whose time signature should be retrieved.

Returns
  The rows per beat of the given pattern. If the pattern does not exist or the time signature is not defined, 0 is returned.

Remarks
  Many module formats lack time signature metadata. In this case, the returned value may be an incorrect estimation.

Since
  0.8.0

## ◆ openmpt_module_get_pattern_rows_per_measure()

int32_t openmpt_module_get_pattern_rows_per_measure | ( | openmpt_module * | mod,
|  | int32_t | pattern )

Get the rows per measure of a pattern.

Parameters

  mod | The module handle to work on.
  pattern | The pattern whose time signature should be retrieved.

Returns
  The rows per measure of the given pattern. If the pattern does not exist or the time signature is not defined, 0 is returned.

Remarks
  Many module formats lack time signature metadata. In this case, the returned value may be an incorrect estimation.

## ◆ openmpt_module_get_position_seconds()

double openmpt_module_get_position_seconds | ( | openmpt_module * | mod | ) |

Get current song position.

Parameters

  mod | The module handle to work on.

Returns
  Current song position in seconds.

See also
  openmpt_module_set_position_seconds

## ◆ openmpt_module_get_render_param()

int openmpt_module_get_render_param | ( | openmpt_module * | mod,
|  | int | param,
|  | int32_t * | value )

Get render parameter.

Parameters

  mod | The module handle to work on.
  param | Parameter to query. See Render param indices
  value | Pointer to the variable that receives the current value of the parameter.

Returns
  1 on success, 0 on failure (invalid param or value is NULL).

See also
  OPENMPT_MODULE_RENDER_MASTERGAIN_MILLIBEL
  OPENMPT_MODULE_RENDER_STEREOSEPARATION_PERCENT
  OPENMPT_MODULE_RENDER_INTERPOLATIONFILTER_LENGTH
  OPENMPT_MODULE_RENDER_VOLUMERAMPING_STRENGTH
  openmpt_module_set_render_param

## ◆ openmpt_module_get_repeat_count()

int32_t openmpt_module_get_repeat_count | ( | openmpt_module * | mod | ) |

Get Repeat Count.

Parameters

  mod | The module handle to work on.

Returns
  Repeat Count
  - -1: repeat forever
  - 0: play once, repeat zero times (the default)
  - n>0: play once and repeat n times after that

See also
  openmpt_module_set_repeat_count

## ◆ openmpt_module_get_restart_order()

int32_t openmpt_module_get_restart_order | ( | openmpt_module * | mod,
|  | int32_t | subsong )

Get the restart order of the specified sub-song.

Parameters

  mod | The module handle to work on.
  subsong | Index of the sub-song to retrieve the restart position from.

Returns
  The restart order of the specified sub-song. This is the order to which playback returns after the last pattern row of the song has been played. -1 is returned if if sub-song is not in range [0,openmpt_module_get_num_subsongs()[

See also
  openmpt_module_get_restart_row

Since
  0.8.0

## ◆ openmpt_module_get_restart_row()

int32_t openmpt_module_get_restart_row | ( | openmpt_module * | mod,
|  | int32_t | subsong )

Get the restart row of the specified sub-song.

Parameters

  mod | The module handle to work on.
  subsong | Index of the sub-song to retrieve the restart position from.

Returns
  The restart row of the specified sub-song. This is the first played row of the order to which playback returns after the last pattern row of the song has been played. -1 is returned if if sub-song is not in range [0,openmpt_module_get_num_subsongs()[

See also
  openmpt_module_get_restart_order

Since
  0.8.0

## ◆ openmpt_module_get_sample_name()

const char * openmpt_module_get_sample_name | ( | openmpt_module * | mod,
|  | int32_t | index )

Get a sample name.

Parameters

  mod | The module handle to work on.
  index | The sample whose name should be retrieved

Returns
  The sample name.

See also
  openmpt_module_get_num_samples

## ◆ openmpt_module_get_selected_subsong()

int32_t openmpt_module_get_selected_subsong | ( | openmpt_module * | mod | ) |

Get currently selected sub-song from a multi-song module.

Parameters

  mod | The module handle to work on.

Returns
  Currently selected sub-song. -1 for all subsongs consecutively, 0 or greater for the current sub-song index.

See also
  openmpt_module_get_num_subsongs, openmpt_module_select_subsong, openmpt_module_get_subsong_name

Since
  0.3.0

## ◆ openmpt_module_get_subsong_name()

const char * openmpt_module_get_subsong_name | ( | openmpt_module * | mod,
|  | int32_t | index )

Get a sub-song name.

Parameters

  mod | The module handle to work on.
  index | The sub-song whose name should be retrieved

Returns
  The sub-song name.

See also
  openmpt_module_get_num_subsongs, openmpt_module_select_subsong, openmpt_module_get_selected_subsong

## ◆ openmpt_module_get_time_at_position()

double openmpt_module_get_time_at_position | ( | openmpt_module * | mod,
|  | int32_t | order,
|  | int32_t | row )

Get approximate playback time in seconds at given position.

Parameters

  mod | The module handle to work on.
  order | The order position at which the time should be retrieved.
  row | The pattern row number at which the time should be retrieved.

Returns
  Approximate playback time in seconds of current sub-song at the start of the given order and row combination. Negative if the position does not exist, or the pattern data is too complex to evaluate.

Remarks
  If an order / row combination is played multiple times (e.g. due the pattern loops), the first occurence of this position is returned.

Since
  0.8.0

## ◆ openmpt_module_highlight_pattern_row_channel()

const char * openmpt_module_highlight_pattern_row_channel | ( | openmpt_module * | mod,
|  | int32_t | pattern,
|  | int32_t | row,
|  | int32_t | channel,
|  | size_t | width,
|  | int | pad )

Get highlighting information for formatted pattern content.

Parameters

  mod | The module handle to work on.
  pattern | The pattern whose data should be retrieved.
  row | The row from which the data should be retrieved.
  channel | The channel from which the data should be retrieved.
  width | The maximum number of characters the string should contain. 0 means no limit.
  pad | If true, the string will be resized to the exact length provided in the width parameter.

Returns
  The highlighting string for the formatted pattern data as retrieved by openmpt_module_format_pattern_row_channel at the given pattern position.

See also
  openmpt_module_format_pattern_row_channel

## ◆ openmpt_module_highlight_pattern_row_channel_command()

const char * openmpt_module_highlight_pattern_row_channel_command | ( | openmpt_module * | mod,
|  | int32_t | pattern,
|  | int32_t | row,
|  | int32_t | channel,
|  | int | command )

Get highlighting information for formatted pattern content.

Parameters

  mod | The module handle to work on.
  pattern | The pattern whose data should be retrieved.
  row | The row from which the data should be retrieved.
  channel | The channel from which the data should be retrieved.
  command | The cell index at which the data should be retrieved. See Pattern cell indices

Returns
  The highlighting string for the formatted pattern data as retrieved by openmpt_module_get_pattern_row_channel_command at the given pattern position.

Remarks
  The returned string will map each character position of the string returned by openmpt_module_get_pattern_row_channel_command to a highlighting instruction. Possible highlighting characters are:
  - " " : empty/space
  - "." : empty/dot
  - "n" : generic note
  - "m" : special note
  - "i" : generic instrument
  - "u" : generic volume column effect
  - "v" : generic volume column parameter
  - "e" : generic effect column effect
  - "f" : generic effect column parameter

See also
  openmpt_module_get_pattern_row_channel_command

## ◆ openmpt_module_is_order_skip_entry()

int openmpt_module_is_order_skip_entry | ( | openmpt_module * | mod,
|  | int32_t | order )

Check if specified order is a skip ("+++") item.

Parameters

  mod | The module handle to work on.
  order | The order index to check.

Returns
  Returns non-zero value if the pattern index at the given order position represents a skip item. During playback, this item is ignored and playback resumes at the next order list item.

See also
  openmpt_module_is_order_stop_entry, openmpt_module_is_pattern_skip_item

Since
  0.8.0

## ◆ openmpt_module_is_order_stop_entry()

int openmpt_module_is_order_stop_entry | ( | openmpt_module * | mod,
|  | int32_t | order )

Check if specified order is a stop ("---") item.

Parameters

  mod | The module handle to work on.
  order | The order index to check.

Returns
  Returns non-zero value if the pattern index at the given order position represents a stop item. When this item is reached, playback continues at the restart position of the current sub-song.

See also
  openmpt_module_is_order_skip_entry, openmpt_module_is_pattern_stop_item

Since
  0.8.0

## ◆ openmpt_module_is_pattern_skip_item()

int openmpt_module_is_pattern_skip_item | ( | openmpt_module * | mod,
|  | int32_t | pattern )

Check if specified pattern index is a skip ("+++") item.

Parameters

  mod | The module handle to work on.
  pattern | The pattern index to check.

Returns
  Returns non-zero value if the pattern index represents a skip item. During playback, this item is ignored and playback resumes at the next order list item.

See also
  openmpt_module_is_pattern_stop_item, openmpt_module_is_order_skip_entry, openmpt_module_get_order_pattern

Since
  0.8.0

## ◆ openmpt_module_is_pattern_stop_item()

int openmpt_module_is_pattern_stop_item | ( | openmpt_module * | mod,
|  | int32_t | pattern )

Check if specified pattern index is a stop ("---") item.

Parameters

  mod | The module handle to work on.
  pattern | The pattern index to check.

Returns
  Returns non-zero value if the pattern index represents a stop item. When this item is reached, playback continues at the restart position of the current sub-song.

See also
  openmpt_module_is_pattern_skip_item, openmpt_module_is_order_stop_entry, openmpt_module_get_order_pattern

Since
  0.8.0

## ◆ openmpt_module_read_float_mono()

size_t openmpt_module_read_float_mono | ( | openmpt_module * | mod,
|  | int32_t | samplerate,
|  | size_t | count,
|  | float * | mono )

Render audio data.

Parameters

  mod | The module handle to work on.
  samplerate | Sample rate to render output. Should be in [8000,192000], but this is not enforced.
  count | Number of audio frames to render per channel.
  mono | Pointer to a buffer of at least count elements that receives the mono/center output.

Returns
  The number of frames actually rendered.

Return values

  0 | The end of song has been reached.

Remarks
  The output buffers are only written to up to the returned number of elements.
  You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
  Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot.

See also
  Output Format

## ◆ openmpt_module_read_float_quad()

size_t openmpt_module_read_float_quad | ( | openmpt_module * | mod,
|  | int32_t | samplerate,
|  | size_t | count,
|  | float * | left,
|  | float * | right,
|  | float * | rear_left,
|  | float * | rear_right )

Render audio data.

Parameters

  mod | The module handle to work on.
  samplerate | Sample rate to render output. Should be in [8000,192000], but this is not enforced.
  count | Number of audio frames to render per channel.
  left | Pointer to a buffer of at least count elements that receives the left output.
  right | Pointer to a buffer of at least count elements that receives the right output.
  rear_left | Pointer to a buffer of at least count elements that receives the rear left output.
  rear_right | Pointer to a buffer of at least count elements that receives the rear right output.

Returns
  The number of frames actually rendered.

Return values

  0 | The end of song has been reached.

Remarks
  The output buffers are only written to up to the returned number of elements.
  You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
  Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot.

See also
  Output Format

## ◆ openmpt_module_read_float_stereo()

size_t openmpt_module_read_float_stereo | ( | openmpt_module * | mod,
|  | int32_t | samplerate,
|  | size_t | count,
|  | float * | left,
|  | float * | right )

Render audio data.

Parameters

  mod | The module handle to work on.
  samplerate | Sample rate to render output. Should be in [8000,192000], but this is not enforced.
  count | Number of audio frames to render per channel.
  left | Pointer to a buffer of at least count elements that receives the left output.
  right | Pointer to a buffer of at least count elements that receives the right output.

Returns
  The number of frames actually rendered.

Return values

  0 | The end of song has been reached.

Remarks
  The output buffers are only written to up to the returned number of elements.
  You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
  Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot.

See also
  Output Format

## ◆ openmpt_module_read_interleaved_float_quad()

size_t openmpt_module_read_interleaved_float_quad | ( | openmpt_module * | mod,
|  | int32_t | samplerate,
|  | size_t | count,
|  | float * | interleaved_quad )

Render audio data.

Parameters

  mod | The module handle to work on.
  samplerate | Sample rate to render output. Should be in [8000,192000], but this is not enforced.
  count | Number of audio frames to render per channel.
  interleaved_quad | Pointer to a buffer of at least count*4 elements that receives the interleaved quad surround output in the order (L,R,RL,RR).

Returns
  The number of frames actually rendered.

Return values

  0 | The end of song has been reached.

Remarks
  The output buffers are only written to up to the returned number of elements.
  You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
  Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot.

See also
  Output Format

## ◆ openmpt_module_read_interleaved_float_stereo()

size_t openmpt_module_read_interleaved_float_stereo | ( | openmpt_module * | mod,
|  | int32_t | samplerate,
|  | size_t | count,
|  | float * | interleaved_stereo )

Render audio data.

Parameters

  mod | The module handle to work on.
  samplerate | Sample rate to render output. Should be in [8000,192000], but this is not enforced.
  count | Number of audio frames to render per channel.
  interleaved_stereo | Pointer to a buffer of at least count*2 elements that receives the interleaved stereo output in the order (L,R).

Returns
  The number of frames actually rendered.

Return values

  0 | The end of song has been reached.

Remarks
  The output buffers are only written to up to the returned number of elements.
  You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
  Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot.

See also
  Output Format

## ◆ openmpt_module_read_interleaved_quad()

size_t openmpt_module_read_interleaved_quad | ( | openmpt_module * | mod,
|  | int32_t | samplerate,
|  | size_t | count,
|  | int16_t * | interleaved_quad )

Render audio data.

Parameters

  mod | The module handle to work on.
  samplerate | Sample rate to render output. Should be in [8000,192000], but this is not enforced.
  count | Number of audio frames to render per channel.
  interleaved_quad | Pointer to a buffer of at least count*4 elements that receives the interleaved quad surround output in the order (L,R,RL,RR).

Returns
  The number of frames actually rendered.

Return values

  0 | The end of song has been reached.

Remarks
  The output buffers are only written to up to the returned number of elements.
  You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
  It is recommended to use the floating point API because of the greater dynamic range and no implied clipping.

See also
  Output Format

## ◆ openmpt_module_read_interleaved_stereo()

size_t openmpt_module_read_interleaved_stereo | ( | openmpt_module * | mod,
|  | int32_t | samplerate,
|  | size_t | count,
|  | int16_t * | interleaved_stereo )

Render audio data.

Parameters

  mod | The module handle to work on.
  samplerate | Sample rate to render output. Should be in [8000,192000], but this is not enforced.
  count | Number of audio frames to render per channel.
  interleaved_stereo | Pointer to a buffer of at least count*2 elements that receives the interleaved stereo output in the order (L,R).

Returns
  The number of frames actually rendered.

Return values

  0 | The end of song has been reached.

Remarks
  The output buffers are only written to up to the returned number of elements.
  You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
  It is recommended to use the floating point API because of the greater dynamic range and no implied clipping.

See also
  Output Format

## ◆ openmpt_module_read_mono()

size_t openmpt_module_read_mono | ( | openmpt_module * | mod,
|  | int32_t | samplerate,
|  | size_t | count,
|  | int16_t * | mono )

Render audio data.

Parameters

  mod | The module handle to work on.
  samplerate | Sample rate to render output. Should be in [8000,192000], but this is not enforced.
  count | Number of audio frames to render per channel.
  mono | Pointer to a buffer of at least count elements that receives the mono/center output.

Returns
  The number of frames actually rendered.

Return values

  0 | The end of song has been reached.

Remarks
  The output buffers are only written to up to the returned number of elements.
  You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
  It is recommended to use the floating point API because of the greater dynamic range and no implied clipping.

See also
  Output Format

## ◆ openmpt_module_read_quad()

size_t openmpt_module_read_quad | ( | openmpt_module * | mod,
|  | int32_t | samplerate,
|  | size_t | count,
|  | int16_t * | left,
|  | int16_t * | right,
|  | int16_t * | rear_left,
|  | int16_t * | rear_right )

Render audio data.

Parameters

  mod | The module handle to work on.
  samplerate | Sample rate to render output. Should be in [8000,192000], but this is not enforced.
  count | Number of audio frames to render per channel.
  left | Pointer to a buffer of at least count elements that receives the left output.
  right | Pointer to a buffer of at least count elements that receives the right output.
  rear_left | Pointer to a buffer of at least count elements that receives the rear left output.
  rear_right | Pointer to a buffer of at least count elements that receives the rear right output.

Returns
  The number of frames actually rendered.

Return values

  0 | The end of song has been reached.

Remarks
  The output buffers are only written to up to the returned number of elements.
  You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
  It is recommended to use the floating point API because of the greater dynamic range and no implied clipping.

See also
  Output Format

## ◆ openmpt_module_read_stereo()

size_t openmpt_module_read_stereo | ( | openmpt_module * | mod,
|  | int32_t | samplerate,
|  | size_t | count,
|  | int16_t * | left,
|  | int16_t * | right )

Render audio data.

Parameters

  mod | The module handle to work on.
  samplerate | Sample rate to render output. Should be in [8000,192000], but this is not enforced.
  count | Number of audio frames to render per channel.
  left | Pointer to a buffer of at least count elements that receives the left output.
  right | Pointer to a buffer of at least count elements that receives the right output.

Returns
  The number of frames actually rendered.

Return values

  0 | The end of song has been reached.

Remarks
  The output buffers are only written to up to the returned number of elements.
  You can freely switch between any of the "openmpt_module_read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
  It is recommended to use the floating point API because of the greater dynamic range and no implied clipping.

See also
  Output Format

## ◆ openmpt_module_select_subsong()

int openmpt_module_select_subsong | ( | openmpt_module * | mod,
|  | int32_t | subsong )

Select a sub-song from a multi-song module.

Parameters

  mod | The module handle to work on.
  subsong | Index of the sub-song. -1 plays all sub-songs consecutively.

Returns
  1 on success, 0 on failure.

See also
  openmpt_module_get_num_subsongs, openmpt_module_get_selected_subsong, openmpt_module_get_subsong_name

Remarks
  Whether subsong -1 (all subsongs consecutively), subsong 0 or some other subsong is selected by default, is an implementation detail and subject to change. If you do not want to care about subsongs, it is recommended to just not call openmpt_module_select_subsong() at all.

## ◆ openmpt_module_set_error_func()

void openmpt_module_set_error_func | ( | openmpt_module * | mod,
|  | openmpt_error_func | errfunc,
|  | void * | erruser )

Set error function.

Set the error function of an already constructed openmpt_module.

Parameters

  mod | The module handle to work on.
  errfunc | Error function to define error behaviour. May be NULL.
  erruser | Error function user context.

Since
  0.3.0

## ◆ openmpt_module_set_log_func()

void openmpt_module_set_log_func | ( | openmpt_module * | mod,
|  | openmpt_log_func | logfunc,
|  | void * | loguser )

Set logging function.

Set the logging function of an already constructed openmpt_module.

Parameters

  mod | The module handle to work on.
  logfunc | Logging function where warning and errors are written. The logging function may be called throughout the lifetime of openmpt_module.
  loguser | User-defined data associated with this module. This value will be passed to the logging callback function (logfunc)

Since
  0.3.0

## ◆ openmpt_module_set_position_order_row()

double openmpt_module_set_position_order_row | ( | openmpt_module * | mod,
|  | int32_t | order,
|  | int32_t | row )

Set approximate current song position.

If order or row are out of range, to position is not modified and the current position is returned.

Parameters

  mod | The module handle to work on.
  order | Pattern order number to seek to.
  row | Pattern row number to seek to.

Returns
  Approximate new song position in seconds.

See also
  openmpt_module_set_position_seconds
  openmpt_module_get_position_seconds

## ◆ openmpt_module_set_position_seconds()

double openmpt_module_set_position_seconds | ( | openmpt_module * | mod,
|  | double | seconds )

Set approximate current song position.

Parameters

  mod | The module handle to work on.
  seconds | Seconds to seek to. If seconds is out of range, the position gets set to song start or end respectively.

Returns
  Approximate new song position in seconds.

See also
  openmpt_module_get_position_seconds

## ◆ openmpt_module_set_render_param()

int openmpt_module_set_render_param | ( | openmpt_module * | mod,
|  | int | param,
|  | int32_t | value )

Set render parameter.

Parameters

  mod | The module handle to work on.
  param | Parameter to set. See Render param indices
  value | The value to set param to.

Returns
  1 on success, 0 on failure (invalid param).

See also
  OPENMPT_MODULE_RENDER_MASTERGAIN_MILLIBEL
  OPENMPT_MODULE_RENDER_STEREOSEPARATION_PERCENT
  OPENMPT_MODULE_RENDER_INTERPOLATIONFILTER_LENGTH
  OPENMPT_MODULE_RENDER_VOLUMERAMPING_STRENGTH
  openmpt_module_get_render_param

## ◆ openmpt_module_set_repeat_count()

int openmpt_module_set_repeat_count | ( | openmpt_module * | mod,
|  | int32_t | repeat_count )

Set Repeat Count.

Parameters

  mod | The module handle to work on.
  repeat_count | Repeat Count -1: repeat forever 0: play once, repeat zero times (the default) n>0: play once and repeat n times after that

Returns
  1 on success, 0 on failure.

See also
  openmpt_module_get_repeat_count

## ◆ openmpt_probe_file_header()

int openmpt_probe_file_header | ( | uint64_t | flags,
|  | const void * | data,
|  | size_t | size,
|  | uint64_t | filesize,
|  | openmpt_log_func | logfunc,
|  | void * | loguser,
|  | openmpt_error_func | errfunc,
|  | void * | erruser,
|  | int * | error,
|  | const char ** | error_message )

Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it.

Parameters

  flags | Bit mask of OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES and OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS, or OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT.
  data | Beginning of the file data.
  size | Size of the beginning of the file data.
  filesize | Full size of the file data on disk.
  logfunc | Logging function where warning and errors are written. May be NULL.
  loguser | Logging function user context. Used to pass any user-defined data associated with this module to the logging function.
  errfunc | Error function to define error behaviour. May be NULL.
  erruser | Error function user context. Used to pass any user-defined data associated with this module to the logging function.
  error | Pointer to an integer where an error may get stored. May be NULL.
  error_message | Pointer to a string pointer where an error message may get stored. May be NULL.

Remarks
  It is recommended to provide openmpt_probe_file_header_get_recommended_size() bytes of data for data and size. If the file is smaller, only provide the filesize amount and set size and filesize to the file's size.
  openmpt_could_open_probability2() provides a more elaborate interface that might be required for special use cases. It is recommended to use openmpt_probe_file_header() though, if possible.

Return values

  OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESS | The file will most likely be supported by libopenmpt.
  OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE | The file is not supported by libopenmpt.
  OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATA | An answer could not be determined with the amount of data provided.
  OPENMPT_PROBE_FILE_HEADER_RESULT_ERROR | An internal error occurred.

See also
  openmpt_probe_file_header_get_recommended_size()
  openmpt_probe_file_header_without_filesize()
  openmpt_probe_file_header_from_stream()
  openmpt_could_open_probability2()

Since
  0.3.0

## ◆ openmpt_probe_file_header_from_stream()

int openmpt_probe_file_header_from_stream | ( | uint64_t | flags,
|  | openmpt_stream_callbacks | stream_callbacks,
|  | void * | stream,
|  | openmpt_log_func | logfunc,
|  | void * | loguser,
|  | openmpt_error_func | errfunc,
|  | void * | erruser,
|  | int * | error,
|  | const char ** | error_message )

Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it.

Parameters

  flags | Bit mask of OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES and OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS, or OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT.
  stream_callbacks | Input stream callback operations.
  stream | Input stream to scan.
  logfunc | Logging function where warning and errors are written. May be NULL.
  loguser | Logging function user context. Used to pass any user-defined data associated with this module to the logging function.
  errfunc | Error function to define error behaviour. May be NULL.
  erruser | Error function user context. Used to pass any user-defined data associated with this module to the logging function.
  error | Pointer to an integer where an error may get stored. May be NULL.
  error_message | Pointer to a string pointer where an error message may get stored. May be NULL.

Remarks
  The stream is left in an unspecified state when this function returns.
  It is recommended to provide openmpt_probe_file_header_get_recommended_size() bytes of data for data and size. If the file is smaller, only provide the filesize amount and set size and filesize to the file's size.
  openmpt_could_open_probability2() provides a more elaborate interface that might be required for special use cases. It is recommended to use openmpt_probe_file_header() though, if possible.

Return values

  OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESS | The file will most likely be supported by libopenmpt.
  OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE | The file is not supported by libopenmpt.
  OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATA | An answer could not be determined with the amount of data provided.
  OPENMPT_PROBE_FILE_HEADER_RESULT_ERROR | An internal error occurred.

See also
  openmpt_probe_file_header_get_recommended_size()
  openmpt_probe_file_header()
  openmpt_probe_file_header_without_filesize()
  openmpt_could_open_probability2()

Since
  0.3.0

## ◆ openmpt_probe_file_header_get_recommended_size()

size_t openmpt_probe_file_header_get_recommended_size | ( | void |  | ) |

Get recommended header size for successfull format probing.

See also
  openmpt_probe_file_header()
  openmpt_probe_file_header_without_filesize()

Since
  0.3.0

## ◆ openmpt_probe_file_header_without_filesize()

int openmpt_probe_file_header_without_filesize | ( | uint64_t | flags,
|  | const void * | data,
|  | size_t | size,
|  | openmpt_log_func | logfunc,
|  | void * | loguser,
|  | openmpt_error_func | errfunc,
|  | void * | erruser,
|  | int * | error,
|  | const char ** | error_message )

Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it.

Parameters

  flags | Bit mask of OPENMPT_PROBE_FILE_HEADER_FLAGS_MODULES and OPENMPT_PROBE_FILE_HEADER_FLAGS_CONTAINERS, or OPENMPT_PROBE_FILE_HEADER_FLAGS_DEFAULT.
  data | Beginning of the file data.
  size | Size of the beginning of the file data.
  logfunc | Logging function where warning and errors are written. May be NULL.
  loguser | Logging function user context. Used to pass any user-defined data associated with this module to the logging function.
  errfunc | Error function to define error behaviour. May be NULL.
  erruser | Error function user context. Used to pass any user-defined data associated with this module to the logging function.
  error | Pointer to an integer where an error may get stored. May be NULL.
  error_message | Pointer to a string pointer where an error message may get stored. May be NULL.

Remarks
  It is recommended to use openmpt_probe_file_header() and provide the acutal file's size as a parameter if at all possible. libopenmpt can provide more accurate answers if the filesize is known.
  It is recommended to provide openmpt_probe_file_header_get_recommended_size() bytes of data for data and size. If the file is smaller, only provide the filesize amount and set size to the file's size.
  openmpt_could_open_probability2() provides a more elaborate interface that might be required for special use cases. It is recommended to use openmpt_probe_file_header() though, if possible.

Return values

  OPENMPT_PROBE_FILE_HEADER_RESULT_SUCCESS | The file will most likely be supported by libopenmpt.
  OPENMPT_PROBE_FILE_HEADER_RESULT_FAILURE | The file is not supported by libopenmpt.
  OPENMPT_PROBE_FILE_HEADER_RESULT_WANTMOREDATA | An answer could not be determined with the amount of data provided.
  OPENMPT_PROBE_FILE_HEADER_RESULT_ERROR | An internal error occurred.

See also
  openmpt_probe_file_header_get_recommended_size()
  openmpt_probe_file_header()
  openmpt_probe_file_header_from_stream()
  openmpt_could_open_probability2()

Since
  0.3.0

## ◆ openmpt_stream_buffer_init()

void openmpt_stream_buffer_init | ( | openmpt_stream_buffer * | buffer,
|  | const void * | file_data,
|  | int64_t | file_size )
| static

## ◆ openmpt_stream_buffer_init2()

void openmpt_stream_buffer_init2 | ( | openmpt_stream_buffer2 * | buffer,
|  | const void * | file_data,
|  | int64_t | file_size )
| static

## ◆ openmpt_stream_buffer_read_func()

size_t openmpt_stream_buffer_read_func | ( | void * | stream,
|  | void * | dst,
|  | size_t | bytes )
| static

## ◆ openmpt_stream_buffer_read_func2()

size_t openmpt_stream_buffer_read_func2 | ( | void * | stream,
|  | void * | dst,
|  | size_t | bytes )
| static

## ◆ openmpt_stream_buffer_seek_func()

int openmpt_stream_buffer_seek_func | ( | void * | stream,
|  | int64_t | offset,
|  | int | whence )
| static

## ◆ openmpt_stream_buffer_seek_func2()

int openmpt_stream_buffer_seek_func2 | ( | void * | stream,
|  | int64_t | offset,
|  | int | whence )
| static

## ◆ openmpt_stream_buffer_tell_func()

int64_t openmpt_stream_buffer_tell_func | ( | void * | stream | ) |
| static

## ◆ openmpt_stream_buffer_tell_func2()

int64_t openmpt_stream_buffer_tell_func2 | ( | void * | stream | ) |
| static

## ◆ openmpt_stream_fd_read_func()

size_t openmpt_stream_fd_read_func | ( | void * | stream,
|  | void * | dst,
|  | size_t | bytes )
| static

## ◆ openmpt_stream_file_mingw_read_func()

size_t openmpt_stream_file_mingw_read_func | ( | void * | stream,
|  | void * | dst,
|  | size_t | bytes )
| static

## ◆ openmpt_stream_file_mingw_seek_func()

int openmpt_stream_file_mingw_seek_func | ( | void * | stream,
|  | int64_t | offset,
|  | int | whence )
| static

## ◆ openmpt_stream_file_mingw_tell_func()

int64_t openmpt_stream_file_mingw_tell_func | ( | void * | stream | ) |
| static

## ◆ openmpt_stream_file_msvcrt_read_func()

size_t openmpt_stream_file_msvcrt_read_func | ( | void * | stream,
|  | void * | dst,
|  | size_t | bytes )
| static

## ◆ openmpt_stream_file_msvcrt_seek_func()

int openmpt_stream_file_msvcrt_seek_func | ( | void * | stream,
|  | int64_t | offset,
|  | int | whence )
| static

## ◆ openmpt_stream_file_msvcrt_tell_func()

int64_t openmpt_stream_file_msvcrt_tell_func | ( | void * | stream | ) |
| static

## ◆ openmpt_stream_file_posix_lfs64_read_func()

size_t openmpt_stream_file_posix_lfs64_read_func | ( | void * | stream,
|  | void * | dst,
|  | size_t | bytes )
| static

## ◆ openmpt_stream_file_posix_lfs64_seek_func()

int openmpt_stream_file_posix_lfs64_seek_func | ( | void * | stream,
|  | int64_t | offset,
|  | int | whence )
| static

## ◆ openmpt_stream_file_posix_lfs64_tell_func()

int64_t openmpt_stream_file_posix_lfs64_tell_func | ( | void * | stream | ) |
| static

## ◆ openmpt_stream_file_posix_read_func()

size_t openmpt_stream_file_posix_read_func | ( | void * | stream,
|  | void * | dst,
|  | size_t | bytes )
| static

## ◆ openmpt_stream_file_posix_seek_func()

int openmpt_stream_file_posix_seek_func | ( | void * | stream,
|  | int64_t | offset,
|  | int | whence )
| static

## ◆ openmpt_stream_file_posix_tell_func()

int64_t openmpt_stream_file_posix_tell_func | ( | void * | stream | ) |
| static

## ◆ openmpt_stream_file_read_func()

size_t openmpt_stream_file_read_func | ( | void * | stream,
|  | void * | dst,
|  | size_t | bytes )
| static

## ◆ openmpt_stream_file_seek_func()

int openmpt_stream_file_seek_func | ( | void * | stream,
|  | int64_t | offset,
|  | int | whence )
| static

## ◆ openmpt_stream_file_tell_func()

int64_t openmpt_stream_file_tell_func | ( | void * | stream | ) |
| static

## ◆ openmpt_stream_get_buffer_callbacks()

openmpt_stream_callbacks openmpt_stream_get_buffer_callbacks | ( | void |  | ) |
| static

Provide openmpt_stream_callbacks for in-memoy buffers.

Fills openmpt_stream_callbacks suitable for passing an in-memory buffer as a stream parameter to functions doing file input/output. A suitable openmpt_stream_buffer object may be initialized with openmpt_stream_buffer_init().

Remarks
  The stream argument must be passed as (void*)(openmpt_stream_buffer*)stream_buffer.

See also
  File I/O
  openmpt_stream_callbacks
  openmpt_could_open_probability2
  openmpt_probe_file_header_from_stream
  openmpt_module_create2
  openmpt_stream_buffer_init

Deprecated
  Please use openmpt_stream_get_buffer_callbacks2().

## ◆ openmpt_stream_get_buffer_callbacks2()

openmpt_stream_callbacks openmpt_stream_get_buffer_callbacks2 | ( | void |  | ) |
| static

Provide openmpt_stream_callbacks for in-memoy buffers.

Fills openmpt_stream_callbacks suitable for passing an in-memory buffer as a stream parameter to functions doing file input/output. A suitable openmpt_stream_buffer2 object can be initialized with openmpt_stream_buffer_init2().

Remarks
  The stream argument must be passed as (void*)(openmpt_stream_buffer2*)stream_buffer.

See also
  File I/O
  openmpt_stream_callbacks
  openmpt_could_open_probability2
  openmpt_probe_file_header_from_stream
  openmpt_module_create2
  openmpt_stream_buffer_init2

Since
  0.7.0

## ◆ openmpt_stream_get_fd_callbacks()

openmpt_stream_callbacks openmpt_stream_get_fd_callbacks | ( | void |  | ) |
| static

Provide openmpt_stream_callbacks for standard POSIX file descriptors.

Fills openmpt_stream_callbacks suitable for passing a POSIX filer descriptor as a stream parameter to functions doing file input/output.

Remarks
  The stream argument must be passed as (void*)(uintptr_t)(int)fd.

See also
  File I/O
  openmpt_stream_callbacks
  openmpt_could_open_probability2
  openmpt_probe_file_header_from_stream
  openmpt_module_create2

## ◆ openmpt_stream_get_file_callbacks()

openmpt_stream_callbacks openmpt_stream_get_file_callbacks | ( | void |  | ) |
| static

Provide openmpt_stream_callbacks for standard C FILE objects.

Fills openmpt_stream_callbacks suitable for passing a standard C FILE object as a stream parameter to functions doing file input/output. Since 0.7.0, it does not try to use platform-specific file seeking any more, but sticks to standard C fseek/ftell only, which means on platforms where long is 32bit, there is no 64bit file access possible any more.

Remarks
  The stream argument must be passed as (void*)(FILE*)file.

See also
  File I/O
  openmpt_stream_callbacks
  openmpt_could_open_probability2
  openmpt_probe_file_header_from_stream
  openmpt_module_create2
  openmpt_stream_get_file_callbacks2()
  openmpt_stream_get_file_mingw_callbacks()
  openmpt_stream_get_file_msvcrt_callbacks()
  openmpt_stream_get_file_posix_callbacks()
  openmpt_stream_get_file_posix_lfs64_callbacks()

Deprecated
  Please use openmpt_stream_get_file_callbacks2().

## ◆ openmpt_stream_get_file_callbacks2()

openmpt_stream_callbacks openmpt_stream_get_file_callbacks2 | ( | void |  | ) |
| static

Provide openmpt_stream_callbacks for standard C FILE objects.

Fills openmpt_stream_callbacks suitable for passing a standard C FILE object as a stream parameter to functions doing file input/output. This function uses the standard C fseek and ftell, thus platform-specific file size limits apply accordingly.

Remarks
  The stream argument must be passed as (void*)(FILE*)file.
  The provided callbacks are limited to handling files up to the size representable in the platform's long type.

See also
  File I/O
  openmpt_stream_callbacks
  openmpt_could_open_probability2
  openmpt_probe_file_header_from_stream
  openmpt_module_create2

Since
  0.7.0

## ◆ openmpt_stream_get_file_mingw_callbacks()

openmpt_stream_callbacks openmpt_stream_get_file_mingw_callbacks | ( | void |  | ) |
| static

Provide openmpt_stream_callbacks for standard C FILE objects.

Fills openmpt_stream_callbacks suitable for passing a standard C FILE object as a stream parameter to functions doing file input/output.

Remarks
  The stream argument must be passed as (void*)(FILE*)file.

See also
  File I/O
  openmpt_stream_callbacks
  openmpt_could_open_probability2
  openmpt_probe_file_header_from_stream
  openmpt_module_create2

## ◆ openmpt_stream_get_file_msvcrt_callbacks()

openmpt_stream_callbacks openmpt_stream_get_file_msvcrt_callbacks | ( | void |  | ) |
| static

Provide openmpt_stream_callbacks for standard C FILE objects.

Fills openmpt_stream_callbacks suitable for passing a standard C FILE object as a stream parameter to functions doing file input/output.

Remarks
  The stream argument must be passed as (void*)(FILE*)file.

See also
  File I/O
  openmpt_stream_callbacks
  openmpt_could_open_probability2
  openmpt_probe_file_header_from_stream
  openmpt_module_create2

## ◆ openmpt_stream_get_file_posix_callbacks()

openmpt_stream_callbacks openmpt_stream_get_file_posix_callbacks | ( | void |  | ) |
| static

Provide openmpt_stream_callbacks for standard C FILE objects.

Fills openmpt_stream_callbacks suitable for passing a standard C FILE object as a stream parameter to functions doing file input/output.

Remarks
  The stream argument must be passed as (void*)(FILE*)file.

See also
  File I/O
  openmpt_stream_callbacks
  openmpt_could_open_probability2
  openmpt_probe_file_header_from_stream
  openmpt_module_create2

## ◆ openmpt_stream_get_file_posix_lfs64_callbacks()

openmpt_stream_callbacks openmpt_stream_get_file_posix_lfs64_callbacks | ( | void |  | ) |
| static

Provide openmpt_stream_callbacks for standard C FILE objects.

Fills openmpt_stream_callbacks suitable for passing a standard C FILE object as a stream parameter to functions doing file input/output.

Remarks
  The stream argument must be passed as (void*)(FILE*)file.

See also
  File I/O
  openmpt_stream_callbacks
  openmpt_could_open_probability2
  openmpt_probe_file_header_from_stream
  openmpt_module_create2