#include <MPxFileResolver.h>

Class Description

Base Class for creating custom Maya File Resolvers.

This class provides a base class from which a custom file resolver plug-in can be derived. A file resolver plug-in allows the user to override the manner in which an unresolved file path value is converted to a resolved file path. The resolved file path is the location Maya will use to access the physical file.

Maya supports plug-in File Resolvers for file paths defined using URI values. When an unresolved URI file path is encountered, Maya will search for any registered URI file resolver plug-ins that can handle it.

URI file resolvers are registered for a given URI scheme. For example, a custom file resolver plug-in could be registered to handle the "http" URI scheme. If Maya attempts to resolve a URI file path that has the scheme "http", the custom resolver plug-in will be called. URI schemes are treated in a case-insensitive manner. For example, the schemes 'http', 'HTTP', and 'Http' are considered equivalent.

MPxFileResolvers for URI schemes are registered using the MFnPlugin::registerURIFileResolver method.

Public Types
enum	MPxFileResolverMode { kNone = (1<<0), kInput = (1<<1) }
	The MFileResolverMode provides additional information about the reason for the resolution call that can be used by the resolver implementation. More...

Public Member Functions
	MPxFileResolver ()
	The class constructor.

virtual	~MPxFileResolver ()
	The class destructor.

virtual MString	resolveURI (const MURI &uriValue, MPxFileResolver::MPxFileResolverMode mode, MStatus *ReturnStatus=NULL)
	This routine is called by Maya to convert a URI value to a file path that can be accessed by Maya. More...

virtual MString	resolveURIWithContext (const MURI &uriValue, MPxFileResolver::MPxFileResolverMode mode, const MString &contextNodeFullName, MStatus *ReturnStatus=NULL)
	This routine is called by Maya to convert a URI value to a file path that can be accessed by Maya. More...

virtual MString	uriScheme () const
	This routine is called to query the URI scheme that is handled by this resolver. More...

MString	resolverName () const
	This routine is called to query the name of this resolver. More...

virtual void	performAfterSaveURI (const MURI &uriValue, const MString &resolvedFullPath)
	This optional handler is provided so that registered URI file resolvers can do custom processing after file save. More...

Static Public Member Functions
static const char *	className ()
	Returns the name of this class. More...

static MPxFileResolver *	findURIResolverByScheme (const MString &uriScheme)
	Find a registered file resolver that implements a given URI scheme. More...

static MPxFileResolver *	findURIResolverByName (const MString &resolverName)
	Find a registered file resolver by name. More...

static MStringArray	getURIResolversByScheme ()
	Generate a list containing the URI schemes for all registered file resolvers. More...

static MStringArray	getURIResolversByName ()
	Generate a list containing the names of all registered file resolvers. More...

static int	numURIResolvers ()
	Determine the number of registered URI file resolvers. More...

Member Enumeration Documentation

enum MPxFileResolverMode

The MFileResolverMode provides additional information about the reason for the resolution call that can be used by the resolver implementation.

Note that this enum is implemented as a bitfield.

Enumerator

kNone

(Default) The resolved path is being requested, but there is no additional information specified.

When kNone is used, it will not be combined with any other modes listed below. In this case, the resolver should simply return the resolved path as efficiently as possible. The path returned by the resolver will not be checked for existence.

kInput

The resolved path is being requested for an input file.

In this case, the resolver plug-in may need to do additional work to ensure that the resolved path is available to the application. The path returned by the resolver will be checked for existence.

Member Function Documentation

MString resolveURI	(	const MURI &	uriValue,
		MPxFileResolver::MPxFileResolverMode	mode,
		MStatus *	ReturnStatus = `NULL`
	)

virtual

This routine is called by Maya to convert a URI value to a file path that can be accessed by Maya.

This routine is only called if the resolveURIWithContext routine is not overridden in derived classes. Choose to use this routine when you do not need the context (fullName of the URI owner) to perform the resolution.

Derived classes must override either this method or resolveURIWithContext(), but not both. This virtual method must be overridden in derived classes if resolveURIWithContext() is not overridden, as the default version defined in MPxFileResolver simply fails unconditionally.

The routine is passed an MURI object that contains the URI value that requires resolution. The resolver will interpret the data in the URI and determine the physical file path value that Maya will use to access the file.

The output from the routine is a fully qualified file path that can be accessed by Maya.

It is important to note that successful resolution of a file path indicates that the URI filepath was successfully converted to a resolved file path. Successful resolution does not necessarily indicate whether or not the file referred to by the resolved file path actually exists.

The resolution mode provides additional information to the resolver about the reason for the resolution request that can be used by the resolver implementation. Refer to the list of supported MPxFileResolver::MPxFileResolverMode modes for more information.

Parameters

[in]	uriValue	the unresolved URI value
[in]	mode	the resolution mode
[out]	ReturnStatus	status code, see below.

Returns: String containing the fully qualified file path of the resolved file, or an empty string if the resolution was not successful.

Status Codes:

MS:kSuccess Resolve succeeded
MS:kFailure Resolve failed

MString resolveURIWithContext	(	const MURI &	uriValue,
		MPxFileResolver::MPxFileResolverMode	mode,
		const MString &	contextNodeFullName,
		MStatus *	ReturnStatus = `NULL`
	)

virtual

This routine is called by Maya to convert a URI value to a file path that can be accessed by Maya.

Derived classes must override either this method or resolveURI(), but not both.

The routine is passed an MURI object that contains the URI value that requires resolution. Additionally, it will be passed the owner fullname (context) when applicable. The resolver will interpret the data in the URI, use the context if required, and determine the physical file path value that Maya will use to access the file.

The context is the fullname of the owner Node. The context fullname might be an empty string if the URI is an application property not associated to any specific scene element.

The output from the routine is a fully qualified file path that can be accessed by Maya.

It is important to note that successful resolution of a file path indicates that the URI filepath was successfully converted to a resolved file path. Successful resolution does not necessarily indicate whether or not the file referred to by the resolved file path actually exists.

The resolution mode provides additional information to the resolver about the reason for the resolution request that can be used by the resolver implementation. Refer to the list of supported MPxFileResolver::MPxFileResolverMode modes for more information.

Parameters

[in]	uriValue	the unresolved URI value
[in]	mode	the resolution mode
[in]	contextNodeFullName	the fullname of the URI owner Node
[out]	ReturnStatus	status code, see below.

Returns: String containing the fully qualified file path of the resolved file, or an empty string if the resolution was not successful.

Status Codes:

MS:kSuccess Resolve succeeded
MS:kFailure Resolve failed

MString uriScheme ( ) const

virtual

This routine is called to query the URI scheme that is handled by this resolver.

An MPxFileResolver handles exactly one URI scheme. For example, a resolver that handles the "http" scheme would return "http".

This virtual method must be overridden in derived classes. The default version defined in MPxFileResolver unconditionally returns an empty string.

Returns: A string containing the URI scheme that is handled by this file resolver.

MString resolverName ( ) const

This routine is called to query the name of this resolver.

The resolver name is specified when the resolver is registered in the call to MFnPlugin::registerURIFileResolver. Derived classes do not override this method.

Returns: The name under which the resolver was registered.

const char * className ( )

static

Returns the name of this class.

Returns: The name of this class.

void performAfterSaveURI	(	const MURI &	uriValue,
		const MString &	resolvedFullName
	)

virtual

This optional handler is provided so that registered URI file resolvers can do custom processing after file save.

The method will be called by Maya after a scene file associated with this URI resolver is saved (i.e. a scene having a URI file path corresponding to the URI scheme implemented by this resolver). The timing of the call is similar to the MSceneMessage:kAfterSave callback, this method will however be called first, before any afterSave callbacks are invoked.

The arguments to the method provide information about the file that was just saved: The URI file path is the unresolved path to the file, the resolved path gives the physical location of the file.

This method is optional, it may be overridden in derived resolvers as required. The default version defined in MPxFileResolver does nothing.

Parameters

[in]	uriValue	the URI (unresolved path) for the saved file
[in]	resolvedFullName	full path to the file that was saved

MPxFileResolver * findURIResolverByScheme ( const MString & uriScheme )

static

Find a registered file resolver that implements a given URI scheme.

Note that URI schemes are matched in a case-insensitive manner. For example, the schemes 'http', 'HTTP', and 'Http' are considered equivalent.

Parameters

[in] uriScheme URI scheme to search for

Returns: The file resolver that implements the given URI scheme, or NULL if no match was found.

MPxFileResolver * findURIResolverByName ( const MString & resolverName )

static

Find a registered file resolver by name.

Parameters

[in] resolverName name of the file resolver to search for

Returns: The file resolver matching the given name, or NULL if no match was found.

MStringArray getURIResolversByScheme ( )

static

Generate a list containing the URI schemes for all registered file resolvers.

Note: when called together, getURIResolversByScheme and getURIResolversByName will return lists of corresponding entries.

Returns: array of strings listing the uri schemes associated with each file resolver

MStringArray getURIResolversByName ( )

static

Generate a list containing the names of all registered file resolvers.

Note: when called together, getURIResolversByScheme and getURIResolversByName will return lists of corresponding entries.

Returns: array of strings listing the name associated with each file resolver

int numURIResolvers ( )

static

Determine the number of registered URI file resolvers.

Returns: The number of registered URI file resolvers.

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

MPxFileResolver.h
MPxFileResolver.cpp

MPxFileResolver Class Reference

Class Description

Public Types

Public Member Functions

Static Public Member Functions

Member Enumeration Documentation

Member Function Documentation