libopenmpt  0.4.3+release
cross-platform C++ and C library to decode tracked music files
openmpt Namespace Reference

Namespaces

 ext
 
 string
 

Classes

class  exception
 libopenmpt exception base class More...
 
class  module
 
class  module_ext
 

Enumerations

enum  probe_file_header_result { probe_file_header_result_success = 1, probe_file_header_result_failure = 0, probe_file_header_result_wantmoredata = -1 }
 Possible return values for openmpt::probe_file_header(). More...
 

Functions

LIBOPENMPT_CXX_API std::uint32_t get_library_version ()
 Get the libopenmpt version number. More...
 
LIBOPENMPT_CXX_API std::uint32_t get_core_version ()
 Get the core version number. More...
 
LIBOPENMPT_CXX_API std::vector< std::string > get_supported_extensions ()
 Get a list of supported file extensions. More...
 
LIBOPENMPT_CXX_API bool is_extension_supported (const std::string &extension)
 Query whether a file extension is supported. More...
 
LIBOPENMPT_CXX_API double 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 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 probe_file_header_get_recommended_size ()
 Get recommended header size for successfull format probing. More...
 
LIBOPENMPT_CXX_API int 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 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 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 = 0x1ul
 Probe for module formats in openmpt::probe_file_header(). More...
 
static const std::uint64_t probe_file_header_flags_containers = 0x2ul
 Probe for module-specific container formats in openmpt::probe_file_header(). More...
 
static const std::uint64_t probe_file_header_flags_default = probe_file_header_flags_modules | probe_file_header_flags_containers
 Probe for the default set of formats in openmpt::probe_file_header(). More...
 
static const std::uint64_t probe_file_header_flags_none = 0x0ul
 Probe for no formats in openmpt::probe_file_header(). More...
 

Enumeration Type Documentation

◆ 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::module::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_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.

◆ probe_file_header() [1/3]

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
flagsOred mask of openmpt::probe_file_header_flags_modules and openmpt::probe_file_header_flags_containers, or openmpt::probe_file_header_flags_default.
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() [2/3]

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
flagsOred mask of openmpt::probe_file_header_flags_modules and openmpt::probe_file_header_flags_containers, or openmpt::probe_file_header_flags_default.
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() [3/3]

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
flagsOred mask of openmpt::probe_file_header_flags_modules and openmpt::probe_file_header_flags_containers, or openmpt::probe_file_header_flags_default.
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

◆ probe_file_header_flags_containers

const std::uint64_t openmpt::probe_file_header_flags_containers = 0x2ul
static

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

Since
0.3.0

◆ probe_file_header_flags_default

const std::uint64_t openmpt::probe_file_header_flags_default = probe_file_header_flags_modules | probe_file_header_flags_containers
static

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

Since
0.3.0

◆ probe_file_header_flags_modules

const std::uint64_t openmpt::probe_file_header_flags_modules = 0x1ul
static

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

Since
0.3.0

◆ probe_file_header_flags_none

const std::uint64_t openmpt::probe_file_header_flags_none = 0x0ul
static

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

Since
0.3.0