#include <opennurbs_file_utilities.h>

Public Types
enum	FindFilePreference : unsigned char { FindFilePreference::None = 0, FindFilePreference::FullPath = 1, FindFilePreference::RelativePath = 2, FindFilePreference::BasePath = 3, FindFilePreference::ContentMatch = 4, FindFilePreference::MostRecent = 5 }
	Defines options for file search. More...

enum	Status : unsigned int { Status::Unknown = 0, Status::FullPathValid = 1, Status::FileNotFound = 2 }
	Enumerates a list of file statuses. More...

Public Member Functions
	ON_FileReference ()=default

	ON_FileReference (const ON_FileReference &)=default

	ON_FileReference (const wchar_t full_path, const wchar_t relative_path, ON_ContentHash content_hash, ON_FileReference::Status full_path_status)

	~ON_FileReference ()=default

void	ClearContentHash ()

void	ClearFullPath ()

void	ClearRelativePath ()

const ON_ContentHash &	ContentHash () const

void	Dump (class ON_TextLog &text_log) const

ON_UUID	EmbeddedFileId () const

ON_FileReference::FindFilePreference	FindFile (const wchar_t *base_path, bool bBasePathIncludesFileName, ON_FileReference::FindFilePreference first_choice, ON_FileReference::FindFilePreference second_choice, ON_FileReference::FindFilePreference third_choice, ON_FileReference::FindFilePreference forth_choice, ON_FileReference::FindFilePreference fifth_choice, ON_wString &found_file_full_path) const
	Uses the full path, relative path and parameter information to find a full path to a file that exists. More...

ON_FileReference::FindFilePreference	FindFile (const wchar_t *base_path, bool bBasePathIncludesFileName, ON_wString &found_file_full_path) const
	Uses the full path, relative path and parameter information to find a full path to a file that exists. More...

ON_FileReference::FindFilePreference	FindFileAndUpdateReference (const wchar_t *base_path, bool bBasePathIncludesFileName, ON_FileReference::FindFilePreference first_choice, ON_FileReference::FindFilePreference second_choice, ON_FileReference::FindFilePreference third_choice, ON_FileReference::FindFilePreference forth_choice, ON_FileReference::FindFilePreference fifth_choice, bool bUpdateContentHash, ON_wString &found_file_full_path)
	The search for the file is identical to the one performed by find file. If a file is found, the full path setting in this reference is updated. More...

ON_FileReference::FindFilePreference	FindFileAndUpdateReference (const wchar_t *base_path, bool bBasePathIncludesFileName, bool bUpdateContentHash, ON_wString &found_file_full_path)
	The search for the file is identical to the one performed by find file. If a file is found, the full path setting in this reference is updated. More...

ON_FileReference::FindFilePreference	FindFileAndUpdateReference (const wchar_t *base_path, bool bBasePathIncludesFileName, bool bUpdateContentHash)

const ON_wString &	FullPath () const

const wchar_t *	FullPathAsPointer () const

const ON_SHA1_Hash &	FullPathHash () const

ON_FileReference::Status	FullPathStatus () const

bool	IsNotSet () const

bool	IsSet () const

ON_FileReference &	operator= (const ON_FileReference &)=default

bool	Read (ON_BinaryArchive &archive)

const ON_ContentHash &	RecentContentHash (ON__UINT64 recent_time) const

const ON_wString &	RelativePath () const

const wchar_t *	RelativePathAsPointer () const

void	SetContentHash (ON_ContentHash content_hash)

void	SetEmbeddedFileId (ON_UUID embedded_file_id)

void	SetFullPath (const wchar_t *full_path, bool bSetContentHash)

void	SetFullPath (const char *full_path, bool bSetContentHash)

void	SetFullPathStatus (ON_FileReference::Status full_path_status)

void	SetRelativePath (const wchar_t *relative_path)

void	SetRelativePath (const char *relative_path)

void	SetRelativePathFromBasePath (const wchar_t *base_path, bool bBasePathContainsFileName)

void	SetRelativePathFromBasePath (const char *base_path, bool bBasePathContainsFileName)

unsigned int	SizeOf () const

bool	UpdateContentHash ()

bool	Write (bool bUseArchiveDirectoryAsBasePath, ON_BinaryArchive &archive) const

bool	Write (const wchar_t *base_path, bool bBasePathIncludesFileName, ON_BinaryArchive &archive) const

Static Public Member Functions
static int	Compare (const ON_FileReference &a, const ON_FileReference &b)

static ON_FileReference	CreateFromFullPath (const wchar_t *full_path, bool bSetContentHash, bool bSetFullPathStatus)

static ON_FileReference::Status	StatusFromUnsigned (unsigned int full_path_status_as_unsigned)

Static Public Attributes
static const ON_FileReference	Unset

Member Enumeration Documentation

◆ FindFilePreference

enum ON_FileReference::FindFilePreference : unsigned char

strong

Defines options for file search.

Enumerator
None	The choice is not defined.
FullPath	File name exists in FullPath().
RelativePath	File name exists in base path + RelativePath().
BasePath	File name exists in base path directory.
ContentMatch	File with mathing content exists.
MostRecent	Most recently modifed file.

◆ Status

enum ON_FileReference::Status : unsigned int

strong

Enumerates a list of file statuses.

Enumerator
Unknown	Status of a the full path is not known.
FullPathValid	Full path is valid.
FileNotFound	Unable to locate file.

Constructor & Destructor Documentation

◆ ON_FileReference() [1/3]

ON_FileReference::ON_FileReference ( )

default

◆ ~ON_FileReference()

ON_FileReference::~ON_FileReference ( )

default

◆ ON_FileReference() [2/3]

ON_FileReference::ON_FileReference ( const ON_FileReference & )

default

◆ ON_FileReference() [3/3]

ON_FileReference::ON_FileReference	(	const wchar_t *	full_path,
		const wchar_t *	relative_path,
		ON_ContentHash	content_hash,
		ON_FileReference::Status	full_path_status
	)

Member Function Documentation

◆ ClearContentHash()

void ON_FileReference::ClearContentHash ( )

◆ ClearFullPath()

void ON_FileReference::ClearFullPath ( )

◆ ClearRelativePath()

void ON_FileReference::ClearRelativePath ( )

◆ Compare()

static int ON_FileReference::Compare	(	const ON_FileReference &	a,
		const ON_FileReference &	b
	)

static

◆ ContentHash()

const ON_ContentHash& ON_FileReference::ContentHash ( ) const

Returns: File content hash. This value is persistent, saved in 3dm archive, and could have been calculated a long time ago on a different computer.

◆ CreateFromFullPath()

static ON_FileReference ON_FileReference::CreateFromFullPath	(	const wchar_t *	full_path,
		bool	bSetContentHash,
		bool	bSetFullPathStatus
	)

static

◆ Dump()

void ON_FileReference::Dump ( class ON_TextLog & text_log ) const

◆ EmbeddedFileId()

ON_UUID ON_FileReference::EmbeddedFileId ( ) const

◆ FindFile() [1/2]

ON_FileReference::FindFilePreference ON_FileReference::FindFile	(	const wchar_t *	base_path,
		bool	bBasePathIncludesFileName,
		ON_FileReference::FindFilePreference	first_choice,
		ON_FileReference::FindFilePreference	second_choice,
		ON_FileReference::FindFilePreference	third_choice,
		ON_FileReference::FindFilePreference	forth_choice,
		ON_FileReference::FindFilePreference	fifth_choice,
		ON_wString &	found_file_full_path
	)		const

Uses the full path, relative path and parameter information to find a full path to a file that exists.

Parameters

base_path	[in] If base_path and RelativePath() are not empty, then path base_path+RelativePath(). If base_path is not empty, then base_path + filename is considered.
bBasePathIncludesFileName	[in] True if base_path contains a file name that must be removed to get a directory path.
first_choice	[in] When multiple files are found in different locations, the first_choice, second_choice, third_choice, forth_choice, and fifth_choice parameters are used to select which file is returned.
second_choice	[in] When multiple files are found in different locations, the first_choice, second_choice, third_choice, forth_choice, and fifth_choice parameters are used to select which file is returned.
third_choice	[in] When multiple files are found in different locations, the first_choice, second_choice, third_choice, forth_choice, and fifth_choice parameters are used to select which file is returned.
forth_choice	[in] When multiple files are found in different locations, the first_choice, second_choice, third_choice, forth_choice, and fifth_choice parameters are used to select which file is returned.
fifth_choice	[in] When multiple files are found in different locations, the first_choice, second_choice, third_choice, forth_choice, and fifth_choice parameters are used to select which file is returned.
full_path	[out] A full path to a file that exists. If FullPath() and base_path+RelativePath() resolve to different files, the content hash information is used to select the file.

Returns: If the file is found, then the returned ON_FileReference::FindFilePreference enum value indicates why it was selected. If the file is not found, then ON_FileReference::FindFilePreference::None is returned and full_path is empty.

The locations FullPath(), base_path+RelativePath(), and base_path+FileName() are tested. If multiple files are found, first_choice, second_choice, third_choice, forth_choice, and fifth_choice are used to select which file is returned.

◆ FindFile() [2/2]

ON_FileReference::FindFilePreference ON_FileReference::FindFile	(	const wchar_t *	base_path,
		bool	bBasePathIncludesFileName,
		ON_wString &	found_file_full_path
	)		const

Uses the full path, relative path and parameter information to find a full path to a file that exists.

Parameters

base_path	[in] If base_path and RelativePath() are not empty, then path base_path+RelativePath(). If base_path is not empty, then base_path + filename is considered.
bBasePathIncludesFileName	[in] True if base_path contains a file name that must be removed to get a directory path.

Returns: If the file is found, then the returned ON_FileReference::FindFilePreference enum value indicates why it was selected. If the file is not found, then ON_FileReference::FindFilePreference::None is returned and full_path is empty.

The locations FullPath(), base_path+RelativePath(), and base_path+FileName() are tested. If multiple files are found, the returned file is selected in the order relative path, full path, content match, base path and most recently modified. If you prefer a different order, use the version of ON_FileReference::FindFile with 5 ON_FileReference::FindFilePreference parameters.

◆ FindFileAndUpdateReference() [1/3]

ON_FileReference::FindFilePreference ON_FileReference::FindFileAndUpdateReference	(	const wchar_t *	base_path,
		bool	bBasePathIncludesFileName,
		ON_FileReference::FindFilePreference	first_choice,
		ON_FileReference::FindFilePreference	second_choice,
		ON_FileReference::FindFilePreference	third_choice,
		ON_FileReference::FindFilePreference	forth_choice,
		ON_FileReference::FindFilePreference	fifth_choice,
		bool	bUpdateContentHash,
		ON_wString &	found_file_full_path
	)

The search for the file is identical to the one performed by find file. If a file is found, the full path setting in this reference is updated.

◆ FindFileAndUpdateReference() [2/3]

ON_FileReference::FindFilePreference ON_FileReference::FindFileAndUpdateReference	(	const wchar_t *	base_path,
		bool	bBasePathIncludesFileName,
		bool	bUpdateContentHash,
		ON_wString &	found_file_full_path
	)

The search for the file is identical to the one performed by find file. If a file is found, the full path setting in this reference is updated.

◆ FindFileAndUpdateReference() [3/3]

ON_FileReference::FindFilePreference ON_FileReference::FindFileAndUpdateReference	(	const wchar_t *	base_path,
		bool	bBasePathIncludesFileName,
		bool	bUpdateContentHash
	)

◆ FullPath()

const ON_wString& ON_FileReference::FullPath ( ) const

◆ FullPathAsPointer()

const wchar_t* ON_FileReference::FullPathAsPointer ( ) const

◆ FullPathHash()

const ON_SHA1_Hash& ON_FileReference::FullPathHash ( ) const

Returns: ON_SHA1_Hash::FileSystemPathHash(FullPath());

The value of the hash is saved in a runtime cache so using this function when comparing paths is efficient when multple compares are required.

See also: ON_NameHash::CreateFilePathHash( ON_FileReference& file_reference );

◆ FullPathStatus()

ON_FileReference::Status ON_FileReference::FullPathStatus ( ) const

◆ IsNotSet()

bool ON_FileReference::IsNotSet ( ) const

Returns: True if FullPath() is empty.

◆ IsSet()

bool ON_FileReference::IsSet ( ) const

Returns: True if FullPath() is not empty.

◆ operator=()

ON_FileReference& ON_FileReference::operator= ( const ON_FileReference & )

default

◆ Read()

bool ON_FileReference::Read ( ON_BinaryArchive & archive )

Calling Read() sets m_full_path_status = ON_FileReference::Status::Unknown, even if that was not the status when Write() was called.

◆ RecentContentHash()

const ON_ContentHash& ON_FileReference::RecentContentHash ( ON__UINT64 recent_time ) const

Parameters

recent_time [in] The time, in number of seconds since January 1, 1970 UTC, to use when deciding what content hashes can be considered recent. If recent_time is 0 or in the future, then the current value of ON_SecondsSinceJanOne1970UTC() is used. Typically this parameter is the value of ON_SecondsSinceJanOne1970UTC() at the beginning of a calculation durint which any referenced files will not be changed.

Returns: A file content hash value calculated on or after a specified time in the current instance of the application. This value is used to detect changed files in the current instance of the application. It is cached for performance reasons. This value is never saved in 3dm files.

◆ RelativePath()

const ON_wString& ON_FileReference::RelativePath ( ) const

◆ RelativePathAsPointer()

const wchar_t* ON_FileReference::RelativePathAsPointer ( ) const

◆ SetContentHash()

void ON_FileReference::SetContentHash ( ON_ContentHash content_hash )

◆ SetEmbeddedFileId()

void ON_FileReference::SetEmbeddedFileId ( ON_UUID embedded_file_id )

◆ SetFullPath() [1/2]

void ON_FileReference::SetFullPath	(	const wchar_t *	full_path,
		bool	bSetContentHash
	)

◆ SetFullPath() [2/2]

void ON_FileReference::SetFullPath	(	const char *	full_path,
		bool	bSetContentHash
	)

◆ SetFullPathStatus()

void ON_FileReference::SetFullPathStatus ( ON_FileReference::Status full_path_status )

◆ SetRelativePath() [1/2]

void ON_FileReference::SetRelativePath ( const wchar_t * relative_path )

◆ SetRelativePath() [2/2]

void ON_FileReference::SetRelativePath ( const char * relative_path )

◆ SetRelativePathFromBasePath() [1/2]

void ON_FileReference::SetRelativePathFromBasePath	(	const wchar_t *	base_path,
		bool	bBasePathContainsFileName
	)

◆ SetRelativePathFromBasePath() [2/2]

void ON_FileReference::SetRelativePathFromBasePath	(	const char *	base_path,
		bool	bBasePathContainsFileName
	)

◆ SizeOf()

unsigned int ON_FileReference::SizeOf ( ) const

◆ StatusFromUnsigned()

static ON_FileReference::Status ON_FileReference::StatusFromUnsigned ( unsigned int full_path_status_as_unsigned )

static

◆ UpdateContentHash()

bool ON_FileReference::UpdateContentHash ( )

◆ Write() [1/2]

bool ON_FileReference::Write	(	bool	bUseArchiveDirectoryAsBasePath,
		ON_BinaryArchive &	archive
	)		const

Parameters

bUseArchiveBasePath [in] If bUseArchiveBasePath is true and a file is being written, then the base path of the file being written use used as the base path to calculate the relative path. If bUseArchiveBasePath is false, then the current value of RelativePath() is saved in the archive.

◆ Write() [2/2]

bool ON_FileReference::Write	(	const wchar_t *	base_path,
		bool	bBasePathIncludesFileName,
		ON_BinaryArchive &	archive
	)		const

Parameters

base_path [in] If base_path is not empty, then the relative path saved in the archive will be calculated from FullPath() and base_path. If base_path is nullptr or empty, then RelativePath() is saved in the archive.

Member Data Documentation

◆ Unset

const ON_FileReference ON_FileReference::Unset

static

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Member Enumeration Documentation

◆ FindFilePreference

◆ Status

Constructor & Destructor Documentation

◆ ON_FileReference() [1/3]

◆ ~ON_FileReference()

◆ ON_FileReference() [2/3]

◆ ON_FileReference() [3/3]

Member Function Documentation

◆ ClearContentHash()

◆ ClearFullPath()

◆ ClearRelativePath()

◆ Compare()

◆ ContentHash()

◆ CreateFromFullPath()

◆ Dump()

◆ EmbeddedFileId()

◆ FindFile() [1/2]

◆ FindFile() [2/2]

◆ FindFileAndUpdateReference() [1/3]

◆ FindFileAndUpdateReference() [2/3]

◆ FindFileAndUpdateReference() [3/3]

◆ FullPath()

◆ FullPathAsPointer()

◆ FullPathHash()

◆ FullPathStatus()

◆ IsNotSet()

◆ IsSet()

◆ operator=()

◆ Read()

◆ RecentContentHash()

◆ RelativePath()

◆ RelativePathAsPointer()

◆ SetContentHash()

◆ SetEmbeddedFileId()

◆ SetFullPath() [1/2]

◆ SetFullPath() [2/2]

◆ SetFullPathStatus()

◆ SetRelativePath() [1/2]

◆ SetRelativePath() [2/2]

◆ SetRelativePathFromBasePath() [1/2]

◆ SetRelativePathFromBasePath() [2/2]

◆ SizeOf()

◆ StatusFromUnsigned()

◆ UpdateContentHash()

◆ Write() [1/2]

◆ Write() [2/2]

Member Data Documentation

◆ Unset