libopenmpt C++

Namespaces
namespace	openmpt::string

Classes
class	openmpt::exception
	libopenmpt exception base class More...
class	openmpt::module

Enumerations
enum	openmpt::probe_file_header_flags : std::uint64_t { openmpt::probe_file_header_flags_modules2 = 0x1ull , openmpt::probe_file_header_flags_containers2 = 0x2ull , openmpt::probe_file_header_flags_default2 = probe_file_header_flags_modules2 | probe_file_header_flags_containers2 , openmpt::probe_file_header_flags_none2 = 0x0ull }
	Possible values for openmpt::probe_file_header() flags parameter. More...
enum	openmpt::probe_file_header_result { openmpt::probe_file_header_result_success = 1 , openmpt::probe_file_header_result_failure = 0 , openmpt::probe_file_header_result_wantmoredata = -1 }
	Possible return values for openmpt::probe_file_header(). More...

Functions
LIBOPENMPT_CXX_API std::uint32_t	openmpt::get_library_version ()
	Get the libopenmpt version number.
LIBOPENMPT_CXX_API std::uint32_t	openmpt::get_core_version ()
	Get the core version number.
LIBOPENMPT_CXX_API std::vector< std::string >	openmpt::get_supported_extensions ()
	Get a list of supported file extensions.
LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API bool	openmpt::is_extension_supported (const std::string &extension)
	Query whether a file extension is supported.
LIBOPENMPT_CXX_API bool	openmpt::is_extension_supported2 (std::string_view extension)
	Query whether a file extension is supported.
LIBOPENMPT_CXX_API double	openmpt::could_open_probability (std::istream &stream, double effort=1.0, std::ostream &log=std::clog)
	Roughly scan the input stream to find out whether libopenmpt might be able to open it.
LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API double	openmpt::could_open_propability (std::istream &stream, double effort=1.0, std::ostream &log=std::clog)
	Roughly scan the input stream to find out whether libopenmpt might be able to open it.
LIBOPENMPT_CXX_API std::size_t	openmpt::probe_file_header_get_recommended_size ()
	Get recommended header size for successfull format probing.
LIBOPENMPT_CXX_API int	openmpt::probe_file_header (std::uint64_t flags, const std::byte *data, std::size_t size, std::uint64_t filesize)
	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.
LIBOPENMPT_CXX_API int	openmpt::probe_file_header (std::uint64_t flags, const std::uint8_t *data, std::size_t size, std::uint64_t filesize)
	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.
LIBOPENMPT_CXX_API int	openmpt::probe_file_header (std::uint64_t flags, const std::byte *data, std::size_t size)
	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.
LIBOPENMPT_CXX_API int	openmpt::probe_file_header (std::uint64_t flags, const std::uint8_t *data, std::size_t size)
	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.
LIBOPENMPT_CXX_API int	openmpt::probe_file_header (std::uint64_t flags, std::istream &stream)
	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.

Variables
static const std::uint64_t probe_file_header_flags_modules	openmpt::LIBOPENMPT_ATTR_DEPRECATED = 0x1ull
	Probe for module formats in openmpt::probe_file_header().

Detailed Description

Enumeration Type Documentation

probe_file_header_flags

enum openmpt::probe_file_header_flags : std::uint64_t

Possible values for openmpt::probe_file_header() flags parameter.

Since

0.6.0

Enumerator
probe_file_header_flags_modules2	Probe for module formats in openmpt::probe_file_header(). Since 0.6.0
probe_file_header_flags_containers2	Probe for module-specific container formats in openmpt::probe_file_header(). Since 0.6.0
probe_file_header_flags_default2	Probe for the default set of formats in openmpt::probe_file_header(). Since 0.6.0
probe_file_header_flags_none2	Probe for no formats in openmpt::probe_file_header(). Since 0.6.0

probe_file_header_result

enum openmpt::probe_file_header_result

Possible return values for openmpt::probe_file_header().

Since

0.3.0

Enumerator
probe_file_header_result_success	The file will most likely be supported by libopenmpt. Since 0.3.0
probe_file_header_result_failure	The file is not supported by libopenmpt. Since 0.3.0
probe_file_header_result_wantmoredata	An answer could not be determined with the amount of data provided. Since 0.3.0

Function Documentation

could_open_probability()

LIBOPENMPT_CXX_API double openmpt::could_open_probability	(	std::istream &	stream,
		double	effort = 1.0,
		std::ostream &	log = std::clog
	)

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

Parameters

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.
log	Log where warning and errors are written.

Returns

Probability between 0.0 and 1.0.

Remarks

openmpt::probe_file_header() provides a simpler and faster interface that fits almost all use cases better. It is recommended to use openmpt::probe_file_header() instead of openmpt::could_open_probability().

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 std::istream implementation 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::probe_file_header()

Since

0.3.0

could_open_propability()

LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API double openmpt::could_open_propability	(	std::istream &	stream,
		double	effort = 1.0,
		std::ostream &	log = std::clog
	)

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

Deprecated:

Please use openmpt::could_open_probability().

get_core_version()

LIBOPENMPT_CXX_API std::uint32_t openmpt::get_core_version

(

)

Get the core version number.

Return the OpenMPT core version number.

Returns

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

get_library_version()

LIBOPENMPT_CXX_API std::uint32_t openmpt::get_library_version

(

)

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

get_supported_extensions()

LIBOPENMPT_CXX_API std::vector< std::string > openmpt::get_supported_extensions

(

)

Get a list of supported file extensions.

Returns

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

is_extension_supported()

LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API bool openmpt::is_extension_supported

(

const std::string &

extension

)

Query whether a file extension is supported.

Parameters

extension

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

Returns

true if the extension is supported by libopenmpt, false otherwise.

Deprecated:

Please use openmpt::is_extension_supported2().

is_extension_supported2()

LIBOPENMPT_CXX_API bool openmpt::is_extension_supported2

(

std::string_view

extension

)

Query whether a file extension is supported.

Parameters

extension

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

Returns

true if the extension is supported by libopenmpt, false otherwise.

Since

0.5.0

probe_file_header() [1/5]

LIBOPENMPT_CXX_API int openmpt::probe_file_header	(	std::uint64_t	flags,
		const std::byte *	data,
		std::size_t	size
	)

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_modules2 and openmpt::probe_file_header_flags_containers2, or openmpt::probe_file_header_flags_default2.
data	Beginning of the file data.
size	Size of the beginning of the file data.

Remarks

It is recommended to use the overload of this function that also takes the filesize as parameter if at all possile. 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_probability() 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

probe_file_header_result_success	The file will most likely be supported by libopenmpt.
probe_file_header_result_failure	The file is not supported by libopenmpt.
probe_file_header_result_wantmoredata	An answer could not be determined with the amount of data provided.

See also

openmpt::probe_file_header_get_recommended_size()

openmpt::could_open_probability()

Since

0.5.0

probe_file_header() [2/5]

LIBOPENMPT_CXX_API int openmpt::probe_file_header	(	std::uint64_t	flags,
		const std::byte *	data,
		std::size_t	size,
		std::uint64_t	filesize
	)

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_modules2 and openmpt::probe_file_header_flags_containers2, or openmpt::probe_file_header_flags_default2.
data	Beginning of the file data.
size	Size of the beginning of the file data.
filesize	Full size of the file data on disk.

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_probability() 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

probe_file_header_result_success	The file will most likely be supported by libopenmpt.
probe_file_header_result_failure	The file is not supported by libopenmpt.
probe_file_header_result_wantmoredata	An answer could not be determined with the amount of data provided.

See also

openmpt::probe_file_header_get_recommended_size()

openmpt::could_open_probability()

Since

0.5.0

probe_file_header() [3/5]

LIBOPENMPT_CXX_API int openmpt::probe_file_header	(	std::uint64_t	flags,
		const std::uint8_t *	data,
		std::size_t	size
	)

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_modules2 and openmpt::probe_file_header_flags_containers2, or openmpt::probe_file_header_flags_default2.
data	Beginning of the file data.
size	Size of the beginning of the file data.

Remarks

It is recommended to use the overload of this function that also takes the filesize as parameter if at all possile. 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_probability() 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

probe_file_header_result_success	The file will most likely be supported by libopenmpt.
probe_file_header_result_failure	The file is not supported by libopenmpt.
probe_file_header_result_wantmoredata	An answer could not be determined with the amount of data provided.

See also

openmpt::probe_file_header_get_recommended_size()

openmpt::could_open_probability()

Since

0.3.0

probe_file_header() [4/5]

LIBOPENMPT_CXX_API int openmpt::probe_file_header	(	std::uint64_t	flags,
		const std::uint8_t *	data,
		std::size_t	size,
		std::uint64_t	filesize
	)

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_modules2 and openmpt::probe_file_header_flags_containers2, or openmpt::probe_file_header_flags_default2.
data	Beginning of the file data.
size	Size of the beginning of the file data.
filesize	Full size of the file data on disk.

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_probability() 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

probe_file_header_result_success	The file will most likely be supported by libopenmpt.
probe_file_header_result_failure	The file is not supported by libopenmpt.
probe_file_header_result_wantmoredata	An answer could not be determined with the amount of data provided.

See also

openmpt::probe_file_header_get_recommended_size()

openmpt::could_open_probability()

Since

0.3.0

probe_file_header() [5/5]

LIBOPENMPT_CXX_API int openmpt::probe_file_header	(	std::uint64_t	flags,
		std::istream &	stream
	)

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_modules2 and openmpt::probe_file_header_flags_containers2, or openmpt::probe_file_header_flags_default2.
stream	Input stream to scan.

Remarks

stream is left in an unspecified state when this function returns.

openmpt::could_open_probability() 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

probe_file_header_result_success	The file will most likely be supported by libopenmpt.
probe_file_header_result_failure	The file is not supported by libopenmpt.
probe_file_header_result_wantmoredata	An answer could not be determined with the amount of data provided.

See also

openmpt::probe_file_header_get_recommended_size()

openmpt::could_open_probability()

Since

0.3.0

probe_file_header_get_recommended_size()

LIBOPENMPT_CXX_API std::size_t openmpt::probe_file_header_get_recommended_size

(

)

Get recommended header size for successfull format probing.

See also

openmpt::probe_file_header()

Since

0.3.0

Variable Documentation

LIBOPENMPT_ATTR_DEPRECATED

static const std::uint64_t probe_file_header_flags_none openmpt::LIBOPENMPT_ATTR_DEPRECATED = 0x1ull

static

Probe for module formats in openmpt::probe_file_header().

Probe for no formats in openmpt::probe_file_header().

Probe for the default set of formats in openmpt::probe_file_header().

Probe for module-specific container formats in openmpt::probe_file_header().

Since

0.3.0

Deprecated:

Please use openmpt::probe_file_header_flags_modules2.

Since

0.3.0

Deprecated:

Please use openmpt::probe_file_header_flags_containers2.

Since

0.3.0

Deprecated:

Please use openmpt::probe_file_header_flags_default2.

Since

0.3.0

Deprecated:

Please use openmpt::probe_file_header_flags_none2.