00001 /* 
00002  * File:        recls.h
00003  *
00004  * Purpose:     Main header file for the recls API.
00005  *
00006  * Created:     15th August 2003
00007  * Updated:     21st November 2003
00008  *
00009  * License:     (Licensed under the Synesis Software Standard Source License)
00010  *
00011  *              Copyright (C) 2002-2003, 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    5
00065 # define RECLS_VER_H_RECLS_REVISION 2
00066 # define RECLS_VER_H_RECLS_EDIT     24
00067 #endif /* !RECLS_DOCUMENTATION_SKIP_SECTION */
00068 
00085 /* recls version */
00086 #define RECLS_VER_MAJOR     1
00087 #define RECLS_VER_MINOR     2
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           RECLS_VER_1_2_1
00093 
00094 /* 
00095  * Strictness
00096  */
00097 
00098 #ifndef RECLS_NO_STRICT
00099 # define RECLS_STRICT
00100 #endif /* !RECLS_NO_STRICT */
00101 
00102 /* 
00103  * Includes
00104  */
00105 
00106 /* Detects C & C++ things, such as namespace support */
00107 #include "recls_language.h"
00108 /* Includes platform-specific headers */
00109 #include "recls_platform.h"
00110 /* Includes stddef.h / cstddef, and defines the recls types: recls_s/uint8/16/32/64_t */
00111 #include "recls_compiler.h"
00112 /* Defines recls_filesize_t, recls_time_t */
00113 #include "recls_platform_types.h"
00114 
00115 /* 
00116  * Namespace
00117  */
00118 
00119 #if !defined(RECLS_NO_NAMESPACE)
00120 namespace recls
00121 {
00122 #endif /* !RECLS_NO_NAMESPACE */
00123 
00124 #if !defined(RECLS_NO_NAMESPACE)
00125 # define RECLS_QUAL(x)                  ::recls::x
00126 #else
00127 # define RECLS_QUAL(x)                  x
00128 #endif /* !RECLS_NO_NAMESPACE */
00129 
00130 /* 
00131  * Pre-processor discrimination
00132  */
00133 
00134 /* 
00135  * Function specifications
00136  */
00137 
00138 /*** Defines the recls linkage and calling convention */
00139 #define RECLS_FNDECL(rt)    RECLS_LINKAGE_C rt RECLS_CALLCONV_DEFAULT
00140 
00141 /* 
00142  * Typedefs
00143  */
00144 
00145 /* recls_rc_t */
00146 #ifdef __cplusplus
00147 
00149 typedef recls_sint32_t                                              recls_rc_t;
00150 
00152 const recls_rc_t                                                    RECLS_RC_OK(0);
00154 const recls_rc_t                                                    RECLS_RC_FAIL(-1);
00155 
00157 inline bool RECLS_FAILED(recls_rc_t const &rc)
00158 {
00159     return rc < 0;
00160 }
00161 
00163 inline bool RECLS_SUCCEEDED(recls_rc_t const &rc)
00164 {
00165     return !RECLS_FAILED(rc);
00166 }
00167 
00168 #else /* ? __cplusplus */
00169 
00171 typedef recls_sint32_t                                              recls_rc_t;
00172 
00174 #define RECLS_RC_OK                                                 (0)
00175 
00176 #define RECLS_RC_FAIL                                               (-1)
00177 
00179 #define RECLS_FAILED(rc)                                            ((rc) < 0)
00180 
00181 #define RECLS_SUCCEEDED(rc)                                         (!FAILED(rc))
00182 
00183 #endif /* __cplusplus */
00184 
00185 
00186 /* hrecls_t */
00187 struct hrecls_t_;
00189 typedef struct hrecls_t_ const *                                    hrecls_t;
00190 
00191 
00192 /* 
00193  * Namespace
00194  */
00195 
00196 #if !defined(RECLS_NO_NAMESPACE)
00197 } /* namespace recls */
00198 #endif /* !RECLS_NO_NAMESPACE */
00199 
00200 /* 
00201  * Includes
00202  */
00203 
00204 /* Defines result codes */
00205 #include "recls_retcodes.h"
00206 
00207 /* 
00208  * Namespace
00209  */
00210 
00211 #if !defined(RECLS_NO_NAMESPACE)
00212 namespace recls
00213 {
00214 #endif /* !RECLS_NO_NAMESPACE */
00215 
00216 /* 
00217  * Flags
00218  */
00219 
00227 enum RECLS_FLAG
00228 {
00229         RECLS_F_FILES               =   0x00000001 
00230     ,   RECLS_F_DIRECTORIES         =   0x00000002 
00231     ,   RECLS_F_LINKS               =   0x00000004 
00232     ,   RECLS_F_DEVICES             =   0x00000008 
00233     ,   RECLS_F_TYPEMASK            =   0x00000FFF
00234     ,   RECLS_F_RECURSIVE           =   0x00010000 
00235     ,   RECLS_F_NO_FOLLOW_LINKS     =   0x00020000 
00236     ,   RECLS_F_DIRECTORY_PARTS     =   0x00040000 
00237     ,   RECLS_F_DETAILS_LATER       =   0x00080000 
00238 };
00239 
00240 #if !defined(__cplusplus) && \
00241     !defined(RECLS_DOCUMENTATION_SKIP_SECTION)
00242 typedef enum RECLS_FLAG RECLS_FLAG;
00243 #endif /* !__cplusplus && !RECLS_DOCUMENTATION_SKIP_SECTION */
00244 
00245 /* 
00246  * Typedefs
00247  */
00248 
00249 struct recls_fileinfo_t;
00250 
00252 typedef struct recls_fileinfo_t const   *recls_info_t;
00253 
00255 typedef void                            *recls_process_fn_param_t;
00256 
00265 typedef int (RECLS_CALLCONV_DEFAULT *hrecls_process_fn_t)(recls_info_t info, recls_process_fn_param_t param);
00266 
00267 /* 
00268  * Namespace typedefs
00269  */
00270 
00271 #if !defined(RECLS_NO_NAMESPACE)
00272 typedef recls_info_t                info_t;
00273 typedef recls_process_fn_param_t    process_fn_param_t;
00274 #endif /* !RECLS_NO_NAMESPACE */
00275 
00276 /* 
00277  * Functions
00278  */
00279 
00280 /***************************************
00281  * Search control
00282  */
00283 
00300 RECLS_FNDECL(recls_rc_t) Recls_Search(          recls_char_t const          *searchRoot
00301                                     ,           recls_char_t const          *pattern
00302                                     ,           recls_uint32_t              flags
00303                                     ,           hrecls_t                    *phSrch);
00304 
00316 RECLS_FNDECL(recls_rc_t) Recls_SearchProcess(   recls_char_t const          *searchRoot
00317                                             ,   recls_char_t const          *pattern
00318                                             ,   recls_uint32_t              flags
00319                                             ,   hrecls_process_fn_t         pfn
00320                                             ,   recls_process_fn_param_t    param);
00321 
00326 RECLS_FNDECL(void) Recls_SearchClose(           hrecls_t                    hSrch);
00327 
00330 /***************************************
00331  * Search enumeration
00332  */
00333 
00348 RECLS_FNDECL(recls_rc_t) Recls_GetNext(         hrecls_t                    hSrch);
00349 
00359 RECLS_FNDECL(recls_rc_t) Recls_GetDetails(      hrecls_t                    hSrch
00360                                             ,   recls_info_t                *phEntry);
00361 
00370 RECLS_FNDECL(recls_rc_t) Recls_GetNextDetails(  hrecls_t                    hSrch
00371                                             ,   recls_info_t                *phEntry);
00372 
00375 /***************************************
00376  * File entry info structure
00377  */
00378 
00389 RECLS_FNDECL(void) Recls_CloseDetails(          recls_info_t                hEntry);
00390 
00399 RECLS_FNDECL(recls_rc_t) Recls_CopyDetails(     recls_info_t                hEntry
00400                                             ,   recls_info_t                *phEntry);
00401 
00410 RECLS_FNDECL(recls_rc_t) Recls_OutstandingDetails(hrecls_t                  hSrch
00411                                             ,   recls_uint32_t              *count);
00412 
00415 /***************************************
00416  * Error handling
00417  */
00418 
00430 RECLS_FNDECL(recls_rc_t) Recls_GetLastError(    hrecls_t                    hSrch);
00431 
00439 RECLS_FNDECL(size_t) Recls_GetErrorString(      recls_rc_t                  rc
00440                                     ,           recls_char_t                *buffer
00441                                     ,           size_t                      cchBuffer);
00442 
00450 RECLS_FNDECL(size_t) Recls_GetLastErrorString(  hrecls_t                    hSrch
00451                                         ,       recls_char_t                *buffer
00452                                         ,       size_t                      cchBuffer);
00453 
00456 /***************************************
00457  * Property elicitation
00458  */
00459 
00473 RECLS_FNDECL(size_t) Recls_GetPathProperty(     recls_info_t                hEntry
00474                                         ,       recls_char_t                *buffer
00475                                         ,       size_t                      cchBuffer);
00476 
00484 RECLS_FNDECL(size_t) Recls_GetDirectoryProperty(recls_info_t                hEntry
00485                                             ,   recls_char_t                *buffer
00486                                             ,   size_t                      cchBuffer);
00487 
00496 RECLS_FNDECL(size_t) Recls_GetDirectoryPathProperty(    recls_info_t        hEntry
00497                                                     ,   recls_char_t        *buffer
00498                                                     ,   size_t              cchBuffer);
00499 
00507 RECLS_FNDECL(size_t) Recls_GetFileProperty(     recls_info_t                hEntry
00508                                         ,       recls_char_t                *buffer
00509                                         ,       size_t                      cchBuffer);
00510 
00520 RECLS_FNDECL(size_t) Recls_GetShortFileProperty(recls_info_t                hEntry
00521                                             ,   recls_char_t                *buffer
00522                                             ,   size_t                      cchBuffer);
00523 
00531 RECLS_FNDECL(size_t) Recls_GetFileNameProperty( recls_info_t                hEntry
00532                                             ,   recls_char_t                *buffer
00533                                             ,   size_t                      cchBuffer);
00534 
00542 RECLS_FNDECL(size_t) Recls_GetFileExtProperty(  recls_info_t                hEntry
00543                                             ,   recls_char_t                *buffer
00544                                             ,   size_t                      cchBuffer);
00545 
00556 RECLS_FNDECL(size_t) Recls_GetDirectoryPartProperty(recls_info_t            hEntry
00557                                             ,   int                         part
00558                                             ,   recls_char_t                *buffer
00559                                             ,   size_t                      cchBuffer);
00560 
00561 
00570 RECLS_FNDECL(recls_bool_t) Recls_IsFileReadOnly(recls_info_t                hEntry);
00571 
00580 RECLS_FNDECL(recls_bool_t) Recls_IsFileDirectory(recls_info_t               hEntry);
00581 
00590 RECLS_FNDECL(recls_bool_t) Recls_IsFileLink(    recls_info_t                hEntry);
00591 
00599 RECLS_FNDECL(void)         Recls_GetSizeProperty(   recls_info_t            hEntry
00600                                                 ,   recls_filesize_t        *size);
00601 
00603 RECLS_FNDECL(recls_time_t) Recls_GetCreationTime(recls_info_t               hEntry);
00604 
00606 RECLS_FNDECL(recls_time_t) Recls_GetModificationTime(recls_info_t           hEntry);
00607 
00609 RECLS_FNDECL(recls_time_t) Recls_GetLastAccessTime(recls_info_t             hEntry);
00610 
00612 RECLS_FNDECL(recls_time_t) Recls_GetLastStatusChangeTime(recls_info_t       hEntry);
00613 
00616 /* 
00617  * Namespace
00618  */
00619 
00620 #if !defined(RECLS_NO_NAMESPACE)
00621 } /* namespace recls */
00622 #endif /* !RECLS_NO_NAMESPACE */
00623 
00624 /* 
00625  * Platform-specific includes
00626  */
00627 
00628 /*** \def RECLS_PLATFORM_API_WIN32 Defined if Win32 platform-specific extensions are in use */
00629 /*** \def RECLS_PLATFORM_API_UNIX Defined if UNIX platform-specific extensions are in use */
00630 
00631 #ifdef RECLS_PLATFORM_API_WIN32
00632 # undef RECLS_PLATFORM_API_WIN32
00633 #endif /* RECLS_PLATFORM_API_WIN32 */
00634 
00635 #ifdef RECLS_PLATFORM_API_UNIX
00636 # undef RECLS_PLATFORM_API_UNIX
00637 #endif /* RECLS_PLATFORM_API_UNIX */
00638 
00639 #if !defined(RECLS_PURE_API)
00640 # if defined(RECLS_PLATFORM_IS_WIN32)
00641 #  include "recls_win32.h"
00642 #  define RECLS_PLATFORM_API_WIN32
00643 # elif defined(RECLS_PLATFORM_IS_UNIX)
00644 #  include "recls_unix.h"
00645 #  define RECLS_PLATFORM_API_UNIX
00646 # else
00647 #  error Platform not recognised
00648 # endif /* platform */
00649 #endif /* !RECLS_PURE_API */
00650 
00651 /* 
00652 
00653 #endif /* !RECLS_INCL_H_RECLS */
00654 
00655 /*
/API/include/recls.h
