File Identification

Core file type detection methods. More...

Collaboration diagram for File Identification:

Functions
FileTypeT	Recognition::Magic::MagicPrivate::IdentifyFile (const std::filesystem::path &path, IdentifyFileOptionsMaskT options) const
	Identify a single file's type (throwing version).
ExpectedFileTypeT	Recognition::Magic::MagicPrivate::IdentifyFile (const std::filesystem::path &path, IdentifyFileOptionsMaskT options, const std::nothrow_t &tag) const noexcept
	Identify a single file's type (noexcept version).
DefaultFileContainerT	Recognition::Magic::MagicPrivate::IdentifyDirectoryPreliminaryChecks (const std::filesystem::path &directory, std::filesystem::directory_options option, ProgressTrackerT progress_tracker) const
	Validate preconditions for directory identification (throwing).
std::optional< DefaultFileContainerT >	Recognition::Magic::MagicPrivate::IdentifyDirectoryPreliminaryChecks (const std::filesystem::path &directory, const std::nothrow_t &tag, std::filesystem::directory_options option, ProgressTrackerT progress_tracker) const noexcept
	Validate preconditions for directory identification (noexcept).
void	Recognition::Magic::MagicPrivate::IdentifyContainerPreliminaryChecks (ProgressTrackerT progress_tracker) const
	Validate preconditions for container identification (throwing).
bool	Recognition::Magic::MagicPrivate::IdentifyContainerPreliminaryChecks (const std::nothrow_t &tag, ProgressTrackerT progress_tracker) const noexcept
	Validate preconditions for container identification (noexcept).
FileTypeMapT	Recognition::Magic::MagicPrivate::IdentifyFiles (const DefaultFileContainerT &files, IdentifyFileOptionsMaskT option, ProgressTrackerT progress_tracker) const
	Identify multiple files with progress tracking (throwing).
ExpectedFileTypeMapT	Recognition::Magic::MagicPrivate::IdentifyFiles (const DefaultFileContainerT &files, const std::nothrow_t &tag, IdentifyFileOptionsMaskT option, ProgressTrackerT progress_tracker) const noexcept
	Identify multiple files with progress tracking (noexcept).

Detailed Description

Core file type detection methods.

Methods for identifying file types using magic number analysis.

Function Documentation

IdentifyContainerPreliminaryChecks() [1/2]

bool Recognition::Magic::MagicPrivate::IdentifyContainerPreliminaryChecks ( const std::nothrow_t & tag, ProgressTrackerT progress_tracker ) const

inlinenoexcept

Validate preconditions for container identification (noexcept).

Non-throwing variant that returns false on any validation failure. Simple boolean check of IsValid() && progress_tracker.

Parameters

[in]	tag	Pass std::nothrow to select this overload.
[in]	progress_tracker	Tracker for progress updates.

Returns

true if instance is valid AND tracker is non-null, false otherwise.

See also

Magic::IdentifyFiles(const Utility::FileContainer auto&, const std::nothrow_t&, ...)

IdentifyContainerPreliminaryChecks() [2/2]

void Recognition::Magic::MagicPrivate::IdentifyContainerPreliminaryChecks ( ProgressTrackerT progress_tracker ) const

inline

Validate preconditions for container identification (throwing).

Performs validation before identifying files from a user-provided container. This is simpler than directory validation since the caller provides the file list directly.

Parameters

[in]

progress_tracker

Tracker for progress updates (must not be null).

Exceptions

MagicIsClosed	If instance is not open.
MagicDatabaseNotLoaded	If database is not loaded.
NullTracker	If progress_tracker is null.

See also

Magic::IdentifyFiles(const Utility::FileContainer auto&, ...)

IdentifyFiles()

IdentifyDirectoryPreliminaryChecks() [1/2]

std::optional< DefaultFileContainerT > Recognition::Magic::MagicPrivate::IdentifyDirectoryPreliminaryChecks ( const std::filesystem::path & directory, const std::nothrow_t & tag, std::filesystem::directory_options option, ProgressTrackerT progress_tracker ) const

inlinenodiscardnoexcept

Validate preconditions for directory identification (noexcept).

Non-throwing variant that returns std::nullopt on any validation failure. Unlike the throwing version, this silently fails on:

• Instance not valid (not open or database not loaded)
• Empty directory path
• Directory doesn't exist
• Path is not a directory
• Progress tracker is null
• Filesystem iteration error

Parameters

[in]	directory	Directory path to scan.
[in]	tag	Pass std::nothrow to select this overload.
[in]	option	Filesystem directory iteration options.
[in]	progress_tracker	Tracker for progress updates.

Returns

Optional container of file paths found in directory, or std::nullopt on any validation failure.

See also

Magic::IdentifyFiles(const std::filesystem::path&, const std::nothrow_t&, ...)

IdentifyDirectoryPreliminaryChecks() [2/2]

DefaultFileContainerT Recognition::Magic::MagicPrivate::IdentifyDirectoryPreliminaryChecks ( const std::filesystem::path & directory, std::filesystem::directory_options option, ProgressTrackerT progress_tracker ) const

inlinenodiscard

Validate preconditions for directory identification (throwing).

Performs comprehensive validation before directory scanning:

1. Verifies instance is open and database is loaded
2. Validates directory path is non-empty and exists
3. Confirms path is actually a directory
4. Ensures progress tracker is not null
5. Collects all files via recursive directory iteration

Parameters

[in]	directory	Directory path to scan.
[in]	option	Filesystem directory iteration options.
[in]	progress_tracker	Tracker for progress updates (must not be null).

Returns

Container of file paths found in the directory.

Exceptions

MagicIsClosed	If instance is not open.
MagicDatabaseNotLoaded	If database is not loaded.
EmptyPath	If directory path is empty.
PathDoesNotExist	If directory does not exist.
PathIsNotDirectory	If path is not a directory.
NullTracker	If progress_tracker is null.
FilesystemError	If recursive_directory_iterator fails.

Implementation

Uses std::filesystem::recursive_directory_iterator to collect all files in the directory tree.

See also

Magic::IdentifyFiles(const std::filesystem::path&, ...)

IdentifyFiles()

IdentifyFile() [1/2]

FileTypeT Recognition::Magic::MagicPrivate::IdentifyFile ( const std::filesystem::path & path, IdentifyFileOptionsMaskT options ) const

inlinenodiscard

Identify a single file's type (throwing version).

Analyzes the content of the specified file using libmagic and returns its type based on magic number analysis. The validation checks performed depend on the options parameter.

Parameters

[in]	path	Path to the file to identify.
[in]	options	Validation options to check before identification.

Returns

The file type string (format depends on configured Flags).

Exceptions

MagicIsClosed	If instance is closed (when CheckIsValid set).
MagicDatabaseNotLoaded	If database not loaded (when CheckIsValid set).
EmptyPath	If path is empty (when CheckPathEmpty set).
PathDoesNotExist	If file doesn't exist (when CheckPathExists set).
MagicIdentifyFileError	If magic_file() returns nullptr.

Validation Flow

The options bitmask controls which checks are performed:

1. CheckIsValid → Verify IsOpen() and IsDatabaseLoaded()
2. CheckPathEmpty → Verify !path.empty()
3. CheckPathExists → Verify std::filesystem::exists(path)

libmagic Call

auto type_cstr = Detail::magic_file(m_cookie.get(), path.c_str());

See also

Magic::IdentifyFile()

IdentifyFiles()

IdentifyFileOptions

IdentifyFile() [2/2]

ExpectedFileTypeT Recognition::Magic::MagicPrivate::IdentifyFile ( const std::filesystem::path & path, IdentifyFileOptionsMaskT options, const std::nothrow_t & tag ) const

inlinenodiscardnoexcept

Identify a single file's type (noexcept version).

Non-throwing variant that returns a std::expected with either the file type or an error message.

Parameters

[in]	path	Path to the file to identify.
[in]	options	Validation options to check before identification.
[in]	tag	Pass std::nothrow to select this overload.

Returns

ExpectedFileTypeT containing file type on success, or error message on failure.

Error Handling

Returns std::unexpected with appropriate error message:

• MagicIsClosed::what() if instance not open
• MagicDatabaseNotLoaded::what() if database not loaded
• EmptyPath::what() if path is empty
• PathDoesNotExist::what() if file doesn't exist
• MagicIdentifyFileError::what() if magic_file() fails

See also

Magic::IdentifyFile(const std::filesystem::path&, const std::nothrow_t&)

ExpectedFileTypeT

IdentifyFiles() [1/2]

ExpectedFileTypeMapT Recognition::Magic::MagicPrivate::IdentifyFiles ( const DefaultFileContainerT & files, const std::nothrow_t & tag, IdentifyFileOptionsMaskT option, ProgressTrackerT progress_tracker ) const

inlinenodiscardnoexcept

Identify multiple files with progress tracking (noexcept).

Non-throwing variant that stores results as std::expected values, allowing per-file error handling without stopping the batch.

Parameters

[in]	files	Container of file paths to identify.
[in]	tag	Pass std::nothrow to select this overload.
[in]	option	Validation options to apply per file.
[in,out]	progress_tracker	Progress tracker to update.

Returns

Map from file paths to expected file type results.

Empty Path Handling

Files with empty paths are silently skipped (not added to result map). The CHECK_PATH_EMPTY_OPTION bit is cleared from options.

See also

Magic::IdentifyFiles(const Utility::FileContainer auto&, const std::nothrow_t&, ...)

ExpectedFileTypeMapT

IdentifyFiles() [2/2]

FileTypeMapT Recognition::Magic::MagicPrivate::IdentifyFiles ( const DefaultFileContainerT & files, IdentifyFileOptionsMaskT option, ProgressTrackerT progress_tracker ) const

inlinenodiscard

Identify multiple files with progress tracking (throwing).

Iterates over all files in the container, identifies each one, and updates the progress tracker as work completes.

Parameters

[in]	files	Container of file paths to identify.
[in]	option	Validation options to apply per file.
[in,out]	progress_tracker	Progress tracker to update.

Returns

Map from file paths to their identified types.

Progress Tracking

The progress tracker is:

1. Reset with the total file count
2. Advanced after each file identification
3. Marked as completed when all files are processed

Implementation

Uses std::ranges::for_each with Utility::AdvanceTracker RAII helper.

See also

Magic::IdentifyFiles()

IdentifyDirectoryPreliminaryChecks()

IdentifyContainerPreliminaryChecks()