This file describes syntax of 24U SimpleFile Plug-In's functions.
Returns version string of the active 24U SimpleFile Plug-In, formatted as requested by the parameter.
| versionFormat | Defines the format of the returned version. |
| short | To get just the version number. Default value. |
| long | To get the plug-in name followed by its version number |
| platform | To get the platform of the code currently running |
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.
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.
SFile_Version( "long" )
This will return the plug-in name and its version. In this case it is "24U SimpleFile Plug-In 1.1.1".
SFile_Version( "platform" )
Returns "Mac OS X" or "Windows" depending on the platform the plug-in is currently running.
Attempts to unlock (register) your copy of 24U SimpleFile Plug-In with the specified code.
| originalSerialNumber | The original (non upgrade) code to unlock the full version of the plug-in. |
| upgradeSerialNumber | The upgrade code to unlock the full version of the plug-in. |
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.
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.
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.
Creates new folder (default) or empty file with the specified fileSpec.
| fileSpec | The path to new file or folder. To see valid path type look go to: Paths in SimpleFile |
| itemKind | Specifies what can be created. Can be either "folder" (default) or "file". |
Use this function to create the new file or folder. Using SFile_Choose( itemKind ) is recommended to obtain valid fileSpec. SimpleFile allways tries "best effort" to understand the path presuming that it is inserted correctly.
Function returns 0 if file or folder was created. Otherwise it returns negative error code.
SFile_New( "C:\\Users\\me\\Documents\\TextFile.txt" ; "file" )
This will create a new text file on in Documents folder of user "me" on Windows Vista.
SFile_New( "/Users/me/Documents/NewFolder" ; "folder" )
This will create a new folder "NewFolder" in Documents folder of user "me" on Mac OS X.
Deletes specified file or folder, recursively if it is not empty.
| fileSpec | The path to existing file or folder. To see valid path type look go to: Paths in SimpleFile |
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. Use with care.
Function returns 0 if the file or folder was deleted. Otherwise it returns negative error code.
SFile_Delete( "C:\\Users\\me\\Documents\\OldNastyFile.doc" )
The file "OldNastyFile.doc" in path "C:\Users\me\Documents" will be immediately deleted in Windows.
SFile_Delete( "/Users/me/WrongScript.command" )
The script file "WrongScript.command" in path "/Users/me" will be immediately deleted in Mac OS X.
Duplicates specified file, or folder including all contents.
| sourceFileSpec | The path to source file or folder. To see valid path type look go to: Paths in SimpleFile |
| targetFileSpec | The path to destination file or folder |
If targetFileSpec specifies an existing folder, source item is copied into the target under the source's original name. If targetFileSpec specifies a non-existing item in an existing folder, the source item is copied under new name specified by the targetFileSpec. Fails if target item already exists (error -48).
Function returns 0 if the item was duplicated. Otherwise it returns negative error code.
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".
Moves or renames specified file or folder.
| sourceFileSpec | The path to source file or folder. To see valid path type look go to: Paths in SimpleFile |
| targetFileSpec | The path to destination file or folder |
If targetFileSpec specifies an existing folder, source item is moved into the target under the source's original name. If targetFileSpec specifies a non-existing item in an existing folder, the source item is moved and renamed to a new name specified by the targetFileSpec. If the second parameter is not a valid file specification 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( sourceFileSpec ; targetFileSpec ) and SFile_Delete( sourceFileSpec ) instead.
Function returns 0 if the file or folder was moved. Otherwise it returns negative error code.
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.
Displays a system dialog for choosing an existing file or folder or a destination for a new file.
| itemKind | Three kinds are possible: "file" to choose existing file, "folder" to choose existing folder and "new" to open system dialog with new file (Save As dialog). |
Use this function to invoke operating system dialog to Open or Save file or folder.
Function returns a native full path if user choose one. If user clicks cancel button the function returns -128. In the case of error the function returns negative error code.
SFile_Choose( "new" )
Function invokes "Save As..." dialog where you can specify the name of the new file or folder.
Reads file or folder's contents.
| fileSpec | The path to existing file or folder. To see valid path type look go to: Paths in SimpleFile |
| startIndex | Specifies where to start reading. Searching begins from start if the number is positive and from end of the file if the number is negative. The number is in bytes except for utf-16 encoding where it is in 16-bit characters. |
| maxLength | The maximum number of characters to read. The default is "to the end of file" |
| encoding | The encoding of the file. This can be text or binary encoding. To see full list of encodings got to: Encodings List. The default is the default system encoding for text files. |
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.
Function returns file's or folder's content if successfull. In the case of error it returns negative error code.
SFile_Read( "SomeText.txt" )
Read contents of the file "SomeText.txt". 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 (because the default encoding is byte oriented).
SFile_Read( "/Library/Preferences" )
List the contents of the directory "Preferences" inside directory "Library".
Writes contents into file.
| fileSpec | The path file. To see valid path type look go to: Paths in SimpleFile |
| data | The data to be written. Use FileMaker text field for text files and for hex-dump encoding and FileMaker container for binary files. |
| startIndex | Specifies where to start writing. Searching begins from start if the number is positive and from end of the file if the number is negative. The number is in bytes except for utf-16 encoding where it is in 16-bit characters. |
| encoding | The encoding of the file. This can be text or binary encoding. To see full list of encodings got to: Encodings List. The default is the default system encoding for text files. |
Use this function to write to existing files or to create the new one.
Function returns 0 is the file was written. In the case of error it returns the negative error code.
SFile_Write( "notes.txt" ; "Interesting note" )
Writes text "Interesting note" into file "notes.txt". If the file exists it will be created again.
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.
Function to get parameters of file or folder or to get global plug-in settings.
| what | Which data shoud be get. |
| fileSpec | The file or folder which should be examined. To see valid path type look go to: Paths in SimpleFile |
| what | Description |
|---|---|
| "kind" | Returns "file" if the path specifies an existing file "folder" if the path specifies an existing folder. Symbolic links are considered as files and Mac OS X volumes as folders. Returns error code if the object does not exist. |
| "created" | Returns item's creation date & time as timestamp. |
| "modified" | Returns item's modification date & time as timestamp. |
| "size" | Returns item's total size in bytes. |
| "data-size" | Returns item's data fork size in bytes. The same as "size" on Windows. |
| "resource-size" | Returns item's resource fork size in bytes. Returns 0 on Windows. |
| "available-space" | Returns available space in bytes on the disk where fileSpec belongs to. |
| "owner" | Returns item's owner. |
| "group" | Returns item's group. |
| "owner-rights" | Returns item's owner access rights. |
| "group-rights" | Returns item's group access rights. |
| "everyone-rights" | Returns item's access rights. |
| fileSpecKind | Converts path from one type to another. The list of supported path types are in the next table. |
| fileSpecKind | Description |
|---|---|
| "fsspec" | Returns Macintosh fsspec. This is unique file or folder identifier used in old Mac OS. Today it is obsolete. The format is: "fsspec:VolumeID:FolderID:FileName". On Windows the FileName contains full path to the file and VolumeID and FolderID are 0. |
| "native-relative" | Relative path in the form native to the system. |
| "native-full" | Full path in the form native to the system. |
| "win-relative" | Relative path in the form native to Windows. The backslash is used as a separator. |
| "win-full" | Full path in the form native to Windows. On Mac. |
| "unix_relative" | Returns item's resource fork size in bytes. Returns 0 on Windows. |
| "unix-full" | Returns available space in bytes on the disk where fileSpec belongs to. |
| "FileMaker" | Returns item's owner. |
| "URL" | Returns item's group. |
Use this function to get important parameters for file or folder.
Function returns data if everything is OK. In case of error the function returns negative error code.
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 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 file.
Function to set parameters of files or folders or to set global plug-in settings.
| what | Which data shoud be set. |
| fileSpec | The file or folder which parameters should be changed. To see valid path type look go to: Paths in SimpleFile |
| newValue | The new value of the parameter. |
| what | Description |
|---|---|
| "created" | Set the file creation date and time. Use FileMaker timestamp stored in newValue parameter. |
| "modified" | Set the file modification date and time. Use FileMaker timestamp stored in newValue parameter. |
| "owner" | Sets the file owner. You must have the permission to change owner. |
| "group" | Sets the file group. You must have the permission to change group. |
| "owner-rights" | Sets the file permissions for owner. You must have the permission to change permissions. |
| "group-rights" | Sets the file permissions for group. You must have the permission to change permissions. |
| "everyone-rights" | Sets the file permissions for everyone. You must have the permission to change permissions. |
Use this function to set important parameters.
Function returns 0 if everything is OK. In case of error the function returns negative error code.
SFile_Set( "owner" ; "/Users/me/Documents/someFile.txt" ; "me" )
Change file owner 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".
SimpleFile accepts and converts several path types. Here are some examples and how to use them:
| Path Example | Description |
|---|---|
| "C:\directory\file.ext" | The Windows full path. Use this type on Windows when you want to specify the exact file or folder position. On Mac OS X SimpleFile tries to convert path to this form: "/directory/file.ext". |
| "/directory/file.ext" | Standard unix full path. Use this type on Mac OS X to specify exact file or folder position. On Windows SimpleFile tries to convert the path to the form: "C:\directory\file.ext". |
| "directory\file.ext" | The Windows relative path. Use this type to specify path to file or folder relatively to position of the solution file. If you don't know where your solution will be located (i.e. on FileMaker Server) use full paths instead. On Mac OS X SimpleFile tries to convert this form to the unix one: "directory/file.ext". |
| "directory/file.ext" | This is the unix relative path. Use this type to specify path to file or folder relatively to position of the solution file. If you don't know where your solution will be located (i.e. on FileMaker Server) use full paths instead. On Windows SimpleFile tries to convert this form to the Windows one: "directory\file.ext". |
| "file:\volume\directory\file.ext" | This is the FileMaker path format. This format can be used in both platforms. |
| "file:\\\path\to\file.ext" | URL used on unix. 24U SimpleFile Plug-In can read local files using URL. Use the same format as in your internet browser for local files. |
| "fsspec:-100:883688:file.ext" | The old Macintosh FSSpec. This format is obsolete. It has been used in old Mac OS prior to Mac OS X. If you try to use this on Windows SimpleFile will take the only the last part and tries to use it as relative or absolute path. |
This is the list of valid encodings.
| what | Description |
|---|---|
| "default", "text" | The system default encoding for text files. On english system it is "x-mac-roman" on Mac and "windows-1252" on Windows. |
| "hex-dump" | Useful for reading binary files. The content is returned in hex numbers delimited by space. |
| "utf-16" | Text files encoded in 16-bit encoding. |
| "utf-8" | Utf-8 unicode encoding. The number of bytes is not equal to number of characters. |
| "x-mac-roman", "x-mac-arabic", "x-mac-centraleurroman", "x-mac-chinesesimp", "x-mac-chinesetrad", "x-mac-cyrillic", "x-mac-greek", "x-mac-hebrew", "x-mac-japanese", "x-mac-korean", "x-mac-turkish" | Macintosh 8-bit encodings. The first is the most used. |
| "dos", "windows-1252", "windows-1250", "windows-1251", "windows-1253", "windows-1254", "windows-1255", "windows-1256", "windows-1257" | Windows 8-bit encodings. Windows-1252 is used in the English version of Windows.. |
| "iso-8859-15", "iso-8859-2", "iso-8859-3", "iso-8859-4", "iso-8859-5", "iso-8859-6", "iso-8859-7", "iso-8859-8", "iso-8859-9" | The encodings defined by the ISO standard. |
| "euc-jp", "euc-kr", "gb2312", "johab" | The other text encodings. |
| "image" | The image type. The result of the function will be the FileMaker container filled with image. |
| "file" | The general file type. The result of the function will be the FileMaker container with the file icon. |