Public Member Functions
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:

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:
Inheritance graph
[legend]

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

Default constructor.

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: