Function openmpt_sys::openmpt_could_open_probability2

pub unsafe extern "C" fn openmpt_could_open_probability2(
    stream_callbacks: openmpt_stream_callbacks,
    stream: *mut c_void,
    effort: f64,
    logfunc: openmpt_log_func,
    loguser: *mut c_void,
    errfunc: openmpt_error_func,
    erruser: *mut c_void,
    error: *mut c_int,
    error_message: *mut *const c_char
) -> f64

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

\param stream_callbacks Input stream callback operations. \param stream Input stream to scan. \param 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. \param logfunc Logging function where warning and errors are written. May be NULL. \param loguser Logging function user context. Used to pass any user-defined data associated with this module to the logging function. \param errfunc Error function to define error behaviour. May be NULL. \param erruser Error function user context. Used to pass any user-defined data associated with this module to the logging function. \param error Pointer to an integer where an error may get stored. May be NULL. \param error_message Pointer to a string pointer where an error message may get stored. May be NULL. \return 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(). \remarks 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.). \remarks 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. \include libopenmpt_example_c_probe.c \sa \ref libopenmpt_c_fileio \sa openmpt_stream_callbacks \sa openmpt_probe_file_header \sa openmpt_probe_file_header_without_filesize \since 0.3.0