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:

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

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