24U SimpleFile Plug-In 2.0 Syntax

SFile_Version( { versionFormat } )

Returns version string of the active 24U SimpleFile Plug-In, formatted as requested by the parameter.

Parameters

Parameter values for versionFormat

Description

This function is very important and it has the same output format in all 24U Plug-Ins. You should call this function every time you need to check if the plug-in is properly installed to the FileMaker. Even if the plug-in is not registered (or badly registered) this function should work. Calling this function in the startup script of your solution is recommended.

Result

Returns requested version format or platform. If this function returns "?" than the plug-in is not properly installed or FileMaker cannot load and activate it for some reason.

Examples

SFile_Version( "long" )
This will return the plug-in name and its version. In this case it is "24U SimpleFile Plug-In 2.0".

SFile_Version( "platform" )
Returns "Mac OS X" or "Windows" depending on the platform the plug-in is currently running.

SFile_Version( "autoupdate" )
Returns "02030400" for the plug-in version 2.3.4.

SFile_Register( originalSerialNumber { & " " & upgradeSerialNumber... } )

Attempts to unlock (register) your copy of 24U SimpleFile Plug-In with the specified code.

Parameters

Description

If the code(s) is valid, 24U SimpleFile Plug-In gets unlocked and stays in this state until you quit the FileMaker Pro application, deactivate the plug-in, or the registration code expires. While unlocked, 24U SimpleFile Plug-In is fully functional and does not bother the user with a shareware reminder.

Result

Returns a non-zero error code when the serial numbers are wrong if the numbers cannot be used. Returns 0 if the plug-in was successfully registered.

Examples

SFile_Register( "SFI10J-CM244H-U4UGBN" )
This function will register the plug-in with serial number SFI10J-CM244H-U4UGBN. This method is useful when you register the plug-in with developer license but it can be used for end-user licenses as well.

SFile_Register( "SFI10J-CM244H-U4UGBN SFI20J-BTPDSK-D3AJ9C" )
Use combination of serial numbers delimited by empty space to register using upgrade code. The first code must be the original one, all other codes should be upgrade codes.

SFile_Register( "SFI10J-CM244H-U4UGBN SFI20J-BTPDSK-D3AJ9C SFI30J-5B4J7Z-W9KFNS" )
The example of using one original number and two upgrade numbers. The original is for version 1.0 and upgrades are for 2.0 and 3.0.

Note: All serial numbers here are only for demonstration purposes. They will not work in real plug-in.

SFile_Choose( itemKind )

Displays a system dialog for choosing an existing file or folder or a destination for a new file.

Parameters

Description

Use this function to invoke operating system dialog to Open or Save file or folder.

Result

Function returns a value list of native full paths chosen by the user. If user clicks cancel button the function returns -128. In the case of error the function returns negative error code.

Examples

SFile_Choose( "new" )
Function invokes "Save As..." dialog where you can specify the name of the new file or folder.

SFile_New( path { ; itemKind } )

Creates new folder (default) or empty file on the specified path.

Parameters

Description

Use this function to create the new file or folder. If the file / folder already exists error -48 is returned and no new item is created. Using SFile_Choose( "new" ) is recommended to obtain valid path.

Result

Function returns 0 if file or folder was created. Otherwise it returns negative error code.

Examples

SFile_New( "C:\\Users\\me\Documents\\TextFile.txt" ; "file" )
This will create a new text file in Documents folder of the user "me" in Windows Vista or 7.

SFile_New( "/Users/me/Documents/NewFolder" ; "folder" )
This will create a new folder "NewFolder" in Documents folder of user "me" on Mac OS X.

SFile_New( "Log.txt" ; "file" )
This will create a new file named "Log.txt" on the same folder where current active FileMaker solution is.

SFile_Delete( path )

Deletes specified file or folder, recursively if it is not empty.

Parameters

Description

This function deletes specified existing file or folder. It can be very dangerous if misused - it recursively deletes folders. The function does not follow symbolic links however. It uses operating system functions so the file or folder will be moved to Trash and not deleted irreversibly.

Result

Function returns 0 if the file or folder was deleted. Otherwise it returns negative error code.

Examples

SFile_Delete( "C:\\Users\\me\\Documents\\OldNastyFile.doc" )
The file "OldNastyFile.doc" in path "C:\Users\me\Documents" will be deleted in Windows.

SFile_Delete( "/Users/me/WrongScript.command" )
The script file "WrongScript.command" in path "/Users/me" will be deleted in Mac OS X.

SFile_Delete( "Something" )
The item named "Something" will be deleted. The plug-in tries to find file or folder named "Something" in the same folder as currently running FileMaker solution. If it finds file or folder it will delete it.

SFile_Copy( sourcePath ; targetPath )

Duplicates specified file, or folder including all contents.

Parameters

Description

If targetPath specifies an existing folder, source item is copied into the target under the source's original name. If targetPath specifies a non-existing item in an existing folder, the source item is copied under new name specified by the targetPath. Fails if target item already exists (error -48).

Result

Function returns 0 if the item was duplicated. Otherwise it returns negative error code.

Examples

SFile_Copy( "C:\\Users\\me\\Documents\\OldNastyFile.doc" ; "C:\\Users\\you\\Documents\\NewNiceFile.doc" )
Duplicates "OldNastyFile.doc" to the new file "NewNiceFile.doc".

SFile_Copy( "pictures/BigPicture.jpg" ; "/Volumes/ImgVolume" )
The file "BigPicture.jpg" stored in directory "pictures", which is in the same directory as the solution, will be copied into folder "/Volumes/ImgVolume".

SFile_Move( sourcePath ; targetPath )

Moves or renames specified file or folder.

Parameters

Description

If targetPath specifies an existing folder, source item is moved into the target under the source's original name. If targetPath specifies a non-existing item in an existing folder, the source item is moved and renamed to a new name specified by the targetPath. If the second parameter is not a valid path it is considered being plain file name alone and the source item is just renamed. Fails if target item exists (error -48), or if the target item's volume is different from the source item's volume (error -1303). In this case use SFile_Copy( sourcePath ; targetPath ) and SFile_Delete( sourcePath ) instead.

Result

Function returns 0 if the file or folder has been moved. Otherwise it returns negative error code.

Examples

SFile_Move( "FileWithBadName.dat" ; "FileWithGoodName.dat" )
This will rename the file with name "FileWithBadName.dat" to "FileWithGoodName.dat" in the current folder of the solution.

SFile_Move( "C:\\Temp\\game_config_backup.ini" ; "C:\\Game\\SomeGame\\GameConfig.ini" )
Move file "game_config_backup.ini" to the folder "C:\Game\SomeGame\" and rename it to "GameConfig.ini".

SFile_Move( "C:\\Temp\\game_config_backup.ini" ; "D:\\Game\\SomeGame\\GameConfig.ini" )
Will fail with -1303 because source and target volumes (drives) do not match.

SFile_Read( path { ; startIndex { ; maxLength } } { ; encoding } )

Reads file or folder content.

Parameters

Description

This is a universal reader of files and folders. It can read any file, text or binary and it can list the contents of the folder.

Result

The function returns bytes or characters read from the file. In the case of error the function returns "?" and error code is set. Use SFile_Get( "lastError" ) to obtain error code.

Examples

SFile_Read( "SomeText.txt" )
Read contents of the file "SomeText.txt" in the same directory as the solution. Plug-In uses default values, this means it presumes that: Encoding is default system (Mac-Roman on Mac, CP-1252 on Windows) and file type is Text.

SFile_Read( "SomeText.txt" ; 25 ; 1000 )
Similar to previous example. The plug-in will start reading from 25th byte of file and reads only 1000 bytes.

SFile_Read( "/Library/Preferences/Configuration.conf" ; 42 ; 80 ; "utf-8" )
This command will return the content of the file "Configuration.conf" from folder /Library/Preferences/. Data are from 42nd byte. It reads only 80 bytes and decode the text from utf-8 encoding.

SFile_Read( "file:///Library/Preferences/Configuration.conf" ; -80 ; 80 ; "utf-8" )
Very similar to previous example demonstrating another path type. It reads last 80 bytes in file and decode the text from utf-8 encoding.

SFile_Write( path ; data { ; startIndex } { ; encoding } )

Writes content to the file.

Parameters

Default file encoding used in encoding parameter for data.

Description

Use this function to write to existing files or to create the new one. The function is able to write binary data from container but don't use it to convert binary data between formats. If you use SFile_Read to load jpg picture this function cannot convert it to gif for example.

Result

The function returns the number of bytes / characters which were actually written. In the case of error the function returns "?" and error code is set. Use SFile_Get( "lastError" ) to obtain error code.

Examples

SFile_Write( "C:\\Documents\\TextFile.txt" ; "Hello World!" )
This function will create (or rewrite) the file "TextFile.txt" to "C:\Documents" folder and it writes text "Hello World!" into this file using operating system default encoding.

SFile_Write( "notes.txt" ; "Interesting note" )
Writes text "Interesting note" into file "notes.txt" in the same directory as the solution.

SFile_Write( "/var/logs/log.txt" ; "09:31 - Something happened\n" ; -1 ; "utf-8" )
This will append the text "09:31 - Something happened" to the end of the file "log.txt" stored inside "/var/logs" and moves cursor to the next line in file. The text will be written using UTF-8 encoding.

SFile_Write( "picture.jpg" ; pictureContainer ; "image" )
Writes picture from container to file.

SFile_Write( "picture.jpg" ; fmTextField ; "hex-dump" )
Text in the text field must be in the hex-dump form, for example: "FE ED 03 DE AD 42 ...". The plug-in will process each hex number (two characters [0-9,A-F,a-f]) into binary file. All non-hex characters (white spaces, newlines etc...) are ignored.

SFile_Get( selector { ; path } { ; parameter } )

Gets important internal parameters of the plug-in and information about storage system.

Parameters

Parameter values for selector

Description

Use this function to get important parameters of files, folders and system settings.

Result

The function returns actual value of the parameter. In the case of error the function returns "?" and error code is set. Use SFile_Get( "lastError" ) to obtain error code.

Examples

SFile_Get( "created" ; "C:\\Windows" )
Returns the date and time when the Windows folder was created (probably the time when Windows was installed).

SFile_Get( "available-space" ; "D:\\" )
Returns the number of free bytes available on disk D: on Windows.

SFile_Get( "owner-rights" ; "/Users/me/Documents/myDocument.pages" )
Returns "read|write|delete" if you are owner of this bundle / file.

SFile_Get( "type" ; pictureContainer )
Returns "PNGf" if the container has a picture which has been initially loaded from png picture file.

SFile_Get( "FileMaker" ; "/Users/Pete/file.txt" )
Returns "file:/Macintosh HD/Users/Pete/file.txt" on Mac OS X if the system disk is named "Macintosh HD". On Windows it returns "file:/C:/Users/Pete/file.txt" if system disk is C:.

SFile_Get( "FileMaker" ; "C:\\Users\\Pete\\file.txt" )
Returns "file:/Macintosh HD/Users/Pete/file.txt" on Mac OS X if the system disk is named "Macintosh HD". On Windows it returns "file:/C:/Users/Pete/file.txt".

SFile_Get( "native-full" ; "/Users/Pete/file.txt" )
Returns "/Users/Pete/file.txt" on Mac OS X. On Windows it returns "C:\Users\Pete\file.txt".

SFile_Get( "native-full" ; "C:\\Users\\Pete\\file.txt" )
Returns "/Users/Pete/file.txt" on Mac OS X. On Windows it returns "C:\Users\Pete\file.txt".

SFile_Get( "win-full" ; "/Users/Pete/file.txt" )
Returns "C:\Users\Pete\file.txt" on both platforms.

SFile_Get( "URL" ; "/Users/Pete/file.txt" )
Returns "file:///Users/Pete/file.txt" on both platforms.

SFile_Get( "URL" ; "C:\\Users\\Pete\\file.txt" )
Returns "file:///Users/Pete/file.txt" on Mac OS X. On Windows it returns "file://C:/Users/Pete/file.txt"

SFile_Get( "native-full" ; "file.txt" )
Suppose the current active solution in FileMaker is placed in folder "/Users/Pete" on Mac OS X or "C:\Users\Pete" on Windows. The functions returns "/Users/Pete/file.txt" on Mac OS X. On Windows the returned value is "C:\Users\Pete\file.txt".

SFile_Get( "unix-full" ; "file.txt" )
Suppose the current active solution in FileMaker is placed in folder "/Users/Pete" on Mac OS X or "C:\Users\Pete" on Windows. The functions returns "/Users/Pete/file.txt" on both platforms.

SFile_Get( "native-full" ; "../Suzan/file.txt" )
Suppose the current active solution in FileMaker is placed in folder "/Users/Pete" on Mac OS X or "C:\Users\Pete" on Windows. The functions returns "/Users/Suzan/file.txt" on Mac OS X. On Windows the returned value is "C:\Users\Suzan\file.txt".

SFile_Set( selector ; path ; newValue )

Sets important internal parameters of the plug-in and information about storage system.

Parameters

Parameter values for selector

Description

Use this function to set important parameters.

Result

The function returns actual value of the parameter. In the case of error the function returns "?" and error code is set. Use SFile_Get( "lastError" ) to obtain error code.

Examples

SFile_Set( "owner" ; "/Users/me/Documents/someFile.txt" ; "me" )
Changes file owner of the file on path "/Users/me/Documents/someFile.txt" to "me".

SFile_Set( "everyone-rights" ; "C:\\Documents and Settings\\me\\Documents\\someFile.txt" ; "read|write|delete" )
Everyone can read file, write to file and delete file "someFile.txt".