Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   Namespace Members   Compound Members  

PLMFileUtils Namespace Reference

This namespace defines some usefull functions to work on files, in an OS-independant way. More...


Enumerations

enum  FileListFlag {
  FL_NODIR = 1 << 1, FL_NOFILE = 1 << 2, FL_NOCASE = 1 << 3, FL_NOPARENT = 1 << 4,
  FL_NOHID = 1 << 5, FL_NOLINK = 1 << 6
}

Functions

PLMDLL bool FileExist (const char *name)
PLMDLL bool IsDir (const char *name)
PLMDLL bool IsHidden (const char *name)
PLMDLL u32 FileSize (const char *name)
PLMDLL bool FileRemove (const char *name)
PLMDLL bool FileRename (const char *oldname, const char *newname, bool force)
PLMDLL bool FileCopy (const char *src, const char *dst, bool force)
PLMDLL u32 CopyData (PLMResFile *src, PLMResFile *dst, u32 n)
PLMDLL u32 GetFileList (char **&list, const char *path, const char *pattern, u32 flags)
PLMDLL void FreeFileList (char **&list, u32 nb)
PLMDLL bool IsRoot (const char *path)
PLMDLL bool IsAbsolute (const char *path)
PLMDLL bool IsRelative (const char *path)
PLMDLL char * GetCWD ()
PLMDLL bool GetCWD (char *dir, u32 size)
PLMDLL bool SetCWD (const char *path)
PLMDLL char * GetExeDir ()
PLMDLL const char * GetUserDocDir ()
PLMDLL const char * GetUserAppDir ()
PLMDLL PLMTextGetCDROMDirs ()
PLMDLL u32 DrivesList ()
PLMDLL u32 DriveType (const char *drive)
PLMDLL bool DirCreate (const char *name)
PLMDLL const char * FileName (const char *path)
PLMDLL const char * FileExtension (const char *path)


Detailed Description

This namespace defines some usefull functions to work on files, in an OS-independant way.

Note: if the filenames do not contain an absolute path, these functions use the current working directory as a starting point.


Enumeration Type Documentation

enum PLMFileUtils::FileListFlag
 

Flags for GetFileList() function.

Enumeration values:
FL_NODIR  do not include subdirectories (only files)
FL_NOFILE  do not include files (only dirs)
FL_NOCASE  string comparison is not case dependent (aa = AA)
FL_NOPARENT  do not include '.' and '..' directories
FL_NOHID  do not include hidden files ('.xxx' under linux)
FL_NOLINK  do not include symbolic links (linux only)


Function Documentation

PLMDLL bool FileExist const char *    name
 

Check if a file exists (of any type, may be a directory, a link, ...).

PLMDLL bool IsDir const char *    name
 

Check if a file is a directory.

PLMDLL bool IsHidden const char *    name
 

Check if a file (or directory) is hidden.

PLMDLL u32 FileSize const char *    name
 

Get the size of the file (or directory) in bytes. Return PLM::INDEX_ERROR on error.

PLMDLL bool FileRemove const char *    name
 

Remove/erase/delete the file named name.

Does not work with directories. Return true on success.

PLMDLL bool FileRename const char *    oldname,
const char *    newname,
bool    force
 

Try to change the name of the file oldname into newname.

This function can also be used to move a file into another directory (newname should contain a different path). If a file named newname already exists, the function fails unless force is true.

Parameters:
oldname  the name of the file to rename (or move).
newname  the new name to give to the file, must contain the filename (even for a move), and if oldname contains a path, newname should contain the same for a rename (otherwise, it is moved to the current dir).
force  if true, any existing file named newname is deleted and replaced by oldname.
Returns:
true on success (oldname does not exist any more), false if oldname or newname are invalid or if newname already exists and force is false.

PLMDLL bool FileCopy const char *    src,
const char *    dst,
bool    force
 

Try to create a file named dst and copy the content of the existing file named src.

This function does not modify src. If a file named dst already exists, the function fails unless force is true ; the existing file is then replaced/overwritten.

Parameters:
src  the name of the file to read data from.
dst  the name of the file to create, must contain a valid path and filename.
force  if true and a file named dst already exists, it is truncated and replaced.
Returns:
true on success, false if src or dst are invalid or if dst already exists and force is false.

PLMDLL u32 CopyData PLMResFile   src,
PLMResFile   dst,
u32    n
 

Copy n bytes from file src into dst.

No check performed on state, size, or position.

Parameters:
src  an opened file, ready to be read
dst  an opened file, ready to be written
n  the number of bytes to read from src and write to dst.
Returns:
the number of bytes copied. If less than n, you may consider something wrong has happened (or that the end of file src has been reached).

PLMDLL u32 GetFileList char **&    list,
const char *    path,
const char *    pattern,
u32    flags
 

Return an allocated array of strings containing the names of the files from path, that match the specified pattern.

Parameters:
list  [out] a pointer that will receive the allocated list, or NULL if no file is found (return 0).
path  the directory to look for files
pattern  a pattern to describe the file names to select. It can contain one or more '?', '*', (and [] under linux). It must contain only one filename pattern (no |).
flags  additionnal conditions, see PLM::FileListFlag enum.
Returns:
the size of the list which is the number of files found. 0 means that the list is empty, so NULL is returned. Otherwise the list must be deleted when not used anymore, bu calling FreeFileList().

PLMDLL void FreeFileList char **&    list,
u32    nb
 

Free all strings and the array allocated by GetFileList().

nb is the value returned by GetFileList.

PLMDLL bool IsRoot const char *    path
 

Check if path is a root ("/" under linux, something like "D:\" under windows).

PLMDLL bool IsAbsolute const char *    path
 

Check if path is absolute (begins with "/" under linux, and something like "X:\" under windows, X=A..Z).

PLMDLL bool IsRelative const char *    path
 

Check if path is relative (= not absolute).

PLMDLL char* GetCWD  
 

Get the current working directory of the application (absolute).

Return NULL if the current directory can not be read. Note: returns a new allocated string (that must be delete after use).

PLMDLL bool GetCWD char *    dir,
u32    size
 

Get the current working directory of the application.

This version writes its output to an existing string dir and returns false on error (not enough space).

Parameters:
dir  a pre-allocated string of at least size bytes
size  the number of bytes that can be written into dir.
Returns:
true on success, false if dir is not long enough or the directory can not be read.

PLMDLL bool SetCWD const char *    path
 

Set the current working directory of the application.

Return false on error.

PLMDLL char* GetExeDir  
 

Return an allocated string containing the absolute pathname of the current executable.

  • the string must be deleted after use.
    • the string contains an absolute PATH name (from root), with no trailing path separator.
    • the string does not contain the executable FILE name. The function can return NULL on error (system or memory alloc error).

PLMDLL const char* GetUserDocDir  
 

Get the system directory where the current user stores his documents.

Linux: $HOME or ~ Windows: $Personal, usually called "My Documents" Note: the string is static and should not be modified or deleted.

Returns:
a static string on success, "" on error.

PLMDLL const char* GetUserAppDir  
 

Get the system directory where the current user stores the configuration files for the installed applications.

Linux: $HOME or ~, then the file usually begins by '.' like ".file" Windows: $AppData i.e. "$windows\Application Data" or "X:\Documents and Settings$user\Application Data". Note: the string is static and should not be modified or deleted.

Returns:
a static string on success, "" on error.

PLMDLL PLMText* GetCDROMDirs  
 

Get a list of available CDROM drives, as an array of paths (mount points under linux, drives under windows).

Returns:
an allocated PLMText object on success (that must be deleted after use), or NULL on error or if no CD has been found.

PLMDLL u32 DrivesList  
 

Returns a 32 bit mask of all present drives under windows (bit 0 = A:, bit 1 = B:, ...).

A drive exists if the corresponding bit is set (= 1).

Returns:
a 32 bit integer (bit mask) or 0 on error (or non-windows system).

PLMDLL u32 DriveType const char *    drive
 

Get the type of a drive under windows.

Parameters:
drive  a string containing the root path of the drive ("C:\"), can also be of the form "\netdrive". If NULL, the current drive is used.
Returns:
a 32 bit integer, one of the following values:
  • 0 on non-windows systems
  • DRIVE_UNKNOWN : error,
  • DRIVE_NO_ROOT_DIR : the root directory does not exist,
  • DRIVE_REMOVABLE : floppy, tape, zip,
  • DRIVE_FIXED : hard disk,
  • DRIVE_REMOTE : network,
  • DRIVE_CDROM : cdrom, dvdrom,
  • DRIVE_RAMDISK : in memory.

PLMDLL bool DirCreate const char *    name
 

Create a new directory (all previous directories in the path must exist).

If the name is not absolute, the current working directory (see GetCWD()) is taken as a starting point.

PLMDLL const char* FileName const char *    path
 

Get a pointer on the file part of a pathname (after the last '/').

Example: points to "cc" in "/aa/bb/cc".

Returns:
a pointer on the string or path if no leading directory is found.

PLMDLL const char* FileExtension const char *    path
 

Get a pointer on the extension of a pathname (just after the last '.').

Example: points to "ext" in "/aa/bbb.ccc-ddd.ext". Note: '.' and '..' directories, or any name starting by '.' with no other '.' (extension) are considered as not having an extension (returns NULL).

Returns:
a pointer on the extension (on the first character after the last '.') or NULL if no extension is found.


Generated by Doxygen 1.2.18 on Tue Oct 26 12:07:39 2004.