BRL.Volumes · BlitzMax

Volumes is a small cross-platform module which provides useful volume/device information support for BlitzMax.

The module is essentially split into two parts, that of volume information, and some functions which give user-specific directory paths.

Volume Information

Enables access to all volumes on the system, as well as drive-details such as free and total space for the volume.

To get a list of volumes on the current system, simply call ListVolumes which returns a list of TVolume objects, from which you have access to the extra information.
You can also retrieve size information directly using GetVolumeSize and GetVolumeFreeSpace.

User Directories

Useful for the application developer is access to user-specific directories, like their home and document directories. The Volumes module provides access to four of these for all supported platforms: GetUserAppDir, GetUserDesktopDir, GetUserDocumentsDir, and GetUserHomeDir.

Custom Directories

There are also more platform-specific directories available via the GetCustomDir method.

Generic paths include, DT_SHAREDUSERDATA, DT_USERPICTURES, DT_USERMUSIC and DT_USERMOVIES, which are standard values for all platforms.

On Windows, you can also use any of the CSIDL_xxxxxx identifiers to retrieve the specific path string.

On Mac, you can choose from a selection of "k" folder types, as well as an optional domain. The default domain is kUserDomain. Others domains include kSystemDomain, kLocalDomain and kNetworkDomain.

Types

Type	Description
TVolume	A system Volume

Functions

`Function ListVolumes:TList()`

Returns a list of volumes on the system.

Example 1

SuperStrict

Framework BRL.volumes
Import brl.standardio

Local list:TList = ListVolumes()

If list Then
    Print "Volumes :"

    For Local v:TVolume = EachIn list
    
        'If v.available Then
            Print "~t" + v.volumeName + "  -  " + v.volumeDevice + " (" +  v.volumeType +  ") -  " + ((v.volumeFree / 1024) / 1024) + "mb"
        'End If
    
    Next
End If

Example 2

SuperStrict

Framework BRL.volumes
Import brl.standardio

Local list:TList = ListVolumes()

If list Then
    Print "Volumes :"

    For Local v:TVolume = EachIn list
    
        'If v.available Then
            Print "~t" + v.volumeName + "  -  " + v.volumeDevice + " (" +  v.volumeType +  ") -  " + ((v.volumeFree / 1024) / 1024) + "mb"
        'End If
    
    Next
End If

Example 3

SuperStrict

Framework BRL.volumes
Import brl.standardio

Local list:TList = ListVolumes()

If list Then
    Print "Volumes :"

    For Local v:TVolume = EachIn list
    
        'If v.available Then
            Print "~t" + v.volumeName + "  -  " + v.volumeDevice + " (" +  v.volumeType +  ") -  " + ((v.volumeFree / 1024) / 1024) + "mb"
        'End If
    
    Next
End If

`Function GetVolumeFreeSpace:Long(vol:String)`

Returns the amount of free space (in bytes) on the given volume.

Parameters:

vol : the name of the volume

Example 1

SuperStrict

Framework BRL.Volumes
Import brl.standardio

Local vol:String

?win32
vol = "C:\"
?linux
vol = "/"
?macos
vol = "/"
?

Print "Freespace :"
Print vol + " = " + (GetVolumeFreeSpace(vol) / 1024) + " kb"

Example 2

SuperStrict

Framework BRL.Volumes
Import brl.standardio

Local vol:String

?win32
vol = "C:\"
?linux
vol = "/"
?macos
vol = "/"
?

Print "Freespace :"
Print vol + " = " + (GetVolumeFreeSpace(vol) / 1024) + " kb"

Example 3

SuperStrict

Framework BRL.Volumes
Import brl.standardio

Local vol:String

?win32
vol = "C:\"
?linux
vol = "/"
?macos
vol = "/"
?

Print "Freespace :"
Print vol + " = " + (GetVolumeFreeSpace(vol) / 1024) + " kb"

`Function GetVolumeSize:Long(vol:String)`

Returns the size (in bytes) of the given volume.

Parameters:

vol : the name of the volume

Example 1

SuperStrict

Framework BRL.volumes
Import brl.standardio

Local vol:String

?win32
vol = "C:\"
?linux
vol = "/"
?macos
vol = "/"
?

Print "Total space :"
Print vol + " = " + (GetVolumeSize(vol) / 1024) + " kb"

Example 2

SuperStrict

Framework BRL.volumes
Import brl.standardio

Local vol:String

?win32
vol = "C:\"
?linux
vol = "/"
?macos
vol = "/"
?

Print "Total space :"
Print vol + " = " + (GetVolumeSize(vol) / 1024) + " kb"

Example 3

SuperStrict

Framework BRL.volumes
Import brl.standardio

Local vol:String

?win32
vol = "C:\"
?linux
vol = "/"
?macos
vol = "/"
?

Print "Total space :"
Print vol + " = " + (GetVolumeSize(vol) / 1024) + " kb"

`Function GetVolumeInfo:TVolume(vol:String)`

Populates and returns a TVolume object.

Parameters:

vol : the name of the volume

`Function GetUserHomeDir:String()`

Returns the user home directory.

The table lists examples for the various platforms -

Platform	Example	Equivalent
Linux	`/home/username`	``
Mac OS	`/Users/username`	``
Win32	`C:\Documents and Settings\username`

Example 1

SuperStrict

Framework BRL.Volumes
Import BRL.Standardio

Print GetUserHomeDir()

Example 2

SuperStrict

Framework BRL.Volumes
Import BRL.Standardio

Print GetUserHomeDir()

Example 3

SuperStrict

Framework BRL.Volumes
Import BRL.Standardio

Print GetUserHomeDir()

`Function GetUserDesktopDir:String()`

Returns the user Desktop directory.

The table lists examples for the various platforms -

Platform	Example	Equivalent
Linux	`/home/username/Desktop`	`/Desktop`
Mac OS	`/Users/username/Desktop`	`/Desktop`
Win32	`C:\Documents and Settings\username\Desktop`

Example 1

SuperStrict

Framework BRL.Volumes
Import BRL.Standardio

Print GetUserDesktopDir()

Example 2

SuperStrict

Framework BRL.Volumes
Import BRL.Standardio

Print GetUserDesktopDir()

Example 3

SuperStrict

Framework BRL.Volumes
Import BRL.Standardio

Print GetUserDesktopDir()

`Function GetUserAppDir:String()`

Returns the user directory for application data.

The table lists examples for the various platforms -

Platform	Example	Equivalent
Linux	`/home/username`	``
Mac OS	`/Users/username/Library/Application Support`	`/Library/Application Support`
Win32	`C:\Documents and Settings\username\Application Data`

Example 1

SuperStrict

Framework BRL.Volumes
Import BRL.Standardio

Print GetUserAppDir()

Example 2

SuperStrict

Framework BRL.Volumes
Import BRL.Standardio

Print GetUserAppDir()

Example 3

SuperStrict

Framework BRL.Volumes
Import BRL.Standardio

Print GetUserAppDir()

`Function GetUserDocumentsDir:String()`

Returns the user Documents directory.

The table lists examples for the various platforms -

Platform	Example	Equivalent
Linux	`/home/username/Documents`	`/Documents`
Mac OS	`/Users/username/Documents`	`/Documents`
Win32	`C:\Documents and Settings\username\My Documents`

Example 1

SuperStrict

Framework BRL.Volumes
Import BRL.Standardio

Print GetUserDocumentsDir()

Example 2

SuperStrict

Framework BRL.Volumes
Import BRL.Standardio

Print GetUserDocumentsDir()

Example 3

SuperStrict

Framework BRL.Volumes
Import BRL.Standardio

Print GetUserDocumentsDir()

`Function GetCustomDir:String(dirType:Int, flags:Int = 0)`

Returns the custom directory path.

The following table lists valid dirType -

Platform	dirType	Description
Mac, Linux	DT_SHAREDUSERDATA	The Shared documents folder.
All	DT_USERPICTURES	The "Pictures" or "My Pictures" folder of the user.
All	DT_USERMUSIC	The "Music" or "My Music" folder of the user.
All	DT_USERMOVIES	The "Movies", "Videos" or "My Videos" folder of the user.
Win32	CSIDL_xxxxxxxx	Any of the Windows-specific CSIDL identifiers that represent different folders on the system.

Returns Null if dirType is not valid for the platform.

Consts

`Const kSystemDomain:Int = -32766`

Read-only system hierarchy.

`Const kLocalDomain:Int = -32765`

All users of a single machine have access to these resources.

`Const kNetworkDomain:Int = -32764`

All users configured to use a common network server has access to these resources.

`Const kUserDomain:Int = -32763`

Resources that are private to the user.

Read/write.