ON_FileReference Class Reference

#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 }
enum	Status : unsigned int { Status::Unknown = 0, Status::FullPathValid = 1, Status::FileNotFound = 2 }

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
ON_FileReference::FindFilePreference	FindFile (const wchar_t *base_path, bool bBasePathIncludesFileName, ON_wString &found_file_full_path) const
ON_FileReference::FindFilePreference	FindFileAndUpdateReference (const wchar_t *base_path, bool bBasePathIncludesFileName, bool bUpdateContentHash)
ON_FileReference::FindFilePreference	FindFileAndUpdateReference (const wchar_t *base_path, bool bBasePathIncludesFileName, bool bUpdateContentHash, ON_wString &found_file_full_path)
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)
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 char *full_path, bool bSetContentHash)
void	SetFullPath (const wchar_t *full_path, bool bSetContentHash)
void	SetFullPathStatus (ON_FileReference::Status full_path_status)
void	SetRelativePath (const char *relative_path)
void	SetRelativePath (const wchar_t *relative_path)
void	SetRelativePathFromBasePath (const char *base_path, bool bBasePathContainsFileName)
void	SetRelativePathFromBasePath (const wchar_t *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)
	summary>Defines options for file search. More...
static ON_FileReference::Status	StatusFromUnsigned (unsigned int full_path_status_as_unsigned)

Static Public Attributes
static const ON_FileReference	Unset
	summary>Enumerates a list of file statuses. More...

Member Enumeration Documentation

FindFilePreference

enum ON_FileReference::FindFilePreference : unsigned char

strong

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

Status

enum ON_FileReference::Status : unsigned int

strong

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

summary>Defines options for file search.

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

Description: 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. Remarks: 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

Description: 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. Remarks: 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,
		bool	bUpdateContentHash
	)

FindFileAndUpdateReference() [2/3]

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

Description: 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,
		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
	)

Description: 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.

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()); Remarks: The value of the hash is saved in a runtime cache so using this function when comparing paths is efficient when multiple 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

)

Remarks: 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

Returns: 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 char *	full_path,
		bool	bSetContentHash
	)

SetFullPath() [2/2]

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

SetFullPathStatus()

void ON_FileReference::SetFullPathStatus

(

ON_FileReference::Status

full_path_status

)

SetRelativePath() [1/2]

void ON_FileReference::SetRelativePath

(

const char *

relative_path

)

SetRelativePath() [2/2]

void ON_FileReference::SetRelativePath

(

const wchar_t *

relative_path

)

SetRelativePathFromBasePath() [1/2]

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

SetRelativePathFromBasePath() [2/2]

void ON_FileReference::SetRelativePathFromBasePath	(	const wchar_t *	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

summary>Enumerates a list of file statuses.