Xojo Developer Conference
25/27th April 2018 in Denver.
MBS Xojo Conference
6/7th September 2018 in Munich, Germany.

Platforms to show: All Mac Windows Linux Cross-Platform

Previous items Next items

NewFolderItemFSRefMBS(fsref as memoryblock) as FolderItem
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
global method Files MBS Util Plugin Yes No No Yes, macOS only No
Function: Creates a FolderItem from a specified FSRef.
Example:
dim f,g as folderItem
dim m as memoryBlock

f=getfolderItem("")

m=f.FSRefMBS

g=NewFolderItemFSRefMBS(m)
msgBox g.absolutePath // same path as f
Notes: Only useful for toolbox calls and on Mac OS 9 and later.

Feedback, Comments & Corrections

NewFolderItemFSRefNameMBS(fsref as memoryblock,name as string) as FolderItem
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
global method Files MBS Util Plugin 3.2 Yes No No Yes, macOS only No
Function: Creates a FolderItem from a specified FSRef.
Notes: Only useful for toolbox calls and on Mac OS 9 and later.

Feedback, Comments & Corrections

NewFolderItemFSSpecMBS(fsspec as memoryblock) as FolderItem
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
global method Files MBS Util Plugin Yes Yes No Yes No
Function: Creates a FolderItem from a specified FSSpec.
Example:
dim f,g as folderItem
dim m as memoryBlock

f=getfolderItem("")

m=f.FSSpecMBS

g=NewFolderItemFSSpecMBS(m)
msgBox g.absolutePath // same path as f
Notes:
Only useful for toolbox calls.
With plugin version 3.2, this works also on Windows if QuickTime is installed!

Feedback, Comments & Corrections

NewFolderItemMBS(vRefNum as Integer, parID as Integer, name as String) as FolderItem
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
global method Files MBS Mac Plugin Yes No No Yes, macOS only No
Function: Creates a FolderItem from a specified volume, the item's directory ID and its name.
Notes: The vRefNum with value -1 is the boot volume on Mac OS.

Feedback, Comments & Corrections

NewVolumeFolderItemMBS(vRefNum as Integer) as FolderItem
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
global method Files MBS Mac Plugin Yes No No Yes, macOS only No
Function: Creates a FolderItem from a specified volume based on the volume reference number.
Example:
dim f as folderItem

f=NewVolumeFolderItemMBS(-1)
msgBox f.absolutePath
Notes:
The vRefNum with value -1 is the boot volume on Mac OS.

Pass in the vRefNum of any mounted volume and it returns the Volume as a FolderItem.
Returns nil if the vRefNum was invalid.

Some examples using this method:

Feedback, Comments & Corrections

Folderitem.OpenAsLargeBinaryStreamMBS(write as Boolean) as LargeBinaryStreamMBS
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS Util Plugin Yes Yes Yes Yes No
Function: Opens a file as a LargeBinaryStreamMBS.
Example:
dim l as LargeBinaryStreamMBS
dim f as FolderItem = SpecialFolder.Desktop.Child("testfile")

l=f.OpenAsLargeBinaryStreamMBS(true)
Notes: Returns nil on any error.

Some examples which use this method:

Feedback, Comments & Corrections

folderitem.OpenAsResStreamMBS(write as Boolean) as ResStreamMBS
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS Util Plugin Yes No No Yes, macOS only No
Function: Opens a file's resourcefork as a ResStreamMBS.
Notes: Returns nil on any error.

Some examples which use this method:

Feedback, Comments & Corrections

Folderitem.OpenWithAppMBS(TheApplication as FolderItem, inFront as Boolean) as Boolean
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS Mac Plugin Yes Yes No Yes No
Function: Opens a file using the given application.
Notes:
Similar to Launch (see Folderitem.Launch), with the additional option to specify the application that should be used to open the FolderItem object. Passing nil in the app parameter is functionally identical to calling Launch.

Works with Graphicconverter, but not with Preview!?
Added Windows support in version 3.4.

Some examples which use this method:

Feedback, Comments & Corrections

FolderItem.ParentVolumeMBS as folderitem
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS Util Plugin 9.7 Yes Yes Yes Yes No
Function: Returns the folderitem for the volume the folderitem is pointing to.

Feedback, Comments & Corrections

PathToFolderItemMBS(path as string) as folderitem
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
global method Files MBS MacOSX Plugin Yes No No Yes, macOS only No
Function: Returns a folderitem for the given unix path.
Notes:
Works only on Mac OS X.
This function is not very good, as Apple doesn't document which path is exspected, which encoding the path should use (maybe UTF8) and when it fails.
(e.g. it currently doesn't work for paths with "~" inside)

Some examples using this method:

Feedback, Comments & Corrections

Folderitem.PermissionsMBS(OldWay as boolean) as PermissionsMBS
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS MacOSX Plugin Yes No No Yes, macOS only No
Function: Returns an object for the Permissions of a file.
Example:
dim f as FolderItem
dim p as PermissionsMBS

f=GetOpenFolderItem("special/any")

if f<>nil then
p=f.PermissionsMBS(true)

if p<>Nil then // requires Mac OS X
p.Access=&H6

// &h000006 = -rw-------
// &h000600 = ----rw----
// &h060000 = -------rw-

if 0=p.SetPermissions(true) then
MsgBox "Permissions set"
else
MsgBox "Permissions could not be set"
end if
else
MsgBox "We require Mac OS X"
end if
else
' nothing selected
end if
Notes:
You can use old API if you set Oldway=true. Than you set access value like in older version of the plugin.
If you set Oldway = false, you use the newer API which set unix permissions, but not the old ones.
The old way is not supported for 64bit.

Some examples which use this method:

Feedback, Comments & Corrections

folderitem.PhysicalFileDataLengthMBS as int64
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS Util Plugin 7.4 Yes Yes Yes Yes No
Function: Returns the length of the physical disk space used for this file's data fork.
Example:
filesize.text=format(file.PhysicalFileDataLengthMBS,"0")
Notes:
This function works for files bigger than 2 GB which RB's built in functions don't.
On Windows the physical size reported is equal to the logical size, because there is no function for the physical size.

Some examples which use this method:

Feedback, Comments & Corrections

folderitem.PhysicalFileResLengthMBS as int64
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS Util Plugin 7.4 Yes Yes Yes Yes No
Function: Returns the length of the physical disk space used for this file's resourcefork.
Example:
filesize.text=format(file.PhysicalFileResLengthMBS,"0")
Notes:
This function works for files bigger than 2 GB which RB's built in functions don't.
On Windows the physical size reported is equal to the logical size, because there is no function for the physical size.

Some examples which use this method:

Feedback, Comments & Corrections

folderitem.PhysicalFileTotalLengthMBS as int64
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS Util Plugin 7.4 Yes Yes Yes Yes No
Function: Returns the length of the physical disk space used for this file.
Example:
filesize.text=format(file.PhysicalFileTotalLengthMBS,"0")
Notes:
This function works for files bigger than 2 GB which RB's built in functions don't.
On Windows the physical size reported is equal to the logical size, because there is no function for the physical size.

Some examples which use this method:

Feedback, Comments & Corrections

Folderitem.SetFileFlagsMBS(flags as Integer) as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS Mac Plugin Yes No No Yes, macOS only No
Function: Set the file flags for the folderitem to the given value. Returns 0 if okay.
Example:
dim f as FolderItem
dim err, fdFlags as Integer

// For example, clearing a file's hasCustomIcon flag works like this:
fdFlags = f.GetFileFlagsMBS
if fdFlags >= 0 then
err = f.SetFileFlagsMBS(BitExclMBS(fdFlags, 10))
if err <> 0 then
// ... oops, an error occured
// (for instance, the disk could be write protected)
end
end
Notes:
Sets the fdFlags of a file. Returns an error code (or zero if no error occured). Possible error conditions include "disk is write protected" and "file not found".
When changing flags of a file, use GetFileFlags to get the original flags, then clear or set the flags by using BitwiseAnd and BitwiseOr and call SetFileFlags to set the new flags.

Some examples which use this method:

Feedback, Comments & Corrections

Folderitem.SetFolderFlagsMBS(flags as Integer) as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS Mac Plugin Yes No No Yes, macOS only No
Function: Set the folder flags for the folderitem to the given value. Returns 0 if okay.
Example:
Dim f As FolderItem = GetFolderItem("test") // some folder
If f.SetFolderFlagsMBS(BitwiseOr(f.GetFolderFlagsMBS, 4)) <> 0 Then
MsgBox "Can't set label to green."
End If
Notes:
Sets the frFlags of a folder. Returns an error code (or zero if no error occured). Possible error conditions include "disk is write protected" and "folder not found".
When changing flags of a folder, use GetFolderFlags to get the original flags, then clear or set the flags by using BitwiseAnd and BitwiseOr and call SetFolderFlags to set the new flags.

with values 2, 4 and 8 in the flags, you control the label color in Finder. Example code above uses 4 which is green by default.

Some examples which use this method:

Feedback, Comments & Corrections

folderitem.SetTagNamesMBS(tags() as string) as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS MacOSXCF Plugin 13.5 Yes No No Yes, macOS only No
Function: Sets file tags.
Example:
dim f as FolderItem = SpecialFolder.Desktop.Child("test.xojo_binary_project")

dim Tags() as string = Array("Hello", "World")
dim e as Integer = f.SetTagNamesMBS(tags)

MsgBox "SetTagNamesMBS: "+str(e)
Notes:
tags() is array with new tag names.
Provides error code as return value and details about error in CFErrorMBS object.
Requires Mac OS X 10.9 or newer.
Please note that some tags may include chr(10) followed by a number to indicate which label color is used for compatibility to older OS X versions.

See also:

Some examples which use this method:

Feedback, Comments & Corrections

folderitem.SetTagNamesMBS(tags() as string, byref e as CFErrorMBS) as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS MacOSXCF Plugin 13.5 Yes No No Yes, macOS only No
Function: Sets file tags.
Example:
dim f as FolderItem = SpecialFolder.Desktop.Child("test.xojo_binary_project")

dim Tags() as string = Array("Hello", "World")
dim ce as CFErrorMBS
dim e as Integer = f.SetTagNamesMBS(tags, ce)

if ce <> nil then
MsgBox "SetTagNamesMBS: "+str(e)+EndOfLine+ce.Description
else
MsgBox "SetTagNamesMBS: "+str(e)
end if
Notes:
tags() is array with new tag names.
Provides error code as return value and details about error in CFErrorMBS object.
Requires Mac OS X 10.9 or newer.
Please note that some tags may include chr(10) followed by a number to indicate which label color is used for compatibility to older OS X versions.

See also:

Some examples which use this method:

Feedback, Comments & Corrections

Folderitem.ShortPathMBS as string
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS Win Plugin No Yes No No No
Function: Returns the short path for the file.
Example:
dim f as folderitem = specialfolder.desktop.child("test.file")
msgbox f.ShortPathMBS
Notes:
In contrast to long path this is the short 8.3 path for Windows.
You need this for the WindowsMCI object.
Works with Windows NT 4 or newer.

Some examples which use this method:

Feedback, Comments & Corrections

folderitem.TagNamesMBS as string()
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS MacOSXCF Plugin 13.5 Yes No No Yes, macOS only No
Function: Queries tag names for a file or folder.
Example:
dim f as FolderItem = SpecialFolder.Desktop.Child("test.xojo_binary_project")
dim Tags() as string = f.TagNamesMBS
MsgBox "Tags: "+Join(tags, EndOfLine)
Notes:
Requires Mac OS X 10.9 or newer.
Optionally provides error information in CFErrorMBS object.
Please note that some tags may include chr(10) followed by a number to indicate which label color is used for compatibility to older OS X versions.

See also:

Some examples which use this method:

Feedback, Comments & Corrections

folderitem.TagNamesMBS(byref e as CFErrorMBS) as string()
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS MacOSXCF Plugin 13.5 Yes No No Yes, macOS only No
Function: Queries tag names for a file or folder.
Example:
dim f as FolderItem = SpecialFolder.Desktop.Child("test.xojo_binary_project")

dim ce as CFErrorMBS
dim Tags() as string = f.TagNamesMBS(ce)

if ce <> nil then
MsgBox "Failed: "+ce.Description
else
MsgBox "Tags: "+Join(tags, EndOfLine)
end if
Notes:
Requires Mac OS X 10.9 or newer.
Optionally provides error information in CFErrorMBS object.
Please note that some tags may include chr(10) followed by a number to indicate which label color is used for compatibility to older OS X versions.

See also:

Some examples which use this method:

Feedback, Comments & Corrections

FolderItem.TrueFilesMBS as Folderitem()
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS Util Plugin 12.0 Yes Yes Yes Yes No
Function: Returns array of files in the given folder.
Example:
dim folder as FolderItem = SpecialFolder.Desktop
dim files() as FolderItem = folder.TrueFilesMBS
MsgBox str(UBound(files)+1)+" files"
Notes: Similar to trueitem() function, but returns all files with one call.

Feedback, Comments & Corrections

FolderItem.TrueFoldersMBS as Folderitem()
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS Util Plugin 12.0 Yes Yes Yes Yes No
Function: Returns array of folders in the given folder.
Example:
dim folder as FolderItem = SpecialFolder.Desktop
dim folders() as FolderItem = folder.TrueFoldersMBS
MsgBox str(UBound(folders)+1)+" folders"
Notes: Similar to trueitem() function, but returns all folders with one call.

Some examples which use this method:

Feedback, Comments & Corrections

FolderItem.TrueItemsMBS as Folderitem()
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS Util Plugin 12.0 Yes Yes Yes Yes No
Function: Returns array of items in the given folder.
Example:
dim folder as FolderItem = SpecialFolder.Desktop
dim Items() as FolderItem = folder.TrueItemsMBS
MsgBox str(UBound(Items)+1)+" items"
Notes: Similar to trueitem() function, but returns all items with one call.

Feedback, Comments & Corrections

Folderitem.UnixpathMBS as string
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS MacOSX Plugin Yes Yes No Yes No
Function: Returns the native path for the file.
Example:
dim sh as Shell
dim fi as FolderItem
dim s as String
dim t as TextConverter

sh = new Shell
fi = getfolderitem("test √") // or try some other file name

if fi = nil or fi.exists = false then
beep
return
end if

s="ls -al """ + fi.Unixpathmbs + """"

sh.Execute s
MsgBox sh.Result
Notes:
test on the Desktop could be this:
On Mac OS X: /Users/cs/Desktop/test
On Mac OS 9: Mac OS 9:Desktop folder:test
On Windows: c:\windows\desktop\test

This function will return an empty string if the path can not be encoded in a Realbasic String. For my tests ICQ's path which is includes the folder name "ICQ 3.0 ƒ" can not be converted to MacRoman for some reason.

On Mac OS X this function returns the posix path. So if you are looking for POSIXPathMBS or PosixPath this method is it.
This function should do the same as NativePath in Real Studio 2013r1.

Some examples which use this method:

Feedback, Comments & Corrections

folderitem.UnMountVolumeMBS(force as boolean = false) as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS Mac Plugin 10.3 Yes No No Yes, macOS only No
Function: This routine unmounts the volume specified by the folderitem.
Example:
dim disk as FolderItem

dim c as Integer = VolumeCount-1
for i as Integer = 0 to c
dim v as FolderItem = volume(i)
if v.Name = "monikajuchmes" then
disk = v
exit
end if
next

if disk = nil then
MsgBox "Please change the name in this code."
else
dim e as Integer = disk.UnMountVolumeMBS

if e=0 then
msgBox "Volume unmounted."
else
msgBox "There was an error!"
end if
end if
Notes:
If the volume cannot be unmounted the pid of the process which denied the unmount will be returned in the dissenterPID parameter.
This routine returns after the unmount is complete.

force: Specify true if you want the volume forcibly unmounted. Force unmounting a volume will very likely result in data loss since the volume will be ejected even if there are open files on it. This option should be reserved for situations such as the backing store for a volume is gone (so the data is lost regardless).
dissenterPID: Optionally, pid of the process which denied the unmount if the unmount is denied.

Returns a Mac OS error code. 0 means no error and -1 is a plugin error if the function can't be called. -47 is returned if the disc is in use.

See also:

Some examples which use this method:

Feedback, Comments & Corrections

folderitem.UnMountVolumeMBS(force as boolean, byref dissenterPID as Integer) as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS Mac Plugin 10.3 Yes No No Yes, macOS only No
Function: This routine unmounts the volume specified by the folderitem.
Example:
dim disk as FolderItem

dim c as Integer = VolumeCount-1
for i as Integer = 0 to c
dim v as FolderItem = volume(i)
if v.Name = "testvolume" then
disk = v
exit
end if
next

if disk = nil then
MsgBox "Please change the name in this code."
else
dim pid as Integer
dim e as Integer = disk.UnMountVolumeMBS(false, pid)

if e=0 then
msgBox "Volume unmounted."
else

if pid=0 then
msgBox "Failed to unmount with error: "+str(e)
else
dim name as string
dim p as new ProcessMBS // from Util plugin
p.GetFirstProcess

do
if p.ProcessID = pid then
name = p.Name
end if
loop until not p.GetNextProcess

if len(name)>0 then
msgBox "Failed to unmount with error: "+str(e)
else
MsgBox "Failed to unmount."+EndOfLine+EndOfLine+"The application "+name+" is still using this volume."+EndOfLine+"Error: "+str(e)
end if

end if
end if
end if
Notes:
If the volume cannot be unmounted the pid of the process which denied the unmount will be returned in the dissenterPID parameter.
This routine returns after the unmount is complete.

force: Specify true if you want the volume forcibly unmounted. Force unmounting a volume will very likely result in data loss since the volume will be ejected even if there are open files on it. This option should be reserved for situations such as the backing store for a volume is gone (so the data is lost regardless).
dissenterPID: Optionally, pid of the process which denied the unmount if the unmount is denied.

Returns a Mac OS error code. 0 means no error and -1 is a plugin error if the function can't be called. -47 is returned if the disc is in use.

PS: Seems like on my tests the pid is not set by Apple.

See also:

Some examples which use this method:

Feedback, Comments & Corrections

Folderitem.VolGetFolderItemIDMBS(createFileIDs as Boolean = true) as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method Files MBS Mac Plugin Yes No No Yes, macOS only No
Function: Returns the unique FileID or DirID of a FolderItem.
Notes:
Returns the unique FileID or DirID of a FolderItem. This ID is unique over all items on the same volume. The value 2 always identifies the root directory, all negative values and positive ones above 15 are used for user-created files and folders, while the values 3-15 are used internally by the File System (for the Desktop Database, for example).
If the item does not exists, 0 (zero) is returned instead.

IDs for Folders can always be resolved back to a FolderItem using VolResolveID, while resolving FileIDs only works when they've previously been created explicitly. To create a resolvable FileID, pass true to the createFileIDs parameter. But be aware that if the FileID can not be created (because the disk is locked or because the File System Format does not support it), the call will fail and a zero will be returned!

So, if you are just interested in reading the FileID, pass false to the second parameter. This will not fail even there hasn't been created a resolvable ID for that file yet.

Feedback, Comments & Corrections

VolResolveIDMBS(volume as FolderItem, id as Integer) as FolderItem
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
global method Files MBS Mac Plugin Yes No No Yes, macOS only No
Function:
return a FolderItem for a passed FileID or DirID. If the item can not be resolved, nil is returned instead.
The first parameter specified the volume where you want to resolve the ID on.
Example:
dim f,g as folderItem
f=SpecialFolder.Desktop
g=VolResolveIDMBS(f,f.MacDirID)
msgBox f.absolutePath
Notes: This function returns a FolderItem for a passed FileID or DirID. If the item can not be resolved, nil is returned instead.

See also:

Feedback, Comments & Corrections

VolResolveIDMBS(vRefNum as Integer, id as Integer) as FolderItem
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
global method Files MBS Mac Plugin Yes No No Yes, macOS only No
Function:
return a FolderItem for a passed FileID or DirID. If the item can not be resolved, nil is returned instead.
The first parameter specified the volume where you want to resolve the ID on.
Example:
dim f,g as folderItem
f=SpecialFolder.Desktop
g=VolResolveIDMBS(f.macVRefNum,f.MacDirID)
msgBox f.absolutePath
Notes:
This function returns a FolderItem for a passed FileID or DirID. If the item can not be resolved, nil is returned instead.
The first parameter specified the volume where you want to resolve the ID on.There is a bug in RB which may say "type mistmatch error" in RB. Than use the other variant of that function.

See also:

Feedback, Comments & Corrections

Previous items Next items

The items on this page are in the following plugins: MBS Mac Plugin, MBS MacOSX Plugin, MBS MacOSXCF Plugin, MBS Util Plugin, MBS Win Plugin.




Links
MBS FileMaker tutorial videos