C/C++ User's Journal Synesis Software 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 UNIXSTL - Template Software for the UNIX Operating System WinSTL - where the Standard Template Library meets the Win32 API
Main Page   Modules   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

recls

The recls C API. In C++ compilation, it resides within the recls namespace. More...


Modules

recls.c++
 The recls C++ mapping. It resides within the recls::cpp namespace.

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-Ruby
 The recls Ruby mapping.

recls.stl
 The recls STL mapping.


recls API Version

#define RECLS_VER_MAJOR   1
 The major version number of RECLS.

#define RECLS_VER_MINOR   4
 The minor version number of RECLS.

#define RECLS_VER_REVISION   1
 The revision version number of RECLS.

#define RECLS_VER   RECLS_VER_1_4_1
 The current composite version number of RECLS.


File system functions

size_t Recls_GetRoots (recls_root_t *roots, size_t cRoots)
 Retrieves the file-system roots for the current operating system.

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_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.


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)
 Advances the search one position, and retrieves the information for the new position.

recls_rc_t Recls_GetNextDetails (hrecls_t hSrch, recls_info_t *phEntry)
 Retrieves the information for the current search position.


File entry info structure 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_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_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.

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.


Enumerations

enum  RECLS_FLAG {
  RECLS_F_FILES = 0x00000001,
  RECLS_F_DIRECTORIES = 0x00000002,
  RECLS_F_LINKS = 0x00000004,
  RECLS_F_DEVICES = 0x00000008 ,
  RECLS_F_RECURSIVE = 0x00010000,
  RECLS_F_NO_FOLLOW_LINKS = 0x00020000,
  RECLS_F_DIRECTORY_PARTS = 0x00040000,
  RECLS_F_DETAILS_LATER = 0x00080000
}
 Search flags. More...

Detailed Description

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

Define Documentation

#define RECLS_VER   RECLS_VER_1_4_1
 

The current composite version number of RECLS.

#define RECLS_VER_MAJOR   1
 

The major version number of RECLS.

#define RECLS_VER_MINOR   4
 

The minor version number of RECLS.

#define RECLS_VER_REVISION   1
 

The revision version number of RECLS.

Enumeration Type Documentation

enum RECLS_FLAG
 

Search flags.

These flags moderate the search behaviour of the Recls_Search and Recls_SearchProcess functions.

Enumeration values:
RECLS_F_FILES  Include files in search. Included by default if none specified
RECLS_F_DIRECTORIES  Include directories in search. Not currently supported.
RECLS_F_LINKS  Include links in search. Ignored in Win32.
RECLS_F_DEVICES  Include devices in search. Not currently supported.
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. Not currently supported.

Function Documentation

void Recls_CloseDetails (  recls_info_t    hEntry ) 
 

Releases the resources associated with an entry info structure.

Parameters:
hEntry  The info entry structure.

recls_rc_t 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

recls_time_t Recls_GetCreationTime (  recls_info_t    hEntry ) 
 

Returns the time the file was created.

recls_rc_t Recls_GetDetails (  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
RECLS_RC_NO_MORE_DATA  There are no more items in the search
Any  other status code indicates an error

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.

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_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_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.

size_t 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.

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.

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_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_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_GetLastAccessTime (  recls_info_t    hEntry ) 
 

Returns the time the file was last accessed.

recls_rc_t 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_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_GetLastStatusChangeTime (  recls_info_t    hEntry ) 
 

Returns the time the file status was last changed.

recls_time_t Recls_GetModificationTime (  recls_info_t    hEntry ) 
 

Returns the time the file was last modified.

recls_rc_t 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_GetNextDetails (  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
Any  other status code indicates an error

recls_char_t const* 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_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.

recls_char_t const* 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_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, 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.

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.

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_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.

recls_char_t const* 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());

recls_bool_t 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

recls_bool_t 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_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_rc_t 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

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.

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
phSrch  Address of the search handle
Returns:
A status code indicating success/failure

void Recls_SearchClose (  hrecls_t    hSrch ) 
 

Closes the given search.

Parameters:
hSrch  Handle of the search to close. May not be NULL.

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.

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
recls Library documentation © Synesis Software Pty Ltd, 2001-2004