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


Detailed Description

The core recls C API.

In C++ compilation, it resides within the namespacerecls recls namespace.


Modules

 recls.c++
 The recls C++ mapping.
 recls/C#
 The recls C# mapping.
 recls/COM
 The recls COM mapping.
 recls/D
 The recls D mapping.
 recls/Java
 The recls Java mapping.
 recls/Python
 The recls/Python mapping.
 recls/Ruby
 The recls Ruby mapping.
 recls.stl
 The recls STL mapping.

Classes

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

Search control functions

recls_rc_t Recls_SearchFtp (recls_char_t const *host, recls_char_t const *username, recls_char_t const *password, 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.

File system functions

size_t Recls_GetRoots (recls_root_t *roots, size_t cRoots)
 Retrieves the file-system roots for the current operating system.
size_t 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_GetPathNameSeparator (void)
 Returns the symbol used to separate distinct path names in path name lists.
recls_char_t const * Recls_GetPathSeparator (void)
 Returns the symbol used to separate the directory parts within paths.
recls_char_t const * 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_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_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_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_SearchClose (hrecls_t hSrch)
 Closes the given search.
recls_rc_t 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_GetNext (hrecls_t hSrch)
 Advances the search one position.
recls_rc_t Recls_GetDetails (hrecls_t hSrch, recls_info_t *phEntry)
 Retrieves the information for the current search position.
recls_rc_t 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_CloseDetails (recls_info_t hEntry)
 Releases the resources associated with an entry info structure.
recls_rc_t Recls_CopyDetails (recls_info_t hEntry, recls_info_t *phEntry)
 Copies an entry info structure.
recls_rc_t Recls_OutstandingDetails (hrecls_t hSrch, recls_uint32_t *count)
 Reports on the number of outstanding (i.e.

Error handling functions

recls_rc_t Recls_GetLastError (hrecls_t hSrch)
 Returns the last error code associated with the given search handle.
size_t Recls_GetErrorString (recls_rc_t rc, recls_char_t *buffer, size_t cchBuffer)
 Gets the error string representing the given error.
size_t 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_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_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_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_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_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_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_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_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_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_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_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_IsFileReadOnly (recls_info_t hEntry)
 Returns non-zero if the file entry is read-only.
recls_bool_t Recls_IsFileDirectory (recls_info_t hEntry)
 Returns non-zero if the file entry represents a directory.
recls_bool_t Recls_IsFileLink (recls_info_t hEntry)
 Returns non-zero if the file entry represents a link.
recls_bool_t Recls_DoesEntryExist (recls_info_t hEntry)
 Returns non-zero if the file entry exists "now".
recls_bool_t Recls_IsFileUNC (recls_info_t hEntry)
 Returns non-zero if the file entry's path is UNC.
void Recls_GetSizeProperty (recls_info_t hEntry, recls_filesize_t *size)
 Acquires the size of the file entry.
recls_time_t Recls_GetCreationTime (recls_info_t hEntry)
 Returns the time the file was created.
recls_time_t Recls_GetModificationTime (recls_info_t hEntry)
 Returns the time the file was last modified.
recls_time_t Recls_GetLastAccessTime (recls_info_t hEntry)
 Returns the time the file was last accessed.
recls_time_t Recls_GetLastStatusChangeTime (recls_info_t hEntry)
 Returns the time the file status was last changed.

Extended API functions

recls_bool_t Recls_IsDirectoryEmpty (recls_char_t const *dir)
 Determines whether the given directory is empty.
recls_bool_t Recls_IsDirectoryEntryEmpty (recls_info_t hEntry)
 Determines whether the given directory entry is empty.
recls_filesize_t 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_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_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_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_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_SqueezePath (recls_char_t const *path, recls_char_t *result, size_t cchResult)
 Prepares the path for display into a fixed maximum width field.

Property elicitation functions

void Recls_GetDriveProperty (recls_info_t hEntry, recls_char_t *pchDrive)
 Gets the drive associated with the given file entry info structure.

Defines

#define recls_alloca   alloca
 Compiler-independent implementation of alloca().
#define RECLS_ASSERT(x)   assert(x)
 Assert macro for the recls API.
#define recls_assert(expr)   RECLS_ASSERT(expr)
 Defines a compile-time assertion.
#define RECLS_MESSAGE_ASSERT(m, x)   RECLS_ASSERT(((m), (x)))
 Assert macro for the recls API.
#define recls_message_assert(msg, expr)   RECLS_MESSAGE_ASSERT(msg, expr)
 Defines a compile-time assertion.
#define recls_min(v1, v2)   (((v1) < (v2)) ? (v1) : (v2))
 Returns the smaller of two values.
#define recls_max(v1, v2)   (((v2) < (v1)) ? (v1) : (v2))
 Returns the larger of two values.
#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_rc_t
 The type of return codes issued by the API functions.
typedef hrecls_t_ const * hrecls_t
 The handle to a recursive search operation.
typedef recls_fileinfo_t const * recls_info_t
 Opaque type representing a file-system entry information.
typedef void * recls_process_fn_param_t
 Opaque type representing a user-defined parameter to the process function.
typedef int(RECLS_CALLCONV_DEFAULT *) 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 *) 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_FLAG {
  RECLS_F_FILES = 0x00000001,
  RECLS_F_DIRECTORIES = 0x00000002,
  RECLS_F_LINKS = 0x00000004,
  RECLS_F_DEVICES = 0x00000008 ,
  RECLS_F_DIR_PROGRESS = 0x00001000,
  RECLS_F_RECURSIVE = 0x00010000,
  RECLS_F_NO_FOLLOW_LINKS = 0x00020000,
  RECLS_F_DIRECTORY_PARTS = 0x00040000,
  RECLS_F_DETAILS_LATER = 0x00080000,
  RECLS_F_PASSIVE_FTP = 0x00100000,
  RECLS_F_MARK_DIRS = 0x00200000,
  RECLS_F_ALLOW_REPARSE_DIRS = 0x00400000,
  RECLS_F_CALLBACKS_STDCALL_ON_WIN32 = 0x01000000,
  RECLS_F_USE_TILDE_ON_NO_SEARCHROOT = 0x04000000,
  RECLS_F_IGNORE_HIDDEN_ENTRIES_ON_WIN32 = 0x08000000,
  FILES = RECLS_F_FILES,
  DIRECTORIES = RECLS_F_DIRECTORIES,
  LINKS = RECLS_F_LINKS,
  DEVICES = RECLS_F_DEVICES,
  TYPEMASK = RECLS_F_TYPEMASK,
  DIR_PROGRESS = RECLS_F_DIR_PROGRESS,
  RECURSIVE = RECLS_F_RECURSIVE,
  NO_FOLLOW_LINKS = RECLS_F_NO_FOLLOW_LINKS,
  DIRECTORY_PARTS = RECLS_F_DIRECTORY_PARTS,
  DETAILS_LATER = RECLS_F_DETAILS_LATER,
  PASSIVE_FTP = RECLS_F_PASSIVE_FTP,
  MARK_DIRS = RECLS_F_MARK_DIRS,
  ALLOW_REPARSE_DIRS = RECLS_F_ALLOW_REPARSE_DIRS,
  CALLBACKS_STDCALL_ON_WIN32 = RECLS_F_CALLBACKS_STDCALL_ON_WIN32,
  USE_TILDE_ON_NO_SEARCHROOT = RECLS_F_USE_TILDE_ON_NO_SEARCHROOT,
  IGNORE_HIDDEN_ENTRIES_ON_WIN32 = RECLS_F_IGNORE_HIDDEN_ENTRIES_ON_WIN32
}
 Search flags. More...
enum  RECLS_ROOTS_FLAG {
  RECLS_ROOTS_F_FIXED_DRIVES = 0x0001,
  RECLS_ROOTS_F_NETWORK_DRIVES = 0x0002,
  RECLS_ROOTS_F_CDROM_DRIVES = 0x0004,
  RECLS_ROOTS_F_REMOVABLE_DRIVES = 0x0008,
  RECLS_ROOTS_F_RAM_DRIVES = 0x0010,
  FixedDrives = RECLS_ROOTS_F_FIXED_DRIVES,
  NetworkDrives = RECLS_ROOTS_F_NETWORK_DRIVES,
  CDRomDrives = RECLS_ROOTS_F_CDROM_DRIVES,
  RemovableDrives = RECLS_ROOTS_F_REMOVABLE_DRIVES,
  RamDrives = RECLS_ROOTS_F_RAM_DRIVES
}
 Selected Roots flags. More...

Functions

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


Define Documentation

#define recls_alloca   alloca

Compiler-independent implementation of alloca().

Examples:
example_c_2.c.

#define recls_assert ( expr   )     RECLS_ASSERT(expr)

Defines a compile-time assertion.

Parameters:
expr Must be non-zero, or compilation will fail.
Deprecated:
This is deprecated in favour of RECLS_ASSERT().
Note:
This is a simple #define for RECLS_ASSERT().

#define RECLS_ASSERT (  )     assert(x)

Assert macro for the recls API.

If the given expressions evaluates to false (0), the execution is halted and an error message given.

Parameters:
x The expression that must evaluate to true

#define RECLS_FNDECL ( rt   )     RECLS_LINKAGE_C rt RECLS_CALLCONV_DEFAULT

Defines the recls linkage and calling convention.

#define recls_max ( v1,
v2   )     (((v2) < (v1)) ? (v1) : (v2))

Returns the larger of two values.

Parameters:
v1 The first of the two values
v2 The first of the two values

#define recls_message_assert ( msg,
expr   )     RECLS_MESSAGE_ASSERT(msg, expr)

Defines a compile-time assertion.

Parameters:
msg The message to be displayed to the user if the expr evaluates to 0
expr Must be non-zero, or compilation will fail.
Deprecated:
This is deprecated in favour of RECLS_MESSAGE_ASSERT().
Note:
This is a simple #define for RECLS_MESSAGE_ASSERT().

#define RECLS_MESSAGE_ASSERT ( m,
 )     RECLS_ASSERT(((m), (x)))

Assert macro for the recls API.

If the given expressions evaluates to false (0), the execution is halted and an error message given.

Parameters:
m The literal string describing the failed condition
x The expression that must evaluate to true

#define recls_min ( v1,
v2   )     (((v1) < (v2)) ? (v1) : (v2))

Returns the smaller of two values.

Parameters:
v1 The first of the two values
v2 The first of the two values

#define RECLS_ROOT_NAME_LEN   (1) or (3)

Defines the number of characters in a system root.


Typedef Documentation

typedef int(RECLS_CALLCONV_DEFAULT *) hrecls_process_fn_t(recls_info_t hEntry, recls_process_fn_param_t param)

User-supplied process function, used by Recls_SearchProcess().

Parameters:
hEntry entry info structure
param the parameter passed to Recls_SearchProcess()
Returns:
A status to indicate whether to continue or cancel the processing
Return values:
0 cancel the processing
non-0 continue the processing

typedef int(RECLS_CALLCONV_DEFAULT *) 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.

Parameters:
dir The nul-terminated C-style string containing the sub-directory's full path
dirLen The number of characters in the dir param, not including the nul-terminator
param the parameter passed to Recls_SearchFeedback()
Returns:
A status to indicate whether to continue or cancel the processing
Return values:
0 cancel the processing
non-0 continue the processing

typedef struct hrecls_t_ const* hrecls_t

The handle to a recursive search operation.

Examples:
example_c_1.c, example_c_2.c, example_c_3.c, and example_c_4.c.

typedef struct recls_fileinfo_t const* recls_info_t

Opaque type representing a file-system entry information.

Examples:
example_c_1.c, example_c_2.c, example_c_3.c, example_c_4.c, example_c_5.c, example_c_6.c, and example_c_7.c.

typedef void* recls_process_fn_param_t

Opaque type representing a user-defined parameter to the process function.

Examples:
example_c_2.c, and example_c_5.c.

typedef recls_sint32_t recls_rc_t

The type of return codes issued by the API functions.

Examples:
example_c_1.c, example_c_2.c, example_c_3.c, example_c_4.c, example_c_5.c, example_c_6.c, and example_c_7.c.


Enumeration Type Documentation

enum RECLS_FLAG

Search flags.

These flags moderate the search behaviour of the Recls_Search(), Recls_SearchFeedback(), and Recls_SearchProcess() functions.

Enumerator:
RECLS_F_FILES  Include files in search. Included by default if none specified
RECLS_F_DIRECTORIES  Include directories in search
RECLS_F_LINKS  Include links in search. Ignored in Win32
RECLS_F_DEVICES  Include devices in search. Not currently supported
RECLS_F_DIR_PROGRESS  Reports each traversed directory to the callback function supplied to Recls_SearchFeedback()
RECLS_F_RECURSIVE  Searches given directory and all sub-directories
RECLS_F_NO_FOLLOW_LINKS  Does not expand links
RECLS_F_DIRECTORY_PARTS  Fills out the directory parts. Supported from version 1.1.1 onwards
RECLS_F_DETAILS_LATER  Does not fill out anything other than the path. When specified to Recls_Stat(), and no types (RECLS_F_TYPEMASK) are specified, this will allow some details for a non-existant path to be elicited.
RECLS_F_PASSIVE_FTP  Passive mode in FTP. Supported from version 1.5.1 onwards
RECLS_F_MARK_DIRS  Marks the directories with a trailing slash.
RECLS_F_ALLOW_REPARSE_DIRS  Allow Win32 reparse point directories to be examined (which can cause infinite loops).
RECLS_F_CALLBACKS_STDCALL_ON_WIN32  Treats the callbacks as stdcall calling convention on Win32. Default is cdecl. This is useful for interfacing as delegates with .NET
RECLS_F_USE_TILDE_ON_NO_SEARCHROOT  Interprets a NULL or empty searchRoot as the home directory, rather than the current directory. Supported from version 1.8.1 onwards.
RECLS_F_IGNORE_HIDDEN_ENTRIES_ON_WIN32  This causes hidden files to be ignored. Currently supported on Win32 only.
FILES  Equivalent to RECLS_F_FILES.
DIRECTORIES  Equivalent to RECLS_F_DIRECTORIES.
LINKS  Equivalent to RECLS_F_LINKS.
DEVICES  Equivalent to RECLS_F_DEVICES.
TYPEMASK  Equivalent to RECLS_F_TYPEMASK.
DIR_PROGRESS  Equivalent to RECLS_F_DIR_PROGRESS.
RECURSIVE  Equivalent to RECLS_F_RECURSIVE.
NO_FOLLOW_LINKS  Equivalent to RECLS_F_NO_FOLLOW_LINKS.
DIRECTORY_PARTS  Equivalent to RECLS_F_DIRECTORY_PARTS.
DETAILS_LATER  Equivalent to RECLS_F_DETAILS_LATER.
PASSIVE_FTP  Equivalent to RECLS_F_PASSIVE_FTP.
MARK_DIRS  Equivalent to RECLS_F_MARK_DIRS.
ALLOW_REPARSE_DIRS  Equivalent to RECLS_F_ALLOW_REPARSE_DIRS.
CALLBACKS_STDCALL_ON_WIN32  Equivalent to RECLS_F_CALLBACKS_STDCALL_ON_WIN32.
USE_TILDE_ON_NO_SEARCHROOT  Equivalent to RECLS_F_USE_TILDE_ON_NO_SEARCHROOT.
IGNORE_HIDDEN_ENTRIES_ON_WIN32  Equivalent to RECLS_F_IGNORE_HIDDEN_ENTRIES_ON_WIN32.

enum RECLS_ROOTS_FLAG

Selected Roots flags.

These flags moderate the search behaviour of the Recls_GetSelectedRoots() function.

Note:
The flags are ignored on UNIX, since the only root is '/'
Enumerator:
RECLS_ROOTS_F_FIXED_DRIVES  Include local fixed drives.
RECLS_ROOTS_F_NETWORK_DRIVES  Include network drives.
RECLS_ROOTS_F_CDROM_DRIVES  Include CD-ROM / DVD-ROM drives.
RECLS_ROOTS_F_REMOVABLE_DRIVES  Include removable drives.
RECLS_ROOTS_F_RAM_DRIVES  Include RAM drives.
FixedDrives  Include local fixed drives. Equivalent to RECLS_ROOTS_F_FIXED_DRIVES.
NetworkDrives  Include network drives. Equivalent to RECLS_ROOTS_F_NETWORK_DRIVES.
CDRomDrives  Include CD-ROM / DVD-ROM drives. Equivalent to RECLS_ROOTS_F_CDROM_DRIVES.
RemovableDrives  Include removable drives. Equivalent to RECLS_ROOTS_F_REMOVABLE_DRIVES.
RamDrives  Include RAM drives. Equivalent to RECLS_ROOTS_F_RAM_DRIVES.


Function Documentation

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.

Parameters:
hEntry The directory entry to assess
Examples:
example_c_3.c.

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.

Parameters:
dir The directory to assess
Examples:
example_c_8.c.

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.

Parameters:
flags Ignores RECLS_F_DIRECTORIES, and always adds RECLS_F_FILES. Listens to selected others.
pfn The function that will be invoked for each directory traversed
param The caller-defined parameter that is passed to the callback function
Returns:
A status code indicating success/failure

void recls::Recls_CloseDetails ( recls_info_t  hEntry  ) 

Releases the resources associated with an entry info structure.

Parameters:
hEntry The info entry structure handle. Must not be NULL.
Examples:
example_c_1.c, example_c_2.c, example_c_3.c, example_c_4.c, example_c_5.c, example_c_6.c, and example_c_7.c.

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.

This function takes two path fragments and combines them to form a single path.

Parameters:
path1 The left-most path.
path2 The right-most path.
result Pointer to character buffer in which to write the resultant path. If NULL, the function returns the number of characters required.
cchResult Number of character spaces in result. Ignored if result is NULL.
Returns:
The number of characters written to the buffer, or required for, the path.
Remarks:
If path2 is an absolute path, path1 is ignored and result contains characters copied from path2.
Examples:
example_c_7.c.

recls_rc_t recls::Recls_CopyDetails ( recls_info_t  hEntry,
recls_info_t *  phEntry 
)

Copies an entry info structure.

Parameters:
hEntry The info entry structure.
phEntry Address to receive a copy of the info entry structure. May not be NULL.
Returns:
Status code
Return values:
RECLS_RC_OK Entry was generated.
Any other status code indicates an error

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.

Parameters:
origin The path against which the relativity of target will be evaluated.
target The path.whose relatively (against origin) will be evaluated.
result Pointer to character buffer in which to write the resultant path. If NULL, the function returns the number of characters required.
cchResult Number of character spaces in result. Ignored if result is NULL.
Remarks:
On operating systems that have separate drives,
Examples:
example_c_5.c.

recls_bool_t recls::Recls_DoesEntryExist ( recls_info_t  hEntry  ) 

Returns non-zero if the file entry exists "now".

Parameters:
hEntry The file entry info structure to test. May not be NULL
Return values:
true file entry exists in the file-system at the time of call.
false file entry does not exist in the file-system at the time of call
Note:
There is no error return.

bool recls::RECLS_FAILED ( recls_rc_t const &  rc  )  [inline]

Returns non-zero if the given return code indicates failure.

Examples:
example_c_1.c, example_c_3.c, example_c_4.c, example_c_5.c, example_c_6.c, and example_c_7.c.

recls_time_t recls::Recls_GetCreationTime ( recls_info_t  hEntry  ) 

Returns the time the file was created.

recls_rc_t recls::Recls_GetDetails ( hrecls_t  hSrch,
recls_info_t *  phEntry 
)

Retrieves the information for the current search position.

Parameters:
hSrch Handle of the search to close. May not be NULL.
phEntry Pointer to receive entry info structure.
Returns:
Status code
Return values:
RECLS_RC_OK Position was advanced; search handle can be queried for details
RECLS_RC_NO_MORE_DATA There are no more items in the search
Any other status code indicates an error
Examples:
example_c_1.c, example_c_2.c, example_c_3.c, and example_c_4.c.

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.

Parameters:
hEntry The entry recls_fileinfo_t. Cannot be NULL
part The part requested. If -1, then the function returns the number of parts
buffer Pointer to character buffer in which to write the extension. If NULL, the function returns the number of characters required. Ignored if part is -1.
cchBuffer Number of character spaces in buffer. Ignored if buffer is NULL or part is -1.
Returns:
If part is -1, returns the number of parts. Otherwise, The number of characters written to the buffer, or required for, the extension.
Note:
The behaviour is undefined if part is outside the range of parts.

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.

Parameters:
hEntry The entry recls_fileinfo_t. Cannot be NULL
buffer Pointer to character buffer in which to write the directory. If NULL, the function returns the number of characters required.
cchBuffer Number of character spaces in buffer. Ignored if buffer is NULL.
Returns:
The number of characters written to the buffer, or required for, the directory.
Note:
On systems that do not have a drive, this function behaves identically to Recls_GetDirectoryProperty()

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.

Parameters:
hEntry The entry recls_fileinfo_t. Cannot be NULL
buffer Pointer to character buffer in which to write the directory. If NULL, the function returns the number of characters required.
cchBuffer Number of character spaces in buffer. Ignored if buffer is NULL.
Returns:
The number of characters written to the buffer, or required for, the directory.

void recls::Recls_GetDriveProperty ( recls_info_t  hEntry,
recls_char_t *  pchDrive 
)

Gets the drive associated with the given file entry info structure.

Parameters:
hEntry The info entry structure.
pchDrive Pointer to a character to receive the drive character. Cannot be NULL. The character will be in uppercase.

size_t recls::Recls_GetErrorString ( recls_rc_t  rc,
recls_char_t *  buffer,
size_t  cchBuffer 
)

Gets the error string representing the given error.

Parameters:
rc The error code
buffer Pointer to character buffer in which to write the error. If NULL, the function returns the number of characters required.
cchBuffer Number of character spaces in buffer. Ignored if buffer is NULL.
Returns:
The number of characters written to the buffer, or required for the error.
Examples:
example_c_1.c, example_c_2.c, example_c_3.c, example_c_4.c, example_c_5.c, example_c_6.c, and example_c_7.c.

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.

Parameters:
hEntry The entry recls_fileinfo_t. Cannot be NULL
buffer Pointer to character buffer in which to write the extension. If NULL, the function returns the number of characters required.
cchBuffer Number of character spaces in buffer. Ignored if buffer is NULL.
Returns:
The number of characters written to the buffer, or required for, the extension.

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.

Parameters:
hEntry The entry recls_fileinfo_t. Cannot be NULL
buffer Pointer to character buffer in which to write the filename. If NULL, the function returns the number of characters required.
cchBuffer Number of character spaces in buffer. Ignored if buffer is NULL.
Returns:
The number of characters written to the buffer, or required for, the filename.

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.

Parameters:
hEntry The entry recls_fileinfo_t. Cannot be NULL
buffer Pointer to character buffer in which to write the file. If NULL, the function returns the number of characters required.
cchBuffer Number of character spaces in buffer. Ignored if buffer is NULL.
Returns:
The number of characters written to the buffer, or required for, the file.

recls_time_t recls::Recls_GetLastAccessTime ( recls_info_t  hEntry  ) 

Returns the time the file was last accessed.

recls_rc_t recls::Recls_GetLastError ( hrecls_t  hSrch  ) 

Returns the last error code associated with the given search handle.

Parameters:
hSrch Handle of the search to close. May not be NULL.
Returns:
The last error code for the search handle

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.

Parameters:
hSrch Handle of the search to close. May not be NULL.
buffer Pointer to character buffer in which to write the error. If NULL, the function returns the number of characters required.
cchBuffer Number of character spaces in buffer. Ignored if buffer is NULL.
Returns:
The number of characters written to the buffer, or required for, the error.

recls_time_t recls::Recls_GetLastStatusChangeTime ( recls_info_t  hEntry  ) 

Returns the time the file status was last changed.

recls_time_t recls::Recls_GetModificationTime ( recls_info_t  hEntry  ) 

Returns the time the file was last modified.

recls_rc_t recls::Recls_GetNext ( hrecls_t  hSrch  ) 

Advances the search one position.

Parameters:
hSrch Handle of the search to close. May not be NULL.
Returns:
Status code
Return values:
RECLS_RC_OK Position was advanced; search handle can be queried for details
RECLS_RC_NO_MORE_DATA There are no more items in the search
Any other status code indicates an error

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.

Parameters:
hSrch Handle of the search to close. May not be NULL.
phEntry Pointer to receive entry info structure.
Returns:
Status code
Return values:
RECLS_RC_OK Position was advanced; search handle can be queried for details
Any other status code indicates an error
Examples:
example_c_1.c, example_c_2.c, example_c_3.c, and example_c_4.c.

recls_char_t const* recls::Recls_GetPathNameSeparator ( void   ) 

Returns the symbol used to separate distinct path names in path name lists.

Note:
On UNIX this is "/"; on Win32 it is "\".
It is used as follows:

  puts(Recls_GetPathNameSeparator());

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.

Parameters:
hEntry The entry recls_fileinfo_t. Cannot be NULL
buffer Pointer to character buffer in which to write the path. If NULL, the function returns the number of characters required.
cchBuffer Number of character spaces in buffer. Ignored if buffer is NULL.
Returns:
The number of characters written to the buffer, or required for, the path.
Examples:
example_c_1.c, and example_c_3.c.

recls_char_t const* recls::Recls_GetPathSeparator ( void   ) 

Returns the symbol used to separate the directory parts within paths.

Note:
On UNIX this is ":"; on Win32 it is ";".
It is used as follows:

  puts(Recls_GetPathSeparator());

size_t recls::Recls_GetRoots ( recls_root_t *  roots,
size_t  cRoots 
)

Retrieves the file-system roots for the current operating system.

It is used as follows:

  recls_root_t  roots[26];
  size_t        cRoots  = Recls_GetRoots(&roots[0], 26);
  size_t        i;

  for(i = 0; i < cRoots; ++i)
  {
    puts(roots[i].name);
  }

Parameters:
roots A pointer to an array of size cRoots. If NULL, the function returns the number of available roots.
cRoots The maximum number of roots to retrive in roots.
Returns:
The number of roots actually retrieved. If roots is NULL, then this is the current number of roots on the current operating system. If roots is not NULL, then this is the number of roots written into roots, and is not more than cRoots.
Examples:
example_c_8.c.

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.

Parameters:
hEntry The entry recls_fileinfo_t. Cannot be NULL
buffer Pointer to character buffer in which to write the directory. If NULL, the function returns the number of characters required.
cchBuffer Number of character spaces in buffer. Ignored if buffer is NULL.
Returns:
The number of characters written to the buffer, or required for, the directory.

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.

Parameters:
hEntry The entry recls_fileinfo_t. Cannot be NULL
buffer Pointer to character buffer in which to write the path. If NULL, the function returns the number of characters required.
cchBuffer Number of character spaces in buffer. Ignored if buffer is NULL.
Returns:
The number of characters written to the buffer, or required for, the path.

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.

Parameters:
roots A pointer to an array of size cRoots. If NULL, the function returns the number of available roots.
cRoots The maximum number of roots to retrive in roots.
flags Combination of the RECLS_ROOTS_FLAG enumeration. If 0, implies all available root types.
Returns:
The number of roots actually retrieved. If roots is NULL, then this is the current number of roots on the current operating system. If roots is not NULL, then this is the number of roots written into roots, and is not more than cRoots.
Examples:
example_c_8.c.

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.

Parameters:
hEntry The entry recls_fileinfo_t. Cannot be NULL
buffer Pointer to character buffer in which to write the file. If NULL, the function returns the number of characters required.
cchBuffer Number of character spaces in buffer. Ignored if buffer is NULL.
Returns:
The number of characters written to the buffer, or required for, the file.
Note:
On systems where there is no concept of a short name, this function behaves exactly as Recls_GetFileProperty()

void recls::Recls_GetSizeProperty ( recls_info_t  hEntry,
recls_filesize_t *  size 
)

Acquires the size of the file entry.

Parameters:
hEntry The file entry info structure to test. May not be NULL
size Pointer to the location in which to store the size
Note:
There is no error return. File system entries that do not have a meaningful size will be given a notional size of 0.
Examples:
example_c_3.c.

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.

Parameters:
hEntry The entry recls_fileinfo_t. Cannot be NULL
buffer Pointer to character buffer in which to write the directory. If NULL, the function returns the number of characters required.
cchBuffer Number of character spaces in buffer. Ignored if buffer is NULL.
Returns:
The number of characters written to the buffer, or required for, the directory.
Note:
On operating systems that do not support UNC, this function always returns 0, and writes the empty string into buffer (when non-NULL)

recls_char_t const* recls::Recls_GetWildcardsAll ( void   ) 

Returns the wildcard symbol used to represent the "all files" for the current operating system.

Note:
On UNIX this is "*"; on Win32 it is "*.*".
It is used as follows:

  puts(Recls_GetWildcardsAll());
Examples:
example_c_1.c, example_c_5.c, and example_cpp_1.cpp.

recls_bool_t recls::Recls_IsDirectoryEmpty ( recls_char_t const *  dir  ) 

Determines whether the given directory is empty.

Parameters:
dir The directory to assess

recls_bool_t recls::Recls_IsDirectoryEntryEmpty ( recls_info_t  hEntry  ) 

Determines whether the given directory entry is empty.

Parameters:
hEntry The directory entry to assess
Examples:
example_c_4.c.

recls_bool_t recls::Recls_IsFileDirectory ( recls_info_t  hEntry  ) 

Returns non-zero if the file entry represents a directory.

Parameters:
hEntry The file entry info structure to test. May not be NULL
Return values:
true file entry is a directory
false file entry is not directory
Note:
There is no error return
Examples:
example_c_3.c.

recls_bool_t recls::Recls_IsFileLink ( recls_info_t  hEntry  ) 

Returns non-zero if the file entry represents a link.

Parameters:
hEntry The file entry info structure to test. May not be NULL
Return values:
true file entry is a link
false file entry is not link
Note:
There is no error return

recls_bool_t recls::Recls_IsFileReadOnly ( recls_info_t  hEntry  ) 

Returns non-zero if the file entry is read-only.

Parameters:
hEntry The file entry info structure to test. May not be NULL
Return values:
true file entry is read-only
false file entry is not read-only
Note:
There is no error return

recls_bool_t recls::Recls_IsFileUNC ( recls_info_t  hEntry  ) 

Returns non-zero if the file entry's path is UNC.

Parameters:
hEntry The file entry info structure to test. May not be NULL
Return values:
true file entry's path is UNC
false file entry's path is UNC
Note:
There is no error return

recls_rc_t recls::Recls_OutstandingDetails ( hrecls_t  hSrch,
recls_uint32_t *  count 
)

Reports on the number of outstanding (i.e.

in client code) file entry info structures

Parameters:
hSrch Handle of the search to close. May not be NULL.
count Pointer to an integer variable to receive the result.
Returns:
Status code
Return values:
RECLS_RC_OK Information was retrieved.
Any other status code indicates an error

const recls_rc_t recls::RECLS_RC_FAIL ( 1  ) 

General failure code.

const recls_rc_t recls::RECLS_RC_OK (  ) 

General success code.

Examples:
example_c_2.c.

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.

Parameters:
searchRoot The directory representing the root of the search. NULL or "" means the current directory is assumed, unless RECLS_F_USE_TILDE_ON_NO_SEARCHROOT is specified, in which case the calling identity's home directory is assumed.
pattern The search pattern, e.g. "*.c". NULL means "all files". "" means no files.
flags A combination of 0 or more RECLS_FLAG values.
phSrch Address of the search handle. This is set to NULL on failure.
Returns:
A status code indicating success/failure.
Return values:
RECLS_RC_NO_MORE_DATA No items matched the given search criteria.
Examples:
example_c_1.c, example_c_3.c, and example_c_4.c.

void recls::Recls_SearchClose ( hrecls_t  hSrch  ) 

Closes the given search.

Parameters:
hSrch Handle of the search to close. May not be NULL.
Examples:
example_c_1.c, example_c_3.c, and example_c_4.c.

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.

Parameters:
searchRoot The directory representing the root of the search
pattern The search pattern, e.g. "*.c"
flags A combination of 0 or more RECLS_FLAG values.
pfn The function that will be invoked for each directory traversed
param The caller-defined parameter that is passed to the callback function
phSrch Address of the search handle. This is set to NULL on failure
Returns:
A status code indicating success/failure
Examples:
example_c_2.c.

recls_rc_t recls::Recls_SearchFtp ( recls_char_t const *  host,
recls_char_t const *  username,
recls_char_t const *  password,
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.

Parameters:
host The host on which to search
username The username with which to gain access
password The password with which to gain access
searchRoot The directory representing the root of the search
pattern The search pattern, e.g. "*.c"
flags A combination of 0 or more RECLS_FLAG values
phSrch Address of the search handle. This is set to NULL on failure
Returns:
A status code indicating success/failure
Note:
This function is currently only available on Win32.

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.

Parameters:
searchRoot The directory representing the root of the search
pattern The search pattern, e.g. "*.c"
flags A combination of 0 or more RECLS_FLAG values.
pfn The processing function
param A caller-supplied parameter that is passed through to pfn on each invocation. The function can cancel the enumeration by returning 0
Returns:
A status code indicating success/failure
Note:
Available from version 1.1 of the recls API
Examples:
example_c_5.c.

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.

Parameters:
path The path to be squeezed.
result Pointer to character buffer in which to write the resultant path. If NULL, the function returns the number of characters required.
cchResult Number of character spaces in result. Ignored if result is NULL.
Remarks:
On operating systems that have separate drives,
Examples:
example_c_2.c, and example_c_3.c.

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.

Parameters:
path Absolute or relative path of the file system entry whose information is to be retrieved.
flags Flags to moderate the search. Only the type flags (flags & RECLS_F_TYPEMASK) and RECLS_F_DIRECTORY_PARTS are recognised
phEntry Pointer to receive entry info structure.
Returns:
Status code
Return values:
RECLS_RC_OK Position was advanced; search handle can be queried for details
RECLS_RC_NO_MORE_DATA There was no file system entry that matched the path and flags criteria
Any other status code indicates an error
Examples:
example_c_3.c, example_c_5.c, example_c_6.c, and example_c_7.c.

bool recls::RECLS_SUCCEEDED ( recls_rc_t const &  rc  )  [inline]

Returns non-zero if the given return code indicates success.

Examples:
example_c_1.c, example_c_2.c, example_c_3.c, and example_c_4.c.


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