RFC 12: Improved File Management

Author: Frank Warmerdam
Contact: warmerdam@…
Status: Development

Summary

Some applications using GDAL have a requirement to provide file management operations through the GUI. This includes deleting, renaming, moving and packaging up datasets which often requires operations on several associated files. This RFC introduces an operation on a GDALDataset to identify all the dataset files, and operations move, and rename them.

GetFileList()

The following new virtual method is added on the GDALDataset class, with an analygous C function.

   virtual char   **GDALDataset::GetFileList(void);

The method is intended to return a list of files associated with this open dataset. The return is a NULL terminated string list which becomes owned by the caller and should be deallocated with CSLDestroy(). The default implementation tests the name of the datasource to see if it is a file, and if so it is returned otherwise an empty list is returned.

The GDALPamDataset::GetFileList() method will add the ability to find .aux and .aux.xml files associated with a dataset to the core default behavior.

pfnRename()

The following new function is added to the GDALDriver class.

    CPLErr       (*pfnRename)( const char *pszNewName, const char *pszOldName );

Also a corresponding function is added to the C API.

    CPLErr        GDALRenameDataset( GDALDriverH hDriver, const char *pszNewName, const char *pszOldName );

Note that renaming is done by the driver, but the dataset to be operated on should not be open at the time. GDALRenameDataset() will invoke pfnRename if it is non-NULL.

If pfnRename is NULL the default implementation will be used which will open the dataset, fetch the file list, close the dataset, and then try to rename all the files (based on shared basenames). The default rename operation will fail if it is unable to establish a relationship between the files (ie. a common basename or stem) to indicate how the group of files should be rename to the new pattern.

Optionally a NULL hDriver argument may be passed in, in which case the appropriate driver will be selected by first opening the datasource.

CPLRenameOrCopy()

The POSIX rename() function on which VSIRename() is usually based does not normally allow renaming files between file systems or between different kinds of file systems (ie. /vsimem to C:/abc). In order to implement GDALRenameDataset() such that it works efficiently within a file system, but still works between file systems, a new operation will be added to gdal/port. This is the CPLRenameOrCopy() function which will first try a VSIRename(). If that fails it will use CPLCopyFile() to copy the whole file and then VSIUnlink() to get rid of the old file.

  int CPLRenameOrCopy( const char *pszNewFilename, const char *pszOldFilename );

The return value will be zero on success, otherwise an errno style value.

It should be noted that in some error conditions, such as the destination file system running out of space during a copy, it may happen that some files for a dataset get renamed, and some do not leaving things in an inconsistent state.

pfnDelete()

The delete operations default implementation will be extended to use the GetFileList() results.

Supporting Functions

Some sort of supporting functions should be provided to make it easy to identify worldfiles, .aux files and .prj files associated with a file.