00001 /* 
00002  * File:        recls.h
00003  *
00004  * Purpose:     Main header file for the recls API.
00005  *
00006  * Created:     15th August 2003
00007  * Updated:     24th April 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    8
00065 # define RECLS_VER_H_RECLS_REVISION 3
00066 # define RECLS_VER_H_RECLS_EDIT     32
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  1
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           RECLS_VER_1_4_1
00095 
00096 /* 
00097  * Strictness
00098  */
00099 
00100 #ifndef RECLS_NO_STRICT
00101 # define RECLS_STRICT
00102 #endif /* !RECLS_NO_STRICT */
00103 
00104 /* 
00105  * Includes
00106  */
00107 
00108 /* Detects C & C++ things, such as namespace support */
00109 #include "recls_language.h"
00110 /* Includes platform-specific headers */
00111 #include "recls_platform.h"
00112 /* Includes stddef.h / cstddef, and defines the recls types: recls_s/uint8/16/32/64_t */
00113 #include "recls_compiler.h"
00114 /* Defines recls_filesize_t, recls_time_t */
00115 #include "recls_platform_types.h"
00116 
00117 /* 
00118  * Namespace
00119  */
00120 
00121 #if !defined(RECLS_NO_NAMESPACE)
00122 namespace recls
00123 {
00124 #endif /* !RECLS_NO_NAMESPACE */
00125 
00126 #if !defined(RECLS_NO_NAMESPACE)
00127 # define RECLS_QUAL(x)                  ::recls::x
00128 #else
00129 # define RECLS_QUAL(x)                  x
00130 #endif /* !RECLS_NO_NAMESPACE */
00131 
00132 /* 
00133  * Constants and definitions
00134  */
00135 
00136 /*** Defines the number of characters in a system root. */
00137 #if defined(RECLS_PLATFORM_IS_WIN32)
00138 # define RECLS_ROOT_NAME_LEN            (3)
00139 #elif defined(RECLS_PLATFORM_IS_UNIX)
00140 # define RECLS_ROOT_NAME_LEN            (1)
00141 #else
00142 # error Platform not recognised
00143 #endif /* platform */
00144 
00145 /* 
00146  * Pre-processor discrimination
00147  */
00148 
00149 /* 
00150  * Function specifications
00151  */
00152 
00153 /*** Defines the recls linkage and calling convention */
00154 #define RECLS_FNDECL(rt)    RECLS_LINKAGE_C rt RECLS_CALLCONV_DEFAULT
00155 
00156 /* 
00157  * Typedefs
00158  */
00159 
00160 /* recls_rc_t */
00161 #ifdef __cplusplus
00162 
00164 typedef recls_sint32_t                                              recls_rc_t;
00165 
00167 const recls_rc_t                                                    RECLS_RC_OK(0);
00169 const recls_rc_t                                                    RECLS_RC_FAIL(-1);
00170 
00172 inline bool RECLS_FAILED(recls_rc_t const &rc)
00173 {
00174     return rc < 0;
00175 }
00176 
00178 inline bool RECLS_SUCCEEDED(recls_rc_t const &rc)
00179 {
00180     return !RECLS_FAILED(rc);
00181 }
00182 
00183 #else /* ? __cplusplus */
00184 
00186 typedef recls_sint32_t                                              recls_rc_t;
00187 
00189 # define RECLS_RC_OK                                                (0)
00190 
00191 # define RECLS_RC_FAIL                                              (-1)
00192 
00194 # define RECLS_FAILED(rc)                                           ((rc) < 0)
00195 
00196 # define RECLS_SUCCEEDED(rc)                                        (!RECLS_FAILED(rc))
00197 
00198 #endif /* __cplusplus */
00199 
00200 
00201 /* hrecls_t */
00202 struct hrecls_t_;
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     ,   RECLS_F_RECURSIVE           =   0x00010000 
00250     ,   RECLS_F_NO_FOLLOW_LINKS     =   0x00020000 
00251     ,   RECLS_F_DIRECTORY_PARTS     =   0x00040000 
00252     ,   RECLS_F_DETAILS_LATER       =   0x00080000 
00253 };
00254 
00255 #if !defined(__cplusplus) && \
00256     !defined(RECLS_DOCUMENTATION_SKIP_SECTION)
00257 typedef enum RECLS_FLAG RECLS_FLAG;
00258 #endif /* !__cplusplus && !RECLS_DOCUMENTATION_SKIP_SECTION */
00259 
00260 /* 
00261  * Typedefs
00262  */
00263 
00265 typedef struct recls_root
00266 {
00268     recls_char_t    name[1 + RECLS_ROOT_NAME_LEN];
00269 } recls_root_t;
00270 
00271 struct recls_fileinfo_t;
00272 
00274 typedef struct recls_fileinfo_t const   *recls_info_t;
00275 
00277 typedef void                            *recls_process_fn_param_t;
00278 
00287 typedef int (RECLS_CALLCONV_DEFAULT *hrecls_process_fn_t)(recls_info_t info, recls_process_fn_param_t param);
00288 
00289 /* 
00290  * Namespace typedefs
00291  */
00292 
00293 #if !defined(RECLS_NO_NAMESPACE)
00294 typedef recls_info_t                info_t;
00295 typedef recls_process_fn_param_t    process_fn_param_t;
00296 #endif /* !RECLS_NO_NAMESPACE */
00297 
00298 /* 
00299  * Functions
00300  */
00301 
00302 /***************************************
00303  * File system
00304  */
00305 
00335 RECLS_FNDECL(size_t)                Recls_GetRoots( recls_root_t    *roots
00336                                                 ,   size_t          cRoots);
00337 
00350 RECLS_FNDECL(recls_char_t const*)   Recls_GetPathNameSeparator(void);
00351 
00364 RECLS_FNDECL(recls_char_t const*)   Recls_GetPathSeparator(void);
00365 
00378 RECLS_FNDECL(recls_char_t const*)   Recls_GetWildcardsAll(void);
00379 
00380 
00383 /***************************************
00384  * Search control
00385  */
00386 
00403 RECLS_FNDECL(recls_rc_t) Recls_Search(          recls_char_t const          *searchRoot
00404                                     ,           recls_char_t const          *pattern
00405                                     ,           recls_uint32_t              flags
00406                                     ,           hrecls_t                    *phSrch);
00407 
00419 RECLS_FNDECL(recls_rc_t) Recls_SearchProcess(   recls_char_t const          *searchRoot
00420                                             ,   recls_char_t const          *pattern
00421                                             ,   recls_uint32_t              flags
00422                                             ,   hrecls_process_fn_t         pfn
00423                                             ,   recls_process_fn_param_t    param);
00424 
00429 RECLS_FNDECL(void) Recls_SearchClose(           hrecls_t                    hSrch);
00430 
00433 /***************************************
00434  * Search enumeration
00435  */
00436 
00451 RECLS_FNDECL(recls_rc_t) Recls_GetNext(         hrecls_t                    hSrch);
00452 
00462 RECLS_FNDECL(recls_rc_t) Recls_GetDetails(      hrecls_t                    hSrch
00463                                             ,   recls_info_t                *phEntry);
00464 
00473 RECLS_FNDECL(recls_rc_t) Recls_GetNextDetails(  hrecls_t                    hSrch
00474                                             ,   recls_info_t                *phEntry);
00475 
00478 /***************************************
00479  * File entry info structure
00480  */
00481 
00492 RECLS_FNDECL(void) Recls_CloseDetails(          recls_info_t                hEntry);
00493 
00502 RECLS_FNDECL(recls_rc_t) Recls_CopyDetails(     recls_info_t                hEntry
00503                                             ,   recls_info_t                *phEntry);
00504 
00513 RECLS_FNDECL(recls_rc_t) Recls_OutstandingDetails(hrecls_t                  hSrch
00514                                             ,   recls_uint32_t              *count);
00515 
00518 /***************************************
00519  * Error handling
00520  */
00521 
00533 RECLS_FNDECL(recls_rc_t) Recls_GetLastError(    hrecls_t                    hSrch);
00534 
00542 RECLS_FNDECL(size_t) Recls_GetErrorString(      recls_rc_t                  rc
00543                                     ,           recls_char_t                *buffer
00544                                     ,           size_t                      cchBuffer);
00545 
00553 RECLS_FNDECL(size_t) Recls_GetLastErrorString(  hrecls_t                    hSrch
00554                                         ,       recls_char_t                *buffer
00555                                         ,       size_t                      cchBuffer);
00556 
00559 /***************************************
00560  * Property elicitation
00561  */
00562 
00576 RECLS_FNDECL(size_t) Recls_GetPathProperty(     recls_info_t                hEntry
00577                                         ,       recls_char_t                *buffer
00578                                         ,       size_t                      cchBuffer);
00579 
00587 RECLS_FNDECL(size_t) Recls_GetDirectoryProperty(recls_info_t                hEntry
00588                                             ,   recls_char_t                *buffer
00589                                             ,   size_t                      cchBuffer);
00590 
00599 RECLS_FNDECL(size_t) Recls_GetDirectoryPathProperty(    recls_info_t        hEntry
00600                                                     ,   recls_char_t        *buffer
00601                                                     ,   size_t              cchBuffer);
00602 
00610 RECLS_FNDECL(size_t) Recls_GetFileProperty(     recls_info_t                hEntry
00611                                         ,       recls_char_t                *buffer
00612                                         ,       size_t                      cchBuffer);
00613 
00623 RECLS_FNDECL(size_t) Recls_GetShortFileProperty(recls_info_t                hEntry
00624                                             ,   recls_char_t                *buffer
00625                                             ,   size_t                      cchBuffer);
00626 
00634 RECLS_FNDECL(size_t) Recls_GetFileNameProperty( recls_info_t                hEntry
00635                                             ,   recls_char_t                *buffer
00636                                             ,   size_t                      cchBuffer);
00637 
00645 RECLS_FNDECL(size_t) Recls_GetFileExtProperty(  recls_info_t                hEntry
00646                                             ,   recls_char_t                *buffer
00647                                             ,   size_t                      cchBuffer);
00648 
00659 RECLS_FNDECL(size_t) Recls_GetDirectoryPartProperty(recls_info_t            hEntry
00660                                             ,   int                         part
00661                                             ,   recls_char_t                *buffer
00662                                             ,   size_t                      cchBuffer);
00663 
00664 
00673 RECLS_FNDECL(recls_bool_t) Recls_IsFileReadOnly(recls_info_t                hEntry);
00674 
00683 RECLS_FNDECL(recls_bool_t) Recls_IsFileDirectory(recls_info_t               hEntry);
00684 
00693 RECLS_FNDECL(recls_bool_t) Recls_IsFileLink(    recls_info_t                hEntry);
00694 
00702 RECLS_FNDECL(void)         Recls_GetSizeProperty(   recls_info_t            hEntry
00703                                                 ,   recls_filesize_t        *size);
00704 
00706 RECLS_FNDECL(recls_time_t) Recls_GetCreationTime(recls_info_t               hEntry);
00707 
00709 RECLS_FNDECL(recls_time_t) Recls_GetModificationTime(recls_info_t           hEntry);
00710 
00712 RECLS_FNDECL(recls_time_t) Recls_GetLastAccessTime(recls_info_t             hEntry);
00713 
00715 RECLS_FNDECL(recls_time_t) Recls_GetLastStatusChangeTime(recls_info_t       hEntry);
00716 
00719 /* 
00720  * Namespace
00721  */
00722 
00723 #if !defined(RECLS_NO_NAMESPACE)
00724 } /* namespace recls */
00725 #endif /* !RECLS_NO_NAMESPACE */
00726 
00727 /* 
00728  * Platform-specific includes
00729  */
00730 
00731 /*** \def RECLS_PLATFORM_API_WIN32 Defined if Win32 platform-specific extensions are in use */
00732 /*** \def RECLS_PLATFORM_API_UNIX Defined if UNIX platform-specific extensions are in use */
00733 
00734 #ifdef RECLS_PLATFORM_API_WIN32
00735 # undef RECLS_PLATFORM_API_WIN32
00736 #endif /* RECLS_PLATFORM_API_WIN32 */
00737 
00738 #ifdef RECLS_PLATFORM_API_UNIX
00739 # undef RECLS_PLATFORM_API_UNIX
00740 #endif /* RECLS_PLATFORM_API_UNIX */
00741 
00742 #if !defined(RECLS_PURE_API)
00743 # if defined(RECLS_PLATFORM_IS_WIN32)
00744 #  include "recls_win32.h"
00745 #  define RECLS_PLATFORM_API_WIN32
00746 # elif defined(RECLS_PLATFORM_IS_UNIX)
00747 #  include "recls_unix.h"
00748 #  define RECLS_PLATFORM_API_UNIX
00749 # else
00750 #  error Platform not recognised
00751 # endif /* platform */
00752 #endif /* !RECLS_PURE_API */
00753 
00754 /* 
00755 
00756 #endif /* !RECLS_INCL_H_RECLS */
00757 
00758 /*
/API/include/recls.h
