## FileReference

Object Hierarchy | Related C++ Class: FileReference

### Inheritance

SIObject

FileReference

### Introduced

v5.0

### Description

This object represents a reference to a file on disk. When you specify a file location in a property page (for example, when you specify the image file for a texture map), the file path string is represented by a FileReference object.
The FileReference object uses two levels of path: the user path and the resolved path. You can access the user path using the FileReference.Path property, which can contain environment variables (using either the Windows syntax, %MY_VAR% or the Linux syntax, $MY_VAR) and can be relative to a project.
You can access the resolved path using the read-only FileReference.ResolvedPath property or the FileReference.UNCPath property, which represents the actual full path (as a local or a UNC path).
You can get FileReference objects from the FileReferenceCollection returned by Model.ExternalFiles and Scene.ExternalFiles.

### Methods

FileExists | GetFileInSequence | IsClassOf | IsEqualTo

### Properties

Application | Categories | FileType | FullName
GUID | Help | Name | NestedObjects
NumberOfFilesInSequence | Origin | OriginPath | Owners
Parent | Path | ResolvedPath | Type
UNCPath |  |  |

### Examples

#### JScript Example

    /*
            This example shows how to get the resolved path
            on each member of the external files list and how to
            change the path on the fly.
            Note: To see the UNC path in action, change the location
            of the NewFile variable to a valid UNC path
            (for example, "\\\\mymachine\\toto\\Man_Face.emdl") that is
            mapped to a drive letter (such as Q:) and rerun the example.
    */
    NewScene( null, false );
    // ---------------------------------------------------------------------------
    //      Setup
    //
    // First import a model so we have some external files to find
    var FPath = XSIUtils.BuildPath(
            Application.InstallationPath( siFactoryPath ),
            "Data", "XSI_SAMPLES", "Models", "Man_Face.emdl"
    );
    var oISIVTColl = ImportModel( FPath, null, true );
    // Now copy the reference-model file to a local directory
    var NewFile = "C:\\temp\\Man_Face.emdl";
    var fso = new ActiveXObject( "Scripting.FileSystemObject" );
    fso.CopyFile( FPath, NewFile, true );
    // ---------------------------------------------------------------------------
    //      Using the FileReference Object
    //
    // Get the collection of all external files on the scene
    var oModel = oISIVTColl.Value("Value");
    var l_extFileList = oModel.ExternalFiles;
    // Loop through the list and change only the
    // referenced model file to point to the one we put in c:\temp
    for ( var i=0; i<l_extFileList.Count; i++ ) {
            // Get the FileReference object and print the path
            printFileInfo( l_extFileList(i) );
            // Change the path to point to the temp directory
            if ( l_extFileList(i).FileType == "Models" ) {
                    // Make sure the original path exists, change it to
                    // the new one, and print the new path for confirmation
                    if ( l_extFileList(i).FileExists() ) {
                            var OldPath = l_extFileList(i).Path;
                            Application.LogMessage( "ORIGINAL PATH: " + OldPath );
                            l_extFileList(i).Path = NewFile;
                            Application.LogMessage( "MODIFIED PATH: " + l_extFileList(i).Path );
                            // Restore original name
                            l_extFileList(i).Path = OldPath;
                    }
            }
    }
    // ---------------------------------------------------------------------------
    //      Convenience function
    //
    function printFileInfo( in_file ) {
            try {
                    Application.LogMessage( Application.ClassName(in_file) );
            } catch(e) {
                    if ( typeof(in_file).toLowerCase() == "object" ) {
                            Application.LogMessage( in_file.FileType );
                    } else {
                            Application.LogMessage( typeof(in_file) );
                    }
            }
            if ( in_file.FileExists() ) {
                    // Get the original path
                    var o_path = in_file;
                    // Get the resolved path
                    var r_path = o_path.ResolvedPath;
                    // Get the UNC path
                    var u_path = o_path.UNCPath;
                    // Print all three results
                    Application.LogMessage( "ORIGINAL: " + o_path );
                    Application.LogMessage( "RESOLVED: " + r_path );
                    Application.LogMessage( "UNC     : " + u_path );
            } else {
                    Application.LogMessage( "Skipping non-existent file" );
            }
    }
    // ---------------------------------------------------------------------------
    //      OUTPUT
    //
    // INFO : FileReference
    // INFO : ORIGINAL: <factory_path>\Data\XSI_SAMPLES\Models\Man_Face.emdl
    // INFO : RESOLVED: <factory_path>\Data\XSI_SAMPLES\Models\Man_Face.emdl
    // INFO : UNC     : <factory_path>\Data\XSI_SAMPLES\Models\Man_Face.emdl
    // INFO : ORIGINAL PATH: <factory_path>\Data\XSI_SAMPLES\Models\Man_Face.emdl
    // INFO : MODIFIED PATH: C:\temp\Man_Face.emdl
    // INFO : FileReference
    // INFO : Skipping non-existent file