1 /* 2 Copyright (C) 2015-2021, Dirk Krause 3 SPDX-License-Identifier: BSD-3-Clause 4 */ 5 6 /* 7 WARNING: This file was generated by the dkct program (see 8 http://dktools.sourceforge.net/ for details). 9 Changes you make here will be lost if dkct is run again! 10 You should modify the original source and run dkct on it. 11 Original source: dk4dirwc.ctr 12 */ 13 14 #ifndef DK4DIRWC_H_INCLUDED 15 /** Avoid multiple inclusions. */ 16 #define DK4DIRWC_H_INCLUDED 1 17 18 19 /** @file 20 Directory traversal using wchar_t file names. 21 22 CRT on Windows: Optional. 23 */ 24 25 #ifndef DK4CONF_H_INCLUDED 26 #if DK4_BUILDING_DKTOOLS4 27 #include "dk4conf.h" 28 #else 29 #include <dktools-4/dk4conf.h> 30 #endif 31 #endif 32 33 #ifndef DK4TYPES_H_INCLUDED 34 #if DK4_BUILDING_DKTOOLS4 35 #include <libdk4base/dk4types.h> 36 #else 37 #include <dktools-4/dk4types.h> 38 #endif 39 #endif 40 41 #ifndef DK4ERROR_H_INCLUDED 42 #if DK4_BUILDING_DKTOOLS4 43 #include <libdk4base/dk4error.h> 44 #else 45 #include <dktools-4/dk4error.h> 46 #endif 47 #endif 48 49 #ifndef DK4STO_H_INCLUDED 50 #if DK4_BUILDING_DKTOOLS4 51 #include <libdk4c/dk4sto.h> 52 #else 53 #include <dktools-4/dk4sto.h> 54 #endif 55 #endif 56 57 58 /** Directory structure. 59 */ 60 typedef struct { 61 wchar_t *path; /**< Directory path. */ 62 dk4_sto_t *s_dir; /**< Storage for directories. */ 63 dk4_sto_it_t *i_dir; /**< Iterator for directories. */ 64 dk4_sto_t *s_file; /**< Storage for non-directories. */ 65 dk4_sto_it_t *i_file; /**< Iterator for non-directories. */ 66 size_t maxlen; /**< Maximum entry name length. */ 67 } dk4_dir_wc_t; 68 69 #ifdef __cplusplus 70 extern "C" { 71 #endif 72 73 /** Open directory, create directory structure. 74 @param path Directory path name. 75 @param om Opening mode. 76 @param erp Error report, may be NULL. 77 @return Pointer to new directory structure on success, NULL on error. 78 On success use dk4dir_wc_close() to destroy the directory 79 structure. 80 81 Error codes: 82 - DK4_E_INVALID_ARGUMENTS<br> 83 if path is NULL, 84 - DK4_E_NOT_SUPPORTED<br> 85 if no function to traverse directories was found during build process, 86 - DK4_E_MEMORY_ALLOCATION_FAILED<br> 87 if a memory allocation failed, 88 - DK4_E_MATH_OVERFLOW<br> 89 if a mathematical overflow occured in a size calculation, 90 - DK4_E_BUFFER_TOO_SMALL<br> 91 if one of the involved directory or file names is too long for an 92 internal buffer, 93 - DK4_E_OPENDIR_FAILED<br> 94 with errno value in iDetails1 if the attempt to open the directory 95 failed, 96 - DK4_E_FINDFIRSTFILE_FAILED<br> 97 with GetLastError() value in lDetails1 if the FindFirstFile() 98 function failed on Windows, 99 - DK4_E_SYSTEM<br> 100 if the stat() or lstat() function failed for one of the directory 101 items. 102 */ 103 dk4_dir_wc_t * 104 dk4dir_wc_open(const wchar_t *path, int om, dk4_er_t *erp); 105 106 /** Destroy directory structure. 107 @param dptr Structure to destroy. 108 */ 109 void 110 dk4dir_wc_close(dk4_dir_wc_t *dptr); 111 112 /** Reset directory traversal. 113 @param dptr Directory structure. 114 */ 115 void 116 dk4dir_wc_reset(dk4_dir_wc_t *dptr); 117 118 /** Retrieve directory path. 119 @param dptr Directory structure. 120 @return Directory path on success, 121 NULL on error or if no directory was specified for a 122 file name expansion. 123 */ 124 const wchar_t * 125 dk4dir_wc_get_path(dk4_dir_wc_t const *dptr); 126 127 /** Retrieve next directory name. 128 @param dptr Directory structure. 129 @return Pointer to short name on success, NULL if there are no 130 more directories. 131 */ 132 const wchar_t * 133 dk4dir_wc_next_dir(dk4_dir_wc_t *dptr); 134 135 /** Retrieve next file (non-directory) name. 136 @param dptr Directory structure. 137 @return Pointer to short name on success, NULL if there are no more 138 files. 139 */ 140 const wchar_t * 141 dk4dir_wc_next_file(dk4_dir_wc_t *dptr); 142 143 /** Skip files (remove information about files, release memory). 144 @param dptr Directory structure. 145 */ 146 void 147 dk4dir_wc_skip_files(dk4_dir_wc_t *dptr); 148 149 /** Compare two file or directory names. 150 @param l Left name. 151 @param r Right name. 152 @param cr Comparison criteria (ignored). 153 @return 1 if l>r, 0 if l=r, -1 if l<r. 154 */ 155 int 156 dk4dir_wc_compare(const void *l, const void *r, int cr); 157 158 /** Get maximum entry name length. 159 @param dptr Directory. 160 @return Maximum name length. 161 */ 162 size_t 163 dk4dir_wc_get_max_entry_length(dk4_dir_wc_t const *dptr); 164 165 /** Create full path name for short file name in existing buffer. 166 @param buffer Result buffer. 167 @param szbuf Size of result buffer (number of wchar_t). 168 @param pdir Directory fn was obtained from. 169 @param fn Short file or directory name. 170 @param erp Error report, may be NULL. 171 @return 1 on success, 0 on error. 172 173 Error codes: 174 - DK4_E_INVALID_ARGUMENTS<br> 175 if buffer, pdir or fn is NULL or szbuf is 0, 176 - DK4_E_BUFFER_TOO_SMALL<br> 177 if the buffer is too small. 178 */ 179 int 180 dk4dir_wc_full_name_buffer( 181 wchar_t *buffer, 182 size_t szbuf, 183 dk4_dir_wc_t const *pdir, 184 wchar_t const *fn, 185 dk4_er_t *erp 186 ); 187 188 /** Create full path name for short file name in newly allocated buffer. 189 @param pdir Directory fn was obtained from. 190 @param fn Short file or directory name. 191 @param erp Error report, may be NULL. 192 @return Valid pointer to newly allocated buffer on success, 193 NULL on error. 194 On success use dk4mem_free() to release the memory when done with 195 the name. 196 197 Error codes: 198 - DK4_E_INVALID_ARGUMENTS<br> 199 if pdir or fn is NULL, 200 - DK4_E_MATH_OVERFLOW<br> 201 if the size calculation results in a numeric overflow. 202 - DK4_E_MEMORY_ALLOCATION_FAILED<br> 203 if the memory allocation failed, 204 - DK4_E_BUFFER_TOO_SMALL<br> 205 if the buffer is too small. 206 */ 207 wchar_t * 208 dk4dir_wc_full_name_new( 209 dk4_dir_wc_t const *pdir, 210 wchar_t const *fn, 211 dk4_er_t *erp 212 ); 213 214 #ifdef __cplusplus 215 } 216 #endif 217 218 219 #endif 220