|
<< Click to Display Table of Contents >> Navigation: Using SyncBackPro > Technical Reference > Scripting > Location Scripts |
These are functions that are defined in your Location script and are called by SyncBackPro. A location script is one that controls how files and folders are stored. For example, you could create a location script to backup to a 7zip archive file, or to a database, for example. The functions are called by SyncBackPro at the appropriate time. For a profile to use a location script you must configure the profile to use it. Location scripts have access to the SBLocation and SBSystem objects.
All the example code below is written in using the Pascal scripting language.
Return value: The abilities of the script
This function is called so SyncBack knows what abilities (functions) the location script supports. Note that the value is cached, so the first value returned is used through-out the entire profile run.
The script can optionally support a number of features (the values can be OR'ed together, e.g. CAN_COPYDIRATTRS + CAN_NTFSATTRIBUTES:
For example:
function LocAbilities;
begin
// Cannot use CAN_EXACTDATETIME because some drives may be FAT32
// Cannot use CAN_NTFSATTRIBUTES because some drives may be FAT32
Result:= CAN_COPYDIRATTRS + CAN_USEATTRIBUTES + CAN_CHANGEDATETIME +
CAN_HAVEEMPTYPATH + CAN_VERSION + CAN_MOVE_FILES + CAN_USECRC32 +
CAN_MOVE_FOLDERS;
end;
function LocConnect(MainThread);
MainThread: Passed as True if it is being called from a user interface
Return value: An error message if the script cannot be connect, otherwise an empty string
This function is called to tell the script to connect to the storage location.
There are two different ways in which this function is called: from the profile thread, or from the main thread (which is the user interface, e.g. the Differences window or the File Prompt window). When a profile is run then an instance of the script is created, and that instance is used while the profile is running. However, when there is user interaction (e.g. from the Differences window) then a new script instance is created. This means the state is different between the scripts, i.e. they have different global variables.
Return an error message if the script cannot connect to the storage location, e.g. the network is down.
Return value: An error message if the script is not connected, otherwise an empty string
This function is called to tell ask the script if it is connected to its storage location. If it is connected (or doesn't need to connect to anything) then return an empty string, otherwise return an error message.
See also LocReconnect and LocConnect
function LocCRC32(Filename; var CRC32);
Filename: The complete path of the file to get the hash value of
CRC32: Set this to the CRC32 hash value of the file, in string format
Return value: An error message if the CRC32 cannot be retrieved, otherwise an empty string
This function is called when the CRC32 hash value of a file is required, e.g. for verification. The entire filename is passed, including the base path. If the CRC32 hash value cannot be retrieved then an error message should be returned.
Note that the CRC32 hash value should be returned in string format, e.g. E75A6A52
For example:
function LocCRC32(FullPath; var CRC32);
begin
CRC32:=SBSystem.CRC32(FullPath);
Result:='';
end;
function LocDeleteFile(Filename; var DoesNotExist);
Filename: The complete path of the file to delete
DoesNotExist: Set to True if the file does not exist, otherwise set to False
Return value: An error message if the file exists and cannot be deleted, otherwise an empty string
This function is called when the script must delete a file. The entire filename is passed, including the base path. If the file cannot be deleted then an error message should be returned. If the file does not exist then set DoesNotExist to True, but do not return an error message.
For example:
function LocDeleteFile(FullPath; var DoesNotExist);
begin
Result:='';
DoesNotExist:=not gFSO.FileExists(FullPath);
If Not DoesNotExist Then
gFSO.DeleteFile(FullPath, True);
end;
function LocDirExists(FullPath);
FullPath: The complete directory path including the base path
Return value: An empty string if the directory exists, otherwise an error message
This function is called when the script must check if a directory (folder) exists. The entire directory path will be passed, including the base path. If the directory exists then an empty string should be returned, otherwise return an error message.
For example:
function LocDirExists(FullPath);
begin
if (FullPath = '') Then
Result:=''
else if FSO.FolderExists(FullPath) Then
Result:=''
else
Result:='Folder does not exist';
end;
See also LocFileExists
Return value: An error message if the disconnect failed
This function is called when the location should disconnect from its storage, e.g. when the profile has finished or the user has aborted. If the script does not need to disconnect, or it disconnects without any problem, then it should return an empty string.
See also LocConnect
function LocFileExists(FullFilename);
FullFilename: The complete filename including the base path
Return value: An empty string if the file exists, otherwise an error message
This function is called when the script must check if a file exists. The entire filename will be passed, including the base path. If the file exists then an empty string should be returned, otherwise return an error message.
For example:
function LocFileExists(FullPath);
begin
if (FullPath = '') then
Result:='File does not exist'
else if FSO.FileExists(FullPath) then
Result:=''
else
Result:='File does not exist';
end;
See also DirExists
Return value: The free space in bytes, else -1
This function is called when the location should return how much free space (in bytes) the storage location has. If it's not relevant or practical then return -1. If using VBScript, take note of the 32-bit integer limit, so return the value as a string when using VBScript, e.g.
LocFreeSpace = CStr(CCur(3221225472))
function LocGet(fromFName, toFName);
fromFName: The complete filename of the file to retrieve from the scripts storage location
toFName: Where script should store the file on the local filesystem
Return value: If the file cannot be retrieved and stored then return an error message
This function is called when SyncBack needs the location to retrieve one if its files and store it on the filesystem.
For example:
Function LocGet(fromFName, toFName);
var
FileObj, Attrs, r;
begin
If Not gFSO.FileExists(FromName) Then
Result:='File does not exist'
Else begin
// Read-only?
If gFSO.FileExists(toFName) Then begin
FileObj:=gFSO.GetFile(toFName);
Attrs:=FileObj.Attributes;
If (Attrs And 1 <> 0) Then
FileObj.Attributes:=Attrs - 1;
FileObj:=Unassigned;
end;
// gFSO.CopyFile(FromName, toFName, True);
r:=CopyFile(FromName, toFName);
if (r = 0) then
Result:=''
else
Result:=SysErrorMessage(r);
end;
end;
function LocGetAttributes(Filename; var Attributes);
Filename: The complete path of the file or directory
Attributes: The filesystem attributes of the file or directory
Return value: An error message if the attributes cannot be retrieved, otherwise an empty string
This function is called when the filesystem attributes for a file or directory need to be retrieved. The entire path of the file or directory to get the attributes of is passed. Note that if it's a directory then it will have a trailing backslash. If the attributes cannot be retrieved then an error message should be returned.
For example:
function LocGetAttributes(Filename; var Attrs);
var
FolderObj, FileObj;
begin
Filename:=ExtractFilename(Filename);
If (Filename = '') Then begin
// Its a special folder
Result:='';
Attrs:=1 + 2 + 4 + 16;
Exit;
end;
If SBSystem.IsFolder(Filename) Then begin
//
// A folder
//
If not gFSO.FolderExists(Filename) Then begin
Result:='Folder does not exist';
Exit;
end;
FolderObj:=gFSO.GetFolder(Filename);
Attrs:=FolderObj.Attributes;
Result:='';
end Else begin
//
// A file
//
If not gFSO.FileExists(Filename) Then begin
Result:='File does not exist';
Exit;
end;
FileObj:=gFSO.GetFile(Filename);
Attrs:=FileObj.Attributes;
Result:=''
end;
end;
function LocMakeDir(FullPath);
FullPath: The complete path of the directory to create
Return value: An error message if the directory cannot be created, otherwise an empty string
This function is called when the location should create a directory. The entire path of the directory to create is passed. If the directory cannot be created then an error message should be returned.
Note that an empty string should be returned if the directory already exists. Do not return an error message.
For example:
function LocMakeDir(FullPath);
begin
Result:='';
FullPath:=ExtractFilename(FullPath);
If (FullPath = '') Then
Exit
Else If Not gFSO.FolderExists(FullPath) Then
gFSO.CreateFolder(FullPath);
end;
function LocMD5(Filename; var MD5);
Filename: The complete path of the file to get the hash value of
MD5: Set this to the MD5 hash value of the file, in string format
Return value: An error message if the MD5 cannot be retrieved, otherwise an empty string
This function is called when the MD5 hash value of a file is required, e.g. for file integrity verification. The entire filename is passed, including the base path. If the MD5 hash value cannot be retrieved then an error message should be returned.
Note that the MD5 hash value should be returned in string format, e.g. E75A6A52
For example:
function LocMD5(FullPath; var MD5);
begin
MD5:=SBSystem.MD5(FullPath);
Result:='';
end;
function LocPut(fromFName, toFName, fromAttrs, fromDateTime, fromFileSize, DoSafeCopy; var SafeFName);
fromFName: The complete filename of the file to retrieve from the local filesystem
toFName: Where script should store the file in its storage location
fromAttrs: The filesystem attributes of the file (ignore if < 0)
fromDateTime: The last modification date & time of the file (local timezone) (ignore if <=1.0)
fromFileSize: The size of the file (in bytes). In VBScript this is a string to avoid the 32-bit integer limit (ignore if < 0)
DoSafeCopy: Passed as True if the file should be copied to a temporary file first and not to toFName
SafeFName: Set this to the filename used to store the file if DoSafeCopy was passed as True
Return value: If the file cannot be stored then return an error message
This function is called when SyncBack needs the location to store a file in its storage location. The file to store can be copied from the local filesystem.
It is recommended that you use the newer LocPutEx function instead of this function.
If DoSafeCopy is True then the file should be copied to a temporary file first and not to the filename specified in toFName. The full path of the safe filename used should be returned in SafeFName.
For example:
function LocPutEx(fromFName, toFName, fromAttrs, fromDateTime, fromCreateDateTime, fromFileSize, fromNTFSSec, DoSafeCopy; var SafeFName);
var
FileObj, Attrs, r;
begin
DebugOut('---LocPutEx:' + fromFName + '*' + toFName);
If Not gFSO.FileExists(fromFName) Then
Result:='File does not exist'
Else begin
// Safe copy?
If DoSafeCopy Then begin
// Note that we must return a SafeFName that we will understand when
// it is passed back to us (we will be asked to move the file)
toFName:=ExtractFilename(toFName) + '.$$$';
SafeFName:=toFName + '.$$$';
end Else begin
toFName:=ExtractFilename(toFName);
SafeFName:='';
end;
// Destination file read-only?
If gFSO.FileExists(toFName) Then begin
FileObj:=gFSO.GetFile(toFName);
Attrs:=FileObj.Attributes;
If (Attrs and 1 <> 0) Then
FileObj.Attributes:=Attrs - 1;
FileObj:=Unassigned;
end;
// SBSystem.UpdateFileStatus('Copying ' + fromFName + '...')
r:=CopyFile(fromFName, toFName);
if (r <> 0) then begin
Result:=SysErrorMessage(r);
Exit;
end;
If (fromAttrs >= 0) Then begin
FileObj:=gFSO.GetFile(toFName);
FileObj.Attributes:=fromAttrs;
FileObj:=Unassigned;
end;
If (fromDateTime > 1.0) Then
SBSystem.SetLastModDateTime(toFName, fromDateTime);
If (fromCreateDateTime > 1.0) Then
SBSystem.SetCreateDateTime(toFName, fromCreateDateTime);
Result:='';
end;
end;
function LocPutEx(fromFName, toFName, fromAttrs, fromModDateTime, fromCreateDateTime, fromFileSize, fromNTFSSec, DoSafeCopy; var SafeFName);
fromFName: The complete filename of the file to retrieve from the local filesystem
toFName: Where script should store the file in its storage location
fromAttrs: The filesystem attributes of the file (ignore if < 0)
fromModDateTime: The last modification date & time of the file (local timezone) (ignore if <=1.0)
fromCreateDateTime: The creation date & time of the file (local timezone) (ignore if <=1.0)
fromFileSize: The size of the file (in bytes). In VBScript this is a string to avoid the 32-bit integer limit (ignore if < 0)
fromNTFSSec: The NTFS security of the file (string format). (ignore if empty string)
DoSafeCopy: Passed as True if the file should be copied to a temporary file first and not to toFName
SafeFName: Set this to the filename used to store the file if DoSafeCopy was passed as True
Return value: If the file cannot be stored then return an error message
This function is called when SyncBack needs the location to store a file in its storage location. The file to store can be copied from the local filesystem.
If DoSafeCopy is True then the file should be copied to a temporary file first and not to the filename specified in toFName. The full path of the safe filename used should be returned in SafeFName.
For example:
function LocPutEx(fromFName, toFName, fromAttrs, fromDateTime, fromCreateDateTime, fromFileSize, fromNTFSSec, DoSafeCopy; var SafeFName);
var
FileObj, Attrs, r;
begin
If Not gFSO.FileExists(fromFName) Then
Result:='File does not exist'
Else begin
// Safe copy?
If DoSafeCopy Then begin
// Note that we must return a SafeFName that we will understand when
// it is passed back to us (we will be asked to move the file)
toFName:=ExtractFilename(toFName) + '.$$$';
SafeFName:=toFName + '.$$$';
end Else begin
toFName:=ExtractFilename(toFName);
SafeFName:='';
end;
// Destination file read-only?
If gFSO.FileExists(toFName) Then begin
FileObj:=gFSO.GetFile(toFName);
Attrs:=FileObj.Attributes;
If (Attrs and 1 <> 0) Then
FileObj.Attributes:=Attrs - 1;
FileObj:=Unassigned;
end;
// SBSystem.UpdateFileStatus('Copying ' + fromFName + '...')
r:=CopyFile(fromFName, toFName);
if (r <> 0) then begin
Result:=SysErrorMessage(r);
Exit;
end;
If (fromAttrs >= 0) Then begin
FileObj:=gFSO.GetFile(toFName);
FileObj.Attributes:=fromAttrs;
FileObj:=Unassigned;
end;
If (fromDateTime > 1.0) Then
SBSystem.SetLastModDateTime(toFName, fromDateTime);
If (fromCreateDateTime > 1.0) Then
SBSystem.SetCreateDateTime(toFName, fromCreateDateTime);
Result:='';
end;
end;
Return value: An error message if the script cannot reconnect, otherwise an empty string
This function is called to tell the script to reconnect to the storage location. This is called when LocConnected indicates it is not connected, for example. Return an error message if the reconnect failed, e.g. it cannot reconnect because the network is down.
function LocRemoveDir(FullPath);
FullPath: The complete path of the empty directory to delete
Return value: An error message if the directory cannot be deleted, otherwise an empty string
This function is called when the location should delete an empty directory. The entire path of the directory to delete is passed. If the directory cannot be deleted then an error message should be returned.
Note that an empty string should be returned if the directory does not exist. Do not return an error message.
IMPORTANT: Do not delete a directory unless it is empty, i.e. it contains no files and no sub-directories.
For example:
function LocRemoveDir(FullPath);
var
Folder;
begin
Result:='';
FullPath:=ExtractFilename(FullPath);
If FullPath = '' Then
Exit;
Else If gFSO.FolderExists(FullPath) Then begin
Folder:=gFSO.GetFolder(FullPath);
If (Folder.Files.Count > 0) Then begin
Result:='Directory contains files'
Exit;
end;
If (Folder.SubFolders.Count > 0) Then begin
Result:='Directory contains directories'
Exit;
end;
Folder.Delete(TRUE);
Folder:=Unassigned;
end;
end;
function LocRenameDir(OldFullPath, NewFullPath);
OldFullPath: The existing path
NewFullPath: The new path (rename it to this)
Return value: An error message if the directory cannot be renamed, otherwise an empty string
This function is called when the script must rename a directory. Entire paths are passed, including the base path. If the directory cannot be renamed then return an error message.
For example:
function LocRenameDir(FromPath, ToPath);
var
TempFldr;
begin
If (FromPath = '') Then begin
Result:='Root directory cannot be moved'
Exit;
end Else If (ToPath = '') Then begin
Result:='Cannot move to root directory'
Exit;
end;
If Not gFSO.FolderExists(FromPath) Then begin
Result:='Source directory does not exist'
Exit;
end;
If gFSO.FolderExists(ToPath) Then begin
If SBSystem.SameFilenames(FromPath, ToPath, TRUE) Then begin
Result:='To destination directory already exists'
Exit;
end;
end;
// Do not include trailing backslash
If SBSystem.IsFolder(FromPath) Then
FromPath:=SBSystem.ExcludeTrailingBackslash(FromPath);
If SBSystem.IsFolder(ToPath) Then
ToPath:=SBSystem.ExcludeTrailingBackslash(ToPath);
// Cannot rename just the case, e.g. \abc to \ABC
// Must instead do a two-step process
If SBSystem.SameFilenames(FromPath, ToPath, FALSE) Then begin
TempFldr:=ToPath + '.' + SBSystem.UniqueID;
gFSO.MoveFolder(FromPath, TempFldr);
gFSO.MoveFolder(TempFldr, ToPath);
end Else
gFSO.MoveFolder(FromPath, ToPath);
Result:='';
end;
function LocRenameFile(OldFullFilename, NewFullFilename);
OldFullFilename: The existing filename
NewFullFilename: The new filename (rename it to this)
Return value: An error message if the file cannot be renamed, otherwise an empty string
This function is called when the script must rename a file. Entire filenames are passed, including the base path. If the file cannot be renamed then return an error message.
For example:
function LocRenameFile(FromName, ToName);
var
FileObj, Attrs;
begin
If Not gFSO.FileExists(FromName) Then begin
Result:='Source file does not exist';
Exit;
end;
// Get file attributes. Rename will give archive attribute.
FileObj:=gFSO.GetFile(FromName);
Attrs:=FileObj.Attributes;
If gFSO.FileExists(ToName) Then begin
If SBSystem.SameFilenames(FromName, ToName, TRUE) Then begin
Result:='To destination file already exists';
Exit;
end;
end;
gFSO.MoveFile(FromName, ToName);
Result:='';
// Set attributes
FileObj:=gFSO.GetFile(ToName);
FileObj.Attributes:=Attrs;
end;
function LocScanList(FullPath);
FullPath: The complete directory path including the base path
Return value: An error message if the directory cannot be scanned, otherwise an empty string
This function is called when the script must tell SyncBack what files and sub-directories are in a directory. The entire path of the directory to scan is passed. For each file it must call SBLocation.AddFile, and for each folder it must call SBLocation.AddDir. If the directory cannot be scanned, e.g. access denied or it doesn't exist, then an error message should be returned.
For example:
function LocScanList(FullPath);
var
Folder, DiskDrive, DriveLetter, DrivePath,
SubFol, FileItem, DrivesEnum, FoldersEnum, FilesEnum;
begin
Result:='';
if (FullPath = '\') or (FullPath = '') then begin
//
// Return the list of drives
//
DrivesEnum:=TEnumVariant.Create(gFSO.Drives);
try
while DrivesEnum.ForEach(DiskDrive) do begin
If (DiskDrive.IsReady = TRUE) then
If not SBLocation.AddDir(DiskDrive.DriveLetter) then
Exit;
end;
finally
DrivesEnum.Free;
end;
end else begin
//
// Return the list of folders and files
//
DriveLetter:=Copy(FullPath, 2, 1);
if (DriveLetter = '') then
Exit;
DrivePath:=Copy(FullPath, 3, Length(FullPath) - 2);
If (DrivePath = '') then
DrivePath:= '\';
// Return a list of sub-folders
Folder:=gFSO.GetFolder(DriveLetter + ':' + DrivePath);
FoldersEnum:=TEnumVariant.Create(Folder.SubFolders);
try
while FoldersEnum.ForEach(SubFol) do begin
If not SBLocation.AddDirEx2(SubFol.Name, SubFol.Attributes, SubFol.DateLastModified, SubFol.DateCreated, '') then
Exit;
end;
finally
FoldersEnum.Free;
end;
// Return a list of files
FilesEnum:=TEnumVariant.Create(Folder.Files);
try
while FilesEnum.ForEach(FileItem) do begin
If not SBLocation.AddFileEx(FileItem.Name, '', VarToInt64(FileItem.Size), FileItem.Attributes, FileItem.DateLastModified, FileItem.DateCreated, '') then
Exit;
end;
finally
FilesEnum.Free;
end;
end;
end;
Return value: An error message if the storage location cannot be prepared, otherwise an empty string
This function is called to tell the script to prepare the storage location for scanning. It is called after LocConnect.
function LocSetAttributes(Filename, Attributes);
Filename: The complete path of the file or directory
Attributes: The filesystem attributes to set the file or directory to
Return value: An error message if the attributes cannot be set, otherwise an empty string
This function is called when the filesystem attributes for a file or directory need to be set. The entire path of the file or directory to change the attributes of is passed. Note that if it's a directory then it will have a trailing backslash. If the attributes cannot be changed then an error message should be returned.
For example:
function LocSetAttributes(Filename, Attrs);
var
FolderObj, FileObj;
begin
Filename:=ExtractFilename(Filename);
If (Filename = '') Then begin
// Its a special folder
Result:='Cannot set roots attributes';
Exit;
end;
If SBSystem.IsFolder(Filename) Then begin
//
// A folder
//
If not gFSO.FolderExists(Filename) Then begin
Result:='Folder does not exist';
Exit;
end;
FolderObj:=gFSO.GetFolder(Filename);
FolderObj.Attributes:=Attrs;
Result:='';
end Else begin
//
// A file
//
If not gFSO.FileExists(Filename) Then begin
Result:='File does not exist';
Exit;
end;
FileObj:=gFSO.GetFile(Filename);
FileObj.Attributes:=Attrs;
Result:=''
end;
end;
function LocSetCreateDateTime(Filename, CreateDateTime);
Filename: The complete path of the file or folder
CreateDateTime: The creation date & time (local timezone)
Return value: An error message if the date & time cannot be changed, otherwise an empty string
This function is called when the creation date & time of a file or folder must be changed. The entire path of the file to change the date & time of is passed. If the creation date & time cannot be changed then an error message should be returned.
For example:
function LocSetCreateDateTime(FullPath, CreateDateTime);
begin
Result:=SBSystem.SetCreateDateTime(FullPath, CreateDateTime);
end;
function LocSetModDateTime(Filename, ModDateTime);
Filename: The complete path of the file
ModDateTime: The last modication date & time (local timezone)
Return value: An error message if the date & time cannot be changed, otherwise an empty string
This function is called when the last modification date & time of a file must be changed. The entire path of the file to change the date & time of is passed. If the last modification date & time cannot be changed then an error message should be returned.
For example:
function LocSetModDateTime(FullPath, ModDateTime);
begin
Result:=SBSystem.SetLastModDateTime(FullPath, ModDateTime);
end;
function LocSHA1(Filename; var SHA1);
Filename: The complete path of the file to get the hash value of
SHA1: Set this to the SHA1 hash value of the file, in string format
Return value: An error message if the SHA1 cannot be retrieved, otherwise an empty string
This function is called when the SHA1 hash value of a file is required, e.g. for file integrity verification. The entire filename is passed, including the base path. If the SHA1 hash value cannot be retrieved then an error message should be returned.
Note that the SHA1 hash value should be returned in string format, e.g. E75A6A52
For example:
function LocSHA1(FullPath; var SHA1);
begin
SHA1:=SBSystem.SHA1(FullPath);
Result:='';
end;
function LocSHA256(Filename; var SHA256);
Filename: The complete path of the file to get the hash value of
SHA256: Set this to the SHA256 hash value of the file, in string format
Return value: An error message if the SHA256 cannot be retrieved, otherwise an empty string
This function is called when the SHA256 hash value of a file is required, e.g. for file integrity verification. The entire filename is passed, including the base path. If the SHA256 hash value cannot be retrieved then an error message should be returned.
Note that the SHA256 hash value should be returned in string format, e.g. E75A6A52
For example:
function LocSHA256(FullPath; var SHA256);
begin
SHA256:=SBSystem.SHA256(FullPath);
Result:='';
end;
function LocSHA512(Filename; var SHA512);
Filename: The complete path of the file to get the hash value of
SHA512: Set this to the SHA512 hash value of the file, in string format
Return value: An error message if the SHA512 cannot be retrieved, otherwise an empty string
This function is called when the SHA512 hash value of a file is required, e.g. for file integrity verification. The entire filename is passed, including the base path. If the SHA512 hash value cannot be retrieved then an error message should be returned.
Note that the SHA512 hash value should be returned in string format, e.g. E75A6A52
For example:
function LocSHA512(FullPath; var SHA512);
begin
SHA512:=SBSystem.SHA512(FullPath);
Result:='';
end;
All Content: 2BrightSparks Pte Ltd © 2003-2024