Changes between Version 2 and Version 3 of rfc12_filemanagement

Timestamp:

Apr 30, 2007, 7:52:09 AM (17 years ago)

Author:

warmerdam

Comment:

--

rfc12_filemanagement

@@ -19 +19 @@
 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. 
+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() ==
@@ -26 +26 @@
 
 {{{
-    CPLErr       (*pfnRename)( const char *pszOldName, const char *pszNewName );
+    CPLErr       (*pfnRename)( const char *pszNewName, const char *pszOldName );
 }}}
 
@@ -32 +32 @@
 
 {{{
-    CPLErr        GDALRenameDataset( GDALDriverH hDriver, const char *pszOldName, const char *pszNewName );
+    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.  The default rename operation will use VSIRename() to rename the files, so this function may only be suitable if they remain in the same filesystem or even directory.
+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. 
 
-== pfnMove() == 
+=== CPLRenameOrCopy() ===
 
-... similar to rename, but uses CPLCopyFile() to move files allowing cross filesystem operations. 
+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() ==