1 /*************************************************************************** 2 begin : Tue Sep 09 2003 3 copyright : (C) 2003-2010 by Martin Preuss 4 email : martin@libchipcard.de 5 6 *************************************************************************** 7 * * 8 * This library is free software; you can redistribute it and/or * 9 * modify it under the terms of the GNU Lesser General Public * 10 * License as published by the Free Software Foundation; either * 11 * version 2.1 of the License, or (at your option) any later version. * 12 * * 13 * This library is distributed in the hope that it will be useful, * 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * 16 * Lesser General Public License for more details. * 17 * * 18 * You should have received a copy of the GNU Lesser General Public * 19 * License along with this library; if not, write to the Free Software * 20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, * 21 * MA 02111-1307 USA * 22 * * 23 ***************************************************************************/ 24 25 26 #ifndef GWENHYWFAR_PATH_H 27 #define GWENHYWFAR_PATH_H 28 29 #include <gwenhywfar/gwenhywfarapi.h> 30 #include <gwenhywfar/types.h> 31 #include <gwenhywfar/buffer.h> 32 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 /** @defgroup MOD_PATH Paths 39 * @ingroup MOD_PARSER 40 * 41 * @brief These functions work on general paths. 42 * 43 * A path consists of a list of elements separated by a slash, like in 44 * <i>/element1/element2/element3</i>. 45 * An element can either be a <i>group</i> or an <i>item</i>. 46 * Groups can contain multiple items and groups, but an item can not contain 47 * anything. 48 * So there can at most be <strong>one</strong> item, and it must be the 49 * last element. 50 * An example of how to use these functions is given in the module 51 * @ref MOD_DB. These functions can also be used with files and folders. In 52 * this case a group corresponds to a folder and items correspond to files. 53 */ 54 /*@{*/ 55 56 /** 57 * @name Path Flags 58 * 59 * The path flags only use the lower word of the integer. The high word 60 * may be used/interpreted by the called function. 61 */ 62 /*@{*/ 63 /** 64 * if this is set then all elements of the path must exist. 65 */ 66 #define GWEN_PATH_FLAGS_PATHMUSTEXIST 0x00000001 67 /** 68 * if this is set then none of the elements of the path must exist. 69 */ 70 #define GWEN_PATH_FLAGS_PATHMUSTNOTEXIST 0x00000002 71 72 /** 73 * if this bit is set then the whole path (at any depth!) will be created. 74 * This may lead to double entries at any part of the path. 75 * You need this in very rare cases, most likely you want 76 * @ref GWEN_PATH_FLAGS_NAMEMUSTEXIST. 77 */ 78 #define GWEN_PATH_FLAGS_PATHCREATE 0x00000004 79 80 /** 81 * if this bit is set then the last element of the path MUST exist. 82 * This implies @ref GWEN_PATH_FLAGS_PATHMUSTEXIST 83 */ 84 #define GWEN_PATH_FLAGS_NAMEMUSTEXIST 0x00000008 85 86 /** 87 * if this bit is set then the last element of the path MUST NOT exist. 88 */ 89 #define GWEN_PATH_FLAGS_NAMEMUSTNOTEXIST 0x00000010 90 91 /** 92 * if this bit is set then the last element of the path is created in any 93 * case (this is for groups). 94 * This may lead to double entries of the last element. 95 */ 96 #define GWEN_PATH_FLAGS_CREATE_GROUP 0x00000020 97 98 /** 99 * if this bit is set then the last element of the path is created in any 100 * case (this is for variables). 101 * This may lead to double entries of the last element. 102 */ 103 #define GWEN_PATH_FLAGS_CREATE_VAR 0x00000040 104 105 /** 106 * a variable is wanted (if this bit is 0 then a group is wanted). 107 * This flag is used internally, too. When the path handler function 108 * is called by @ref GWEN_Path_Handle then this flag is modified 109 * to reflect the type of the current path element. 110 */ 111 #define GWEN_PATH_FLAGS_VARIABLE 0x00000080 112 113 114 /** 115 * all elements of the path are to be escaped. 116 * This is usefull when used with file names etc. It makes sure that the 117 * path elements presented to the path element handler function only 118 * consist of alphanumeric characters. All other characters are escaped 119 * using @ref GWEN_Text_Escape. 120 */ 121 #define GWEN_PATH_FLAGS_ESCAPE 0x00000100 122 123 /** use the same flag for both escape and unescape */ 124 #define GWEN_PATH_FLAGS_UNESCAPE 0x00000100 125 126 /* be more tolerant, don't escape common characters such as '.' */ 127 #define GWEN_PATH_FLAGS_TOLERANT_ESCAPE 0x00000200 128 129 /** 130 * Allow to also escape/unescape the last path element (otherwise it will 131 * not be escaped/unescaped). 132 */ 133 #define GWEN_PATH_FLAGS_CONVERT_LAST 0x00000400 134 135 /** 136 * Allows checking for root. If the path begins with a slash ('/') and this 137 * flags is set the slash will be included in the first path element 138 * passed to the element handler function. Additionally the flag 139 * @ref GWEN_PATH_FLAGS_ROOT will be set. Otherwise there will be no check 140 * and special treatment of root entries. 141 */ 142 #define GWEN_PATH_FLAGS_CHECKROOT 0x00000800 143 144 /** 145 * This flag is only used with @ref GWEN_Path_HandleWithIdx to disable 146 * index handling. 147 */ 148 #define GWEN_PATH_FLAGS_NO_IDX 0x00001000 149 150 /** 151 * 152 */ 153 #define GWEN_PATH_FLAGS_RFU1 0x00002000 154 155 156 /** 157 * @internal 158 */ 159 #define GWEN_PATH_FLAGS_INTERNAL 0x0000c000 160 161 /** 162 * @internal 163 * this is flagged for the path function. If this is set then the 164 * element given is the last one, otherwise it is not. 165 */ 166 #define GWEN_PATH_FLAGS_LAST 0x00004000 167 168 /** 169 * @internal 170 * this is flagged for the path function. If this is set then the 171 * element given is within root (in this case the element passed to the 172 * element handler funcion will start with a slash), otherwise it is not. 173 */ 174 #define GWEN_PATH_FLAGS_ROOT 0x00008000 175 176 /*@}*/ 177 178 179 180 typedef void *(*GWEN_PATHHANDLERPTR)(const char *entry, 181 void *data, 182 uint32_t flags); 183 184 typedef void *(*GWEN_PATHIDXHANDLERPTR)(const char *entry, 185 void *data, 186 int idx, 187 uint32_t flags); 188 189 190 /** 191 * This function works on a path according to the given flags. 192 * For every element the given function is called. 193 * A path consists of multiple elements separated by a slash ("/"), 194 * e.g. "first/second/element". 195 * This function is used by the DB module but may also be used for any 196 * type of path handling (like creating all directories along a given path). 197 * This function simply calls the given function for any element as long as 198 * that function returns a non-zero value or the path ends. 199 * The type of the returned value completely depends on the function called. 200 * @return 0 on error, !=0 otherwise 201 */ 202 GWENHYWFAR_API 203 void *GWEN_Path_Handle(const char *path, 204 void *data, 205 uint32_t flags, 206 GWEN_PATHHANDLERPTR elementFunction); 207 208 GWENHYWFAR_API 209 void *GWEN_Path_HandleWithIdx(const char *path, 210 void *data, 211 uint32_t flags, 212 GWEN_PATHIDXHANDLERPTR elementFunction); 213 214 215 /** 216 * Converts the given path according to the given flags. 217 * You can use this function to escape, unescape or simply store all path 218 * elements within a buffer. The converted path will simply be appended to 219 * the given buffer (without any leading slash). 220 */ 221 GWENHYWFAR_API 222 int GWEN_Path_Convert(const char *path, 223 GWEN_BUFFER *buffer, 224 uint32_t flags); 225 226 227 /*@}*/ /* defgroup */ 228 229 230 #ifdef __cplusplus 231 } 232 #endif 233 234 235 #endif /* GWENHYWFAR_PATH_H */ 236 237