file (lx_file.hpp)

From The Foundry MODO SDK wiki
Jump to: navigation, search
There are security restrictions on this page


Contents

File Service

Plug-ins can use the File service for various file operations, such as looking up standard file paths by name, or copying files from one location to another.

Also see PlatformService for functions to walk the list of all aliased paths and for walking the list of import paths.

(1) SDK: LXu_FILESERVICE, etc. defines
 #define LXu_FILESERVICE         "742B3D3D-1151-4AB7-AF4F-668D18468D7F"
 #define LXa_FILESERVICE         "fileservice2"

File Path Utilities

FileSystemPath() returns the standard file path for a given name, as defined by one of the LXsSYSTEM_PATH_ defines.

(2) SDK: LXsSYSTEM_PATH_PROGRAM, etc. defines
 #define LXsSYSTEM_PATH_PROGRAM          "program"
 #define LXsSYSTEM_PATH_EXENAME          "exename"
 #define LXsSYSTEM_PATH_PROJECT          "project"
 #define LXsSYSTEM_PATH_TEMP             "temp"
 #define LXsSYSTEM_PATH_LICENSE          "license"
 #define LXsSYSTEM_PATH_RESOURCE         "resource"
 #define LXsSYSTEM_PATH_MODULE           "module"
 #define LXsSYSTEM_PATH_PREFS            "prefs"
 #define LXsSYSTEM_PATH_HELP             "help"
 #define LXsSYSTEM_PATH_USER             "user"
 #define LXsSYSTEM_PATH_CONTENT          "content"
 #define LXsSYSTEM_PATH_ASSET            "asset"
 #define LXsSYSTEM_PATH_SAMPLE           "sample"
 #define LXsSYSTEM_PATH_CONFIGS          "configs"
 #define LXsSYSTEM_PATH_SCRIPTS          "scripts"
 #define LXsSYSTEM_PATH_DOCUMENTS        "documents"
 #define LXsSYSTEM_PATH_KITS             "kits"
 #define LXsSYSTEM_PATH_USER_KITS        "userkits"
 #define LXsSYSTEM_PATH_LOGS             "logs"
 #define LXsSYSTEM_PATH_CLOUDCACHE       "cloudcache"

(3) SDK: FileService::FileSystemPath
         LXxMETHOD(  LxResult,
 FileSystemPath) (
         LXtObjectID               self,
         const char               *name,
         const char              **path);

(4) SDK: CLxUser_FileService::FileSystemPath method
         LxResult
 FileSystemPath (
         const char              *name,
         std::string             &path)
 {
         LxResult                 result;
         const char              *systemPath;
 
         result = CLxLoc_FileService::FileSystemPath (name, &systemPath);
         if (LXx_OK (result))
                 path = std::string(systemPath);
 
         return result;
 }

Filename Utilities

This returns LXe_TRUE if a path is absolute, and LXe_FALSE if it is not.

(5) SDK: FileService::IsAbsolutePath
         LXxMETHOD(  LxResult,
 IsAbsolutePath) (
         LXtObjectID              self,
         const char              *path);

This compares two paths and returns true if they are equal. This respects case-sensitivity and other quirks specific to the operating system. It doesn't follow symbolic links or other directory traversal.

(6) SDK: FileService::ArePathsEqual
         LXxMETHOD(  LxResult,
 ArePathsEqual) (
         LXtObjectID              self,
         const char              *path1,
         const char              *path2);

This parses a filename path, extracting the last portion of the path into the basename buffer and the path into the path buffer.

(7) SDK: FileService::ParsePath
         LXxMETHOD(  LxResult,
 ParsePath) (
         LXtObjectID              self,
         const char              *filename,
         unsigned                 component,
         char                    *buf,
         unsigned                 len);

The components of the path are the directory, the base filename with extension, the root name without extension, and the extension itself.

(8) SDK: LXiFILECOMP_DIRECTORY, etc. defines

This adds the base filename onto a path with the path separator defined by the OS. If the basename is absolute it returns LXe_INVALIDARG.

(9) SDK: FileService::ComposePath
         LXxMETHOD(  LxResult,
 ComposePath) (
         LXtObjectID              self,
         const char              *basename,
         const char              *path,
         char                    *buf,
         unsigned                 len);

This takes a filename and extension, and returns the same filename but with the new extension. The extension string is just the part after the period.

(10) SDK: FileService::SetExtension
         LXxMETHOD(  LxResult,
 SetExtension) (
         LXtObjectID              self,
         const char              *filename,
         const char              *extension,
         char                    *buf,
         unsigned                 len);

This makes a filename relative to a path, if possible. This fails if the filename could not be made relative.

(11) SDK: FileService::MakeRelative
         LXxMETHOD(  LxResult,
 MakeRelative) (
         LXtObjectID              self,
         const char              *filename,
         const char              *path,
         char                    *buf,
         unsigned                 len);

This computes a unique filename given a base pattern by adding digits. For example, if the path is "c:\a\b\myfile.ext", this will first see if "c:\a\b\myfile.ext" exists. If it does not, it will be returned. If it does exist, then the path will be changed to "c:\a\b\myfile_1.ext" and tested again, and so on until the path is unique.

This method fails if the path portion doesn't exist.

(12) SDK: FileService::MakeUnique
         LXxMETHOD(  LxResult,
 MakeUnique) (
         LXtObjectID              self,
         const char              *filename,
         char                    *buf,
         unsigned                 len);

Given a path to a directory, this creates the directories, if possible.

(13) SDK: FileService::MakeDirectory
         LXxMETHOD(  LxResult,
 MakeDirectory) (
         LXtObjectID               self,
         const char               *path);

File Utilities

This returns LXe_TRUE if a file exists, and LXe_FALSE if it does not. More detailed information can be returned in the type argument (if non-NULL), and will be one of the following defines.

(14) SDK: LXiFILETYPE_NONE, etc. defines

NONE indicates that the file does not exist or cannot be accessed for some reason. UNKNOWN indicates that the file exists but is some unusual type.

(15) SDK: FileService::TestFileType
         LXxMETHOD(  LxResult,
 TestFileType) (
         LXtObjectID              self,
         const char              *filename,
         unsigned                *type);

This returns a combination of flags indicating if a file can be read and/or written. This method always succeeds, even if the file doesn't exist.

(16) SDK: FileService::TestFileMode
         LXxMETHOD(  LxResult,
 TestFileMode) (
         LXtObjectID              self,
         const char              *filename,
         unsigned                *mode);

(17) SDK: LXiFILEMODE_READ, etc. defines
 #define LXiFILEMODE_READ                1
 #define LXiFILEMODE_WRITE               2

This renames a file on disk, if possible. This will also work on directories. This can also be used to move files.

(18) SDK: FileService::RenameFile
         LXxMETHOD(  LxResult,
 RenameFile) (
         LXtObjectID              self,
         const char              *from,
         const char              *to);

This copies a file from one path to another. If a file already exists at the destination path and overwrite is true, it will be overwritten with no warning given. If overwrite is false, then the method will fail if a file already exists at the destination.

(19) SDK: FileService::FileCopy
         LXxMETHOD(  LxResult,
 FileCopy) (
         LXtObjectID              self,
         const char              *srcFilePath,
         const char              *dstFilePath,
         unsigned                 overwrite);

This deletes a file from disk, if possible. In general, this must be a file (not a directory).

(20) SDK: FileService::FileDelete
         LXxMETHOD(  LxResult,
 FileDelete) (
         LXtObjectID              self,
         const char              *filename);

This deletes a dir from disk.

(21) SDK: FileService::DirDelete
         LXxMETHOD(  LxResult,
 DirDelete) (
         LXtObjectID              self,
         const char              *filename);

This opens a file in the application associated with it by the operating system.

(22) SDK: FileService::OpenFileWithDefaultApp
         LXxMETHOD(  LxResult,
 OpenFileWithDefaultApp) (
         LXtObjectID              self,
         const char              *filename);

This finds the file/folder and selects it in Explorer/Finder. Calling this with a folder will open the parent in Explorer/Finder and select it, while using OpenFileWithDefaultApp() on a folder would show the contents of the folder itself.

(23) SDK: FileService::RevealInFileViewer
         LXxMETHOD(  LxResult,
 RevealInFileViewer) (
         LXtObjectID              self,
         const char              *filename);

This executes an arbitrary program given an argv-style array of arguments. If "show" is true, the application will be visible when launched; if false, it will be hidden. If force32 is true, the 32 bit version of the application will be launched on a 64 bit system if available supports fat/universal binaries (such as OS X); otherwise, the native version of the application will launch.

(24) SDK: FileService::Execute
         LXxMETHOD(  LxResult,
 Execute) (
         LXtObjectID              self,
         const char             **argv,
         int                      show,
         int                      force32);

URL Utilities

These two utilities convert between local paths and URLs. These paths begin with the "file://" URL prefix.

(25) SDK: FileService::FileToURL, etc.
         LXxMETHOD(  LxResult,
 FileToURL) (
         LXtObjectID              self,
         const char              *filename,
         char                    *buf,
         unsigned                 len);
 
         LXxMETHOD(  LxResult,
 FileFromURL) (
         LXtObjectID              self,
         const char              *url,
         char                    *buf,
         unsigned                 len);

Path Utilities

Local file and path names can be converted to and from neutral format with these interfaces. The value returned is the result of the conversion. These conversions are raw, performing a simple conversion without validity checks. Aliases are not used in the first two methods, they are in 'ToLocalAlias'.

(26) SDK: FileService::FromLocal, etc.
         LXxMETHOD(  LxResult,
 FromLocal) (
         LXtObjectID              self,
         const char              *local,
         char                    *buf,
         unsigned                 len);
 
         LXxMETHOD(  LxResult,
 ToLocal) (
         LXtObjectID              self,
         char                    *neutral,
         char                    *buf,
         unsigned                 len);
 
         LXxMETHOD(  LxResult,
 ToLocalAlias) (
         LXtObjectID              self,
         const char              *neutral,
         char                    *buf,
         unsigned                 len);

File Objects

(27) SDK: FileService::AllocReference
         LXxMETHOD( LxResult,
 AllocReference) (
         LXtObjectID              self,
         const char              *path,
         void                   **ppvObj);

(28) SDK: LXu_FILEREFERENCE define
 #define LXu_FILEREFERENCE       "A18B9A9D-6623-4463-B6AF-469771B41485"

(29) SDK: FileReference::Path, etc.
         LXxMETHOD( LxResult,
 Path) (
         LXtObjectID              self,
         const char             **path);
 
         LXxMETHOD( LxResult,
 NiceName) (
         LXtObjectID              self,
         char                    *buf,
         unsigned                 len);
 
         LXxMETHOD( LxResult,
 Type) (
         LXtObjectID              self,
         unsigned                *type);
 
         LXxMETHOD( LxResult,
 Mode) (
         LXtObjectID              self,
         unsigned                *mode);
 
         LXxMETHOD( LxResult,
 SubCount) (
         LXtObjectID              self,
         unsigned                *count);
 
         LXxMETHOD( LxResult,
 SubByIndex) (
         LXtObjectID              self,
         unsigned                 index,
         void                   **ppvObj);

Empty FileReference Python user class.

(30) SDK: empty FileReference User Class

(31) PY: empty FileReference user class
 pass

Package Plug-in Staging

The staged file list contains a list of source and destination file paths, that will be copied the next time modo is started up.

This copying is done before any plug-ins are loaded.

(32) SDK: LXsSTAGED_FILE_LIST define
 #define LXsSTAGED_FILE_LIST             "LxStagedFiles.txt"

Sequences

(33) SDK: FileService::FindSequencePattern, etc.
         LXxMETHOD( LxResult,
 FindSequencePattern) (
         LXtObjectID              self,
         const char              *filename,
         char                    *buf,
         unsigned                 len);
 
         LXxMETHOD( LxResult,
 FindSequenceBounds) (
         LXtObjectID              self,
         const char              *pattern,
         unsigned                *first,
         unsigned                *last);
 
         LXxMETHOD( LxResult,
 GenerateSequenceName) (
         LXtObjectID              self,
         const char              *pattern,
         unsigned                 frame,
         char                    *buf,
         unsigned                 len);

License Validation

Takes a product name and version number and returns LXe_OK if there is a valid license.

(34) SDK: FileService::ValidateLicense
         LXxMETHOD( LxResult,
 ValidateLicense) (
         LXtObjectID              self,
         const char              *product,
         int                      versionNum);

Nexus 11.1v1

It is often useful to know the modification time of a file in a platform-agnostic format. This method returns that as a string of "YYYY:MM:DD HH:MM:SS". This assures that sorting date strings using strcmp()-like functions puts the dates in chronological order.

(35) SDK: FileService::FileDateString
         LXxMETHOD( LxResult,
 FileDateString) (
         LXtObjectID              self,
         const char              *filename,
         char                    *buf,
         int                      len);

Empty File service Python user class.

(36) PY: empty Service.File user class
 pass

Path Redirection

Allocate a redirection object from the service. When created it has no history so no redirections are done.

(37) SDK: FileService::AllocRedirect
         LXxMETHOD( LxResult,
 AllocRedirect) (
         LXtObjectID              self,
         void                   **ppvObj);

A file redirection object allows path names from a file to be mapped to an equivalant path found through some method of redirection. This is normally used when loading a file to find all other related assets.

(38) SDK: LXu_FILEREDIRECT define
 #define LXu_FILEREDIRECT        "05DACE30-BFA0-453C-AB7A-33DF35827A35"

Configure the redirection to support neutral format names. This means that references are in a format that is the same on all platforms, so that a file saved on a PC can be loaded on a Mac. If this format is enabled aliases are also supported.

(39) SDK: FileRedirect::NeutralFormat
         LXxMETHOD( LxResult,
 NeutralFormat) (
         LXtObjectID              self,
         unsigned                 allow);

The search path for a redirection object is intended to be set once. Paths will be searched in the order they're added.

(40) SDK: FileRedirect::AddSearchPath
         LXxMETHOD( LxResult,
 AddSearchPath) (
         LXtObjectID              self,
         const char              *path);

This method takes a reference path and tries to find an absolute path to an existing asset matching the reference. The input reference may be absolute or relative, and must be in neutral format if this object is also. The file type is used to open a redirection dialog by the user, and can be left null to suppress that.

(41) SDK: FileRedirect::Locate
         LXxMETHOD( LxResult,
 Locate) (
         LXtObjectID              self,
         const char              *path,
         const char              *type,
         char                    *buf,
         unsigned                 len);

None of these are currently used.

(42) SDK: LXeREMAP_DIRECT, etc. defines

A sequence filename (one that contains sequence pattern) can be found using the same search criteria.

(43) SDK: FileRedirect::LocateSequence
         LXxMETHOD( LxResult,
 LocateSequence) (
         LXtObjectID              self,
         const char              *pattern,
         const char              *type,
         unsigned                *first,
         unsigned                *last,
         char                    *buf,
         unsigned                 len);

This method takes an absolute asset path and returns a reference. The reference may be relative if the asset can be found on the search path. For neutral format redirction the reference is platform-generic and may contain user aliases.

(44) SDK: FileRedirect::Reference
         LXxMETHOD( LxResult,
 Reference) (
         LXtObjectID              self,
         const char              *path,
         char                    *buf,
         unsigned                 len);

(45) SDK: empty FileRedirect User Class

(46) PY: empty FileRedirect user class
 pass