Changes between Version 6 and Version 7 of rfc12_filemanagement

Timestamp:

May 8, 2007, 5:38:38 PM (17 years ago)

Author:

warmerdam

Comment:

Added Copy operation.

rfc12_filemanagement

@@ -7 +7 @@
 == 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 to move/rename them.
+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 to move or copy them.
 
 == !GetFileList() ==
@@ -55 +55 @@
 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. 
 
+== pfnCopyFiles() ==
+
+The following new function is added to the GDALDriver class.
+
+{{{
+    CPLErr       (*pfnCopyFiles)( const char *pszNewName, const char *pszOldName );
+}}}
+
+Also a corresponding function is added to the C API. 
+
+{{{
+    CPLErr        GDALCopyDatasetFiles( GDALDriverH hDriver, const char *pszNewName, const char *pszOldName );
+}}}
+
+Note that copying is done by the driver.  The dataset may be opened, but if opened in update mode it may be prudent to first do a flush to synchronize the in-process state with what is on disk.  GDALCopyDatasetFiles() will invoke pfnCopyFiles if it is non-NULL.  
+
+If pfnCopy is NULL the default implementation will be used which will open the dataset, fetch the file list, close the dataset, and then try to copy all the files (based on shared basenames).  The default copy 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 renamed 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. 
+
+Copy is essentially the same as Rename, but the original files are unaltered.  Note that this form of copy is distinct from CreateCopy() in that it preserves the exact binary files on disk in the new location while CreateCopy() just attempts to reproduce a new dataset with essentially the same data as modelled and carried through GDAL.
+
 == pfnDelete() == 
 
@@ -84 +106 @@
 == SWIG Implications ==
 
-The GDALRenameDataset() operation on the driver, and the !GetFileList() operation on the dataset will need to be exposed through SWIG. 
+The GDALRenameDataset(), and GDALCopyDatasetFiles() operations on the driver, and the !GetFileList() operation on the dataset will need to be exposed through SWIG. 
 
 == Testing ==
 
-Rename testing will be added to the regression tests for a few representative formats.  These rename operations will be between one directory and another, and will not test cross file system copying which will have to be tested manually. 
+Rename and CopyFiles testing will be added to the regression tests for a few representative formats.  These rename operations will be between one directory and another, and will not test cross file system copying which will have to be tested manually. 
 
-A small gdalrename.py script will be implemented allowing use and testing of the rename operation from the commandline in a convenient fashion.  
+A small gdalmanage.py script will be implemented allowing use and testing of the rename, copy and delete operations from the commandline in a convenient fashion.