IFileSystem Interface

Merge supports virtual file systems, which enable Merge to access files and folders that aren’t necessarily present on the user’s hard disk or computer. Example file systems include FTP, HTTP, and SCM integrations.

Support for new (or currently unsupported) file systems can be added to Merge by writing a small set of COM components that implement a set of defined interfaces. The primary interface is the IFileSystem interface, which provides an entry-point into a virtual file system.

Registering new file systems with Merge

File-system plugins are registered with Merge by adding a section to the vfsplugins.ini file that is found in the Merge installation folder. The vfsplugins.ini file lists the URL schemes for which plugins are available and provides Merge with the name of the COM component responsible for implementing access to the scheme’s file system. An example vfsplugins.ini file is shown below:

[.]
progid=Merge.Win32VFS
description=Win32
autoregister=fsplugin.dll

[ftp]
progid=Merge.FtpVFS
description=FTP
autoregister=fsplugin.dll

The vfsplugins.ini file consists of an unlimited number of sections. Each section begins with the URL scheme that is to be handled by a file-system plugin component. The component that is registered for the . scheme is used to handle any URL that isn’t explicitly handled by the other sections.

The first section (beginning [.]) registers the Win32 file-system plugin, which handles Win32 file paths (for example, c:\temp\file.txt, \server\path\file.txt, \path\file.txt) and any URLs that aren’t handled by the other registered plugins. The second section (beginning [ftp]) registers a plugin to handle URLs that use the ftp scheme (for example, ftp://ftp.microsoft.com/).

Each line within a section consists of a key and value, separated by an equals sign. The following table describes the keys that can be used, and the values with which they should be provided:

A component that implements this interface typically implements IFileSystemInit as well.

Threading models

Virtual file system component servers can be implemented either as in-process or as local servers. For performance reasons, we recommend that servers are in-process, and that they use the Apartment, Both, or Free threading model. Merge may create instances of plugin components in multiple threads, so components must follow standard thread-safety guidelines applicable to the threading model that is being used.

Error handling

Merge will use the standard OLE ISupportErrorInfo mechanism to obtain error information when a method or property fails. Error messages provided through this mechanism are usually displayed verbatim to the user, and should therefore be as informative as possible.

Properties

Capabilityread-onlyIFileSystem

Operations on some filesystems may be harder or slower to perform than on others. Merge uses this property to determine the extent to which a particular capability is supported by a plugin, and its efficiency.

• nCapability
  A specific capability for which the plugin’s level of support is required.
• pHintUrls
  A collection of hint URLs that may be specified along with the capability to help determine the level of support for the capability.

TemporaryFileNameread-onlyIFileSystem

This property should return the URL for a file that can be used by Merge to store a temporary copy of the file specified by strUrl. The temporary file should be located close to the file specified by strUrl. When Merge saves over a file, it takes a temporary backup copy in case the save fails due to there being insufficient storage space. If the save fails, the user is told where the temporary backup is located so that they can sort out the problem.

• strUrl
  The URL to an existing file located within the plugin’s file system.

Methods

AppendPathToURLIFileSystem

This method should append strPath to strURL to form a valid URL within the file system.

• strUrl
  The URL to which the path is to be appended.
• strPath
  The path that is to be appended to the URL.

BindFileIFileSystem

This method returns the IFile interface for an object representing a file within the plugin’s file system.

• strUrl
  The URL for a file located within the plugin’s file system.
• bMustExist
  If True, a result should only be returned if the file exists. If False, a result should always be returned (thus enabling files to be created).

BindFolderIFileSystem

This method returns the IFolder interface for an object representing a folder within the plugin’s file system.

• strUrl
  The URL for a folder located within the plugin’s file system.
• bMustExist
  If True, a result should only be returned if the folder exists. If False, a result should always be returned (thus enabling folders to be created).

CopyFileIFileSystem

This method is used to copy a file within the plugin’s file system. The source and target URLs are guaranteed to refer to files within the plugin’s file system. Lengthy copy operations should use the pContinue argument to check whether the user wants to abort the copy. This method should replace an existing target file unless prevented from doing so by an error.

• strFromUrl
  The URL for a file located within the plugin’s file system.
• strToUrl
  The URL for a file located within the plugin’s file system.
• pContinue
  A reference to an object that can be checked during lengthy copy operations to see if the copy should continue.

DeleteIFileSystem

Deletes the URLs specified within the collection.

• pItems
  A collection of URLs that are to be deleted.
• bNeverPrompt
  Whether the user should not be prompted to delete the items.
• bRecursive
  Whether folders within the URL collection should be deleted recursively.