libopenmpt  0.7.0-pre.10+r17981
cross-platform C++ and C library to decode tracked music files
libopenmpt C++

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. More...
 
LIBOPENMPT_CXX_API std::uint32_t openmpt::get_core_version ()
 Get the core version number. More...
 
LIBOPENMPT_CXX_API std::vector< std::string > openmpt::get_supported_extensions ()
 Get a list of supported file extensions. More...
 
LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API bool openmpt::is_extension_supported (const std::string &extension)
 Query whether a file extension is supported. More...
 
LIBOPENMPT_CXX_API bool openmpt::is_extension_supported2 (std::string_view extension)
 Query whether a file extension is supported. More...
 
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. More...
 
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. More...
 
LIBOPENMPT_CXX_API std::size_t openmpt::probe_file_header_get_recommended_size ()
 Get recommended header size for successfull format probing. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 

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

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

Possible return values for openmpt::probe_file_header().

Since
0.3.0
Enumerator
probe_file_header_result_success 
probe_file_header_result_failure 
probe_file_header_result_wantmoredata 

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
streamInput stream to scan.
effortEffort 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.
logLog 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
extensionfile 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
extensionfile 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
flagsBit mask of openmpt::probe_file_header_flags_modules2 and openmpt::probe_file_header_flags_containers2, or openmpt::probe_file_header_flags_default2.
dataBeginning of the file data.
sizeSize 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_successThe file will most likely be supported by libopenmpt.
probe_file_header_result_failureThe file is not supported by libopenmpt.
probe_file_header_result_wantmoredataAn 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
flagsBit mask of openmpt::probe_file_header_flags_modules2 and openmpt::probe_file_header_flags_containers2, or openmpt::probe_file_header_flags_default2.
dataBeginning of the file data.
sizeSize of the beginning of the file data.
filesizeFull 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_successThe file will most likely be supported by libopenmpt.
probe_file_header_result_failureThe file is not supported by libopenmpt.
probe_file_header_result_wantmoredataAn 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
flagsBit mask of openmpt::probe_file_header_flags_modules2 and openmpt::probe_file_header_flags_containers2, or openmpt::probe_file_header_flags_default2.
dataBeginning of the file data.
sizeSize 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_successThe file will most likely be supported by libopenmpt.
probe_file_header_result_failureThe file is not supported by libopenmpt.
probe_file_header_result_wantmoredataAn 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
flagsBit mask of openmpt::probe_file_header_flags_modules2 and openmpt::probe_file_header_flags_containers2, or openmpt::probe_file_header_flags_default2.
dataBeginning of the file data.
sizeSize of the beginning of the file data.
filesizeFull 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_successThe file will most likely be supported by libopenmpt.
probe_file_header_result_failureThe file is not supported by libopenmpt.
probe_file_header_result_wantmoredataAn 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
flagsBit mask of openmpt::probe_file_header_flags_modules2 and openmpt::probe_file_header_flags_containers2, or openmpt::probe_file_header_flags_default2.
streamInput 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_successThe file will most likely be supported by libopenmpt.
probe_file_header_result_failureThe file is not supported by libopenmpt.
probe_file_header_result_wantmoredataAn 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.