1 /** 2 * @file libcomprex/module.h Module API 3 * 4 * $Id: module.h,v 1.25 2003/01/01 06:22:36 chipx86 Exp $ 5 * 6 * @Copyright (C) 2001-2003 The GNUpdate Project. 7 * 8 * This library is free software; you can redistribute it and/or 9 * modify it under the terms of the GNU Library General Public 10 * License as published by the Free Software Foundation; either 11 * version 2 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 * Library General Public License for more details. 17 * 18 * You should have received a copy of the GNU Library General Public 19 * License along with this library; if not, write to the 20 * Free Software Foundation, Inc., 59 Temple Place - Suite 330, 21 * Boston, MA 02111-1307, USA. 22 */ 23 #ifndef _LIBCOMPREX_MODULE_H_ 24 #define _LIBCOMPREX_MODULE_H_ 25 26 #include <stdio.h> 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 typedef enum _CxModuleType CxModuleType; /**< Module types. */ 33 typedef struct _CxArchiveOps CxArchiveOps; /**< File operations. */ 34 typedef struct _CxSchemeOps CxSchemeOps; /**< URI scheme operations. */ 35 typedef struct _CxModule CxModule; /**< A loadable module. */ 36 37 #include <libcomprex/types.h> 38 #include <libcomprex/fsnode.h> 39 #include <libcomprex/fp.h> 40 #include <libcomprex/directory.h> 41 42 /** 43 * Handles the initialization of modules. 44 */ 45 #ifdef STATIC_MODULE 46 # define CX_INIT_ARCHIVE_MODULE(modname, initfunc, archiveops) \ 47 CxModule *init_##modname##_archive_module(void) { \ 48 initfunc(CX_MODULE_ARCHIVE); \ 49 return cxRegisterModule(#modname, &(archiveops), CX_MODULE_ARCHIVE); \ 50 } 51 # define CX_INIT_SCHEME_MODULE(modname, initfunc, schemeops) \ 52 CxModule *init_##modname##_scheme_module(void) { \ 53 initfunc(CX_MODULE_SCHEME); \ 54 return cxRegisterModule(#modname, &(schemeops), CX_MODULE_SCHEME); \ 55 } 56 #else /* if !STATIC_MODULE */ 57 # define CX_INIT_ARCHIVE_MODULE(modname, initfunc, archiveops) \ 58 CxModule *initComprexModule(void) { \ 59 initfunc(CX_MODULE_ARCHIVE); \ 60 return cxRegisterModule(#modname, &(archiveops), CX_MODULE_ARCHIVE); \ 61 } 62 # define CX_INIT_SCHEME_MODULE(modname, initfunc, schemeops) \ 63 CxModule *initComprexModule(void) { \ 64 initfunc(CX_MODULE_SCHEME); \ 65 return cxRegisterModule(#modname, &(schemeops), CX_MODULE_SCHEME); \ 66 } 67 #endif 68 69 /** 70 * A module type. 71 * 72 * These are the types of modules that libcomprex can dynamically load. 73 */ 74 enum _CxModuleType 75 { 76 CX_MODULE_ARCHIVE, /**< File handler module. */ 77 CX_MODULE_SCHEME /**< URI scheme module. */ 78 }; 79 80 /** 81 * @struct _CxArchiveOps module.h libcomprex/module.h 82 * 83 * File operations structure. 84 * 85 * This structure is to be filled out by all modules that handle 86 * comression/decompression of files. 87 * 88 * @see CxModuleType 89 * @see CxSchemeOps 90 */ 91 struct _CxArchiveOps 92 { 93 /** 94 * Reads an archive and returns information on it. 95 * 96 * This is similar to openDir(), but reports information on 97 * the archive file itself, as well as all of the files stored 98 * inside it. 99 * 100 * @param archive The archive structure, which will contain the 101 * archive information. 102 * @param fp The file pointer to the archive file. 103 * 104 * @return The status of the operation. 105 */ 106 CxStatus (*readArchive)(CxArchive *archive, CxFP *fp); 107 108 /** 109 * Saves an archive to a file. 110 * 111 * @param archive The archive structure. 112 * @param fp The file pointer to the archive file. 113 * 114 * @return The status of the operation. 115 */ 116 CxStatus (*saveArchive)(CxArchive *archive, CxFP *fp); 117 118 /** 119 * Closes an archive. 120 * 121 * @param archive The archive structure. 122 */ 123 void (*closeArchive)(CxArchive *archive); 124 125 /** 126 * Opens a contained file for reading, writing, or appending. 127 * 128 * @param file The file structure. 129 * @param mode The access mode. 130 * 131 * @return The file pointer to this file. 132 */ 133 CxFP *(*openFile)(CxFile *file, CxAccessMode mode); 134 135 /** 136 * Destroys the module-specific data in a contained file. 137 * 138 * @param file The file to destroy. 139 */ 140 void (*destroyFile)(CxFile *file); 141 142 /** 143 * Determines if the module supports the specified file extension. 144 * 145 * This should just give a best guess. All string comparisons should 146 * be case-insensitive. 147 * 148 * @param ext The extension (without the leading '.') 149 * 150 * @return 1 if the extension is supported; 0 otherwise. 151 */ 152 char (*supportsExtension)(const char *ext); 153 }; 154 155 /** 156 * @struct _CxSchemeOps module.h libcomprex/module.h 157 * 158 * Scheme operations structure. 159 * 160 * This structure is to be filled out by all modules that handle 161 * the retrieval of files from non-local locations. 162 * 163 * @see CxModuleType 164 * @see CxArchiveOps 165 */ 166 struct _CxSchemeOps 167 { 168 /** 169 * Retrieves a file from a non-local source. 170 * 171 * @param scheme The scheme part of the URI. 172 * @param path The path part of the URI. 173 * @param outFilename The destination filename. 174 * 175 * @return The status of the operation. 176 */ 177 CxStatus (*get)(const char *scheme, const char *path, 178 const char *outFilename); 179 180 /** 181 * Determines if the module supports the specified scheme. 182 * 183 * @param scheme The URI scheme to check. 184 * 185 * @return 1 if the scheme is supported; 0 otherwise. 186 */ 187 char (*supports)(const char *scheme); 188 }; 189 190 /** 191 * @struct _CxModule module.h libcomprex/module.h 192 * 193 * A file or scheme module. 194 * 195 * @see CxModuleType 196 * @see CxArchiveOps 197 * @see CxSchemeOps 198 */ 199 struct _CxModule 200 { 201 CxModuleType type; /**< The type of module. */ 202 203 char *filename; /**< The filename of the module. */ 204 char *name; /**< The name of the module. */ 205 void *handle; /**< The libtool handle. */ 206 207 unsigned int refCount; /**< The module's reference count. */ 208 209 union 210 { 211 CxArchiveOps *archive; /**< File operations. */ 212 CxSchemeOps *scheme; /**< Scheme operations. */ 213 214 } ops; /**< Operations. */ 215 216 CxModule *prev; /**< The previous module in the list. */ 217 CxModule *next; /**< The next module in the list. */ 218 }; 219 220 /** 221 * Registers a module. 222 * 223 * @param name The name of the module. 224 * @param ops The operations structure. 225 * @param type The type of module. 226 * 227 * @return The module structure, or @c NULL on failure. 228 */ 229 CxModule *cxRegisterModule(const char *name, void *ops, CxModuleType type); 230 231 /** 232 * Loads the module of the specified name and type. 233 * 234 * @param name The name of the module (without ".so") 235 * @param type The type of module. 236 * 237 * @return A CxModule structure representing the module. 238 * 239 * @see cxUnloadModule() 240 * @see cxGetModule() 241 */ 242 CxModule *cxLoadModule(const char *name, CxModuleType type); 243 244 /** 245 * Unloads the specified module. 246 * 247 * @param module The module to unload. 248 * 249 * @see cxLoadModule() 250 */ 251 void cxUnloadModule(CxModule *module); 252 253 /** 254 * Returns the specified module. 255 * 256 * The module 257 * 258 * @param name The name of the module. 259 * @param type The type of the module. 260 * 261 * @return A CxModule structure representing the module. 262 * 263 * @see cxLoadModule() 264 */ 265 CxModule *cxGetModule(const char *name, CxModuleType type); 266 267 /** 268 * Notifies libcomprex that the module is being used. 269 * 270 * This is used to increment the module's reference count. 271 * 272 * @param ptr The module. 273 * 274 * @see cxUnlinkModule() 275 */ 276 void cxLinkModule(CxModule **ptr); 277 278 /** 279 * Notifies libcomprex that the module is no longer being used. 280 * 281 * This is used to decrement the module's reference count. 282 * 283 * @see ptr The module. 284 * 285 * @see cxLinkModule() 286 */ 287 void cxUnlinkModule(CxModule **ptr); 288 289 /** 290 * Returns the first module in the list. 291 * 292 * This will probably only be useful inside libcomprex. 293 * 294 * @param type The type of module. 295 * 296 * @return The first module in the list. 297 * 298 * @see cxGetModule() 299 */ 300 CxModule *cxGetFirstModule(CxModuleType type); 301 302 /** 303 * Unloads all modules. 304 * 305 * This should only be called when you are absolutely done with 306 * this library. 307 * 308 * This will be automatically called by cxCleanup(). 309 * 310 * @see cxCleanup() 311 */ 312 void cxCleanupModules(); 313 314 /** 315 * Cleans up the entire library. 316 * 317 * This should only be called when you are absolutely done with 318 * this library. 319 * 320 * This will call cxCleanupModules() automatically. 321 * 322 * @see cxCleanupModules() 323 */ 324 void cxCleanup(void); 325 326 #ifdef __cplusplus 327 } 328 #endif 329 330 #endif /* _LIBCOMPREX_MODULE_H_ */ 331 332