SFXDirectory

Class for operating a directory.

#include <SFXDirectory.h.hpp>

class SFXDirectory;

SFMTYPEDEFCLASS(SFXDirectory)

Description

SFXDirectory is a class that creates a directory, accesses information such as its attribute, gets a file within the directory or an enumerator of directory, or makes a temporary directory.

Reference

SFXFile | SFXPath | Directory

Member

Public Functions
static `SFCError`	Create( `SFXPathConstRef` path , `Bool` force = false ) Create a directory.
static `SFCError`	DeviceFreeSpace( `UInt32Ptr` result ) Get free space of the device
static `SFCError`	DeviceTotalSpace( `UInt32Ptr` result ) Get total space of the device
static `SFCError`	Exists( `SFXPathConstRef` path , `BoolPtr` result ) Check whether the directory exists
static `SFCError`	GetCreateDate( `SFXPathConstRef` path , `SFXDatePtr` result ) Get the date and time that the directory was created
static `SFCError`	GetDirectoryEnumerator( `SFXPathConstRef` path , `EnumeratorPtr` result ) Get a directory enumerator within the directory
static `SFCError`	GetFileEnumerator( `SFXPathConstRef` path , `EnumeratorPtr` result ) Get a file enumerator within the directory
static `SFCError`	GetTemporaryPath( `SFXPathConstRef` path , `SFXPathPtr` result ) Get the unique temporary directory path name that does not duplicate the existing ones
static `SFCError`	GetUniquePath( `SFXPathConstRef` path , `SFXAnsiStringConstRef` prefix , `SFXAnsiStringConstRef` suffix , `SFXPathPtr` result ) Get the unique directory path name that does not duplicate the existing ones
static `SFCError`	IsReadOnly( `SFXPathConstRef` path , `BoolPtr` result ) Check whether the directory is read only or not.
static `SFCError`	IsSystem( `SFXPathConstRef` path , `BoolPtr` result ) Check whether the directory is system directory or not.
static `SFCError`	Remove( `SFXPathConstRef` path , `Bool` force = false ) Remove a directory.

Types
Enumerator Class for managing a list of enumerators.

SFXDirectory::Create

Create a directory.

[ public, static ]
SFCError Create(
    SFXPathConstRef path   // directory path to create
    Bool force = false     // whether to create forcedly
);

Return value

Success : SFERR_NO_ERROR
If the specified path is not a directory : SFERR_INVALID_PARAM
If a directory already exists or failed : SFERR_FAILED

Description

When setting the force variable to "true", the directories that don't exist in the specified path will be created automatically.

Example

// create directory forcedly
// if dir1 does not exist, dir1 will be created automatically
SFXDirectory::Create(SFXPath("/dir1/dir2/"), true);

Reference

SFXDirectory::Remove

SFXDirectory::DeviceFreeSpace

Get free space of the device

[ public, static ]
SFCError DeviceFreeSpace(
    UInt32Ptr result   // pointer to get free space
);

Return value

Success : SFERR_NO_ERROR
If argument is null : SFERR_INVALID_PARAM
If failed : SFERR_FAILED

Example

UInt32 space;

// get free space of device
SFXDirectory::DeviceFreeSpace(&space);

Reference

SFXDirectory::DeviceTotalSpace

SFXDirectory::DeviceTotalSpace

Get total space of the device

[ public, static ]
SFCError DeviceTotalSpace(
    UInt32Ptr result   // pointer to get total space
);

Return value

Success : SFERR_NO_ERROR
If argument is null : SFERR_INVALID_PARAM
If failed : SFERR_FAILED

Example

UInt32 space;

// get total space of device
SFXDirectory::DeviceTotalSpace(&space);

Reference

SFXDirectory::DeviceFreeSpace

SFXDirectory::Exists

Check whether the directory exists

[ public, static ]
SFCError Exists(
    SFXPathConstRef path   // path to check its existence
    BoolPtr result         // pointer to receive the result
);

Return value

Success : SFERR_NO_ERROR
If argument is null or the path is not a directory : SFERR_INVALID_PARAM
If failed : SFERR_FAILED

Example

Bool b;

// return value of Exists function is of SFCError type
// b : set by Exists function whether specifiled directory exists or not

SFXDirectory::Exists(SFXPath("/dir1/"), &b);

if (b) {
    // when directory exists

}

Reference

SFXDirectory::IsReadOnly | SFXDirectory::IsSystem

SFXDirectory::GetCreateDate

Get the date and time that the directory was created

[ public, static ]
SFCError GetCreateDate(
    SFXPathConstRef path   // directory path
    SFXDatePtr result      // pointer to get the date and time created
);

Return value

Success : SFERR_NO_ERROR
If argument is null or the path is not a directory : SFERR_INVALID_PARAM
If failed : SFERR_FAILED

Example

SFXDate date; // date class

// get date and time when directory was created
SFXDirectory::GetCreateDate(SFXPath("/dir1/"), &date);

SFXDirectory::GetDirectoryEnumerator

Get a directory enumerator within the directory

[ public, static ]
SFCError GetDirectoryEnumerator(
    SFXPathConstRef path   // directory path
    EnumeratorPtr result   // pointer to the directory enumerator
);

Return value

Success : SFERR_NO_ERROR
If argument is null or the path is not a directory : SFERR_INVALID_PARAM
If failed : SFERR_FAILED

Example

Get each directory within the directory.

SFXPath path;
SFXDirectory::Enumerator etor;  

// get directory enumerator
SFXDirectory::GetDirectoryEnumerator(SFXPath("/dir1/"), &etor);

// enumerate each directory
while (etor.HasNext()) {
    // get directory path within the "/dir1" directory in order
    path = etor.GetNext();
    // display path name on BREW Output Window                      
    TRACE("dir = %s", path.Get().GetCString()); 
}

Reference

SFXDirectory::GetFileEnumerator | SFXDirectory::Enumerator

SFXDirectory::GetFileEnumerator

Get a file enumerator within the directory

[ public, static ]
SFCError GetFileEnumerator(
    SFXPathConstRef path   // directory path
    EnumeratorPtr result   // pointer the file enumerator
);

Return value

Success : SFERR_NO_ERROR
If argument is null or the path is not a directory : SFERR_INVALID_PARAM
If failed : SFERR_FAILED

Example

Get each file within the directory.

SFXPath path;
SFXDirectory::Enumerator etor;  

// get file enumerator
SFXDirectory::GetFileEnumerator(SFXPath("/dir1/"), &etor);

// enumerate each file
while (etor.HasNext()) {
    // get file path within the "/dir1" directory in order
    path = etor.GetNext();                       
    // display path name on BREW Output Window                      
    TRACE("file = %s", path.Get().GetCString()); 
}

Reference

SFXDirectory::GetDirectoryEnumerator | SFXDirectory::Enumerator

SFXDirectory::GetTemporaryPath

Get the unique temporary directory path name that does not duplicate the existing ones

[ public, static ]
SFCError GetTemporaryPath(
    SFXPathConstRef path   // directory path to create a temporary directory
    SFXPathPtr result      // pointer to the temporary directory path
);

Return value

Success : SFERR_NO_ERROR
If argument is null or the path is not a directory : SFERR_INVALID_PARAM
If failed : SFERR_FAILED

Description

The SFXDirectory::GetTemporaryPath function returns the temporary directory path that does not duplicate existing ones.

	Note
	To get the permanent directory which is not temporary one, use the `SFXDirectory::GetUniquePath` function.

	Note
	The SFXDirectory::GetTemporaryPath function internally calls the `SFXDirectory::GetUniquePath` function by specifying "sfx" as the prefix argument and "dir" as the suffix argument respectively.

Example

SFXPath path;

path.Set(SFXAnsiString("/"));
if (SFXDirectory::GetTemporaryPath(path, &path) == SFERR_NO_ERROR) {
    // directory path like "/8A2949E2/" will be created
    TRACE("%s", path.Get().GetCString());
}

Reference

SFXDirectory::GetUniquePath | SFXFile::GetTemporaryPath | SFXFile::GetUniquePath

SFXDirectory::GetUniquePath

Get the unique directory path name that does not duplicate the existing ones

[ public, static ]
SFCError GetUniquePath(
    SFXPathConstRef path           // path of parent directory to create the directory
    SFXAnsiStringConstRef prefix   // prefix of directory name
    SFXAnsiStringConstRef suffix   // suffix of directory name
    SFXPathPtr result              // pointer to the directory path
);

Return value

Success : SFERR_NO_ERROR
If argument is null or the path is not a directory : SFERR_INVALID_PARAM
If failed : SFERR_FAILED

Description

Since the directory name is generated using a random number, this function might fail in case many directories have already existed.

	Note
	If the directory name generated using a random number has already existed, repeat to retry this operation up to 64 times. Nevertheless, in case the directory path that does not duplicate existing ones can not be generated, this function will fail.

	Note
	To get the temporary directory path which will be deleted soon, use the `SFXDirectory::GetTemporaryPath` function.

Example

SFXPath dir("/");
SFXPath path;

if (SFXFile::GetUniquePath(dir, "sfx", "dat", &path) == SFERR_NO_ERROR) {
    // directory path like "/sfx7182CBD4dat/" will be created
    TRACE("%s", path.Get().GetCString());
}

Reference

SFXDirectory::GetTemporaryPath | SFXFile::GetUniquePath | SFXFile::GetTemporaryPath

SFXDirectory::IsReadOnly

Check whether the directory is read only or not.

[ public, static ]
SFCError IsReadOnly(
    SFXPathConstRef path   // directory path
    BoolPtr result         // pointer to receive the result
);

Return value

Success : SFERR_NO_ERROR
If argument is null or the path is not a directory : SFERR_INVALID_PARAM
If failed : SFERR_FAILED

Example

Bool b;

// return value of isReadOnly function is of SFCError type
// b : set by isReadOnly function whether specifiled directory is read only or not
SFXDirectory::IsReadOnly(SFXPath("/dir1/data.txt"), &b);

if (b) {
    // when directory is read only
    ...
}

Reference

SFXDirectory::Exists | SFXDirectory::IsSystem

SFXDirectory::IsSystem

Check whether the directory is system directory or not.

[ public, static ]
SFCError IsSystem(
    SFXPathConstRef path   // directory path
    BoolPtr result         // pointer to receive the result
);

Return value

Success : SFERR_NO_ERROR
If argument is null or the path is not a directory : SFERR_INVALID_PARAM
If failed : SFERR_FAILED

Reference

SFXDirectory::Exists | SFXDirectory::IsReadOnly

SFXDirectory::Remove

Remove a directory.

[ public, static ]
SFCError Remove(
    SFXPathConstRef path   // directory path to remove
    Bool force = false     // whether or not to remove a directory recursively
);

Return value

Success : SFERR_NO_ERROR
If the path is not a directory : SFERR_INVALID_PARAM
If failed : SFERR_FAILED

Example

If there is no file nor directory in the "dir1" directory, remove the "dir1" directory.

if (SFXDirectory::Remove(SFXPath("/dir1/")) == SFERR_NO_ERROR) {
    ...
}

Remove the "dir1" directory recursively.

if (SFXDirectory::Remove(SFXPath("/dir1/"), false) == SFERR_NO_ERROR) {
    ....
}

Reference

SFXDirectory::Create

SFXDirectory::Enumerator

Class for managing a list of enumerators.

[ public ]

SFMTYPEDEFCLASS(Enumerator)
class Enumerator {
    public:
        explicit            Enumerator          (Void);
        SFXPath             GetNext             (Void);
        Bool                HasNext             (Void) const;
        Bool                IsValid             (Void) const;
};

Description

Enumerator is a class that manage a list of enumerators.

The member functions of Enumerator class are as follows.

GetNext	Get the next element. Return null if the next element does not exist.
HasNext	check whether the next element exists or not.
IsValid	Check whether the enumerator is valid or not.

Example

Get each file within the directory.

SFXPath path;
SFXDirectory::Enumerator etor;  

// get file enumerator
SFXDirectory::GetFileEnumerator(SFXPath("/dir1/"), &etor);

// enumerate each file
while (etor.HasNext()) {
    // get file path within "/dir1" directory in order
    path = etor.GetNext(); 
    // display path name on BREW Output Window                      
    TRACE("file = %s", path.Get().GetCString()); 
}