---

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.stl
	The recls STL mapping.
recls-C#
	The recls C# mapping.
recls API Version
#define	RECLS_VER_MAJOR   1
	The major version number of RECLS.
#define	RECLS_VER_MINOR   1
	The minor version number of RECLS.
#define	RECLS_VER_REVISION   1
	The revision version number of RECLS.
#define	RECLS_VER   RECLS_VER_1_1_1
	The current composite version number of RECLS.
Search control functions
recls_rc_t	Recls_Search (char const *searchRoot, char 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 (char const *searchRoot, char 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 *pinfo)
	Advances the search one position, and retrieves the information for the new position.
recls_rc_t	Recls_GetNextDetails (hrecls_t hSrch, recls_info_t *pinfo)
	Retrieves the information for the current search position.
File entry info structure functions
void	Recls_CloseDetails (recls_info_t fileInfo)
	Releases the resources associated with an entry info structure.
recls_rc_t	Recls_CopyDetails (recls_info_t fileInfo, recls_info_t *pinfo)
	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.
int	Recls_GetErrorString (recls_rc_t rc, char *buffer, size_t cchBuffer)
	Gets the error string representing the given error.
int	Recls_GetLastErrorString (hrecls_t hSrch, char *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 fileInfo, char *buffer, size_t cchBuffer)
	Retrieves the full path of the given entry recls_fileinfo_t.
size_t	Recls_GetDirectoryProperty (recls_info_t fileInfo, char *buffer, size_t cchBuffer)
	Retrieves the directory of the given entry recls_fileinfo_t.
size_t	Recls_GetDirectoryPathProperty (recls_info_t fileInfo, char *buffer, size_t cchBuffer)
	Retrieves the directory and drive of the given entry recls_fileinfo_t.
size_t	Recls_GetFileProperty (recls_info_t fileInfo, char *buffer, size_t cchBuffer)
	Retrieves the file (filename + extension) of the given entry recls_fileinfo_t.
size_t	Recls_GetShortFileProperty (recls_info_t fileInfo, char *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 fileInfo, char *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 fileInfo, char *buffer, size_t cchBuffer)
	Retrieves the file extension of the given entry recls_fileinfo_t.
size_t	Recls_GetDirectoryPartProperty (recls_info_t fileInfo, int part, char *buffer, size_t cchBuffer)
	Retrieves a directory part of the given entry recls_fileinfo_t.
recls_bool_t	Recls_IsFileReadOnly (recls_info_t fileInfo)
	Returns non-zero if the file entry is read-only.
recls_bool_t	Recls_IsFileDirectory (recls_info_t fileInfo)
	Returns non-zero if the file entry represents a directory.
recls_bool_t	Recls_IsFileLink (recls_info_t fileInfo)
	Returns non-zero if the file entry represents a link.
void	Recls_GetSizeProperty (recls_info_t fileInfo, recls_filesize_t *size)
	Acquires the size of the file entry.
recls_time_t	Recls_GetCreationTime (recls_info_t fileInfo)
	Returns the time the file was created.
recls_time_t	Recls_GetModificationTime (recls_info_t fileInfo)
	Returns the time the file was last modified.
recls_time_t	Recls_GetLastAccessTime (recls_info_t fileInfo)
	Returns the time the file was last accessed.
recls_time_t	Recls_GetLastStatusChangeTime (recls_info_t fileInfo)
	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_1_1

The current composite version number of RECLS.

#define RECLS_VER_MAJOR   1

The major version number of RECLS.

#define RECLS_VER_MINOR   1

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    fileInfo )

Releases the resources associated with an entry info structure. Parameters: fileInfo  The info entry structure.

recls_rc_t Recls_CopyDetails (  recls_info_t    fileInfo, recls_info_t *    pinfo )

Copies an entry info structure. Parameters: fileInfo  The info entry structure. pinfo  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    fileInfo )

Returns the time the file was created.

recls_rc_t Recls_GetDetails (  hrecls_t    hSrch, recls_info_t *    pinfo )

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. pinfo  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    fileInfo, int    part, char *    buffer, size_t    cchBuffer )

Retrieves a directory part of the given entry recls_fileinfo_t. Parameters: fileInfo  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    fileInfo, char *    buffer, size_t    cchBuffer )

Retrieves the directory and drive of the given entry recls_fileinfo_t. Parameters: fileInfo  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    fileInfo, char *    buffer, size_t    cchBuffer )

Retrieves the directory of the given entry recls_fileinfo_t. Parameters: fileInfo  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.

int Recls_GetErrorString (  recls_rc_t    rc, char *    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    fileInfo, char *    buffer, size_t    cchBuffer )

Retrieves the file extension of the given entry recls_fileinfo_t. Parameters: fileInfo  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    fileInfo, char *    buffer, size_t    cchBuffer )

Retrieves the filename (not including extension, if any) of the given entry recls_fileinfo_t. Parameters: fileInfo  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    fileInfo, char *    buffer, size_t    cchBuffer )

Retrieves the file (filename + extension) of the given entry recls_fileinfo_t. Parameters: fileInfo  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    fileInfo )

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

int Recls_GetLastErrorString (  hrecls_t    hSrch, char *    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    fileInfo )

Returns the time the file status was last changed.

recls_time_t Recls_GetModificationTime (  recls_info_t    fileInfo )

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 *    pinfo )

Retrieves the information for the current search position. Parameters: hSrch  Handle of the search to close. May not be NULL. pinfo  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

size_t Recls_GetPathProperty (  recls_info_t    fileInfo, char *    buffer, size_t    cchBuffer )

Retrieves the full path of the given entry recls_fileinfo_t. Parameters: fileInfo  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_GetShortFileProperty (  recls_info_t    fileInfo, char *    buffer, size_t    cchBuffer )

Retrieves the short version of the file of the given entry recls_fileinfo_t. Parameters: fileInfo  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    fileInfo, recls_filesize_t *    size )

Acquires the size of the file entry. Parameters: fileInfo  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_bool_t Recls_IsFileDirectory (  recls_info_t    fileInfo )

Returns non-zero if the file entry represents a directory. Parameters: fileInfo  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    fileInfo )

Returns non-zero if the file entry represents a link. Parameters: fileInfo  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    fileInfo )

Returns non-zero if the file entry is read-only. Parameters: fileInfo  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 (  char const *    searchRoot, char 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 (  char const *    searchRoot, char 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-2003