C/C++ User's Journal STLSoft - ... Robust, Lightweight, Cross-platform, Template Software ... ATLSTL - where the Standard Template Library meets the Active Template Library COMSTL - where the Standard Template Library meets the Component Object Model
Synesis Software InetSTL - where the Standard Template Library meets the Internet UNIXSTL - Template Software for the UNIX Operating System WinSTL - where the Standard Template Library meets the Win32 API

recls/recls.h File Reference


Detailed Description

[C, C++] The root header for the recls API

#include <recls/internal/language.h>
#include <recls/internal/platform.h>
#include <recls/internal/compiler.h>
#include <recls/internal/platform_types.h>
#include <recls/internal/retcodes.h>
#include <recls/internal/doc/includes.h>

Go to the source code of this file.

Namespaces

namespace  recls
namespace  stlsoft

Classes

struct  recls_root_t
 Structure containing information about a file-system root. More...

recls API Version

#define RECLS_VER_MAJOR   1
 The major version number of RECLS.
#define RECLS_VER_MINOR   8
 The minor version number of RECLS.
#define RECLS_VER_REVISION   10
 The revision version number of RECLS.
#define RECLS_VER   RECLS_VER_1_8_10
 The current composite version number of RECLS.

File system functions

size_t recls::Recls_GetRoots (recls_root_t *roots, size_t cRoots)
 Retrieves the file-system roots for the current operating system.
size_t recls::Recls_GetSelectedRoots (recls_root_t *roots, size_t cRoots, recls_uint32_t flags)
 Like Recls_GetRoots(), but only returns roots of selected disk types.
recls_char_t const * recls::Recls_GetPathNameSeparator (void)
 Returns the symbol used to separate distinct path names in path name lists.
recls_char_t const * recls::Recls_GetPathSeparator (void)
 Returns the symbol used to separate the directory parts within paths.
recls_char_t const * recls::Recls_GetWildcardsAll (void)
 Returns the wildcard symbol used to represent the "all files" for the current operating system.

Search control functions

recls_rc_t recls::Recls_Search (recls_char_t const *searchRoot, recls_char_t const *pattern, recls_uint32_t flags, hrecls_t *phSrch)
 Searches a given directory for matching files of the given pattern.
recls_rc_t recls::Recls_SearchFeedback (recls_char_t const *searchRoot, recls_char_t const *pattern, recls_uint32_t flags, hrecls_progress_fn_t pfn, recls_process_fn_param_t param, hrecls_t *phSrch)
 Searches a given directory for matching files of the given pattern, calling back on the given progress function pointer to inform the caller as each (sub-)directory is traversed.
recls_rc_t recls::Recls_SearchProcess (recls_char_t const *searchRoot, recls_char_t const *pattern, recls_uint32_t flags, hrecls_process_fn_t pfn, recls_process_fn_param_t param)
 Searches a given directory for matching files of the given pattern, and processes them according to the given process function.
void recls::Recls_SearchClose (hrecls_t hSrch)
 Closes the given search.
recls_rc_t recls::Recls_Stat (recls_char_t const *path, recls_uint32_t flags, recls_info_t *phEntry)
 Retrieves the information for the given path.

Search enumeration functions

recls_rc_t recls::Recls_GetNext (hrecls_t hSrch)
 Advances the search one position.
recls_rc_t recls::Recls_GetDetails (hrecls_t hSrch, recls_info_t *phEntry)
 Retrieves the information for the current search position.
recls_rc_t recls::Recls_GetNextDetails (hrecls_t hSrch, recls_info_t *phEntry)
 Advances the search one position, and retrieves the information for the new position.

File entry information functions

void recls::Recls_CloseDetails (recls_info_t hEntry)
 Releases the resources associated with an entry info structure.
recls_rc_t recls::Recls_CopyDetails (recls_info_t hEntry, recls_info_t *phEntry)
 Copies an entry info structure.
recls_rc_t recls::Recls_OutstandingDetails (hrecls_t hSrch, recls_uint32_t *count)
 Reports on the number of outstanding (i.e.

Error handling functions

recls_rc_t recls::Recls_GetLastError (hrecls_t hSrch)
 Returns the last error code associated with the given search handle.
size_t recls::Recls_GetErrorString (recls_rc_t rc, recls_char_t *buffer, size_t cchBuffer)
 Gets the error string representing the given error.
size_t recls::Recls_GetLastErrorString (hrecls_t hSrch, recls_char_t *buffer, size_t cchBuffer)
 Gets the error string representing the current error associated with the given search handle.

Property elicitation functions

size_t recls::Recls_GetPathProperty (recls_info_t hEntry, recls_char_t *buffer, size_t cchBuffer)
 Retrieves the full path of the given entry recls_fileinfo_t.
size_t recls::Recls_GetSearchRelativePathProperty (recls_info_t hEntry, recls_char_t *buffer, size_t cchBuffer)
 Retrieves the path of the given entry recls_fileinfo_t, relative to the search directory.
size_t recls::Recls_GetDirectoryProperty (recls_info_t hEntry, recls_char_t *buffer, size_t cchBuffer)
 Retrieves the directory of the given entry recls_fileinfo_t.
size_t recls::Recls_GetDirectoryPathProperty (recls_info_t hEntry, recls_char_t *buffer, size_t cchBuffer)
 Retrieves the directory (and drive) of the given entry recls_fileinfo_t.
size_t recls::Recls_GetSearchDirectoryProperty (recls_info_t hEntry, recls_char_t *buffer, size_t cchBuffer)
 Retrieves the directory (and drive) of the given entry recls_fileinfo_t that was used in the search resulting in the given entry.
size_t recls::Recls_GetUNCDriveProperty (recls_info_t hEntry, recls_char_t *buffer, size_t cchBuffer)
 Retrieves the UNC drive property of the given entry recls_fileinfo_t.
size_t recls::Recls_GetFileProperty (recls_info_t hEntry, recls_char_t *buffer, size_t cchBuffer)
 Retrieves the file (filename + extension) of the given entry recls_fileinfo_t.
size_t recls::Recls_GetShortFileProperty (recls_info_t hEntry, recls_char_t *buffer, size_t cchBuffer)
 Retrieves the short version of the file of the given entry recls_fileinfo_t.
size_t recls::Recls_GetFileNameProperty (recls_info_t hEntry, recls_char_t *buffer, size_t cchBuffer)
 Retrieves the filename (not including extension, if any) of the given entry recls_fileinfo_t.
size_t recls::Recls_GetFileExtProperty (recls_info_t hEntry, recls_char_t *buffer, size_t cchBuffer)
 Retrieves the file extension of the given entry recls_fileinfo_t.
size_t recls::Recls_GetDirectoryPartProperty (recls_info_t hEntry, int part, recls_char_t *buffer, size_t cchBuffer)
 Retrieves a directory part of the given entry recls_fileinfo_t.
recls_bool_t recls::Recls_IsFileReadOnly (recls_info_t hEntry)
 Returns non-zero if the file entry is read-only.
recls_bool_t recls::Recls_IsFileDirectory (recls_info_t hEntry)
 Returns non-zero if the file entry represents a directory.
recls_bool_t recls::Recls_IsFileLink (recls_info_t hEntry)
 Returns non-zero if the file entry represents a link.
recls_bool_t recls::Recls_DoesEntryExist (recls_info_t hEntry)
 Returns non-zero if the file entry exists "now".
recls_bool_t recls::Recls_IsFileUNC (recls_info_t hEntry)
 Returns non-zero if the file entry's path is UNC.
void recls::Recls_GetSizeProperty (recls_info_t hEntry, recls_filesize_t *size)
 Acquires the size of the file entry.
recls_time_t recls::Recls_GetCreationTime (recls_info_t hEntry)
 Returns the time the file was created.
recls_time_t recls::Recls_GetModificationTime (recls_info_t hEntry)
 Returns the time the file was last modified.
recls_time_t recls::Recls_GetLastAccessTime (recls_info_t hEntry)
 Returns the time the file was last accessed.
recls_time_t recls::Recls_GetLastStatusChangeTime (recls_info_t hEntry)
 Returns the time the file status was last changed.

Extended API functions

recls_bool_t recls::Recls_IsDirectoryEmpty (recls_char_t const *dir)
 Determines whether the given directory is empty.
recls_bool_t recls::Recls_IsDirectoryEntryEmpty (recls_info_t hEntry)
 Determines whether the given directory entry is empty.
recls_filesize_t recls::Recls_CalcDirectorySize (recls_char_t const *dir)
 Calculates the number of bytes in files in the given directory and all its sub-directories.
recls_filesize_t recls::Recls_CalcDirectoryEntrySize (recls_info_t hEntry)
 Calculates the number of bytes in files in the given directory entry and all its sub-directories.
recls_filesize_t recls::Recls_CalcDirectorySizeFeedback (recls_char_t const *dir, recls_uint32_t flags, hrecls_progress_fn_t pfn, recls_process_fn_param_t param)
 Calculates the number of bytes in files in the given directory and all its sub-directories, calling back on the given progress function pointer to inform the caller as each (sub-)directory is traversed.

Path functions

size_t recls::Recls_CombinePaths (recls_char_t const *path1, recls_char_t const *path2, recls_char_t *result, size_t cchResult)
 Combines two paths into one.
size_t recls::Recls_DeriveRelativePath (recls_char_t const *origin, recls_char_t const *target, recls_char_t *result, size_t cchResult)
 Determines the relative path between two paths.
size_t recls::Recls_SqueezePath (recls_char_t const *path, recls_char_t *result, size_t cchResult)
 Prepares the path for display into a fixed maximum width field.

Defines

#define RECLS_ROOT_NAME_LEN   (1) or (3)
 Defines the number of characters in a system root.
#define RECLS_FNDECL(rt)   RECLS_LINKAGE_C rt RECLS_CALLCONV_DEFAULT
 Defines the recls linkage and calling convention.

Typedefs

typedef recls_sint32_t recls::recls_rc_t
 The type of return codes issued by the API functions.
typedef hrecls_t_ const * recls::hrecls_t
 The handle to a recursive search operation.
typedef recls_fileinfo_t const * recls::recls_info_t
 Opaque type representing a file-system entry information.
typedef void * recls::recls_process_fn_param_t
 Opaque type representing a user-defined parameter to the process function.
typedef int(RECLS_CALLCONV_DEFAULT *) recls::hrecls_process_fn_t (recls_info_t hEntry, recls_process_fn_param_t param)
 User-supplied process function, used by Recls_SearchProcess().
typedef int(RECLS_CALLCONV_DEFAULT *) recls::hrecls_progress_fn_t (recls_char_t const *dir, size_t dirLen, recls_process_fn_param_t param, void *reserved0, recls_uint32_t reserved1)
 User-supplied process function, used by Recls_SearchFeedback(), which receives the sub-directories traversed.

Enumerations

enum  recls::RECLS_FLAG {
  recls::RECLS_F_FILES = 0x00000001,
  recls::RECLS_F_DIRECTORIES = 0x00000002,
  recls::RECLS_F_LINKS = 0x00000004,
  recls::RECLS_F_DEVICES = 0x00000008 ,
  recls::RECLS_F_DIR_PROGRESS = 0x00001000,
  recls::RECLS_F_RECURSIVE = 0x00010000,
  recls::RECLS_F_NO_FOLLOW_LINKS = 0x00020000,
  recls::RECLS_F_DIRECTORY_PARTS = 0x00040000,
  recls::RECLS_F_DETAILS_LATER = 0x00080000,
  recls::RECLS_F_PASSIVE_FTP = 0x00100000,
  recls::RECLS_F_MARK_DIRS = 0x00200000,
  recls::RECLS_F_ALLOW_REPARSE_DIRS = 0x00400000,
  recls::RECLS_F_CALLBACKS_STDCALL_ON_WIN32 = 0x01000000,
  recls::RECLS_F_USE_TILDE_ON_NO_SEARCHROOT = 0x04000000,
  recls::RECLS_F_IGNORE_HIDDEN_ENTRIES_ON_WIN32 = 0x08000000,
  recls::FILES = RECLS_F_FILES,
  recls::DIRECTORIES = RECLS_F_DIRECTORIES,
  recls::LINKS = RECLS_F_LINKS,
  recls::DEVICES = RECLS_F_DEVICES,
  recls::TYPEMASK = RECLS_F_TYPEMASK,
  recls::DIR_PROGRESS = RECLS_F_DIR_PROGRESS,
  recls::RECURSIVE = RECLS_F_RECURSIVE,
  recls::NO_FOLLOW_LINKS = RECLS_F_NO_FOLLOW_LINKS,
  recls::DIRECTORY_PARTS = RECLS_F_DIRECTORY_PARTS,
  recls::DETAILS_LATER = RECLS_F_DETAILS_LATER,
  recls::PASSIVE_FTP = RECLS_F_PASSIVE_FTP,
  recls::MARK_DIRS = RECLS_F_MARK_DIRS,
  recls::ALLOW_REPARSE_DIRS = RECLS_F_ALLOW_REPARSE_DIRS,
  recls::CALLBACKS_STDCALL_ON_WIN32 = RECLS_F_CALLBACKS_STDCALL_ON_WIN32,
  recls::USE_TILDE_ON_NO_SEARCHROOT = RECLS_F_USE_TILDE_ON_NO_SEARCHROOT,
  recls::IGNORE_HIDDEN_ENTRIES_ON_WIN32 = RECLS_F_IGNORE_HIDDEN_ENTRIES_ON_WIN32
}
 Search flags. More...
enum  recls::RECLS_ROOTS_FLAG {
  recls::RECLS_ROOTS_F_FIXED_DRIVES = 0x0001,
  recls::RECLS_ROOTS_F_NETWORK_DRIVES = 0x0002,
  recls::RECLS_ROOTS_F_CDROM_DRIVES = 0x0004,
  recls::RECLS_ROOTS_F_REMOVABLE_DRIVES = 0x0008,
  recls::RECLS_ROOTS_F_RAM_DRIVES = 0x0010,
  recls::FixedDrives = RECLS_ROOTS_F_FIXED_DRIVES,
  recls::NetworkDrives = RECLS_ROOTS_F_NETWORK_DRIVES,
  recls::CDRomDrives = RECLS_ROOTS_F_CDROM_DRIVES,
  recls::RemovableDrives = RECLS_ROOTS_F_REMOVABLE_DRIVES,
  recls::RamDrives = RECLS_ROOTS_F_RAM_DRIVES
}
 Selected Roots flags. More...

Functions

const recls_rc_t recls::RECLS_RC_OK (0)
 General success code.
const recls_rc_t recls::RECLS_RC_FAIL (-1)
 General failure code.
bool recls::RECLS_FAILED (recls_rc_t const &rc)
 Returns non-zero if the given return code indicates failure.
bool recls::RECLS_SUCCEEDED (recls_rc_t const &rc)
 Returns non-zero if the given return code indicates success.


Define Documentation

#define RECLS_VER   RECLS_VER_1_8_10

The current composite version number of RECLS.

#define RECLS_VER_MAJOR   1

The major version number of RECLS.

#define RECLS_VER_MINOR   8

The minor version number of RECLS.

#define RECLS_VER_REVISION   10

The revision version number of RECLS.


recls Library documentation © Synesis Software Pty Ltd, 2001-2006