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

Main Page   Modules   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

/include/recls.h

Go to the documentation of this file.
00001 /* 
00002  * File:        recls.h
00003  *
00004  * Purpose:     Main header file for the recls API.
00005  *
00006  * Created:     15th August 2003
00007  * Updated:     28th March 2005
00008  *
00009  * Home:        http://recls.org/
00010  *
00011  * Copyright 2003-2005, Matthew Wilson and Synesis Software
00012  * All rights reserved.
00013  *
00014  * Redistribution and use in source and binary forms, with or without 
00015  * modification, are permitted provided that the following conditions are met:
00016  *
00017  * - Redistributions of source code must retain the above copyright notice, this
00018  *   list of conditions and the following disclaimer. 
00019  * - Redistributions in binary form must reproduce the above copyright notice,
00020  *   this list of conditions and the following disclaimer in the documentation
00021  *   and/or other materials provided with the distribution.
00022  * - Neither the name(s) of Matthew Wilson and Synesis Software nor the names of
00023  *   any contributors may be used to endorse or promote products derived from
00024  *   this software without specific prior written permission.
00025  *
00026  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00027  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00028  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00029  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
00030  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
00031  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
00032  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00033  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00034  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
00035  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00036  * POSSIBILITY OF SUCH DAMAGE.
00037  *
00038  * 
00039 
00040 
00043 #ifndef RECLS_INCL_H_RECLS
00044 #define RECLS_INCL_H_RECLS
00045 
00046 /* File version */
00047 #ifndef RECLS_DOCUMENTATION_SKIP_SECTION
00048 # define RECLS_VER_H_RECLS_MAJOR    2
00049 # define RECLS_VER_H_RECLS_MINOR    4
00050 # define RECLS_VER_H_RECLS_REVISION 1
00051 # define RECLS_VER_H_RECLS_EDIT     54
00052 #endif /* !RECLS_DOCUMENTATION_SKIP_SECTION */
00053 
00068 /* recls version */
00069 #define RECLS_VER_MAJOR     1
00070 #define RECLS_VER_MINOR     6
00071 #define RECLS_VER_REVISION  2
00072 #define RECLS_VER_1_0_1     0x01000100
00073 #define RECLS_VER_1_1_1     0x01010100
00074 #define RECLS_VER_1_2_1     0x01020100
00075 #define RECLS_VER_1_3_1     0x01030100
00076 #define RECLS_VER_1_4_1     0x01040100
00077 #define RECLS_VER_1_4_2     0x01040200
00078 #define RECLS_VER_1_5_1     0x01050100
00079 #define RECLS_VER_1_5_2     0x01050200
00080 #define RECLS_VER_1_5_3     0x01050300
00081 #define RECLS_VER_1_6_1     0x01060100
00082 #define RECLS_VER_1_6_2     0x01060200
00083 #define RECLS_VER           RECLS_VER_1_6_2
00084 
00085 /* 
00086  * Strictness
00087  */
00088 
00089 #ifndef RECLS_NO_STRICT
00090 # define RECLS_STRICT
00091 #endif /* !RECLS_NO_STRICT */
00092 
00093 /* 
00094  * Includes
00095  */
00096 
00097 /* Detects C & C++ things, such as namespace support */
00098 #include "recls_language.h"
00099 /* Includes platform-specific headers */
00100 #include "recls_platform.h"
00101 /* Includes stddef.h / cstddef, and defines the recls types: recls_s/uint8/16/32/64_t */
00102 #include "recls_compiler.h"
00103 /* Defines recls_filesize_t, recls_time_t */
00104 #include "recls_platform_types.h"
00105 
00106 /* 
00107  * Namespace
00108  */
00109 
00110 #if !defined(RECLS_NO_NAMESPACE)
00111 namespace recls
00112 {
00113 #endif /* !RECLS_NO_NAMESPACE */
00114 
00115 #if !defined(RECLS_NO_NAMESPACE)
00116 #  define RECLS_QUAL(x)                 ::recls::x
00117 #else
00118 # define RECLS_QUAL(x)                  x
00119 #endif /* !RECLS_NO_NAMESPACE */
00120 
00121 /* 
00122  * Constants and definitions
00123  */
00124 
00125 /*** Defines the number of characters in a system root. */
00126 #if defined(RECLS_PLATFORM_IS_WIN32)
00127 # define RECLS_ROOT_NAME_LEN            (3)
00128 #elif defined(RECLS_PLATFORM_IS_UNIX)
00129 # define RECLS_ROOT_NAME_LEN            (1)
00130 #elif defined(RECLS_OVERRIDE_PLATFORM)
00131   /* Assume that the appropriate inclusions are made */
00132 #else
00133 # error Platform not recognised
00134 #endif /* platform */
00135 
00136 /* 
00137  * Pre-processor discrimination
00138  */
00139 
00140 /* 
00141  * Function specifications
00142  */
00143 
00144 /*** Defines the recls linkage and calling convention */
00145 #define RECLS_FNDECL(rt)    RECLS_LINKAGE_C rt RECLS_CALLCONV_DEFAULT
00146 
00147 /* 
00148  * Typedefs
00149  */
00150 
00151 /* recls_rc_t */
00152 #ifdef __cplusplus
00153 
00155 typedef recls_sint32_t                                              recls_rc_t;
00156 
00158 const recls_rc_t                                                    RECLS_RC_OK(0);
00160 const recls_rc_t                                                    RECLS_RC_FAIL(-1);
00161 
00163 inline bool RECLS_FAILED(recls_rc_t const &rc)
00164 {
00165     return rc < 0;
00166 }
00167 
00169 inline bool RECLS_SUCCEEDED(recls_rc_t const &rc)
00170 {
00171     return !RECLS_FAILED(rc);
00172 }
00173 
00174 #else /* ? __cplusplus */
00175 
00177 typedef recls_sint32_t                                              recls_rc_t;
00178 
00180 # define RECLS_RC_OK                                                (0)
00181 
00182 # define RECLS_RC_FAIL                                              (-1)
00183 
00185 # define RECLS_FAILED(rc)                                           ((rc) < 0)
00186 
00187 # define RECLS_SUCCEEDED(rc)                                        (!RECLS_FAILED(rc))
00188 
00189 #endif /* __cplusplus */
00190 
00191 
00192 /* hrecls_t */
00193 #if !defined(RECLS_DOCUMENTATION_SKIP_SECTION) && \
00194     defined(RECLS_COMPILER_IS_BORLAND) && \
00195     __BORLANDC__ < 0x0560
00196 struct hrecls_t_
00197 {
00198     int dummy;
00199 };
00200 #else /* ? compiler */
00201 struct hrecls_t_;
00202 #endif /* compiler */
00203 
00205 typedef struct hrecls_t_ const *                                    hrecls_t;
00206 
00207 
00208 /* 
00209  * Namespace
00210  */
00211 
00212 #if !defined(RECLS_NO_NAMESPACE)
00213 } /* namespace recls */
00214 #endif /* !RECLS_NO_NAMESPACE */
00215 
00216 /* 
00217  * Includes
00218  */
00219 
00220 /* Defines result codes */
00221 #include "recls_retcodes.h"
00222 
00223 /* 
00224  * Namespace
00225  */
00226 
00227 #if !defined(RECLS_NO_NAMESPACE)
00228 namespace recls
00229 {
00230 #endif /* !RECLS_NO_NAMESPACE */
00231 
00232 /* 
00233  * Flags
00234  */
00235 
00243 enum RECLS_FLAG
00244 {
00245         RECLS_F_FILES               =   0x00000001 
00246     ,   RECLS_F_DIRECTORIES         =   0x00000002 
00247     ,   RECLS_F_LINKS               =   0x00000004 
00248     ,   RECLS_F_DEVICES             =   0x00000008 
00249     ,   RECLS_F_TYPEMASK            =   0x00000FFF
00250 #if 0
00251     ,   RECLS_F_DIR_PROGRESS        =   0x00001000 
00252 #endif /* 0 */
00253     ,   RECLS_F_RECURSIVE           =   0x00010000 
00254     ,   RECLS_F_NO_FOLLOW_LINKS     =   0x00020000 
00255     ,   RECLS_F_DIRECTORY_PARTS     =   0x00040000 
00256     ,   RECLS_F_DETAILS_LATER       =   0x00080000 
00257     ,   RECLS_F_PASSIVE_FTP         =   0x00100000 
00258 };
00259 
00260 #if !defined(__cplusplus) && \
00261     !defined(RECLS_DOCUMENTATION_SKIP_SECTION)
00262 typedef enum RECLS_FLAG RECLS_FLAG;
00263 #endif /* !__cplusplus && !RECLS_DOCUMENTATION_SKIP_SECTION */
00264 
00265 /* 
00266  * Typedefs
00267  */
00268 
00271 /* #if defined(RECLS_PLATFORM_IS_WIN32)
00272 # define RECLS_ROOT_NAME_LEN            (3)
00273 #elif defined(RECLS_PLATFORM_IS_UNIX)
00274  */
00275 #ifndef RECLS_COMPILER_IS_CH
00276 typedef struct recls_root
00277 {
00279     recls_char_t    name[1 + RECLS_ROOT_NAME_LEN];
00280 } recls_root_t;
00281 #endif /* !RECLS_COMPILER_IS_CH */
00282 
00283 #ifndef RECLS_COMPILER_IS_CH
00284 struct recls_fileinfo_t;
00285 #endif /* !RECLS_COMPILER_IS_CH */
00286 
00288 typedef struct recls_fileinfo_t const   *recls_info_t;
00289 
00291 typedef void                            *recls_process_fn_param_t;
00292 
00301 typedef int (RECLS_CALLCONV_DEFAULT *hrecls_process_fn_t)(recls_info_t hEntry, recls_process_fn_param_t param);
00302 
00303 /* 
00304  * Namespace typedefs
00305  */
00306 
00307 #if !defined(RECLS_NO_NAMESPACE)
00308 typedef recls_info_t                info_t;
00309 typedef recls_process_fn_param_t    process_fn_param_t;
00310 #endif /* !RECLS_NO_NAMESPACE */
00311 
00312 /* 
00313  * Functions
00314  */
00315 
00316 /***************************************
00317  * File system
00318  */
00319 
00349 #ifndef RECLS_COMPILER_IS_CH
00350 RECLS_FNDECL(size_t)                Recls_GetRoots( recls_root_t    *roots
00351                                                 ,   size_t          cRoots);
00352 #endif /* !RECLS_COMPILER_IS_CH */
00353 
00366 RECLS_FNDECL(recls_char_t const*)   Recls_GetPathNameSeparator(void);
00367 
00380 RECLS_FNDECL(recls_char_t const*)   Recls_GetPathSeparator(void);
00381 
00394 RECLS_FNDECL(recls_char_t const*)   Recls_GetWildcardsAll(void);
00395 
00398 /***************************************
00399  * Search control
00400  */
00401 
00418 RECLS_FNDECL(recls_rc_t) Recls_Search(          recls_char_t const          *searchRoot
00419                                     ,           recls_char_t const          *pattern
00420                                     ,           recls_uint32_t              flags
00421                                     ,           hrecls_t                    *phSrch);
00422 
00434 RECLS_FNDECL(recls_rc_t) Recls_SearchProcess(   recls_char_t const          *searchRoot
00435                                             ,   recls_char_t const          *pattern
00436                                             ,   recls_uint32_t              flags
00437                                             ,   hrecls_process_fn_t         pfn
00438                                             ,   recls_process_fn_param_t    param);
00439 
00444 RECLS_FNDECL(void) Recls_SearchClose(           hrecls_t                    hSrch);
00445 
00446 
00457 RECLS_FNDECL(recls_rc_t) Recls_Stat(            recls_char_t const          *path
00458                                             ,   recls_uint32_t              flags
00459                                             ,   recls_info_t                *phEntry);
00460 
00463 /***************************************
00464  * Search enumeration
00465  */
00466 
00481 RECLS_FNDECL(recls_rc_t) Recls_GetNext(         hrecls_t                    hSrch);
00482 
00492 RECLS_FNDECL(recls_rc_t) Recls_GetDetails(      hrecls_t                    hSrch
00493                                             ,   recls_info_t                *phEntry);
00494 
00503 RECLS_FNDECL(recls_rc_t) Recls_GetNextDetails(  hrecls_t                    hSrch
00504                                             ,   recls_info_t                *phEntry);
00505 
00508 /***************************************
00509  * File entry information
00510  */
00511 
00522 RECLS_FNDECL(void) Recls_CloseDetails(          recls_info_t                hEntry);
00523 
00532 RECLS_FNDECL(recls_rc_t) Recls_CopyDetails(     recls_info_t                hEntry
00533                                             ,   recls_info_t                *phEntry);
00534 
00543 RECLS_FNDECL(recls_rc_t) Recls_OutstandingDetails(hrecls_t                  hSrch
00544                                             ,   recls_uint32_t              *count);
00545 
00548 /***************************************
00549  * Error handling
00550  */
00551 
00563 RECLS_FNDECL(recls_rc_t) Recls_GetLastError(    hrecls_t                    hSrch);
00564 
00572 RECLS_FNDECL(size_t) Recls_GetErrorString(      /* [in] */ recls_rc_t       rc
00573                                     ,           /* [in] */ recls_char_t     *buffer
00574                                     ,           /* [in] */ size_t           cchBuffer);
00575 
00583 RECLS_FNDECL(size_t) Recls_GetLastErrorString(  /* [in] */ hrecls_t         hSrch
00584                                         ,       /* [in] */ recls_char_t     *buffer
00585                                         ,       /* [in] */ size_t           cchBuffer);
00586 
00589 /***************************************
00590  * Property elicitation
00591  */
00592 
00606 RECLS_FNDECL(size_t) Recls_GetPathProperty(     recls_info_t                hEntry
00607                                         ,       recls_char_t                *buffer
00608                                         ,       size_t                      cchBuffer);
00609 
00617 RECLS_FNDECL(size_t) Recls_GetDirectoryProperty(recls_info_t                hEntry
00618                                             ,   recls_char_t                *buffer
00619                                             ,   size_t                      cchBuffer);
00620 
00629 RECLS_FNDECL(size_t) Recls_GetDirectoryPathProperty(    recls_info_t        hEntry
00630                                                     ,   recls_char_t        *buffer
00631                                                     ,   size_t              cchBuffer);
00632 
00641 RECLS_FNDECL(size_t) Recls_GetUNCDriveProperty(         recls_info_t        hEntry
00642                                                     ,   recls_char_t        *buffer
00643                                                     ,   size_t              cchBuffer);
00644 
00652 RECLS_FNDECL(size_t) Recls_GetFileProperty(     recls_info_t                hEntry
00653                                         ,       recls_char_t                *buffer
00654                                         ,       size_t                      cchBuffer);
00655 
00665 RECLS_FNDECL(size_t) Recls_GetShortFileProperty(recls_info_t                hEntry
00666                                             ,   recls_char_t                *buffer
00667                                             ,   size_t                      cchBuffer);
00668 
00676 RECLS_FNDECL(size_t) Recls_GetFileNameProperty( recls_info_t                hEntry
00677                                             ,   recls_char_t                *buffer
00678                                             ,   size_t                      cchBuffer);
00679 
00687 RECLS_FNDECL(size_t) Recls_GetFileExtProperty(  recls_info_t                hEntry
00688                                             ,   recls_char_t                *buffer
00689                                             ,   size_t                      cchBuffer);
00690 
00701 RECLS_FNDECL(size_t) Recls_GetDirectoryPartProperty(recls_info_t            hEntry
00702                                             ,   int                         part
00703                                             ,   recls_char_t                *buffer
00704                                             ,   size_t                      cchBuffer);
00705 
00706 
00715 RECLS_FNDECL(recls_bool_t) Recls_IsFileReadOnly(recls_info_t                hEntry);
00716 
00725 RECLS_FNDECL(recls_bool_t) Recls_IsFileDirectory(recls_info_t               hEntry);
00726 
00735 RECLS_FNDECL(recls_bool_t) Recls_IsFileLink(    recls_info_t                hEntry);
00736 
00745 RECLS_FNDECL(recls_bool_t) Recls_IsFileUNC(     recls_info_t                hEntry);
00746 
00754 RECLS_FNDECL(void)         Recls_GetSizeProperty(   recls_info_t            hEntry
00755                                                 ,   recls_filesize_t        *size);
00756 
00758 RECLS_FNDECL(recls_time_t) Recls_GetCreationTime(recls_info_t               hEntry);
00759 
00761 RECLS_FNDECL(recls_time_t) Recls_GetModificationTime(recls_info_t           hEntry);
00762 
00764 RECLS_FNDECL(recls_time_t) Recls_GetLastAccessTime(recls_info_t             hEntry);
00765 
00767 RECLS_FNDECL(recls_time_t) Recls_GetLastStatusChangeTime(recls_info_t       hEntry);
00768 
00771 /***************************************
00772  * Extended API functions
00773  */
00774 
00781 /* \brief Determines whether the given directory is empty
00782  *
00783  * \param dir The directory to assess
00784  * \note New with recls version 1.4.2
00785  */
00786 RECLS_FNDECL(recls_bool_t) Recls_IsDirectoryEmpty(recls_char_t const        *dir);
00787 
00788 RECLS_FNDECL(recls_bool_t) Recls_IsDirectoryEntryEmpty(recls_info_t         hEntry);
00789 
00790 RECLS_FNDECL(recls_filesize_t) Recls_CalcDirectorySize(recls_char_t const   *dir);
00791 
00792 RECLS_FNDECL(recls_filesize_t) Recls_CalcDirectoryEntrySize(recls_info_t    hEntry);
00793 
00796 /* 
00797  * Namespace
00798  */
00799 
00800 #if !defined(RECLS_NO_NAMESPACE)
00801 } /* namespace recls */
00802 #endif /* !RECLS_NO_NAMESPACE */
00803 
00804 #ifdef __cplusplus
00805 
00806 # ifndef _STLSOFT_NO_NAMESPACE
00807 namespace stlsoft
00808 {
00809 # endif /* !_STLSOFT_NO_NAMESPACE */
00810 
00811 # if defined(RECLS_NO_NAMESPACE)
00812 inline recls_char_t const *c_str_ptr(recls_root_t const &root)
00813 # else /* ? RECLS_NO_NAMESPACE */
00814 inline ::recls::recls_char_t const *c_str_ptr(::recls::recls_root_t const &root)
00815 # endif /* RECLS_NO_NAMESPACE */
00816 {
00817     return root.name;
00818 }
00819 
00820 # ifndef _STLSOFT_NO_NAMESPACE
00821 } /* namespace stlsoft */
00822 # endif /* !_STLSOFT_NO_NAMESPACE */
00823 
00824 #endif /* __cplusplus */
00825 
00826 /* 
00827  * Platform-specific includes
00828  */
00829 
00830 /*** \def RECLS_PLATFORM_API_WIN32 Defined if Win32 platform-specific extensions are in use */
00831 /*** \def RECLS_PLATFORM_API_UNIX Defined if UNIX platform-specific extensions are in use */
00832 
00833 #ifdef RECLS_PLATFORM_API_WIN32
00834 # undef RECLS_PLATFORM_API_WIN32
00835 #endif /* RECLS_PLATFORM_API_WIN32 */
00836 
00837 #ifdef RECLS_PLATFORM_API_UNIX
00838 # undef RECLS_PLATFORM_API_UNIX
00839 #endif /* RECLS_PLATFORM_API_UNIX */
00840 
00841 #if !defined(RECLS_PURE_API)
00842 # if defined(RECLS_PLATFORM_IS_WIN32)
00843 #  include "recls_win32.h"
00844 #  define RECLS_PLATFORM_API_WIN32
00845 # elif defined(RECLS_PLATFORM_IS_UNIX)
00846 #  include "recls_unix.h"
00847 #  define RECLS_PLATFORM_API_UNIX
00848 # else
00849 #  error Platform not recognised
00850 # endif /* platform */
00851 #endif /* !RECLS_PURE_API */
00852 
00853 /* 
00854 
00855 #endif /* !RECLS_INCL_H_RECLS */
00856 
00857 /* 

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