#include <MFileObject.h>

Class Description

Manipulate filenames and search paths.

The MFileObject class implements an object that contains both a filename and a search path. The search path is specified by a single string in which multiple elements are separated by ':' characters. As well this string can contain Unix environment variables, specified as $VARNAME,

Filenames can be produced by the class by combining the path element with the filename element of the MFileObject. As well, methods are available to test for the existance of the files produced.

Examples:: AbcBullet/AbcBullet.cpp, AbcExport/AbcExport.cpp, AbcImport/AbcImport.cpp, AbcImport/AlembicImportFileTranslator.cpp, AbcImport/AlembicImportFileTranslator.h, AbcImport/AlembicNode.cpp, animExportUtil/animExportUtil.cpp, animExportUtil/animExportUtil.h, animImportExport/animImportExport.cpp, animImportExport/animImportExport.h, atomImportExport/atomImportExport.cpp, atomImportExport/atomImportExport.h, autoLoader/moduleLogic.cpp, cgFx/cgfxFindImage.cpp, cgFx/cgfxTextureCache.cpp, colorTransformData/colorTransformData.cpp, dx11Shader/dx11Shader.cpp, dx11Shader/dx11ShaderCompileHelper.cpp, filteredAsciiFile/filteredAsciiFile.cpp, glslShader/GLSLShader.cpp, gpuCache/CacheReader.cpp, gpuCache/CacheReader.h, gpuCache/CacheReaderAlembic.cpp, gpuCache/CacheReaderAlembic.h, gpuCache/CacheWriter.cpp, gpuCache/CacheWriter.h, gpuCache/CacheWriterAlembic.cpp, gpuCache/CacheWriterAlembic.h, gpuCache/gpuCacheCmd.cpp, gpuCache/gpuCacheCmd.h, gpuCache/gpuCacheShapeNode.cpp, hlslShader/hlslShader.cpp, hwApiTextureTest/hwApiTextureTest.cpp, lepTranslator/lepTranslator.cpp, maTranslator/maTranslator.cpp, MayaPluginForSpreticle/spReticleLoc.cpp, MetadataSample/metadataBase.cpp, MetadataSample/metadataBase.h, objExport/objExport.cpp, polyRawExporter/polyExporter.cpp, polyRawExporter/polyExporter.h, polyX3DExporter/polyExporter.cpp, polyX3DExporter/polyExporter.h, and rawfootPrintNode/rawfootPrintNode.cpp.

Public Types
enum	MFileResolveMethod { kNone = (1<<0), kExact = (1<<1), kDirMap = (1<<2), kReferenceMappings = (1<<3), kRelative = (1<<4), kBaseName = (1<<5), kInputFile = kExact \| kDirMap \| kRelative \| kBaseName, kInputReference = kInputFile \| kReferenceMappings, kStrict = kExact \| kDirMap }
	Options to be used when resolving a file path. More...

Public Member Functions
	MFileObject ()
	Class constructor. More...

	MFileObject (const MFileObject &other)
	Copy constructor. More...

virtual	~MFileObject ()
	Class destructor.

MFileObject &	operator= (const MFileObject &other)
	Assignment operator. More...

MStatus	setRawName (const MString &fileName)
	Set the unresolved filename element of the MFileObject instance. More...

MStatus	setRawPath (const MString &filePath)
	Set the unresolved path element of the MFileObject instance. More...

MStatus	setRawFullName (const MString &fullFileName)
	This method combines the functions of the setRawName and setRawPath methods in that it sets both the path and filename from the given name. More...

MStatus	setRawURI (const MString &uri)
	Set the unresolved URI of the MFileObject instance from a string. More...

MStatus	setRawURI (const MURI &uri)
	Set the unresolved URI of the MFileObject instance. More...

MStatus	overrideResolvedFullName (const MString &fullFileName)
	Normally when a raw file name is set, Maya will perform a series of operations on it in an attempt to resolve it to a valid file name. More...

MString	rawName () const
	Returns the unresolved filename element of the MFileObject. More...

MString	rawPath () const
	Returns the path element of the MFileObject with all environment variables unexpanded. More...

MString	rawFullName () const
	Returns the unresolved full file name (path plus filename) of the MFileObject with all environment variables unexpanded. More...

MURI	rawURI () const
	Returns the unresolved URI of the MFileObject, if any. More...

MString	expandedPath () const
	Returns the raw path element of the unresolved MFileObject with all environment variables expanded. More...

MString	expandedFullName () const
	Returns the pathname of a file constructed from the unresolved MFileObject values. More...

MString	resolvedName () const
	Returns the resolved filename element of the MFileObject. More...

MString	resolvedPath () const
	Returns the resolved path element of the MFileObject. More...

MString	resolvedFullName () const
	Returns the first pathname of a file constructed from the path and filename elements. More...

unsigned int	pathCount ()
	Returns the number of paths in the path element of the MFileObject. More...

MString	ithPath (unsigned int index)
	Returns the indicated portion of the path element of the MFileObject. More...

MString	ithFullName (unsigned int index)
	Returns the pathname of a file constructed from the indicated portion of the path element and filename element. More...

bool	exists ()
	Checks to see if the file returned by the fullName method exists and is readable. More...

bool	exists (unsigned int index)
	Checks to see if the file constructed from the indicated portion of the path element and filename element exists and is readable. More...

bool	isSet () const
	Checks to see if both file and path elements of the MFileObject have been set. More...

void	setResolveMethod (MFileResolveMethod method)
	Set the steps that should be used to resolve this file path. More...

MFileResolveMethod	resolveMethod () const
	Returns the file-path resolution steps this object will use. More...

MStatus	setName (const MString &fileName)
	This method is obsolete. More...

MStatus	setFullName (const MString &fileName)
	This method is obsolete. More...

MString	name () const
	This method is obsolete. More...

MString	path () const
	This method is obsolete. More...

MString	fullName () const
	This method is obsolete. More...

Static Public Member Functions
static bool	isAbsolutePath (const MString &fileName)
	Utility method which checks a file path string and determines if it represents an absolute file path. More...

static MString	getResolvedFullName (const MString &rawFullName)
	This is a static convenience method for performing a straightforward resolve of a file path. More...

static MString	getResolvedFullName (const MString &rawFullName, bool &exists, MFileObject::MFileResolveMethod method=MFileObject::kNone)
	This is a static convenience method for performing a straightforward resolve of a file path. More...

Member Enumeration Documentation

enum MFileResolveMethod

Options to be used when resolving a file path.

When more than one resolve method is used, Maya will perform checks in a pre-determined sequence, stopping when it encounters an existing file. The default mode MFileResolveMethod::kNone cannot be used in combination with other modes. Note that not all resolve methods check whether or not a file actually exists. Some resolution modes, such as MFileResolveMethod::kInputFile, imply that the file is being used for input, and is expected to exist. These modes will check if the file exists to determine whether or not the resolution is successful.

Enumerator
kNone	(Default) The resolved path is simply the resulting path after converting the raw value to its expanded form. If the path contains environment variables, the resolved value will be the first path returned from their expansion. Relative paths will be considered to be relative to root of the current project. The resolution algorithm will not check if this file actually exists - the resolution will be considered successful whether it exists or not. With this mode, the resolver will not continue on to attempt to resolve using any other resolve method. The user must explicitly check MFileObject::exists() to determine if it is an existing path.
kExact	Checks if expanded paths exist. If paths are relative, assume it's relative to the current workspace (so check workspace current directory, file-rule directory and root directory)
kDirMap	Checks path against mappings defined with the dirmap command. Only for absolute paths.
kReferenceMappings	Check path against any previously re-mapped reference locations. If kRelative/kBaseName are set, then even if we have an absolute path, convert to relative and/or baseName and look for them in directories provided to the missing reference dialog.
kRelative	Strips away the project directory, and treats path as relative. Relative to the current workspace, that is. So look in the workspace current directory, file-rules directory and the root directory
kBaseName	Strips away everything but the base file name and look in the current workspace.
kInputFile	This mode is the default on file open and import, and is suitable for files that are to be used as input files. The file will be checked for existence.
kInputReference	This mode is the default on file reference. In addition to the checks done for a regular input file, it will also check the reference mappings.
kStrict	Equivalent to the file -strict flag.

Constructor & Destructor Documentation

MFileObject ( )

Class constructor.

Create a new MFileObject that contains neither a path nor a filename.

MFileObject ( const MFileObject & other )

Copy constructor.

Create a new MFileObject instance and initialize it with the same path and filename as the given instance.

Parameters

[in] other The MFileObject to copy.

Member Function Documentation

MFileObject & operator= ( const MFileObject & other )

Assignment operator.

Allows assignment between MFileObjects.

Parameters

[in] other Existing MFileObject to be assigned to this one.

Returns: Reference to this MFileObject instance.

MStatus setRawName ( const MString & fileName )

Set the unresolved filename element of the MFileObject instance.

This name should not contain any '/' characters, it should indicate simply the name of a file. The directories in which this name will be searched for are specified by setRawPath.

Parameters

[in] fileName The filename to set.

Returns: MS::kSuccess

Examples:: autoLoader/moduleLogic.cpp.

MStatus setRawPath ( const MString & pathName )

Set the unresolved path element of the MFileObject instance.

This should contain a list of directories, each separated by a single ':' character. The pathnames can contain Unix environment variables in the form $VARNAME. These will be expanded when paths to actual filenames are constructed.

Note that if the specified pathName is relative, contains environment variables, or does not exist, the paths returned by MFileObject::resolvedPath() and MFileObject::expandedPath() may not match the rawPath. See the description of MFileObject::resolvedPath() and MFileObject::expandedPath() for more information.

Parameters

[in] pathName The path string.

Returns: MS::kSuccess

Examples:: autoLoader/moduleLogic.cpp.

MStatus setRawFullName ( const MString & fullFileName )

This method combines the functions of the setRawName and setRawPath methods in that it sets both the path and filename from the given name.

If any '/' characters appear in the given name then the path element of the MFileObject is set to everything in name up to, but not including the last '/'. The filename is set to the part of name after the final '/'.

If no '/' characters appear in the given name then the path element is set to "." and the filename is set to the given name.

Note that if the specified fullFileName is relative, contains environment variables, or does not exist, the full names returned by MFileObject::resolvedFullName() and MFileObject::expandedFullName() may not match the fullFileName. See the description of MFileObject::resolvedFullName() and MFileObject::expandedFullName() for more information.

Also note that for URI-based file paths (e.g. "arrow:uri_path_to_file"), setRawFullName will not call setRawName and setRawPath (raw name and path will remain empty). Use resolvedName and resolvedPath to retrieve the resolved file path, or rawFullName to retrieve the unresolved file path.

Parameters

[in] fullFileName the string used to initialize the path and filename.

Returns: MS::kSuccess

Examples:: AbcBullet/AbcBullet.cpp, AbcExport/AbcExport.cpp, AbcImport/AbcImport.cpp, AbcImport/AlembicNode.cpp, cgFx/cgfxFindImage.cpp, cgFx/cgfxTextureCache.cpp, dx11Shader/dx11Shader.cpp, dx11Shader/dx11ShaderCompileHelper.cpp, glslShader/GLSLShader.cpp, gpuCache/CacheReader.cpp, gpuCache/gpuCacheCmd.cpp, gpuCache/gpuCacheShapeNode.cpp, hlslShader/hlslShader.cpp, and rawfootPrintNode/rawfootPrintNode.cpp.

MStatus setRawURI ( const MString & uri )

Set the unresolved URI of the MFileObject instance from a string.

This is equivalent to constructing an MURI from the string and calling the other form of setRawURI().

See the description of MURI for information on URIs.

Parameters

[in] uri The URI string.

Returns: MS::kSuccess

MStatus setRawURI ( const MURI & uri )

Set the unresolved URI of the MFileObject instance.

See the description of MURI for information on URIs.

Parameters

[in] uri The URI object.

Returns: MS::kSuccess

MStatus overrideResolvedFullName ( const MString & fullFileName )

Normally when a raw file name is set, Maya will perform a series of operations on it in an attempt to resolve it to a valid file name.

This final resolved file name can be accessed through the MFileObject::resolvedName(), MFileObject::resolvedPath(), and MFileObject::resolvedFullFileName() methods and can be quite different from the originally specified raw file name.

This method will override the normal Maya path resolution process and explicitly set the resolved file name. This path does not have to be a valid file path, but if any '/' characters appear in the given name then the resolved path element of the MFileObject is set to everything in name up to, but not including the last '/'. The resolved filename is set to the part of name after the final '/'.

Once the resolved file name is set, it is only guaranteed to be retained in the MFileObject so long as the raw file path is not updated. Once MFileObject::setRawPath(), MFileObject::setRawName(), or MFileObject::setRawFullName() is called, the normal Maya path resolution process will be re-invoked and the resolved path and filename will be updated.

Parameters

[in] fullFileName the string used to override the path and filename.

Returns: MS::kSuccess

MString rawName ( ) const

Returns the unresolved filename element of the MFileObject.

Returns: The unresolved filename.

MString rawPath ( ) const

Returns the path element of the MFileObject with all environment variables unexpanded.

Returns: The path.

Examples:: glslShader/GLSLShader.cpp.

MString rawFullName ( ) const

Returns the unresolved full file name (path plus filename) of the MFileObject with all environment variables unexpanded.

This routine differs from MFileObject::expandedFullName() in that it returns the unexpanded instead of expanded values.

Returns: The full, unresolved file path.

Examples:: AbcImport/AlembicNode.cpp, and gpuCache/CacheReaderAlembic.cpp.

MURI rawURI ( ) const

Returns the unresolved URI of the MFileObject, if any.

This will be empty if the MFileObject was not resolved from a URI.

Returns: The unresolved URI.

MString expandedPath ( ) const

Returns the raw path element of the unresolved MFileObject with all environment variables expanded.

In the case that the path expands to multiple paths, the first expanded path will be returned.

After expanding environment variables Maya may perform additional modifications to the path in order to resolve it to a valid location on disk. This resolved path can be accessed through MFileObject::resolvedPath().

Returns: The expanded path.

MString expandedFullName ( ) const

Returns the pathname of a file constructed from the unresolved MFileObject values.

The file name will consist of the the expanded raw path and raw name elements. All variables in the path element are expanded, and the first path (the part before the first separator (':') in the path) is prepended to the filename element to construct the fullName.

After expanding environment variables Maya may perform additional modifications to the full file name in order to resolve it to a valid location on disk. This resolved full file name can be accessed through MFileObject::resolvedFullName().

This routine differs from MFileObject::rawFullName() in that it returns the expanded instead of unexpanded values.

Returns: The expanded filename.

Examples:: AbcBullet/AbcBullet.cpp, AbcExport/AbcExport.cpp, and AbcImport/AbcImport.cpp.

MString resolvedName ( ) const

Returns the resolved filename element of the MFileObject.

Returns: The resolved filename.

Examples:: autoLoader/moduleLogic.cpp, and dx11Shader/dx11Shader.cpp.

MString resolvedPath ( ) const

Returns the resolved path element of the MFileObject.

In order to build the resolved path, Maya first expands all environment variables and then may perform additional modifications, such as prepending directories to a relative path name, in order to resolve the path to a valid location on disk.

Returns: The resolved path.

Examples:: autoLoader/moduleLogic.cpp, cgFx/cgfxFindImage.cpp, gpuCache/gpuCacheCmd.cpp, and hlslShader/hlslShader.cpp.

MString resolvedFullName ( ) const

Returns the first pathname of a file constructed from the path and filename elements.

All variables in the path element are expanded, and the first path (the part before the first ':' in the path) is prepended to the filename element. After expanding all environment variables Maya may then perform additional modifications, such as prepending directories to a relative path name, in order to resolve the path to a valid location on disk.

The resolution is performed using the ResolveMethod of the MFileObject. By default, this will be set to MFileObject::kNone. While this is suitable in many situations, it may not be appropriate if the file is expected to exist. Refer to MFileObject::MFileResolveMethod for more information about how the resolution mode is used.

Failure to resolve the path according to the specifications of the MFileObject will result in an empty return value.

Returns: The full path to the resolved file, or an empty string if the resolution was unsuccessful.

Examples:: AbcBullet/AbcBullet.cpp, AbcExport/AbcExport.cpp, AbcImport/AbcImport.cpp, AbcImport/AlembicImportFileTranslator.cpp, AbcImport/AlembicNode.cpp, gpuCache/CacheReader.cpp, gpuCache/CacheReaderAlembic.cpp, gpuCache/CacheWriterAlembic.cpp, gpuCache/gpuCacheCmd.cpp, gpuCache/gpuCacheShapeNode.cpp, and rawfootPrintNode/rawfootPrintNode.cpp.

unsigned int pathCount ( )

Returns the number of paths in the path element of the MFileObject.

This will be equal to one more than the number of ':' characters specified by the setRawPath method.

Returns: The number of path elements.

MString ithPath ( unsigned int index )

Returns the indicated portion of the path element of the MFileObject.

All variables in the path element are expanded, and the portion indicated by the argument is extracted and returned.

Parameters

[in] index the index of the desired path portion.

Returns: The path element.

MString ithFullName ( unsigned int index )

Returns the pathname of a file constructed from the indicated portion of the path element and filename element.

All variables in the path element are expanded, and the indicated path portion is prepended to the filename element to construct the fullName.

Parameters

[in] index the index of the desired path portion.

Returns: The pathname.

bool exists ( )

Checks to see if the file returned by the fullName method exists and is readable.

Returns: true if the file exists and is readable, false otherwise.

Examples:: AbcBullet/AbcBullet.cpp, AbcExport/AbcExport.cpp, AbcImport/AbcImport.cpp, autoLoader/moduleLogic.cpp, dx11Shader/dx11ShaderCompileHelper.cpp, gpuCache/gpuCacheCmd.cpp, and rawfootPrintNode/rawfootPrintNode.cpp.

bool exists ( unsigned int index )

Checks to see if the file constructed from the indicated portion of the path element and filename element exists and is readable.

Parameters

[in] index Index of the path element to be used in searching for the file.

Returns: true if the file exists and is readable, false otherwise.

bool isSet ( ) const

Checks to see if both file and path elements of the MFileObject have been set.

Returns: true if both elements have been set, false otherwise.

void setResolveMethod ( MFileResolveMethod method )

Set the steps that should be used to resolve this file path.

Parameters

[in] method Structure indicating how to resolve the file path.

Examples:: AbcImport/AbcImport.cpp, AbcImport/AlembicImportFileTranslator.cpp, gpuCache/CacheReader.cpp, gpuCache/gpuCacheCmd.cpp, gpuCache/gpuCacheShapeNode.cpp, hlslShader/hlslShader.cpp, and rawfootPrintNode/rawfootPrintNode.cpp.

MFileObject::MFileResolveMethod resolveMethod ( ) const

Returns the file-path resolution steps this object will use.

Returns: Resolution method

MStatus setName ( const MString & fileName )

This method is obsolete.

Deprecated:: Use the method MFileObject::setRawName instead.

Set the filename element of the MFileObject instance. This name should not contain any '/' characters, it should indicate simply the name of a file. The directories in which this name will be searched for are specified by setRawPath.

Parameters

[in] fileName The filename.

Returns: MS::kSuccess

MStatus setFullName ( const MString & fileName )

This method is obsolete.

Deprecated:: Use the method MFileObject::setRawFullName instead.

This method combines the functions of the setName and setRawPath methods in that it sets both the path and filename from the given name.

If any '/' characters appear in the given name then the path element of the MFileObject is set to everything in name up to, but not including the last '/'. The filename is set to the part of name after the final '/'.

If no '/' characters appear in the given name then the path element is set to "." and the filename is set to the given name.

Parameters

[in] fileName the string used to initialize the path and filename.

Returns: MS::kSuccess

Examples:: autoLoader/moduleLogic.cpp, and MayaPluginForSpreticle/spReticleLoc.cpp.

MString name ( ) const

This method is obsolete.

Deprecated:: Use the method MFileObject::resolvedName instead.

Returns the filename element of the MFileObject.

Returns: The resolved filename.

Examples:: animExportUtil/animExportUtil.cpp, animImportExport/animImportExport.cpp, atomImportExport/atomImportExport.cpp, maTranslator/maTranslator.cpp, MayaPluginForSpreticle/spReticleLoc.cpp, and objExport/objExport.cpp.

MString path ( ) const

This method is obsolete.

Deprecated:: Use the methods MFileObject::expandedPath or MFileObject::resolvedPath instead.

Returns the path element of the MFileObject with all environment variables expanded.

Returns: The expanded path.

Examples:: AbcBullet/AbcBullet.cpp, AbcExport/AbcExport.cpp, cgFx/cgfxTextureCache.cpp, and MayaPluginForSpreticle/spReticleLoc.cpp.

MString fullName ( ) const

This method is obsolete.

Deprecated:: Use the methods MFileObject::expandedFullName or MFileObject::resolvedFullName instead.

Returns the first pathname of a file constructed from the path and filename elements. All variables in the path element are expanded, and the first path (the part before the first ':' in the path) is prepended to the filename element to construct the fullName.

Returns: The expanded filename.

Examples:: animExportUtil/animExportUtil.cpp, animImportExport/animImportExport.cpp, atomImportExport/atomImportExport.cpp, colorTransformData/colorTransformData.cpp, lepTranslator/lepTranslator.cpp, maTranslator/maTranslator.cpp, objExport/objExport.cpp, polyRawExporter/polyExporter.cpp, and polyX3DExporter/polyExporter.cpp.

bool isAbsolutePath ( const MString & fileName )

static

Utility method which checks a file path string and determines if it represents an absolute file path.

An absolute path can uniquely identify a directory or file.

Parameters

[in] fileName the string used to check if it is absolute

Returns: True if fileName is an absolute path

Examples:: AbcBullet/AbcBullet.cpp, AbcExport/AbcExport.cpp, AbcImport/AbcImport.cpp, dx11Shader/dx11ShaderCompileHelper.cpp, and glslShader/GLSLShader.cpp.

MString getResolvedFullName ( const MString & rawFullName )

static

This is a static convenience method for performing a straightforward resolve of a file path.

This is the simplest version of this overloaded method. Another version provides additional arguments to the call.

The caller specifies the rawFullName of the unresolved file path, and the resolved name is returned.

Use of this method is suitable when the requirement is simply to convert an unresolved path to a resolved path using the default settings and when the calling code does not require access to the instance of the MFileObject before the resolution for additional setup, or after the resolution for subsequent operations.

Note: internally the resolution is performed using the default ResolveMethod of MFileObject::kNone. While this is suitable in many situations, it may not be appropriate if the file is expected to exist. The overloaded version of this method provides more control over the resolve method that is used. Refer to MFileObject::MFileResolveMethod for more information about how the resolution mode is used.

Failure to resolve the path according to the specifications will result in an empty return value.

Parameters

[in] rawFullName The fully specified unresolved path

Returns: The full path to the resolved file, or an empty string if the resolution was unsuccessful.

MString getResolvedFullName	(	const MString &	rawFullName,
		bool &	exists,
		MFileObject::MFileResolveMethod	resolveMethod = `MFileObject::kNone`
	)

static

This is a static convenience method for performing a straightforward resolve of a file path.

This overloaded version of the method provides additional options to the resolution call than the simpler version above.

The caller specifies the rawFullName of the unresolved file path, and the resolved name is returned. The method will also perform a check to determine whether or not the file exists and will return the result. The optional resolveMethod argument can be set by the caller to override the resolution mode if desired; by default the setting is MFileObject::kNone which will resolve the file path, but not require the file to exist to resolve successfully. If the file is to be used for input, the resolve setting should generally be set to a mode that will check its existence - the most common mode for input is MFileObject::kInputFile. Refer to MFileObject::MFileResolveMethod for more information about how the resolution mode is used.

Use of this method is suitable when the requirement is simply to convert an unresolved path to a resolved path and when the calling code does not require access to the instance of the MFileObject before the resolution for additional setup, or after the resolution for subsequent operations.

Failure to resolve the path according to the specifications will result in an empty return value.

Parameters

[in]	rawFullName	The fully specified unresolved path
[out]	exists	Set on return to indicate if the resolved path exists or not
[in]	resolveMethod	(optional) set by caller to override the resolve method used (default MFileObject::kNone)

Returns: The full path to the resolved file, or an empty string if the resolution was unsuccessful.

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

MFileObject.h
MFileObject.cpp

MFileObject Class Reference

Class Description

Public Types

Public Member Functions

Static Public Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation