00001 /* 
00002  * File:        recls.h
00003  *
00004  * Purpose:     Main header file for the recls API.
00005  *
00006  * Created:     15th August 2003
00007  * Updated:     13th October 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    3
00065 # define RECLS_VER_H_RECLS_REVISION 2
00066 # define RECLS_VER_H_RECLS_EDIT     21
00067 #endif /* !RECLS_DOCUMENTATION_SKIP_SECTION */
00068 
00085 /* recls version */
00086 #define RECLS_VER_MAJOR     1
00087 #define RECLS_VER_MINOR     1
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           RECLS_VER_1_1_1
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 #if !defined(RECLS_NO_NAMESPACE)
00124 # define RECLS_QUAL(x)                  ::recls::x
00125 #else
00126 # define RECLS_QUAL(x)                  x
00127 #endif /* !RECLS_NO_NAMESPACE */
00128 
00129 /* 
00130  * Pre-processor discrimination
00131  */
00132 
00133 /* 
00134  * Function specifications
00135  */
00136 
00137 /*** Defines the recls linkage and calling convention */
00138 #define RECLS_FNDECL(rt)    RECLS_LINKAGE_C rt RECLS_CALLCONV_DEFAULT
00139 
00140 /* 
00141  * Typedefs
00142  */
00143 
00144 /* recls_rc_t */
00145 #ifdef __cplusplus
00146 
00148 typedef recls_sint32_t                                              recls_rc_t;
00149 
00151 const recls_rc_t                                                    RECLS_RC_OK(0);
00153 const recls_rc_t                                                    RECLS_RC_FAIL(-1);
00154 
00156 inline bool RECLS_FAILED(recls_rc_t const &rc)
00157 {
00158     return rc < 0;
00159 }
00160 
00162 inline bool RECLS_SUCCEEDED(recls_rc_t const &rc)
00163 {
00164     return !RECLS_FAILED(rc);
00165 }
00166 
00167 #else /* ? __cplusplus */
00168 
00170 typedef recls_sint32_t                                              recls_rc_t;
00171 
00173 #define RECLS_RC_OK                                                 (0)
00174 
00175 #define RECLS_RC_FAIL                                               (-1)
00176 
00178 #define RECLS_FAILED(rc)                                            ((rc) < 0)
00179 
00180 #define RECLS_SUCCEEDED(rc)                                         (!FAILED(rc))
00181 
00182 #endif /* __cplusplus */
00183 
00184 
00185 /* hrecls_t */
00186 struct hrecls_t_;
00188 typedef struct hrecls_t_ const *                                    hrecls_t;
00189 
00190 /* 
00191  * Namespace
00192  */
00193 
00194 #if !defined(RECLS_NO_NAMESPACE)
00195 } /* namespace recls */
00196 #endif /* !RECLS_NO_NAMESPACE */
00197 
00198 /* 
00199  * Includes
00200  */
00201 
00202 /* Defines result codes */
00203 #include "recls_retcodes.h"
00204 
00205 /* 
00206  * Namespace
00207  */
00208 
00209 #if !defined(RECLS_NO_NAMESPACE)
00210 namespace recls
00211 {
00212 #endif /* !RECLS_NO_NAMESPACE */
00213 
00214 /* 
00215  * Flags
00216  */
00217 
00225 enum RECLS_FLAG
00226 {
00227         RECLS_F_FILES               =   0x00000001 
00228     ,   RECLS_F_DIRECTORIES         =   0x00000002 
00229     ,   RECLS_F_LINKS               =   0x00000004 
00230     ,   RECLS_F_DEVICES             =   0x00000008 
00231     ,   RECLS_F_TYPEMASK            =   0x00000FFF
00232     ,   RECLS_F_RECURSIVE           =   0x00010000 
00233     ,   RECLS_F_NO_FOLLOW_LINKS     =   0x00020000 
00234     ,   RECLS_F_DIRECTORY_PARTS     =   0x00040000 
00235     ,   RECLS_F_DETAILS_LATER       =   0x00080000 
00236 };
00237 
00238 #if !defined(__cplusplus) && \
00239     !defined(RECLS_DOCUMENTATION_SKIP_SECTION)
00240 typedef enum RECLS_FLAG RECLS_FLAG;
00241 #endif /* !__cplusplus && !RECLS_DOCUMENTATION_SKIP_SECTION */
00242 
00243 /* 
00244  * Typedefs
00245  */
00246 
00247 struct recls_fileinfo_t;
00248 
00250 typedef struct recls_fileinfo_t const   *recls_info_t;
00251 
00253 typedef void                            *recls_process_fn_param_t;
00254 
00263 typedef int (RECLS_CALLCONV_DEFAULT *hrecls_process_fn_t)(recls_info_t info, recls_process_fn_param_t param);
00264 
00265 /* 
00266  * Namespace typedefs
00267  */
00268 
00269 #if !defined(RECLS_NO_NAMESPACE)
00270 typedef recls_info_t                info_t;
00271 typedef recls_process_fn_param_t    process_fn_param_t;
00272 #endif /* !RECLS_NO_NAMESPACE */
00273 
00274 /* 
00275  * Functions
00276  */
00277 
00278 /***************************************
00279  * Search control
00280  */
00281 
00298 RECLS_FNDECL(recls_rc_t) Recls_Search(          char const                  *searchRoot
00299                                     ,           char const                  *pattern
00300                                     ,           recls_uint32_t              flags
00301                                     ,           hrecls_t                    *phSrch);
00302 
00314 RECLS_FNDECL(recls_rc_t) Recls_SearchProcess(   char const                  *searchRoot
00315                                             ,   char const                  *pattern
00316                                             ,   recls_uint32_t              flags
00317                                             ,   hrecls_process_fn_t         pfn
00318                                             ,   recls_process_fn_param_t    param);
00319 
00324 RECLS_FNDECL(void) Recls_SearchClose(           hrecls_t                    hSrch);
00325 
00328 /***************************************
00329  * Search enumeration
00330  */
00331 
00346 RECLS_FNDECL(recls_rc_t) Recls_GetNext(         hrecls_t                    hSrch);
00347 
00357 RECLS_FNDECL(recls_rc_t) Recls_GetDetails(      hrecls_t                    hSrch
00358                                             ,   recls_info_t                *pinfo);
00359 
00368 RECLS_FNDECL(recls_rc_t) Recls_GetNextDetails(  hrecls_t                    hSrch
00369                                             ,   recls_info_t                *pinfo);
00370 
00373 /***************************************
00374  * File entry info structure
00375  */
00376 
00387 RECLS_FNDECL(void) Recls_CloseDetails(          recls_info_t                fileInfo);
00388 
00397 RECLS_FNDECL(recls_rc_t) Recls_CopyDetails(     recls_info_t                fileInfo
00398                                             ,   recls_info_t                *pinfo);
00399 
00408 RECLS_FNDECL(recls_rc_t) Recls_OutstandingDetails(hrecls_t                  hSrch
00409                                             ,   recls_uint32_t              *count);
00410 
00413 /***************************************
00414  * Error handling
00415  */
00416 
00428 RECLS_FNDECL(recls_rc_t) Recls_GetLastError(    hrecls_t                    hSrch);
00429 
00437 RECLS_FNDECL(int) Recls_GetErrorString(         recls_rc_t                  rc
00438                                     ,           char                        *buffer
00439                                     ,           size_t                      cchBuffer);
00440 
00448 RECLS_FNDECL(int) Recls_GetLastErrorString(     hrecls_t                    hSrch
00449                                         ,       char                        *buffer
00450                                         ,       size_t                      cchBuffer);
00451 
00454 /***************************************
00455  * Property elicitation
00456  */
00457 
00471 RECLS_FNDECL(size_t) Recls_GetPathProperty(     recls_info_t                fileInfo
00472                                         ,       char                        *buffer
00473                                         ,       size_t                      cchBuffer);
00474 
00482 RECLS_FNDECL(size_t) Recls_GetDirectoryProperty(recls_info_t                fileInfo
00483                                             ,   char                        *buffer
00484                                             ,   size_t                      cchBuffer);
00485 
00494 RECLS_FNDECL(size_t) Recls_GetDirectoryPathProperty(    recls_info_t        fileInfo
00495                                                     ,   char                *buffer
00496                                                     ,   size_t              cchBuffer);
00497 
00505 RECLS_FNDECL(size_t) Recls_GetFileProperty(     recls_info_t                fileInfo
00506                                         ,       char                        *buffer
00507                                         ,       size_t                      cchBuffer);
00508 
00518 RECLS_FNDECL(size_t) Recls_GetShortFileProperty(recls_info_t                fileInfo
00519                                             ,   char                        *buffer
00520                                             ,   size_t                      cchBuffer);
00521 
00529 RECLS_FNDECL(size_t) Recls_GetFileNameProperty( recls_info_t                fileInfo
00530                                             ,   char                        *buffer
00531                                             ,   size_t                      cchBuffer);
00532 
00540 RECLS_FNDECL(size_t) Recls_GetFileExtProperty(  recls_info_t                fileInfo
00541                                             ,   char                        *buffer
00542                                             ,   size_t                      cchBuffer);
00543 
00554 RECLS_FNDECL(size_t) Recls_GetDirectoryPartProperty(recls_info_t            fileInfo
00555                                             ,   int                         part
00556                                             ,   char                        *buffer
00557                                             ,   size_t                      cchBuffer);
00558 
00559 
00568 RECLS_FNDECL(recls_bool_t) Recls_IsFileReadOnly(recls_info_t                fileInfo);
00569 
00578 RECLS_FNDECL(recls_bool_t) Recls_IsFileDirectory(recls_info_t               fileInfo);
00579 
00588 RECLS_FNDECL(recls_bool_t) Recls_IsFileLink(    recls_info_t                fileInfo);
00589 
00597 RECLS_FNDECL(void)         Recls_GetSizeProperty(   recls_info_t            fileInfo
00598                                                 ,   recls_filesize_t        *size);
00599 
00601 RECLS_FNDECL(recls_time_t) Recls_GetCreationTime(recls_info_t               fileInfo);
00602 
00604 RECLS_FNDECL(recls_time_t) Recls_GetModificationTime(recls_info_t           fileInfo);
00605 
00607 RECLS_FNDECL(recls_time_t) Recls_GetLastAccessTime(recls_info_t             fileInfo);
00608 
00610 RECLS_FNDECL(recls_time_t) Recls_GetLastStatusChangeTime(recls_info_t       fileInfo);
00611 
00614 /* 
00615  * Namespace
00616  */
00617 
00618 #if !defined(RECLS_NO_NAMESPACE)
00619 } /* namespace recls */
00620 #endif /* !RECLS_NO_NAMESPACE */
00621 
00622 /* 
00623  * Platform-specific includes
00624  */
00625 
00626 /*** \def RECLS_PLATFORM_API_WIN32 Defined if Win32 platform-specific extensions are in use */
00627 /*** \def RECLS_PLATFORM_API_UNIX Defined if UNIX platform-specific extensions are in use */
00628 
00629 #ifdef RECLS_PLATFORM_API_WIN32
00630 # undef RECLS_PLATFORM_API_WIN32
00631 #endif /* RECLS_PLATFORM_API_WIN32 */
00632 
00633 #ifdef RECLS_PLATFORM_API_UNIX
00634 # undef RECLS_PLATFORM_API_UNIX
00635 #endif /* RECLS_PLATFORM_API_UNIX */
00636 
00637 #if !defined(RECLS_PURE_API)
00638 # if defined(RECLS_PLATFORM_IS_WIN32)
00639 #  include "recls_win32.h"
00640 #  define RECLS_PLATFORM_API_WIN32
00641 # elif defined(RECLS_PLATFORM_IS_UNIX)
00642 #  include "recls_unix.h"
00643 #  define RECLS_PLATFORM_API_UNIX
00644 # else
00645 #  error Platform not recognised
00646 # endif /* platform */
00647 #endif /* !RECLS_PURE_API */
00648 
00649 /* 
00650 
00651 #endif /* !RECLS_INCL_H_RECLS */
00652 
00653 /*
/API/include/recls.h
