SFXDirectory

Class for operating a directory.

#include <SFXDirectory.h.hpp>

class SFXDirectory;

SFMTYPEDEFCLASS(SFXDirectory)

Description

The SFXDirectory class is used to perform the directory operations such as creating a directory, moving a directory, deleting a directory, retrieving directory attribute information, traversing files and subdirectories in a directory, making a temporary directory etc.

Reference

SFXFile | SFXPath | Directory

Member

Public Functions
static `SFCError`	Create( `SFXPathConstRef` path , `Bool` force = false ) Create the specified directory.
static `SFCError`	DeviceFreeSpace( `UInt32Ptr` result ) Get the number of free bytes currently available on file system.
static `SFCError`	DeviceTotalSpace( `UInt32Ptr` result ) Get the total room in the file system.
static `SFCError`	Exists( `SFXPathConstRef` path , `BoolPtr` result ) Check whether or not the specified directory exists.
static `SFCError`	GetCreateDate( `SFXPathConstRef` path , `SFXDatePtr` result ) Get the creation date of the specified directory.
static `SFCError`	GetDirectoryEnumerator( `SFXPathConstRef` path , `EnumeratorPtr` result ) Get the directory enumerator within the specified directory
static `SFCError`	GetFileEnumerator( `SFXPathConstRef` path , `EnumeratorPtr` result ) Get the file enumerator within the specified directory
static `SFCError`	GetTemporaryPath( `SFXPathConstRef` path , `SFXPathPtr` result ) Get the temporary directory path.
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 or not the specified directory is read only.
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 the specified directory.

Types
Enumerator Class that represents an enumerator.

SFXDirectory::Create

Create the specified directory.

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

Return value

If succeeds: SFERR_NO_ERROR
If the path argument is not a directory: SFERR_INVALID_PARAM
Otherwise: error that BREW API IFILEMGR_GetLastError function returns or SFERR_FAILED

Description

This function creates the directory specified in the path argument.

If the force argument is set to true, the directories which do not exist in the specified path will be created automatically.

	Note
	This function calls the `SFBFileMgr::MkDir` function internally.

Example

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

Reference

SFBFileMgr::MkDir | SFXDirectory::Remove | BREW API IFILEMGR_MkDir | BREW API IFILEMGR_GetLastError

SFXDirectory::DeviceFreeSpace

Get the number of free bytes currently available on file system.

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

Return value

If succeeds: SFERR_NO_ERROR
If the result argument is null: SFERR_INVALID_PARAM
Otherwise: error that the IFILEMGR_GetLastError function of BREW API returns or SFERR_FAILED

Description

This function gets the number of free bytes currently available on file system

	Note
	This function internally calls the `SFBFileMgr::GetFreeSpace` function.

	Caution
	In case of the Simulator, if the space available is larger than the maximum 32-bit integer value, the maximum value of a 32-bit integer is returned(0xFFFFFFFF).

Example

UInt32 space;

// get the number of free bytes currently available on file system
SFXDirectory::DeviceFreeSpace(&space);

Reference

SFBFileMgr::GetFreeSpace | SFXDirectory::DeviceTotalSpace | BREW API IFILE_IFILEMGR_GetFreeSpace | BREW API IFILEMGR_GetLastError

SFXDirectory::DeviceTotalSpace

Get the total room in the file system.

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

Return value

If succeeds: SFERR_NO_ERROR
If the result argument is null: SFERR_INVALID_PARAM
Otherwise: error that the IFILEMGR_GetLastError function of BREW API returns or SFERR_FAILED

Description

This function gets the total room in the file system.

	Note
	This function internally calls the `SFBFileMgr::GetFreeSpace` function.

	Caution
	In case of the Simulator, if the total room is larger than the maximum 32-bit integer value, the maximum value of a 32-bit integer is returned(0xFFFFFFFF).

Example

UInt32 space;

// get the total room in the file system
SFXDirectory::DeviceTotalSpace(&space);

Reference

SFBFileMgr::GetFreeSpace | SFXDirectory::DeviceFreeSpace | BREW API IFILE_IFILEMGR_GetFreeSpace | BREW API IFILEMGR_GetLastError

SFXDirectory::Exists

Check whether or not the specified directory exists.

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

Return value

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

Description

The function checks whether or not the directory specified in the path argument exists. The result will be returned to the result argument.

	Note
	This function internally calls the `SFBFileMgr::Test` function.

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

SFBFileMgr::Test | SFXDirectory::IsReadOnly | SFXDirectory::IsSystem | BREW API IFILEMGR_Test

SFXDirectory::GetCreateDate

Get the creation date of the specified directory.

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

Return value

If succeeds: SFERR_NO_ERROR
If the result argument is null or the path argument is not a directory: SFERR_INVALID_PARAM
Otherwise: error that the BREW API IFILEMGR_GetLastError function returns or SFERR_FAILED

Description

The function gets creation date of the directory specified in the path argument, which will be returned to the result argument.

	Note
	This function internally calls the `SFBFileMgr::GetInfo` function.

Example

SFXDate date; // date

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

Reference

SFBFileMgr::GetInfo | BREW API IFILE_IFILEMGR_GetInfo | BREW API IFILEMGR_GetLastError

SFXDirectory::GetDirectoryEnumerator

Get the directory enumerator within the specified directory

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

Return value

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

Description

This function gets the directory enumerator within the directory specified in the path argument. The directory enumerator will be returned to the result argument.

	Note
	This function internally calls the `SFBFileMgr::EnumInit` function.

Example

Get each directory within the directory.

SFXPath path;
SFXDirectory::Enumerator etor;  

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

// enumerate each directory
while (etor.HasNext()) {
    // get the 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 | BREW API IFILEMGR_EnumInit

SFXDirectory::GetFileEnumerator

Get the file enumerator within the specified directory

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

Return value

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

Description

This function gets the file enumerator within the directory specified in the path argument. The file enumerator will be returned to the result argument.

	Note
	This function internally calls the `SFBFileMgr::EnumInit` function.

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 | BREW API IFILEMGR_EnumInit

SFXDirectory::GetTemporaryPath

Get the temporary directory path.

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

Return value

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

Description

This function gets the temporary directory path that does not duplicate existing ones.

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

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

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

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

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

Description

This function gets the unique directory path that does not duplicate existing ones.

	Note
Since the directory name is generated using a random number, this function might fail in case many directorys have already existed. 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 and return SFERR_FAILED.

Note

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

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 and return SFERR_FAILED.

	Tip
	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

SFXDirectory::IsReadOnly

Check whether or not the specified directory is read only.

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

Return value

If succeeds: SFERR_NO_ERROR
If the result argument is null or the path argument is not a directory: SFERR_INVALID_PARAM
Otherwise: error that the BREW API IFILEMGR_GetLastError function returns or SFERR_FAILED

Description

The functionc checks whether or not the directory specified in the path argument is read only. The result will be returned to the result argument.

	Note
	This function internally calls the `SFBFileMgr::GetInfo` function.

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

SFBFileMgr::GetInfo | SFXDirectory::Exists | SFXDirectory::IsSystem | BREW API IFILEMGR_GetInfo | BREW API IFILEMGR_GetLastError

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

If succeeds: SFERR_NO_ERROR
If the result argument is null or the path argument is not a directory: SFERR_INVALID_PARAM
Otherwise: error that the BREW API IFILEMGR_GetLastError function returns or SFERR_FAILED

Description

The functionc checks whether or not the directory specified in the path argument is a system directory. The result will be returned to the result argument.

	Note
	This function internally calls the `SFBFileMgr::GetInfo` function.

Reference

SFBFileMgr::GetInfo | SFXFile::Exists | SFXFile::IsReadOnly | BREW API IFILEMGR_GetInfo | BREW API IFILEMGR_GetLastError

SFXDirectory::Remove

Remove the specified directory.

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

Return value

If succeeds: SFERR_NO_ERROR
If the path argument is not a directory: SFERR_INVALID_PARAM
Otherwise: error that the BREW API IFILEMGR_GetLastError function returns or SFERR_FAILED

Description

This function deletes the directory specified in the path argument.

	Note
	This function calls the `SFBFileMgr::RmDir` / `SFBFileMgr::Remove` function internally.

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::Enumerator

Class that represents an enumerator.

[ public ]

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

Description

This class represents an enumerator.

The member functions of the SFXDirectory::Enumerator class are as follows:

GetNext	Get the next element. If the next element does not exist, null will be returned.
HasNext	Check whether or not the next element exists.
IsValid	Check whether or not the enumerator is valid.

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()); 
}

Reference

SFXDirectory::GetDirectoryEnumerator | SFXDirectory::GetFileEnumerator | BREW API IFILEMGR_EnumInit