00001 /* 
00002  * File:        recls.h
00003  *
00004  * Purpose:     Main header file for the recls API.
00005  *
00006  * Created:     15th August 2003
00007  * Updated:     16th 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    3
00050 # define RECLS_VER_H_RECLS_REVISION 2
00051 # define RECLS_VER_H_RECLS_EDIT     53
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  1
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           RECLS_VER_1_6_1
00083 
00084 /* 
00085  * Strictness
00086  */
00087 
00088 #ifndef RECLS_NO_STRICT
00089 # define RECLS_STRICT
00090 #endif /* !RECLS_NO_STRICT */
00091 
00092 /* 
00093  * Includes
00094  */
00095 
00096 /* Detects C & C++ things, such as namespace support */
00097 #include "recls_language.h"
00098 /* Includes platform-specific headers */
00099 #include "recls_platform.h"
00100 /* Includes stddef.h / cstddef, and defines the recls types: recls_s/uint8/16/32/64_t */
00101 #include "recls_compiler.h"
00102 /* Defines recls_filesize_t, recls_time_t */
00103 #include "recls_platform_types.h"
00104 
00105 /* 
00106  * Namespace
00107  */
00108 
00109 #if !defined(RECLS_NO_NAMESPACE)
00110 namespace recls
00111 {
00112 #endif /* !RECLS_NO_NAMESPACE */
00113 
00114 #if !defined(RECLS_NO_NAMESPACE)
00115 # define RECLS_QUAL(x)                  ::recls::x
00116 #else
00117 # define RECLS_QUAL(x)                  x
00118 #endif /* !RECLS_NO_NAMESPACE */
00119 
00120 /* 
00121  * Constants and definitions
00122  */
00123 
00124 /*** Defines the number of characters in a system root. */
00125 #if defined(RECLS_PLATFORM_IS_WIN32)
00126 # define RECLS_ROOT_NAME_LEN            (3)
00127 #elif defined(RECLS_PLATFORM_IS_UNIX)
00128 # define RECLS_ROOT_NAME_LEN            (1)
00129 #elif defined(RECLS_OVERRIDE_PLATFORM)
00130   /* Assume that the appropriate inclusions are made */
00131 #else
00132 # error Platform not recognised
00133 #endif /* platform */
00134 
00135 /* 
00136  * Pre-processor discrimination
00137  */
00138 
00139 /* 
00140  * Function specifications
00141  */
00142 
00143 /*** Defines the recls linkage and calling convention */
00144 #define RECLS_FNDECL(rt)    RECLS_LINKAGE_C rt RECLS_CALLCONV_DEFAULT
00145 
00146 /* 
00147  * Typedefs
00148  */
00149 
00150 /* recls_rc_t */
00151 #ifdef __cplusplus
00152 
00154 typedef recls_sint32_t                                              recls_rc_t;
00155 
00157 const recls_rc_t                                                    RECLS_RC_OK(0);
00159 const recls_rc_t                                                    RECLS_RC_FAIL(-1);
00160 
00162 inline bool RECLS_FAILED(recls_rc_t const &rc)
00163 {
00164     return rc < 0;
00165 }
00166 
00168 inline bool RECLS_SUCCEEDED(recls_rc_t const &rc)
00169 {
00170     return !RECLS_FAILED(rc);
00171 }
00172 
00173 #else /* ? __cplusplus */
00174 
00176 typedef recls_sint32_t                                              recls_rc_t;
00177 
00179 # define RECLS_RC_OK                                                (0)
00180 
00181 # define RECLS_RC_FAIL                                              (-1)
00182 
00184 # define RECLS_FAILED(rc)                                           ((rc) < 0)
00185 
00186 # define RECLS_SUCCEEDED(rc)                                        (!RECLS_FAILED(rc))
00187 
00188 #endif /* __cplusplus */
00189 
00190 
00191 /* hrecls_t */
00192 #if !defined(RECLS_DOCUMENTATION_SKIP_SECTION) && \
00193     defined(RECLS_COMPILER_IS_BORLAND) && \
00194     __BORLANDC__ < 0x0560
00195 struct hrecls_t_
00196 {
00197     int dummy;
00198 };
00199 #else /* ? compiler */
00200 struct hrecls_t_;
00201 #endif /* compiler */
00202 
00204 typedef struct hrecls_t_ const *                                    hrecls_t;
00205 
00206 
00207 /* 
00208  * Namespace
00209  */
00210 
00211 #if !defined(RECLS_NO_NAMESPACE)
00212 } /* namespace recls */
00213 #endif /* !RECLS_NO_NAMESPACE */
00214 
00215 /* 
00216  * Includes
00217  */
00218 
00219 /* Defines result codes */
00220 #include "recls_retcodes.h"
00221 
00222 /* 
00223  * Namespace
00224  */
00225 
00226 #if !defined(RECLS_NO_NAMESPACE)
00227 namespace recls
00228 {
00229 #endif /* !RECLS_NO_NAMESPACE */
00230 
00231 /* 
00232  * Flags
00233  */
00234 
00242 enum RECLS_FLAG
00243 {
00244         RECLS_F_FILES               =   0x00000001 
00245     ,   RECLS_F_DIRECTORIES         =   0x00000002 
00246     ,   RECLS_F_LINKS               =   0x00000004 
00247     ,   RECLS_F_DEVICES             =   0x00000008 
00248     ,   RECLS_F_TYPEMASK            =   0x00000FFF
00249 #if 0
00250     ,   RECLS_F_DIR_PROGRESS        =   0x00001000 
00251 #endif /* 0 */
00252     ,   RECLS_F_RECURSIVE           =   0x00010000 
00253     ,   RECLS_F_NO_FOLLOW_LINKS     =   0x00020000 
00254     ,   RECLS_F_DIRECTORY_PARTS     =   0x00040000 
00255     ,   RECLS_F_DETAILS_LATER       =   0x00080000 
00256     ,   RECLS_F_PASSIVE_FTP         =   0x00100000 
00257 };
00258 
00259 #if !defined(__cplusplus) && \
00260     !defined(RECLS_DOCUMENTATION_SKIP_SECTION)
00261 typedef enum RECLS_FLAG RECLS_FLAG;
00262 #endif /* !__cplusplus && !RECLS_DOCUMENTATION_SKIP_SECTION */
00263 
00264 /* 
00265  * Typedefs
00266  */
00267 
00270 /* #if defined(RECLS_PLATFORM_IS_WIN32)
00271 # define RECLS_ROOT_NAME_LEN            (3)
00272 #elif defined(RECLS_PLATFORM_IS_UNIX)
00273  */
00274 #ifndef RECLS_COMPILER_IS_CH
00275 typedef struct recls_root
00276 {
00278     recls_char_t    name[1 + RECLS_ROOT_NAME_LEN];
00279 } recls_root_t;
00280 #endif /* !RECLS_COMPILER_IS_CH */
00281 
00282 #ifndef RECLS_COMPILER_IS_CH
00283 struct recls_fileinfo_t;
00284 #endif /* !RECLS_COMPILER_IS_CH */
00285 
00287 typedef struct recls_fileinfo_t const   *recls_info_t;
00288 
00290 typedef void                            *recls_process_fn_param_t;
00291 
00300 typedef int (RECLS_CALLCONV_DEFAULT *hrecls_process_fn_t)(recls_info_t hEntry, recls_process_fn_param_t param);
00301 
00302 /* 
00303  * Namespace typedefs
00304  */
00305 
00306 #if !defined(RECLS_NO_NAMESPACE)
00307 typedef recls_info_t                info_t;
00308 typedef recls_process_fn_param_t    process_fn_param_t;
00309 #endif /* !RECLS_NO_NAMESPACE */
00310 
00311 /* 
00312  * Functions
00313  */
00314 
00315 /***************************************
00316  * File system
00317  */
00318 
00348 #ifndef RECLS_COMPILER_IS_CH
00349 RECLS_FNDECL(size_t)                Recls_GetRoots( recls_root_t    *roots
00350                                                 ,   size_t          cRoots);
00351 #endif /* !RECLS_COMPILER_IS_CH */
00352 
00365 RECLS_FNDECL(recls_char_t const*)   Recls_GetPathNameSeparator(void);
00366 
00379 RECLS_FNDECL(recls_char_t const*)   Recls_GetPathSeparator(void);
00380 
00393 RECLS_FNDECL(recls_char_t const*)   Recls_GetWildcardsAll(void);
00394 
00397 /***************************************
00398  * Search control
00399  */
00400 
00417 RECLS_FNDECL(recls_rc_t) Recls_Search(          recls_char_t const          *searchRoot
00418                                     ,           recls_char_t const          *pattern
00419                                     ,           recls_uint32_t              flags
00420                                     ,           hrecls_t                    *phSrch);
00421 
00433 RECLS_FNDECL(recls_rc_t) Recls_SearchProcess(   recls_char_t const          *searchRoot
00434                                             ,   recls_char_t const          *pattern
00435                                             ,   recls_uint32_t              flags
00436                                             ,   hrecls_process_fn_t         pfn
00437                                             ,   recls_process_fn_param_t    param);
00438 
00443 RECLS_FNDECL(void) Recls_SearchClose(           hrecls_t                    hSrch);
00444 
00445 
00456 RECLS_FNDECL(recls_rc_t) Recls_Stat(            recls_char_t const          *path
00457                                             ,   recls_uint32_t              flags
00458                                             ,   recls_info_t                *phEntry);
00459 
00462 /***************************************
00463  * Search enumeration
00464  */
00465 
00480 RECLS_FNDECL(recls_rc_t) Recls_GetNext(         hrecls_t                    hSrch);
00481 
00491 RECLS_FNDECL(recls_rc_t) Recls_GetDetails(      hrecls_t                    hSrch
00492                                             ,   recls_info_t                *phEntry);
00493 
00502 RECLS_FNDECL(recls_rc_t) Recls_GetNextDetails(  hrecls_t                    hSrch
00503                                             ,   recls_info_t                *phEntry);
00504 
00507 /***************************************
00508  * File entry information
00509  */
00510 
00521 RECLS_FNDECL(void) Recls_CloseDetails(          recls_info_t                hEntry);
00522 
00531 RECLS_FNDECL(recls_rc_t) Recls_CopyDetails(     recls_info_t                hEntry
00532                                             ,   recls_info_t                *phEntry);
00533 
00542 RECLS_FNDECL(recls_rc_t) Recls_OutstandingDetails(hrecls_t                  hSrch
00543                                             ,   recls_uint32_t              *count);
00544 
00547 /***************************************
00548  * Error handling
00549  */
00550 
00562 RECLS_FNDECL(recls_rc_t) Recls_GetLastError(    hrecls_t                    hSrch);
00563 
00571 RECLS_FNDECL(size_t) Recls_GetErrorString(      /* [in] */ recls_rc_t       rc
00572                                     ,           /* [in] */ recls_char_t     *buffer
00573                                     ,           /* [in] */ size_t           cchBuffer);
00574 
00582 RECLS_FNDECL(size_t) Recls_GetLastErrorString(  /* [in] */ hrecls_t         hSrch
00583                                         ,       /* [in] */ recls_char_t     *buffer
00584                                         ,       /* [in] */ size_t           cchBuffer);
00585 
00588 /***************************************
00589  * Property elicitation
00590  */
00591 
00605 RECLS_FNDECL(size_t) Recls_GetPathProperty(     recls_info_t                hEntry
00606                                         ,       recls_char_t                *buffer
00607                                         ,       size_t                      cchBuffer);
00608 
00616 RECLS_FNDECL(size_t) Recls_GetDirectoryProperty(recls_info_t                hEntry
00617                                             ,   recls_char_t                *buffer
00618                                             ,   size_t                      cchBuffer);
00619 
00628 RECLS_FNDECL(size_t) Recls_GetDirectoryPathProperty(    recls_info_t        hEntry
00629                                                     ,   recls_char_t        *buffer
00630                                                     ,   size_t              cchBuffer);
00631 
00640 RECLS_FNDECL(size_t) Recls_GetUNCDriveProperty(         recls_info_t        hEntry
00641                                                     ,   recls_char_t        *buffer
00642                                                     ,   size_t              cchBuffer);
00643 
00651 RECLS_FNDECL(size_t) Recls_GetFileProperty(     recls_info_t                hEntry
00652                                         ,       recls_char_t                *buffer
00653                                         ,       size_t                      cchBuffer);
00654 
00664 RECLS_FNDECL(size_t) Recls_GetShortFileProperty(recls_info_t                hEntry
00665                                             ,   recls_char_t                *buffer
00666                                             ,   size_t                      cchBuffer);
00667 
00675 RECLS_FNDECL(size_t) Recls_GetFileNameProperty( recls_info_t                hEntry
00676                                             ,   recls_char_t                *buffer
00677                                             ,   size_t                      cchBuffer);
00678 
00686 RECLS_FNDECL(size_t) Recls_GetFileExtProperty(  recls_info_t                hEntry
00687                                             ,   recls_char_t                *buffer
00688                                             ,   size_t                      cchBuffer);
00689 
00700 RECLS_FNDECL(size_t) Recls_GetDirectoryPartProperty(recls_info_t            hEntry
00701                                             ,   int                         part
00702                                             ,   recls_char_t                *buffer
00703                                             ,   size_t                      cchBuffer);
00704 
00705 
00714 RECLS_FNDECL(recls_bool_t) Recls_IsFileReadOnly(recls_info_t                hEntry);
00715 
00724 RECLS_FNDECL(recls_bool_t) Recls_IsFileDirectory(recls_info_t               hEntry);
00725 
00734 RECLS_FNDECL(recls_bool_t) Recls_IsFileLink(    recls_info_t                hEntry);
00735 
00744 RECLS_FNDECL(recls_bool_t) Recls_IsFileUNC(     recls_info_t                hEntry);
00745 
00753 RECLS_FNDECL(void)         Recls_GetSizeProperty(   recls_info_t            hEntry
00754                                                 ,   recls_filesize_t        *size);
00755 
00757 RECLS_FNDECL(recls_time_t) Recls_GetCreationTime(recls_info_t               hEntry);
00758 
00760 RECLS_FNDECL(recls_time_t) Recls_GetModificationTime(recls_info_t           hEntry);
00761 
00763 RECLS_FNDECL(recls_time_t) Recls_GetLastAccessTime(recls_info_t             hEntry);
00764 
00766 RECLS_FNDECL(recls_time_t) Recls_GetLastStatusChangeTime(recls_info_t       hEntry);
00767 
00770 /***************************************
00771  * Extended API functions
00772  */
00773 
00780 /* \brief Determines whether the given directory is empty
00781  *
00782  * \param dir The directory to assess
00783  * \note New with recls version 1.4.2
00784  */
00785 RECLS_FNDECL(recls_bool_t) Recls_IsDirectoryEmpty(recls_char_t const        *dir);
00786 
00787 RECLS_FNDECL(recls_bool_t) Recls_IsDirectoryEntryEmpty(recls_info_t         hEntry);
00788 
00789 RECLS_FNDECL(recls_filesize_t) Recls_CalcDirectorySize(recls_char_t const   *dir);
00790 
00791 RECLS_FNDECL(recls_filesize_t) Recls_CalcDirectoryEntrySize(recls_info_t    hEntry);
00792 
00795 /* 
00796  * Namespace
00797  */
00798 
00799 #if !defined(RECLS_NO_NAMESPACE)
00800 } /* namespace recls */
00801 #endif /* !RECLS_NO_NAMESPACE */
00802 
00803 #ifdef __cplusplus
00804 
00805 # ifndef _STLSOFT_NO_NAMESPACE
00806 namespace stlsoft
00807 {
00808 # endif /* !_STLSOFT_NO_NAMESPACE */
00809 
00810 # if defined(RECLS_NO_NAMESPACE)
00811 inline recls_char_t const *c_str_ptr(recls_root_t const &root)
00812 # else /* ? RECLS_NO_NAMESPACE */
00813 inline ::recls::recls_char_t const *c_str_ptr(::recls::recls_root_t const &root)
00814 # endif /* RECLS_NO_NAMESPACE */
00815 {
00816     return root.name;
00817 }
00818 
00819 # ifndef _STLSOFT_NO_NAMESPACE
00820 } /* namespace stlsoft */
00821 # endif /* !_STLSOFT_NO_NAMESPACE */
00822 
00823 #endif /* __cplusplus */
00824 
00825 /* 
00826  * Platform-specific includes
00827  */
00828 
00829 /*** \def RECLS_PLATFORM_API_WIN32 Defined if Win32 platform-specific extensions are in use */
00830 /*** \def RECLS_PLATFORM_API_UNIX Defined if UNIX platform-specific extensions are in use */
00831 
00832 #ifdef RECLS_PLATFORM_API_WIN32
00833 # undef RECLS_PLATFORM_API_WIN32
00834 #endif /* RECLS_PLATFORM_API_WIN32 */
00835 
00836 #ifdef RECLS_PLATFORM_API_UNIX
00837 # undef RECLS_PLATFORM_API_UNIX
00838 #endif /* RECLS_PLATFORM_API_UNIX */
00839 
00840 #if !defined(RECLS_PURE_API)
00841 # if defined(RECLS_PLATFORM_IS_WIN32)
00842 #  include "recls_win32.h"
00843 #  define RECLS_PLATFORM_API_WIN32
00844 # elif defined(RECLS_PLATFORM_IS_UNIX)
00845 #  include "recls_unix.h"
00846 #  define RECLS_PLATFORM_API_UNIX
00847 # else
00848 #  error Platform not recognised
00849 # endif /* platform */
00850 #endif /* !RECLS_PURE_API */
00851 
00852 /* 
00853 
00854 #endif /* !RECLS_INCL_H_RECLS */
00855 
00856 /*
/include/recls.h
