libopenmpt: libopenmpt C++

libopenmpt 0.8.5-pre.0+r24758 cross-platform C++ and C library to decode tracked music files

Namespaces | Classes | Enumerations | Functions | Variables
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. 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

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.