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