00001 /* 
00002  * File:        recls.h
00003  *
00004  * Purpose:     Main header file for the recls API.
00005  *
00006  * Created:     15th August 2003
00007  * Updated:     23rd September 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    0
00065 # define RECLS_VER_H_RECLS_REVISION 15
00066 # define RECLS_VER_H_RECLS_EDIT     15
00067 #endif /* !RECLS_DOCUMENTATION_SKIP_SECTION */
00068 
00085 /* recls version */
00086 #define RECLS_VER_MAJOR     1
00087 #define RECLS_VER_MINOR     0
00088 #define RECLS_VER_REVISION  1
00089 #define RECLS_MAKE_VER(ma, mi, re)  (((ma) & 0xff) << 16) | ((mi) & 0xff) << 8) | ((re) & 0xff) << 0))
00090 #define RECLS_VER           RECLS_MAKE_VER(RECLS_VER_MAJOR, RECLS_VER_MINOR, RECLS_VER_REVISION)
00091 
00092 
00093 /* 
00094  * Strictness
00095  */
00096 
00097 #ifndef RECLS_NO_STRICT
00098 # define RECLS_STRICT
00099 #endif /* !RECLS_NO_STRICT */
00100 
00101 /* 
00102  * Includes
00103  */
00104 
00105 /* Detects C & C++ things, such as namespace support */
00106 #include "recls_language.h"
00107 /* Includes platform-specific headers */
00108 #include "recls_platform.h"
00109 /* Includes stddef.h / cstddef, and defines the recls types: recls_s/uint8/16/32/64_t */
00110 #include "recls_compiler.h"
00111 /* Defines recls_filesize_t, recls_time_t */
00112 #include "recls_platform_types.h"
00113 
00114 /* 
00115  * Namespace
00116  */
00117 
00118 #if !defined(RECLS_NO_NAMESPACE)
00119 namespace recls
00120 {
00121 #endif /* !RECLS_NO_NAMESPACE */
00122 
00123 /* 
00124  * Pre-processor discrimination
00125  */
00126 
00127 /* 
00128  * Function specifications
00129  */
00130 
00131 /*** Defines the recls linkage and calling convention */
00132 #define RECLS_FNDECL(rt)    RECLS_LINKAGE_C rt RECLS_CALLCONV_DEFAULT
00133 
00134 /* 
00135  * Typedefs
00136  */
00137 
00138 /* recls_rc_t */
00139 #ifdef __cplusplus
00140 
00142 typedef recls_sint32_t                                              recls_rc_t;
00143 
00145 const recls_rc_t                                                    RECLS_RC_OK(0);
00147 const recls_rc_t                                                    RECLS_RC_FAIL(-1);
00148 
00150 inline bool RECLS_FAILED(recls_rc_t const &rc)
00151 {
00152     return rc < 0;
00153 }
00154 
00156 inline bool RECLS_SUCCEEDED(recls_rc_t const &rc)
00157 {
00158     return !RECLS_FAILED(rc);
00159 }
00160 
00161 #else /* ? __cplusplus */
00162 
00164 typedef recls_sint32_t                                              recls_rc_t;
00165 
00167 #define RECLS_RC_OK                                                 (0)
00168 
00169 #define RECLS_RC_FAIL                                               (-1)
00170 
00172 #define RECLS_FAILED(rc)                                            ((rc) < 0)
00173 
00174 #define RECLS_SUCCEEDED(rc)                                         (!FAILED(rc))
00175 
00176 #endif /* __cplusplus */
00177 
00178 
00179 /* hrecls_t */
00180 struct hrecls_t_;
00182 typedef struct hrecls_t_ const *                                    hrecls_t;
00183 
00184 /* 
00185  * Namespace
00186  */
00187 
00188 #if !defined(RECLS_NO_NAMESPACE)
00189 } /* namespace recls */
00190 #endif /* !RECLS_NO_NAMESPACE */
00191 
00192 /* 
00193  * Includes
00194  */
00195 
00196 /* Defines result codes */
00197 #include "recls_retcodes.h"
00198 
00199 /* 
00200  * Namespace
00201  */
00202 
00203 #if !defined(RECLS_NO_NAMESPACE)
00204 namespace recls
00205 {
00206 #endif /* !RECLS_NO_NAMESPACE */
00207 
00208 /* 
00209  * Flags
00210  */
00211 
00212 /*** Search flags */
00213 enum RECLS_FLAG
00214 {
00215         RECLS_F_FILES               =   0x00000001 
00216     ,   RECLS_F_DIRECTORIES         =   0x00000002 
00217     ,   RECLS_F_LINKS               =   0x00000004 
00218     ,   RECLS_F_DEVICES             =   0x00000008 
00219     ,   RECLS_F_TYPEMASK            =   0x00000FFF
00220     ,   RECLS_F_RECURSIVE           =   0x00010000 
00221     ,   RECLS_F_NO_FOLLOW_LINKS     =   0x00020000 
00222     ,   RECLS_F_DIRECTORY_PARTS     =   0x00040000 
00223     ,   RECLS_F_DETAILS_LATER       =   0x00080000 
00224 };
00225 
00226 typedef enum RECLS_FLAG RECLS_FLAG;
00227 
00228 /* 
00229  * Typedefs
00230  */
00231 
00232 struct recls_fileinfo_t;
00233 
00235 typedef struct recls_fileinfo_t const   *recls_info_t;
00236 
00238 typedef void                            *recls_process_fn_param_t;
00239 
00241 typedef int (*hrecls_process_fn_t)(recls_info_t , recls_process_fn_param_t);
00242 
00243 /* 
00244  * Namespace typedefs
00245  */
00246 
00247 #if !defined(RECLS_NO_NAMESPACE)
00248 typedef recls_info_t                info_t;
00249 typedef recls_process_fn_param_t    process_fn_param_t;
00250 #endif /* !RECLS_NO_NAMESPACE */
00251 
00252 /* 
00253  * Functions
00254  */
00255 
00256 /***************************************
00257  * Search control
00258  */
00259 
00276 RECLS_FNDECL(recls_rc_t) Recls_Search(          char const                  *searchRoot
00277                                     ,           char const                  *pattern
00278                                     ,           recls_uint32_t              flags
00279                                     ,           hrecls_t                    *phSrch);
00280 
00292 RECLS_FNDECL(recls_rc_t) Recls_SearchProcess(   char const                  *searchRoot
00293                                             ,   char const                  *pattern
00294                                             ,   recls_uint32_t              flags
00295                                             ,   hrecls_process_fn_t         pfn
00296                                             ,   recls_process_fn_param_t    param);
00297 
00302 RECLS_FNDECL(void) Recls_SearchClose(           hrecls_t                    hSrch);
00303 
00306 /***************************************
00307  * Search enumeration
00308  */
00309 
00324 RECLS_FNDECL(recls_rc_t) Recls_GetNext(         hrecls_t                    hSrch);
00325 
00335 RECLS_FNDECL(recls_rc_t) Recls_GetDetails(      hrecls_t                    hSrch
00336                                             ,   recls_info_t                *pinfo);
00337 
00346 RECLS_FNDECL(recls_rc_t) Recls_GetNextDetails(  hrecls_t                    hSrch
00347                                             ,   recls_info_t                *pinfo);
00348 
00351 /***************************************
00352  * File entry info structure
00353  */
00354 
00365 RECLS_FNDECL(void) Recls_CloseDetails(          recls_info_t                fileInfo);
00366 
00375 RECLS_FNDECL(recls_rc_t) Recls_CopyDetails(     recls_info_t                fileInfo
00376                                             ,   recls_info_t                *pinfo);
00377 
00386 RECLS_FNDECL(recls_rc_t) Recls_OutstandingDetails(hrecls_t                  hSrch
00387                                             ,   recls_uint32_t              *count);
00388 
00391 /***************************************
00392  * Error handling
00393  */
00394 
00406 RECLS_FNDECL(recls_rc_t) Recls_GetLastError(    hrecls_t                    hSrch);
00407 
00415 RECLS_FNDECL(int) Recls_GetErrorString(         recls_rc_t                  rc
00416                                     ,           char                        *buffer
00417                                     ,           size_t                      cchBuffer);
00418 
00426 RECLS_FNDECL(int) Recls_GetLastErrorString(     hrecls_t                    hSrch
00427                                         ,       char                        *buffer
00428                                         ,       size_t                      cchBuffer);
00429 
00432 /***************************************
00433  * Property elicitation
00434  */
00435 
00449 RECLS_FNDECL(size_t) Recls_GetPathProperty(     recls_info_t                fileInfo
00450                                         ,       char                        *buffer
00451                                         ,       size_t                      cchBuffer);
00452 
00460 RECLS_FNDECL(size_t) Recls_GetDirectoryProperty(recls_info_t                fileInfo
00461                                             ,   char                        *buffer
00462                                             ,   size_t                      cchBuffer);
00463 
00471 RECLS_FNDECL(size_t) Recls_GetFileProperty(     recls_info_t                fileInfo
00472                                         ,       char                        *buffer
00473                                         ,       size_t                      cchBuffer);
00474 
00484 RECLS_FNDECL(size_t) Recls_GetShortFileProperty(recls_info_t                fileInfo
00485                                             ,   char                        *buffer
00486                                             ,   size_t                      cchBuffer);
00487 
00495 RECLS_FNDECL(size_t) Recls_GetFileNameProperty( recls_info_t                fileInfo
00496                                             ,   char                        *buffer
00497                                             ,   size_t                      cchBuffer);
00498 
00506 RECLS_FNDECL(size_t) Recls_GetFileExtProperty(  recls_info_t                fileInfo
00507                                             ,   char                        *buffer
00508                                             ,   size_t                      cchBuffer);
00509 
00520 RECLS_FNDECL(size_t) Recls_GetDirectoryPartProperty(recls_info_t            fileInfo
00521                                             ,   int                         part
00522                                             ,   char                        *buffer
00523                                             ,   size_t                      cchBuffer);
00524 
00525 
00534 RECLS_FNDECL(recls_bool_t) Recls_IsFileReadOnly(recls_info_t                fileInfo);
00535 
00544 RECLS_FNDECL(recls_bool_t) Recls_IsFileDirectory(recls_info_t               fileInfo);
00545 
00554 RECLS_FNDECL(recls_bool_t) Recls_IsFileLink(    recls_info_t                fileInfo);
00555 
00557 RECLS_FNDECL(recls_time_t) Recls_GetCreationTime(recls_info_t               fileInfo);
00558 
00560 RECLS_FNDECL(recls_time_t) Recls_GetModificationTime(recls_info_t           fileInfo);
00561 
00563 RECLS_FNDECL(recls_time_t) Recls_GetLastAccessTime(recls_info_t             fileInfo);
00564 
00566 RECLS_FNDECL(recls_time_t) Recls_GetLastStatusChangeTime(recls_info_t       fileInfo);
00567 
00570 /* 
00571  * Namespace
00572  */
00573 
00574 #if !defined(RECLS_NO_NAMESPACE)
00575 } /* namespace recls */
00576 #endif /* !RECLS_NO_NAMESPACE */
00577 
00578 /* 
00579  * Platform-specific includes
00580  */
00581 
00582 /*** \def RECLS_PLATFORM_API_WIN32 Defined if Win32 platform-specific extensions are in use */
00583 /*** \def RECLS_PLATFORM_API_UNIX Defined if UNIX platform-specific extensions are in use */
00584 
00585 #ifdef RECLS_PLATFORM_API_WIN32
00586 # undef RECLS_PLATFORM_API_WIN32
00587 #endif /* RECLS_PLATFORM_API_WIN32 */
00588 
00589 #ifdef RECLS_PLATFORM_API_UNIX
00590 # undef RECLS_PLATFORM_API_UNIX
00591 #endif /* RECLS_PLATFORM_API_UNIX */
00592 
00593 #if !defined(RECLS_PURE_API)
00594 # if defined(RECLS_PLATFORM_IS_WIN32)
00595 #  include "recls_win32.h"
00596 #  define RECLS_PLATFORM_API_WIN32
00597 # elif defined(RECLS_PLATFORM_IS_UNIX)
00598 #  include "recls_unix.h"
00599 #  define RECLS_PLATFORM_API_UNIX
00600 # else
00601 #  error Platform not recognised
00602 # endif /* platform */
00603 #endif /* !RECLS_PURE_API */
00604 
00605 /* 
00606 
00607 #endif /* !RECLS_INCL_H_RECLS */
00608 
00609 /*
/API/include/recls.h
