Add Custom Helper

To add your own custom file system helpers, start by deriving from FS_ReaderHelper and/or FS_WriterHelper. Although it is not necessary to implement both a reader and writer subclass, you should always implement a FS_InfoHelper subclass if you derive from either one of those.

The FS/FS_HomeHelper.C example shows how to implement a custom helper. It is a toy helper that supports the home: protocol which allows access to files in the HOME directory.

To register your helper, simply construct it in the special installFSHelpers() entry point in your plugin. The base class constructors automatically add themselves to the global helper table.

void
installFSHelpers()
{
    new HDK_Sample::FS_HomeReadHelper();
    new HDK_Sample::FS_HomeWriteHelper();
    new HDK_Sample::FS_HomeInfoHelper();
}

Your helper subclasses then need to override the createStream() stream method that returns the appropriate stream subclass. It should return NULL if the given source string does not match your protocol prefix.

For FS_InfoHelper, there are several pure virtual classes that are necessary for returning information about the source such as access permission, timestamp, size, directory, and contents.

For FS_ReaderHelper you can optionally also override splitIndexFileSectionPath() and combineIndexFileSectionPath() methods, if the file path protocol that you are implementing requires a special meaning for the question mark character, '?', which by default is used to separate an index file section name in the path. An index file is a proprietary file format used by Houdini to use a single file to store several pieces of data indexed by a section name. Handling the '?' separator in FS_Reader by default has the advantage of supporting index files for custom protocols without implementing any special code in helpers, but the disadvantage is that custom helpers cannot use '?' for any other meaning. If they need to handle it in a special manner, they must override the two virtual methods mentioned above. The FS/FS_HomeHelper.C example shows how to do that.

If your helper wants to interpret URI formatted strings (myhelper://dir/file.ext), it is important to call UTaddAbsolutePathPrefix, passing in the URI prefix, followed by a colon and a single forward slash (for example, UTaddAbsolutePathPrefix("myhelper:/")). Without the colon, a relative path that starts with your URI prefix may be interpreted as an absolute path destined for your helper. Without the forward slash, the double slash after the colon in a URI will confuse Houdini's path parsing code in some situations. The FS_HomeHelper sample does not include the forward slash in it's absolute path prefix because it does not use URI path formatting. It expects paths to have only a single slash following the colon (home:/file.ext rather than home://file.ext).

Install Location

The compiled dso needs to be installed somewhere in $HOUDINI_DSO_PATH under the fs subdirectory. For example, the $HOME/houdiniX.Y/dso/fs subdirectory.

See Also

FS/FS_HomeHelper.C