00001 /* 
00002  * File:        recls.h
00003  *
00004  * Purpose:     Main header file for the recls API.
00005  *
00006  * Created:     15th August 2003
00007  * Updated:     8th June 2004
00008  *
00009  * License:     (Licensed under the Synesis Software Standard Source License)
00010  *
00011  *              Copyright (C) 2002-2004, Synesis Software Pty Ltd.
00012  *
00013  *              All rights reserved.
00014  *
00015  *              www:        http://www.synesis.com.au/software
00016  *                          http://www.recls.org/
00017  *
00018  *              email:      submissions@recls.org  for submissions
00019  *                          admin@recls.org        for other enquiries
00020  *
00021  *              Redistribution and use in source and binary forms, with or
00022  *              without modification, are permitted provided that the following
00023  *              conditions are met:
00024  *
00025  *              (i) Redistributions of source code must retain the above
00026  *              copyright notice and contact information, this list of
00027  *              conditions and the following disclaimer.
00028  *
00029  *              (ii) Any derived versions of this software (howsoever modified)
00030  *              remain the sole property of Synesis Software.
00031  *
00032  *              (iii) Any derived versions of this software (howsoever modified)
00033  *              remain subject to all these conditions.
00034  *
00035  *              (iv) Neither the name of Synesis Software nor the names of any
00036  *              subdivisions, employees or agents of Synesis Software, nor the
00037  *              names of any other contributors to this software may be used to
00038  *              endorse or promote products derived from this software without
00039  *              specific prior written permission.
00040  *
00041  *              This source code is provided by Synesis Software "as is" and any
00042  *              warranties, whether expressed or implied, including, but not
00043  *              limited to, the implied warranties of merchantability and
00044  *              fitness for a particular purpose are disclaimed. In no event
00045  *              shall the Synesis Software be liable for any direct, indirect,
00046  *              incidental, special, exemplary, or consequential damages
00047  *              (including, but not limited to, procurement of substitute goods
00048  *              or services; loss of use, data, or profits; or business
00049  *              interruption) however caused and on any theory of liability,
00050  *              whether in contract, strict liability, or tort (including
00051  *              negligence or otherwise) arising in any way out of the use of
00052  *              this software, even if advised of the possibility of such
00053  *              damage.
00054  *
00055  * 
00056 
00057 
00058 #ifndef RECLS_INCL_H_RECLS
00059 #define RECLS_INCL_H_RECLS
00060 
00061 /* File version */
00062 #ifndef RECLS_DOCUMENTATION_SKIP_SECTION
00063 # define RECLS_VER_H_RECLS_MAJOR    1
00064 # define RECLS_VER_H_RECLS_MINOR    11
00065 # define RECLS_VER_H_RECLS_REVISION 5
00066 # define RECLS_VER_H_RECLS_EDIT     42
00067 #endif /* !RECLS_DOCUMENTATION_SKIP_SECTION */
00068 
00085 /* recls version */
00086 #define RECLS_VER_MAJOR     1
00087 #define RECLS_VER_MINOR     4
00088 #define RECLS_VER_REVISION  2
00089 #define RECLS_VER_1_0_1     0x01000100
00090 #define RECLS_VER_1_1_1     0x01010100
00091 #define RECLS_VER_1_2_1     0x01020100
00092 #define RECLS_VER_1_3_1     0x01030100
00093 #define RECLS_VER_1_4_1     0x01040100
00094 #define RECLS_VER_1_4_2     0x01040200
00095 #define RECLS_VER_1_5_1     0x01050100
00096 #define RECLS_VER           RECLS_VER_1_5_1
00097 
00098 /* 
00099  * Strictness
00100  */
00101 
00102 #ifndef RECLS_NO_STRICT
00103 # define RECLS_STRICT
00104 #endif /* !RECLS_NO_STRICT */
00105 
00106 /* 
00107  * Includes
00108  */
00109 
00110 /* Detects C & C++ things, such as namespace support */
00111 #include "recls_language.h"
00112 /* Includes platform-specific headers */
00113 #include "recls_platform.h"
00114 /* Includes stddef.h / cstddef, and defines the recls types: recls_s/uint8/16/32/64_t */
00115 #include "recls_compiler.h"
00116 /* Defines recls_filesize_t, recls_time_t */
00117 #include "recls_platform_types.h"
00118 
00119 /* 
00120  * Namespace
00121  */
00122 
00123 #if !defined(RECLS_NO_NAMESPACE)
00124 namespace recls
00125 {
00126 #endif /* !RECLS_NO_NAMESPACE */
00127 
00128 #if !defined(RECLS_NO_NAMESPACE)
00129 # define RECLS_QUAL(x)                  ::recls::x
00130 #else
00131 # define RECLS_QUAL(x)                  x
00132 #endif /* !RECLS_NO_NAMESPACE */
00133 
00134 /* 
00135  * Constants and definitions
00136  */
00137 
00138 /*** Defines the number of characters in a system root. */
00139 #if defined(RECLS_PLATFORM_IS_WIN32)
00140 # define RECLS_ROOT_NAME_LEN            (3)
00141 #elif defined(RECLS_PLATFORM_IS_UNIX)
00142 # define RECLS_ROOT_NAME_LEN            (1)
00143 #else
00144 # error Platform not recognised
00145 #endif /* platform */
00146 
00147 /* 
00148  * Pre-processor discrimination
00149  */
00150 
00151 /* 
00152  * Function specifications
00153  */
00154 
00155 /*** Defines the recls linkage and calling convention */
00156 #define RECLS_FNDECL(rt)    RECLS_LINKAGE_C rt RECLS_CALLCONV_DEFAULT
00157 
00158 /* 
00159  * Typedefs
00160  */
00161 
00162 /* recls_rc_t */
00163 #ifdef __cplusplus
00164 
00166 typedef recls_sint32_t                                              recls_rc_t;
00167 
00169 const recls_rc_t                                                    RECLS_RC_OK(0);
00171 const recls_rc_t                                                    RECLS_RC_FAIL(-1);
00172 
00174 inline bool RECLS_FAILED(recls_rc_t const &rc)
00175 {
00176     return rc < 0;
00177 }
00178 
00180 inline bool RECLS_SUCCEEDED(recls_rc_t const &rc)
00181 {
00182     return !RECLS_FAILED(rc);
00183 }
00184 
00185 #else /* ? __cplusplus */
00186 
00188 typedef recls_sint32_t                                              recls_rc_t;
00189 
00191 # define RECLS_RC_OK                                                (0)
00192 
00193 # define RECLS_RC_FAIL                                              (-1)
00194 
00196 # define RECLS_FAILED(rc)                                           ((rc) < 0)
00197 
00198 # define RECLS_SUCCEEDED(rc)                                        (!RECLS_FAILED(rc))
00199 
00200 #endif /* __cplusplus */
00201 
00202 
00203 /* hrecls_t */
00204 #if !defined(RECLS_DOCUMENTATION_SKIP_SECTION) && \
00205     defined(RECLS_COMPILER_IS_BORLAND) && \
00206     __BORLANDC__ < 0x0560
00207 struct hrecls_t_
00208 {
00209     int dummy;
00210 };
00211 #else /* ? compiler */
00212 struct hrecls_t_;
00213 #endif /* compiler */
00214 
00216 typedef struct hrecls_t_ const *                                    hrecls_t;
00217 
00218 
00219 /* 
00220  * Namespace
00221  */
00222 
00223 #if !defined(RECLS_NO_NAMESPACE)
00224 } /* namespace recls */
00225 #endif /* !RECLS_NO_NAMESPACE */
00226 
00227 /* 
00228  * Includes
00229  */
00230 
00231 /* Defines result codes */
00232 #include "recls_retcodes.h"
00233 
00234 /* 
00235  * Namespace
00236  */
00237 
00238 #if !defined(RECLS_NO_NAMESPACE)
00239 namespace recls
00240 {
00241 #endif /* !RECLS_NO_NAMESPACE */
00242 
00243 /* 
00244  * Flags
00245  */
00246 
00254 enum RECLS_FLAG
00255 {
00256         RECLS_F_FILES               =   0x00000001 
00257     ,   RECLS_F_DIRECTORIES         =   0x00000002 
00258     ,   RECLS_F_LINKS               =   0x00000004 
00259     ,   RECLS_F_DEVICES             =   0x00000008 
00260     ,   RECLS_F_TYPEMASK            =   0x00000FFF
00261     ,   RECLS_F_RECURSIVE           =   0x00010000 
00262     ,   RECLS_F_NO_FOLLOW_LINKS     =   0x00020000 
00263     ,   RECLS_F_DIRECTORY_PARTS     =   0x00040000 
00264     ,   RECLS_F_DETAILS_LATER       =   0x00080000 
00265     ,   RECLS_F_PASSIVE_FTP         =   0x00100000 
00266 };
00267 
00268 #if !defined(__cplusplus) && \
00269     !defined(RECLS_DOCUMENTATION_SKIP_SECTION)
00270 typedef enum RECLS_FLAG RECLS_FLAG;
00271 #endif /* !__cplusplus && !RECLS_DOCUMENTATION_SKIP_SECTION */
00272 
00273 /* 
00274  * Typedefs
00275  */
00276 
00278 typedef struct recls_root
00279 {
00281     recls_char_t    name[1 + RECLS_ROOT_NAME_LEN];
00282 } recls_root_t;
00283 
00284 struct recls_fileinfo_t;
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 RECLS_FNDECL(size_t)                Recls_GetRoots( recls_root_t    *roots
00349                                                 ,   size_t          cRoots);
00350 
00363 RECLS_FNDECL(recls_char_t const*)   Recls_GetPathNameSeparator(void);
00364 
00377 RECLS_FNDECL(recls_char_t const*)   Recls_GetPathSeparator(void);
00378 
00391 RECLS_FNDECL(recls_char_t const*)   Recls_GetWildcardsAll(void);
00392 
00395 /***************************************
00396  * Search control
00397  */
00398 
00415 RECLS_FNDECL(recls_rc_t) Recls_Search(          recls_char_t const          *searchRoot
00416                                     ,           recls_char_t const          *pattern
00417                                     ,           recls_uint32_t              flags
00418                                     ,           hrecls_t                    *phSrch);
00419 
00431 RECLS_FNDECL(recls_rc_t) Recls_SearchProcess(   recls_char_t const          *searchRoot
00432                                             ,   recls_char_t const          *pattern
00433                                             ,   recls_uint32_t              flags
00434                                             ,   hrecls_process_fn_t         pfn
00435                                             ,   recls_process_fn_param_t    param);
00436 
00441 RECLS_FNDECL(void) Recls_SearchClose(           hrecls_t                    hSrch);
00442 
00445 /***************************************
00446  * Search enumeration
00447  */
00448 
00463 RECLS_FNDECL(recls_rc_t) Recls_GetNext(         hrecls_t                    hSrch);
00464 
00474 RECLS_FNDECL(recls_rc_t) Recls_GetDetails(      hrecls_t                    hSrch
00475                                             ,   recls_info_t                *phEntry);
00476 
00485 RECLS_FNDECL(recls_rc_t) Recls_GetNextDetails(  hrecls_t                    hSrch
00486                                             ,   recls_info_t                *phEntry);
00487 
00490 /***************************************
00491  * File entry information
00492  */
00493 
00504 RECLS_FNDECL(void) Recls_CloseDetails(          recls_info_t                hEntry);
00505 
00514 RECLS_FNDECL(recls_rc_t) Recls_CopyDetails(     recls_info_t                hEntry
00515                                             ,   recls_info_t                *phEntry);
00516 
00525 RECLS_FNDECL(recls_rc_t) Recls_OutstandingDetails(hrecls_t                  hSrch
00526                                             ,   recls_uint32_t              *count);
00527 
00530 /***************************************
00531  * Error handling
00532  */
00533 
00545 RECLS_FNDECL(recls_rc_t) Recls_GetLastError(    hrecls_t                    hSrch);
00546 
00554 RECLS_FNDECL(size_t) Recls_GetErrorString(      recls_rc_t                  rc
00555                                     ,           recls_char_t                *buffer
00556                                     ,           size_t                      cchBuffer);
00557 
00565 RECLS_FNDECL(size_t) Recls_GetLastErrorString(  hrecls_t                    hSrch
00566                                         ,       recls_char_t                *buffer
00567                                         ,       size_t                      cchBuffer);
00568 
00571 /***************************************
00572  * Property elicitation
00573  */
00574 
00588 RECLS_FNDECL(size_t) Recls_GetPathProperty(     recls_info_t                hEntry
00589                                         ,       recls_char_t                *buffer
00590                                         ,       size_t                      cchBuffer);
00591 
00599 RECLS_FNDECL(size_t) Recls_GetDirectoryProperty(recls_info_t                hEntry
00600                                             ,   recls_char_t                *buffer
00601                                             ,   size_t                      cchBuffer);
00602 
00611 RECLS_FNDECL(size_t) Recls_GetDirectoryPathProperty(    recls_info_t        hEntry
00612                                                     ,   recls_char_t        *buffer
00613                                                     ,   size_t              cchBuffer);
00614 
00622 RECLS_FNDECL(size_t) Recls_GetFileProperty(     recls_info_t                hEntry
00623                                         ,       recls_char_t                *buffer
00624                                         ,       size_t                      cchBuffer);
00625 
00635 RECLS_FNDECL(size_t) Recls_GetShortFileProperty(recls_info_t                hEntry
00636                                             ,   recls_char_t                *buffer
00637                                             ,   size_t                      cchBuffer);
00638 
00646 RECLS_FNDECL(size_t) Recls_GetFileNameProperty( recls_info_t                hEntry
00647                                             ,   recls_char_t                *buffer
00648                                             ,   size_t                      cchBuffer);
00649 
00657 RECLS_FNDECL(size_t) Recls_GetFileExtProperty(  recls_info_t                hEntry
00658                                             ,   recls_char_t                *buffer
00659                                             ,   size_t                      cchBuffer);
00660 
00671 RECLS_FNDECL(size_t) Recls_GetDirectoryPartProperty(recls_info_t            hEntry
00672                                             ,   int                         part
00673                                             ,   recls_char_t                *buffer
00674                                             ,   size_t                      cchBuffer);
00675 
00676 
00685 RECLS_FNDECL(recls_bool_t) Recls_IsFileReadOnly(recls_info_t                hEntry);
00686 
00695 RECLS_FNDECL(recls_bool_t) Recls_IsFileDirectory(recls_info_t               hEntry);
00696 
00705 RECLS_FNDECL(recls_bool_t) Recls_IsFileLink(    recls_info_t                hEntry);
00706 
00714 RECLS_FNDECL(void)         Recls_GetSizeProperty(   recls_info_t            hEntry
00715                                                 ,   recls_filesize_t        *size);
00716 
00718 RECLS_FNDECL(recls_time_t) Recls_GetCreationTime(recls_info_t               hEntry);
00719 
00721 RECLS_FNDECL(recls_time_t) Recls_GetModificationTime(recls_info_t           hEntry);
00722 
00724 RECLS_FNDECL(recls_time_t) Recls_GetLastAccessTime(recls_info_t             hEntry);
00725 
00727 RECLS_FNDECL(recls_time_t) Recls_GetLastStatusChangeTime(recls_info_t       hEntry);
00728 
00731 /***************************************
00732  * Extended API functions
00733  */
00734 
00741 /* \brief Determines whether the given directory is empty
00742  *
00743  * \param dir The directory to assess
00744  * \note New with recls version 1.4.2
00745  */
00746 RECLS_FNDECL(recls_bool_t) Recls_IsDirectoryEmpty(recls_char_t const        *dir);
00747 
00748 RECLS_FNDECL(recls_bool_t) Recls_IsDirectoryEntryEmpty(recls_info_t         hEntry);
00749 
00750 RECLS_FNDECL(recls_filesize_t) Recls_CalcDirectorySize(recls_char_t const   *dir);
00751 
00752 RECLS_FNDECL(recls_filesize_t) Recls_CalcDirectoryEntrySize(recls_info_t    hEntry);
00753 
00756 /* 
00757  * Namespace
00758  */
00759 
00760 #if !defined(RECLS_NO_NAMESPACE)
00761 } /* namespace recls */
00762 #endif /* !RECLS_NO_NAMESPACE */
00763 
00764 /* 
00765  * Platform-specific includes
00766  */
00767 
00768 /*** \def RECLS_PLATFORM_API_WIN32 Defined if Win32 platform-specific extensions are in use */
00769 /*** \def RECLS_PLATFORM_API_UNIX Defined if UNIX platform-specific extensions are in use */
00770 
00771 #ifdef RECLS_PLATFORM_API_WIN32
00772 # undef RECLS_PLATFORM_API_WIN32
00773 #endif /* RECLS_PLATFORM_API_WIN32 */
00774 
00775 #ifdef RECLS_PLATFORM_API_UNIX
00776 # undef RECLS_PLATFORM_API_UNIX
00777 #endif /* RECLS_PLATFORM_API_UNIX */
00778 
00779 #if !defined(RECLS_PURE_API)
00780 # if defined(RECLS_PLATFORM_IS_WIN32)
00781 #  include "recls_win32.h"
00782 #  define RECLS_PLATFORM_API_WIN32
00783 # elif defined(RECLS_PLATFORM_IS_UNIX)
00784 #  include "recls_unix.h"
00785 #  define RECLS_PLATFORM_API_UNIX
00786 # else
00787 #  error Platform not recognised
00788 # endif /* platform */
00789 #endif /* !RECLS_PURE_API */
00790 
00791 /* 
00792 
00793 #endif /* !RECLS_INCL_H_RECLS */
00794 
00795 /*
/API/include/recls.h
