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: dk4pathw.ctr 12 */ 13 14 #ifndef DK4PATHW_H_INCLUDED 15 /** Avoid multiple inclusions. */ 16 #define DK4PATHW_H_INCLUDED 1 17 18 19 /** @file 20 String operations for path names 21 (wchar_t characters). 22 */ 23 24 #ifndef DK4CONF_H_INCLUDED 25 #if DK4_BUILDING_DKTOOLS4 26 #include "dk4conf.h" 27 #else 28 #include <dktools-4/dk4conf.h> 29 #endif 30 #endif 31 32 #ifndef DK4TYPES_H_INCLUDED 33 #if DK4_BUILDING_DKTOOLS4 34 #include <libdk4base/dk4types.h> 35 #else 36 #include <dktools-4/dk4types.h> 37 #endif 38 #endif 39 40 #ifndef DK4ERROR_H_INCLUDED 41 #if DK4_BUILDING_DKTOOLS4 42 #include <libdk4base/dk4error.h> 43 #else 44 #include <dktools-4/dk4error.h> 45 #endif 46 #endif 47 48 #ifdef __cplusplus 49 extern "C" { 50 #endif 51 52 /** Check whether a file name is an absolute path. 53 CRT on Windows: Not used. 54 @param path Path name to check. 55 @return 1 for absolute path, 0 for other path. 56 */ 57 int 58 dk4pathw_is_absolute(const wchar_t *path); 59 60 /** Check whether a file name is a relative path. 61 CRT on Windows: Not used. 62 @param path Path name to check. 63 @return 1 for absolute path, 0 for other path. 64 */ 65 int 66 dk4pathw_is_relative(const wchar_t *path); 67 68 /** Append path filename to path name already stored in buffer. 69 Resolve . and .. for current directory and parent directory. 70 CRT on Windows: Optional, disabling CRT degrades performance. 71 @param buffer Buffer already containing a path. 72 @param sz Buffer size. 73 @param filename Relative file name to append to buffer. 74 @param erp Error report, may be NULL. 75 @return 1 on success, 0 on error. 76 77 Error codes: 78 - DK4_E_INVALID_ARGUMENTS<br> 79 if buffer or filename is NULL or sz is 0, 80 - DK4_E_MATH_OVERFLOW<br> 81 if filename is too long, 82 - DK4_E_MEMORY<br> 83 if allocation of a filename copy fails, 84 - DK4_E_SYNTAX<br> 85 if too many .. in filename, 86 - DK4_E_BUFFER_TOO_SMALL<br> 87 if buffer size is too small. 88 */ 89 int 90 dk4pathw_append( 91 wchar_t *buffer, size_t sz, const wchar_t *filename, dk4_er_t *erp 92 ); 93 94 /** Find pointer to suffix. 95 CRT on Windows: Not used. 96 @param filename File name to find suffix for. 97 @param erp Error report, may be NULL. 98 @return Pointer to suffix dot if found, NULL otherwise. 99 100 Error codes: 101 - DK4_E_INVALID_ARGUMENTS<br> 102 if filename is NULL, 103 - DK4_E_NOT_FOUND<br> 104 if the file name does not contain a suffix. 105 */ 106 wchar_t * 107 dk4pathw_get_suffix(const wchar_t *filename, dk4_er_t *erp); 108 109 /** Correct file name separators from slash to backslash on Windows, 110 vice versa on other systems. 111 CRT on Windows: Not used. 112 @param filename File name to correct. 113 */ 114 void 115 dk4pathw_correct_sep(wchar_t *filename); 116 117 /** Check whether file name needs expansion on Windows. 118 CRT on Windows: Not used. 119 @param filename File name to check. 120 @return 1 if expansion is necessary, 0 otherwise. 121 */ 122 int 123 dk4pathw_must_expand(const wchar_t *filename); 124 125 /** Create file name with specified suffix. 126 @param pdst Destination buffer. 127 @param szdst Size of pdst (number of wchar_t). 128 @param srcname Source file name. 129 @param newsu New file suffix. 130 @param erp Error report, may be NULL. 131 @return 1 on success, 0 on error. 132 133 Error codes: 134 - DK4_E_INVALID_ARGUMENTS<br> 135 if pdst or srcname or newsu is NULL or szdst is 0, 136 - DK4_E_BUFFER_TOO_SMALL<br> 137 if the dst buffer is too small. 138 - DK4_E_MATH_OVERFLOW<br> 139 if a mathematical overflow occured in size calculation, 140 */ 141 int 142 dk4pathw_set_suffix( 143 wchar_t *pdst, 144 size_t szdst, 145 wchar_t const *srcname, 146 wchar_t const *newsu, 147 dk4_er_t *erp 148 ); 149 150 /** Create a dynamic copy of a file name with changed suffix. 151 @param srcname Old file name. 152 @param newsu New suffix. 153 @param erp Error report, may be NULL. 154 @return Valid pointer to changed file name on success, NULL on error. 155 On success call dk4mem_free() on the pointer when no longer needed 156 to release the memory. 157 158 Error codes: 159 - DK4_E_INVALID_ARGUMENTS<br> 160 if srcname or newsu is NULL, 161 - DK4_E_BUG<br> 162 if a bug occured, 163 - DK4_E_MATH_OVERFLOW<br> 164 if a mathematical overflow occured in size calculation, 165 - DK4_E_MEMORY_ALLOCATION_FAILED<br> 166 with mem.elsize and mem.nelem set if there is not enough memory 167 available. 168 */ 169 wchar_t * 170 dk4pathw_dup_change_suffix( 171 wchar_t const *srcname, 172 wchar_t const *newsu, 173 dk4_er_t *erp 174 ); 175 176 /** Calculate buffer size required to concatenate a directory 177 name and a file name. 178 @param dirname Directory name. 179 @param filename File name. 180 @param erp Error report, may be NULL. 181 @return Buffer size for concatenated names including the finalizer 182 byte on success, 0 on error. 183 184 Error codes: 185 - DK4_E_INVALID_ARGUMENTS<br> 186 if dirname or filename is NULL, 187 - DK4_E_MATH_OVERFLOW<br> 188 if the calculation results in a numeric overflow. 189 */ 190 size_t 191 dk4pathw_concatenate_size( 192 wchar_t const *dirname, 193 wchar_t const *filename, 194 dk4_er_t *erp 195 ); 196 197 /** Concatenate a directory name and a file name into an existing buffer. 198 This function simply concatenates directory name and file name, 199 . and .. for current and parent directory are not resolved. 200 @param buffer Result buffer for combined file name. 201 @param szbuf Buffer size (number of wchar_t). 202 @param dirn Directory name. 203 @param filen File name. 204 @param erp Error report, may be NULL. 205 @return 1 on success, 0 on error. 206 207 Error codes: 208 - DK4_E_INVALID_ARGUMENTS<br> 209 if buffer, dirn or filen is NULL or szbuf is 0, 210 - DK4_E_BUFFER_TOO_SMALL<br> 211 if the buffer is too small. 212 */ 213 int 214 dk4pathw_concatenate_buffer( 215 wchar_t *buffer, 216 size_t szbuf, 217 wchar_t const *dirn, 218 wchar_t const *filen, 219 dk4_er_t *erp 220 ); 221 222 /** Concatenate a directory name and a file name into newly 223 allocated memory. 224 This function simply concatenates directory name and file name, 225 . and .. for current and parent directory are not resolved. 226 @param dirn Directory name. 227 @param filen File name. 228 @param erp Error report, may be NULL. 229 @return Valid pointer to newly allocated memory containing the 230 concatenation on success, NULL on error. 231 On success use dk4mem_free() to release the memory when done 232 with it. 233 234 Error codes: 235 - DK4_E_INVALID_ARGUMENTS<br> 236 if dirn or filen is NULL, 237 - DK4_E_MATH_OVERFLOW<br> 238 if the size calculation results in a numeric overflow. 239 - DK4_E_MEMORY_ALLOCATION_FAILED<br> 240 if the memory allocation failed, 241 - DK4_E_BUFFER_TOO_SMALL<br> 242 if the buffer is too small. 243 */ 244 wchar_t * 245 dk4pathw_concatenate_new( 246 wchar_t const *dirn, 247 wchar_t const *filen, 248 dk4_er_t *erp 249 ); 250 251 #ifdef __cplusplus 252 } 253 #endif 254 255 256 257 258 #endif 259