FileReference Class Reference

---

Detailed Description

The FileReference class represents a reference to a file on disk.

When the user specifies the location of a file in a property page (for example, specifying the image file to use on a texture map) the string location is represented by the FileReference. This class uses two levels of path:

• the user path
• the resolved path

You can access the user path using the FileReference::GetPath function and it can contain environment variables and be relative to a project.

You can access the resolved path using either FileReference::GetResolvedPath or the FileReference::GetUNCPath which represents the actual full path (as a local or UNCPath).

See also:

Model::GetExternalFiles, Scene::GetExternalFiles

Since:

5.0

#include <xsi_filereference.h>

Inheritance diagram for FileReference:

List of all members.

Public Member Functions
	FileReference ()
	~FileReference ()
	FileReference (const CRef &in_ref)
	FileReference (const FileReference &in_obj)
bool	IsA (siClassID in_ClassID) const
siClassID	GetClassID () const
FileReference &	operator= (const FileReference &in_obj)
FileReference &	operator= (const CRef &in_ref)
CString	GetName () const
CString	GetPath ()
CStatus	PutPath (const CString &in_Path)
CString	GetFileType () const
CString	GetResolvedPath () const
bool	FileExists () const
CString	GetUNCPath () const
CString	GetGUID () const
CRefArray	GetOwners () const
ULONG	GetNumberOfFilesInSequence () const
CString	GetFileInSequence (ULONG in_iIndex) const

---

Constructor & Destructor Documentation

FileReference

(

)

Default constructor.

~FileReference

(

)

Default destructor.

FileReference

(

const CRef &

in_ref

)

Constructor.

Parameters:

in_ref

constant reference object.

FileReference

(

const FileReference &

in_obj

)

Copy constructor.

Parameters:

in_obj

constant class object.

---

Member Function Documentation

bool IsA

(

siClassID

in_ClassID

)

const [virtual]

Returns true if a given class type is compatible with this API class.

Parameters:

in_ClassID

class type.

Returns:

true if the class is compatible, false otherwise.

Reimplemented from SIObject.

siClassID GetClassID

(

)

const [virtual]

Returns the type of the API class.

Returns:

The class type.

Reimplemented from SIObject.

FileReference& operator=

(

const FileReference &

in_obj

)

Creates an object from another object. The newly created object is set to empty if the input object is not compatible.

Parameters:

in_obj

constant class object.

Returns:

The new FileReference object.

FileReference& operator=

(

const CRef &

in_ref

)

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:

in_ref

constant class object.

Returns:

The new FileReference object.

Reimplemented from SIObject.

CString GetName

(

)

const

Returns the name of the item.

Returns:

The resolved path of the file (see FileReference::GetResolvedPath).

Reimplemented from SIObject.

CString GetPath

(

)

Returns the user path of the file object. The user path can contain environment variables specified with either $ or % (for example, $USERNAME on Linux and %USERNAME% on Windows).

This function supports relative paths (relative to the project, the factory or the user location).

Returns:

The user path.

See also:

Linktab

CStatus PutPath

(

const CString &

in_Path

)

Sets the user path. The user path can contain environment variables specified with either $ or % (for example, $USERNAME on Linux and %USERNAME% on Windows).

This function supports relative paths (relative to the project, the factory or the user location).

Parameters:

in_Path

The user path to set.

Returns:

Success or failure of the operation

See also:

Linktab

CString GetFileType

(

)

const

Returns the type of file. The different types include models, pictures, audio, actions, scripts, simulation, queries, and synoptic.

Note:

The type is also used as the directory name when copying files locally to the project.

Returns:

The file type.

CString GetResolvedPath

(

)

const

Returns the resolved path of this file object. If the path is on a local drive or is on a shared network resource mapped to a drive letter, the local path or drive letter is returned; otherwise, the UNCPath is returned.

Note:

In the case of an image sequence, the resolved path will not be a valid file but rather the symbolic name for the sequence. For example:

 c:\images\mysequence.[1..10].pic 

Tip:

To get a specific file use FileReference::GetFileInSequence and FileReference::GetNumberOfFilesInSequence.

Returns:

The resolved path.

bool FileExists

(

)

const

Checks whether the file is valid or not.

Returns:

True if the file exists

CString GetUNCPath

(

)

const

Returns the resolved path of this file object. If the path is on a local drive, the local path is returned; otherwise, the UNCPath is returned.

Returns:

The UNCPath.

CString GetGUID

(

)

const

Returns the GUID of the path. The GUID is a unique identifier for the dynamic life of a path. It should be used to retrieve a handle on the path object when dealing with the external file list.

Note:

The GUID may change if the filename changes or when reloading the scene.

Returns:

The GUID as a CString.

CRefArray GetOwners

(

)

const

Returns the list of objects within the scene that reference this file path. Usually there is only one owner: the Parameter containing the Source (the audio or image file, etc).

Returns:

Array of references to the owners.

ULONG GetNumberOfFilesInSequence

(

)

const

Returns the number of files that this sequence of files contains. If the sequence consists of only one file, this property returns 1.

A file sequence is a set of multiple files with the same base name, such as myfile.1.pic, myfile.2.pic, etc. When rendering to disk, Softimage creates file sequences based on a base filename that you provide in the Render Options property page and when browsing the output folder, Softimage displays file sequences as a single entity with an annotation like: myfile[1..2].pic.

Returns:

The number of files in the file sequence.

Since:

5.0

CString GetFileInSequence

(

ULONG

in_iIndex

)

const

Returns the resolved path of the specified file in the file sequence.

A file sequence is a set of multiple files with the same base name, such as myfile.1.pic, myfile.2.pic, etc. When rendering to disk, Softimage creates file sequences based on a base filename that you provide in the Render Options property page and when browsing the output folder, Softimage displays file sequences as a single entity with an annotation like: myfile[1..2].pic.

Parameters:

in_iIndex

The zero-based index of the desired file.

Note:

If the index greater than the number of files in the sequence, an error is returned

Returns:

The resolved path if the file is not a sequence and the specified index is 0

Error if the specified index is greater than 0

Empty path and an error if the specified index is out of bounds

Since:

5.0

---

The documentation for this class was generated from the following file:

• xsi_filereference.h