Rhino C++ API  8.5
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
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_ContentHashContentHash () 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_wStringFullPath () const
 
const wchar_t * FullPathAsPointer () const
 
const ON_SHA1_HashFullPathHash () const
 
ON_FileReference::Status FullPathStatus () const
 
bool IsNotSet () const
 
bool IsSet () const
 
ON_FileReferenceoperator= (const ON_FileReference &)=default
 
bool Read (ON_BinaryArchive &archive)
 
const ON_ContentHashRecentContentHash (ON__UINT64 recent_time) const
 
const ON_wStringRelativePath () 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.