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:     27th May 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 2
00051 # define RECLS_VER_H_RECLS_EDIT     55
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  3
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_1_6_3     0x01060300
00084 #define RECLS_VER           RECLS_VER_1_6_3
00085 
00086 /* 
00087  * Strictness
00088  */
00089 
00090 #ifndef RECLS_NO_STRICT
00091 # define RECLS_STRICT
00092 #endif /* !RECLS_NO_STRICT */
00093 
00094 /* 
00095  * Includes
00096  */
00097 
00098 /* Detects C & C++ things, such as namespace support */
00099 #include "recls_language.h"
00100 /* Includes platform-specific headers */
00101 #include "recls_platform.h"
00102 /* Includes stddef.h / cstddef, and defines the recls types: recls_s/uint8/16/32/64_t */
00103 #include "recls_compiler.h"
00104 /* Defines recls_filesize_t, recls_time_t */
00105 #include "recls_platform_types.h"
00106 
00107 /* 
00108  * Namespace
00109  */
00110 
00111 #if !defined(RECLS_NO_NAMESPACE)
00112 namespace recls
00113 {
00114 #endif /* !RECLS_NO_NAMESPACE */
00115 
00116 #if !defined(RECLS_NO_NAMESPACE)
00117 #  define RECLS_QUAL(x)                 ::recls::x
00118 #else
00119 # define RECLS_QUAL(x)                  x
00120 #endif /* !RECLS_NO_NAMESPACE */
00121 
00122 /* 
00123  * Constants and definitions
00124  */
00125 
00126 /*** Defines the number of characters in a system root. */
00127 #if defined(RECLS_PLATFORM_IS_WIN32)
00128 # define RECLS_ROOT_NAME_LEN            (3)
00129 #elif defined(RECLS_PLATFORM_IS_UNIX)
00130 # define RECLS_ROOT_NAME_LEN            (1)
00131 #elif defined(RECLS_OVERRIDE_PLATFORM)
00132   /* Assume that the appropriate inclusions are made */
00133 #else
00134 # error Platform not recognised
00135 #endif /* platform */
00136 
00137 /* 
00138  * Pre-processor discrimination
00139  */
00140 
00141 /* 
00142  * Function specifications
00143  */
00144 
00145 /*** Defines the recls linkage and calling convention */
00146 #define RECLS_FNDECL(rt)    RECLS_LINKAGE_C rt RECLS_CALLCONV_DEFAULT
00147 
00148 /* 
00149  * Typedefs
00150  */
00151 
00152 /* recls_rc_t */
00153 #ifdef __cplusplus
00154 
00156 typedef recls_sint32_t                                              recls_rc_t;
00157 
00159 const recls_rc_t                                                    RECLS_RC_OK(0);
00161 const recls_rc_t                                                    RECLS_RC_FAIL(-1);
00162 
00164 inline bool RECLS_FAILED(recls_rc_t const &rc)
00165 {
00166     return rc < 0;
00167 }
00168 
00170 inline bool RECLS_SUCCEEDED(recls_rc_t const &rc)
00171 {
00172     return !RECLS_FAILED(rc);
00173 }
00174 
00175 #else /* ? __cplusplus */
00176 
00178 typedef recls_sint32_t                                              recls_rc_t;
00179 
00181 # define RECLS_RC_OK                                                (0)
00182 
00183 # define RECLS_RC_FAIL                                              (-1)
00184 
00186 # define RECLS_FAILED(rc)                                           ((rc) < 0)
00187 
00188 # define RECLS_SUCCEEDED(rc)                                        (!RECLS_FAILED(rc))
00189 
00190 #endif /* __cplusplus */
00191 
00192 
00193 /* hrecls_t */
00194 #if !defined(RECLS_DOCUMENTATION_SKIP_SECTION) && \
00195     defined(RECLS_COMPILER_IS_BORLAND) && \
00196     __BORLANDC__ < 0x0560
00197 struct hrecls_t_
00198 {
00199     int dummy;
00200 };
00201 #else /* ? compiler */
00202 struct hrecls_t_;
00203 #endif /* compiler */
00204 
00206 typedef struct hrecls_t_ const *                                    hrecls_t;
00207 
00208 
00209 /* 
00210  * Namespace
00211  */
00212 
00213 #if !defined(RECLS_NO_NAMESPACE)
00214 } /* namespace recls */
00215 #endif /* !RECLS_NO_NAMESPACE */
00216 
00217 /* 
00218  * Includes
00219  */
00220 
00221 /* Defines result codes */
00222 #include "recls_retcodes.h"
00223 
00224 /* 
00225  * Namespace
00226  */
00227 
00228 #if !defined(RECLS_NO_NAMESPACE)
00229 namespace recls
00230 {
00231 #endif /* !RECLS_NO_NAMESPACE */
00232 
00233 /* 
00234  * Flags
00235  */
00236 
00244 enum RECLS_FLAG
00245 {
00246         RECLS_F_FILES               =   0x00000001 
00247     ,   RECLS_F_DIRECTORIES         =   0x00000002 
00248     ,   RECLS_F_LINKS               =   0x00000004 
00249     ,   RECLS_F_DEVICES             =   0x00000008 
00250     ,   RECLS_F_TYPEMASK            =   0x00000FFF
00251 #if 0
00252     ,   RECLS_F_DIR_PROGRESS        =   0x00001000 
00253 #endif /* 0 */
00254     ,   RECLS_F_RECURSIVE           =   0x00010000 
00255     ,   RECLS_F_NO_FOLLOW_LINKS     =   0x00020000 
00256     ,   RECLS_F_DIRECTORY_PARTS     =   0x00040000 
00257     ,   RECLS_F_DETAILS_LATER       =   0x00080000 
00258     ,   RECLS_F_PASSIVE_FTP         =   0x00100000 
00259 };
00260 
00261 #if !defined(__cplusplus) && \
00262     !defined(RECLS_DOCUMENTATION_SKIP_SECTION)
00263 typedef enum RECLS_FLAG RECLS_FLAG;
00264 #endif /* !__cplusplus && !RECLS_DOCUMENTATION_SKIP_SECTION */
00265 
00266 /* 
00267  * Typedefs
00268  */
00269 
00272 /* #if defined(RECLS_PLATFORM_IS_WIN32)
00273 # define RECLS_ROOT_NAME_LEN            (3)
00274 #elif defined(RECLS_PLATFORM_IS_UNIX)
00275  */
00276 #ifndef RECLS_COMPILER_IS_CH
00277 typedef struct recls_root
00278 {
00280     recls_char_t    name[1 + RECLS_ROOT_NAME_LEN];
00281 } recls_root_t;
00282 #endif /* !RECLS_COMPILER_IS_CH */
00283 
00284 #ifndef RECLS_COMPILER_IS_CH
00285 struct recls_fileinfo_t;
00286 #endif /* !RECLS_COMPILER_IS_CH */
00287 
00289 typedef struct recls_fileinfo_t const   *recls_info_t;
00290 
00292 typedef void                            *recls_process_fn_param_t;
00293 
00302 typedef int (RECLS_CALLCONV_DEFAULT *hrecls_process_fn_t)(recls_info_t hEntry, recls_process_fn_param_t param);
00303 
00304 /* 
00305  * Namespace typedefs
00306  */
00307 
00308 #if !defined(RECLS_NO_NAMESPACE)
00309 typedef recls_info_t                info_t;
00310 typedef recls_process_fn_param_t    process_fn_param_t;
00311 #endif /* !RECLS_NO_NAMESPACE */
00312 
00313 /* 
00314  * Functions
00315  */
00316 
00317 /***************************************
00318  * File system
00319  */
00320 
00350 #ifndef RECLS_COMPILER_IS_CH
00351 RECLS_FNDECL(size_t)                Recls_GetRoots( recls_root_t    *roots
00352                                                 ,   size_t          cRoots);
00353 #endif /* !RECLS_COMPILER_IS_CH */
00354 
00367 RECLS_FNDECL(recls_char_t const*)   Recls_GetPathNameSeparator(void);
00368 
00381 RECLS_FNDECL(recls_char_t const*)   Recls_GetPathSeparator(void);
00382 
00395 RECLS_FNDECL(recls_char_t const*)   Recls_GetWildcardsAll(void);
00396 
00399 /***************************************
00400  * Search control
00401  */
00402 
00419 RECLS_FNDECL(recls_rc_t) Recls_Search(          recls_char_t const          *searchRoot
00420                                     ,           recls_char_t const          *pattern
00421                                     ,           recls_uint32_t              flags
00422                                     ,           hrecls_t                    *phSrch);
00423 
00435 RECLS_FNDECL(recls_rc_t) Recls_SearchProcess(   recls_char_t const          *searchRoot
00436                                             ,   recls_char_t const          *pattern
00437                                             ,   recls_uint32_t              flags
00438                                             ,   hrecls_process_fn_t         pfn
00439                                             ,   recls_process_fn_param_t    param);
00440 
00445 RECLS_FNDECL(void) Recls_SearchClose(           hrecls_t                    hSrch);
00446 
00447 
00458 RECLS_FNDECL(recls_rc_t) Recls_Stat(            recls_char_t const          *path
00459                                             ,   recls_uint32_t              flags
00460                                             ,   recls_info_t                *phEntry);
00461 
00464 /***************************************
00465  * Search enumeration
00466  */
00467 
00482 RECLS_FNDECL(recls_rc_t) Recls_GetNext(         hrecls_t                    hSrch);
00483 
00493 RECLS_FNDECL(recls_rc_t) Recls_GetDetails(      hrecls_t                    hSrch
00494                                             ,   recls_info_t                *phEntry);
00495 
00504 RECLS_FNDECL(recls_rc_t) Recls_GetNextDetails(  hrecls_t                    hSrch
00505                                             ,   recls_info_t                *phEntry);
00506 
00509 /***************************************
00510  * File entry information
00511  */
00512 
00523 RECLS_FNDECL(void) Recls_CloseDetails(          recls_info_t                hEntry);
00524 
00533 RECLS_FNDECL(recls_rc_t) Recls_CopyDetails(     recls_info_t                hEntry
00534                                             ,   recls_info_t                *phEntry);
00535 
00544 RECLS_FNDECL(recls_rc_t) Recls_OutstandingDetails(hrecls_t                  hSrch
00545                                             ,   recls_uint32_t              *count);
00546 
00549 /***************************************
00550  * Error handling
00551  */
00552 
00564 RECLS_FNDECL(recls_rc_t) Recls_GetLastError(    hrecls_t                    hSrch);
00565 
00573 RECLS_FNDECL(size_t) Recls_GetErrorString(      /* [in] */ recls_rc_t       rc
00574                                     ,           /* [in] */ recls_char_t     *buffer
00575                                     ,           /* [in] */ size_t           cchBuffer);
00576 
00584 RECLS_FNDECL(size_t) Recls_GetLastErrorString(  /* [in] */ hrecls_t         hSrch
00585                                         ,       /* [in] */ recls_char_t     *buffer
00586                                         ,       /* [in] */ size_t           cchBuffer);
00587 
00590 /***************************************
00591  * Property elicitation
00592  */
00593 
00607 RECLS_FNDECL(size_t) Recls_GetPathProperty(     recls_info_t                hEntry
00608                                         ,       recls_char_t                *buffer
00609                                         ,       size_t                      cchBuffer);
00610 
00618 RECLS_FNDECL(size_t) Recls_GetDirectoryProperty(recls_info_t                hEntry
00619                                             ,   recls_char_t                *buffer
00620                                             ,   size_t                      cchBuffer);
00621 
00630 RECLS_FNDECL(size_t) Recls_GetDirectoryPathProperty(    recls_info_t        hEntry
00631                                                     ,   recls_char_t        *buffer
00632                                                     ,   size_t              cchBuffer);
00633 
00642 RECLS_FNDECL(size_t) Recls_GetUNCDriveProperty(         recls_info_t        hEntry
00643                                                     ,   recls_char_t        *buffer
00644                                                     ,   size_t              cchBuffer);
00645 
00653 RECLS_FNDECL(size_t) Recls_GetFileProperty(     recls_info_t                hEntry
00654                                         ,       recls_char_t                *buffer
00655                                         ,       size_t                      cchBuffer);
00656 
00666 RECLS_FNDECL(size_t) Recls_GetShortFileProperty(recls_info_t                hEntry
00667                                             ,   recls_char_t                *buffer
00668                                             ,   size_t                      cchBuffer);
00669 
00677 RECLS_FNDECL(size_t) Recls_GetFileNameProperty( recls_info_t                hEntry
00678                                             ,   recls_char_t                *buffer
00679                                             ,   size_t                      cchBuffer);
00680 
00688 RECLS_FNDECL(size_t) Recls_GetFileExtProperty(  recls_info_t                hEntry
00689                                             ,   recls_char_t                *buffer
00690                                             ,   size_t                      cchBuffer);
00691 
00702 RECLS_FNDECL(size_t) Recls_GetDirectoryPartProperty(recls_info_t            hEntry
00703                                             ,   int                         part
00704                                             ,   recls_char_t                *buffer
00705                                             ,   size_t                      cchBuffer);
00706 
00707 
00716 RECLS_FNDECL(recls_bool_t) Recls_IsFileReadOnly(recls_info_t                hEntry);
00717 
00726 RECLS_FNDECL(recls_bool_t) Recls_IsFileDirectory(recls_info_t               hEntry);
00727 
00736 RECLS_FNDECL(recls_bool_t) Recls_IsFileLink(    recls_info_t                hEntry);
00737 
00746 RECLS_FNDECL(recls_bool_t) Recls_IsFileUNC(     recls_info_t                hEntry);
00747 
00755 RECLS_FNDECL(void)         Recls_GetSizeProperty(   recls_info_t            hEntry
00756                                                 ,   recls_filesize_t        *size);
00757 
00759 RECLS_FNDECL(recls_time_t) Recls_GetCreationTime(recls_info_t               hEntry);
00760 
00762 RECLS_FNDECL(recls_time_t) Recls_GetModificationTime(recls_info_t           hEntry);
00763 
00765 RECLS_FNDECL(recls_time_t) Recls_GetLastAccessTime(recls_info_t             hEntry);
00766 
00768 RECLS_FNDECL(recls_time_t) Recls_GetLastStatusChangeTime(recls_info_t       hEntry);
00769 
00772 /***************************************
00773  * Extended API functions
00774  */
00775 
00782 /* \brief Determines whether the given directory is empty
00783  *
00784  * \param dir The directory to assess
00785  * \note New with recls version 1.4.2
00786  */
00787 RECLS_FNDECL(recls_bool_t) Recls_IsDirectoryEmpty(recls_char_t const        *dir);
00788 
00789 RECLS_FNDECL(recls_bool_t) Recls_IsDirectoryEntryEmpty(recls_info_t         hEntry);
00790 
00791 RECLS_FNDECL(recls_filesize_t) Recls_CalcDirectorySize(recls_char_t const   *dir);
00792 
00793 RECLS_FNDECL(recls_filesize_t) Recls_CalcDirectoryEntrySize(recls_info_t    hEntry);
00794 
00797 /* 
00798  * Namespace
00799  */
00800 
00801 #if !defined(RECLS_NO_NAMESPACE)
00802 } /* namespace recls */
00803 #endif /* !RECLS_NO_NAMESPACE */
00804 
00805 #ifdef __cplusplus
00806 
00807 # ifndef _STLSOFT_NO_NAMESPACE
00808 namespace stlsoft
00809 {
00810 # endif /* !_STLSOFT_NO_NAMESPACE */
00811 
00812 # if defined(RECLS_NO_NAMESPACE)
00813 inline recls_char_t const *c_str_ptr(recls_root_t const &root)
00814 # else /* ? RECLS_NO_NAMESPACE */
00815 inline ::recls::recls_char_t const *c_str_ptr(::recls::recls_root_t const &root)
00816 # endif /* RECLS_NO_NAMESPACE */
00817 {
00818     return root.name;
00819 }
00820 
00821 # ifndef _STLSOFT_NO_NAMESPACE
00822 } /* namespace stlsoft */
00823 # endif /* !_STLSOFT_NO_NAMESPACE */
00824 
00825 #endif /* __cplusplus */
00826 
00827 /* 
00828  * Platform-specific includes
00829  */
00830 
00831 /*** \def RECLS_PLATFORM_API_WIN32 Defined if Win32 platform-specific extensions are in use */
00832 /*** \def RECLS_PLATFORM_API_UNIX Defined if UNIX platform-specific extensions are in use */
00833 
00834 #ifdef RECLS_PLATFORM_API_WIN32
00835 # undef RECLS_PLATFORM_API_WIN32
00836 #endif /* RECLS_PLATFORM_API_WIN32 */
00837 
00838 #ifdef RECLS_PLATFORM_API_UNIX
00839 # undef RECLS_PLATFORM_API_UNIX
00840 #endif /* RECLS_PLATFORM_API_UNIX */
00841 
00842 #if !defined(RECLS_PURE_API)
00843 # if defined(RECLS_PLATFORM_IS_WIN32)
00844 #  include "recls_win32.h"
00845 #  define RECLS_PLATFORM_API_WIN32
00846 # elif defined(RECLS_PLATFORM_IS_UNIX)
00847 #  include "recls_unix.h"
00848 #  define RECLS_PLATFORM_API_UNIX
00849 # else
00850 #  error Platform not recognised
00851 # endif /* platform */
00852 #endif /* !RECLS_PURE_API */
00853 
00854 /* 
00855 
00856 #endif /* !RECLS_INCL_H_RECLS */
00857 
00858 /* 

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