1 /*=========================================================================== 2 * 3 * PUBLIC DOMAIN NOTICE 4 * National Center for Biotechnology Information 5 * 6 * This software/database is a "United States Government Work" under the 7 * terms of the United States Copyright Act. It was written as part of 8 * the author's official duties as a United States Government employee and 9 * thus cannot be copyrighted. This software/database is freely available 10 * to the public for use. The National Library of Medicine and the U.S. 11 * Government have not placed any restriction on its use or reproduction. 12 * 13 * Although all reasonable efforts have been taken to ensure the accuracy 14 * and reliability of the software and data, the NLM and the U.S. 15 * Government do not and cannot warrant the performance or results that 16 * may be obtained by using this software or data. The NLM and the U.S. 17 * Government disclaim all warranties, express or implied, including 18 * warranties of performance, merchantability or fitness for any particular 19 * purpose. 20 * 21 * Please cite the author in any work or product based on this material. 22 * 23 * =========================================================================== 24 * 25 */ 26 #ifndef _h_vfs_manager_ 27 #define _h_vfs_manager_ 28 29 #ifndef _h_vfs_extern_ 30 #include <vfs/extern.h> 31 #endif 32 33 #ifndef _h_klib_defs_ 34 #include <klib/defs.h> 35 #endif 36 37 38 #ifndef _h_kfs_defs_ 39 #include <kfs/defs.h> 40 #endif 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 47 /*-------------------------------------------------------------------------- 48 * forwards 49 */ 50 struct KFile; 51 struct VPath; 52 struct VResolver; 53 struct KDirectory; 54 struct KNSManager; 55 56 /* temporary */ 57 58 59 /*-------------------------------------------------------------------------- 60 * VFSManager 61 */ 62 typedef struct VFSManager VFSManager; 63 64 #define VFS_KRYPTO_PASSWORD_MAX_SIZE 4096 65 66 67 /* AddRef 68 * Release 69 * ignores NULL references 70 */ 71 VFS_EXTERN rc_t CC VFSManagerAddRef ( const VFSManager *self ); 72 VFS_EXTERN rc_t CC VFSManagerRelease ( const VFSManager *self ); 73 74 /* OpenFileRead 75 * opens an existing file with read-only access 76 * 77 * "f" [ OUT ] - return parameter for newly opened file 78 * 79 * "path" [ IN ] VPath representing the path, URL or URN of the desired file 80 */ 81 VFS_EXTERN rc_t CC VFSManagerOpenFileRead ( const VFSManager *self, 82 struct KFile const **f, 83 const struct VPath * path ); 84 85 VFS_EXTERN rc_t CC VFSManagerOpenFileReadWithBlocksize ( const VFSManager *self, 86 struct KFile const **f, 87 const struct VPath * path, 88 uint32_t blocksize, 89 bool promote ); 90 91 VFS_EXTERN rc_t CC VFSManagerOpenDirectoryRead ( const VFSManager *self, 92 struct KDirectory const **d, const struct VPath * path ); 93 94 /* it forces decryption to be used for kdb */ 95 VFS_EXTERN rc_t CC VFSManagerOpenDirectoryReadDecrypt ( const VFSManager *self, 96 struct KDirectory const **d, const struct VPath * path ); 97 98 /* VPath has already been resolved to a URL and an optional cache file */ 99 VFS_EXTERN rc_t CC VFSManagerOpenDirectoryReadDecryptRemote (const struct VFSManager *self, 100 struct KDirectory const **d, const struct VPath * path, const struct VPath * cache); 101 102 VFS_EXTERN rc_t CC VFSManagerOpenDirectoryUpdate ( const VFSManager *self, 103 struct KDirectory **d, const struct VPath * path ); 104 105 /* OpenFileWrite 106 * opens an existing file with write access 107 * 108 * "f" [ OUT ] - return parameter for newly opened file 109 * 110 * "update" [ IN ] - if true, open in read/write mode 111 * otherwise, open in write-only mode 112 * 113 * "path" [ IN ] VPath representing the path, URL or URN of the desired file 114 */ 115 VFS_EXTERN rc_t CC VFSManagerOpenFileWrite (const VFSManager *self, 116 struct KFile **f, 117 bool update, 118 const struct VPath * path); 119 120 /* CreateFile 121 * opens a file with write access 122 * 123 * "f" [ OUT ] - return parameter for newly opened file 124 * 125 * "update" [ IN ] - if true, open in read/write mode 126 * otherwise, open in write-only mode 127 * 128 * "access" [ IN ] - standard Unix access mode, e.g. 0664 129 * 130 * "mode" [ IN ] - a creation mode ( see explanation above ). 131 * 132 * "path" [ IN ] VPath representing the path, URL or URN of the desired file 133 */ 134 VFS_EXTERN rc_t CC VFSManagerCreateFile (const VFSManager *self, 135 struct KFile **f, 136 bool update, uint32_t access, 137 KCreateMode mode, 138 const struct VPath * path ); 139 140 141 /* Remove 142 * remove an accessible object from its directory 143 * 144 * "force" [ IN ] - if true and target is a directory, 145 * remove recursively 146 * 147 * "path" [ IN ] - NUL terminated string in directory-native 148 * character set denoting target object 149 */ 150 VFS_EXTERN rc_t CC VFSManagerRemove (const VFSManager *self, bool force, 151 const struct VPath * path ); 152 153 154 /* Make 155 */ 156 VFS_EXTERN rc_t CC VFSManagerMake ( VFSManager ** pmanager ); 157 158 /* GetCWD 159 */ 160 VFS_EXTERN rc_t CC VFSManagerGetCWD (const VFSManager * self, struct KDirectory ** cwd); 161 162 VFS_EXTERN rc_t CC VFSManagerGetResolver ( const VFSManager * self, struct VResolver ** resolver ); 163 164 VFS_EXTERN rc_t CC VFSManagerGetKNSMgr ( const VFSManager * self, struct KNSManager ** kns ); 165 166 167 VFS_EXTERN rc_t CC VFSManagerGetKryptoPassword (const VFSManager * self, char * new_password, size_t max_size, size_t * size); 168 169 /* 170 NULL value for self 171 RC (rcVFS, rcEncryptionKey, rcUpdating, rcSelf, rcNull); 172 173 NULL value for password or 0 value for size 174 RC (rcVFS, rcEncryptionKey, rcUpdating, rcParam, rcNull); 175 176 size greater than VFS_KRYPTO_PASSWORD_MAX_SIZE 177 RC (rcVFS, rcEncryptionKey, rcUpdating, rcSize, rcExcessive); 178 179 illegal CR or LF (NL) in the password 180 RC (rcVFS, rcEncryptionKey, rcUpdating, rcEncryptionKey, rcInvalid); 181 182 path/file name for password too long for function as written 183 RC (rcVFS, rcEncryptionKey, rcUpdating, rcPath, rcExcessive); 184 185 existing password path/file name is not a file 186 RC (rcVFS, rcEncryptionKey, rcUpdating, rcPath, rcIncorrect); 187 188 unknown file type for configured path/file name 189 RC (rcVFS, rcEncryptionKey, rcUpdating, rcPath, rcCorrupt); 190 191 incomplete writes to temporary password file 192 RC (rcVFS, rcEncryptionKey, rcWriting, rcFile, rcInsufficient); 193 194 other errors from KFS and KLIB 195 */ 196 197 /* pwd_dir[pwd_dir_size] - 198 Output parameters for path to directory containing the password file. 199 pwd_dir is not updated if pwd_dir == NULL or pwd_dir_size == 0 200 or pwd_dir_size is insufficient to copy the path 201 */ 202 VFS_EXTERN rc_t CC VFSManagerUpdateKryptoPassword (const VFSManager * self, 203 const char * password, 204 size_t size, 205 char * pwd_dir, 206 size_t pwd_dir_size); 207 208 209 VFS_EXTERN rc_t CC VFSManagerResolveSpec ( const VFSManager * self, 210 const char * spec, 211 struct VPath ** path_to_build, 212 const struct KFile ** remote_file, 213 const struct VPath ** local_cache, 214 bool resolve_acc ); 215 216 struct KDirectory; 217 218 VFS_EXTERN rc_t CC VFSManagerResolveSpecIntoDir ( const VFSManager * self, 219 const char * spec, 220 const struct KDirectory ** dir, 221 bool resolve_acc ); 222 223 /*-------------------------------------------------------------------------- 224 * KConfig 225 * placing some KConfig code that relies upon VFS here 226 */ 227 struct KConfig; 228 struct KConfigNode; 229 230 /* ReadVPath 231 * read a VPath node value 232 * 233 * self [ IN ] - KConfig object 234 * path [ IN ] - path to the node 235 * result [ OUT ] - return value (rc != 0 if cannot be converted) 236 * 237 */ 238 VFS_EXTERN rc_t CC KConfigReadVPath ( struct KConfig const* self, const char* path, struct VPath** result ); 239 240 /* ReadVPath 241 * read a VPath node value 242 * 243 * self [ IN ] - KConfigNode object 244 * result [ OUT ] - return value (rc != 0 if cannot be converted) 245 * 246 */ 247 VFS_EXTERN rc_t CC KConfigNodeReadVPath ( struct KConfigNode const *self, struct VPath** result ); 248 249 /* ResolvePath 250 * 251 * take a VPath and resolve to a final form apropriate for KDB 252 * 253 * that is take a relative path and resolve it against the CWD 254 * or take an accession and resolve into the local or remote 255 * VResolver file based on config. It is just a single resolution percall 256 * 257 * flags 258 * can disable all Accession resolution 259 * can let VPath With no scheme be treated as a possible accession 260 * 261 */ 262 263 /* bit values for flags */ 264 /* allow no local accession resolution */ 265 #define vfsmgr_rflag_no_acc_local (1<<0) 266 /* allow no remote accession resolution */ 267 #define vfsmgr_rflag_no_acc_remote (1<<1) 268 /* never do VResolver Accession resolution */ 269 #define vfsmgr_rflag_no_acc (vfsmgr_rflag_no_acc_local|vfsmgr_rflag_no_acc_remote) 270 /* use VResolver Accession resolution for simple names with no scheme */ 271 272 #define vfsmgr_rflag_kdb_acc (1<<2) 273 /* over ridden by vfsmgr_rflag_no_acc */ 274 275 276 VFS_EXTERN rc_t CC VFSManagerResolvePath (const VFSManager * self, 277 uint32_t flags, 278 const struct VPath * in_path, 279 struct VPath ** out_path); 280 281 VFS_EXTERN rc_t CC VFSManagerResolvePathRelative (const VFSManager * self, 282 uint32_t flags, 283 const struct VPath * base_path, 284 const struct VPath * in_path, 285 struct VPath ** out_path); 286 287 /* 288 * Registering bindings between dbGaP object Ids and object names 289 */ 290 291 /* VFSManagerRegisterObject 292 * registers a binding between an object Id and an object name (object = accession or dbGaP file) 293 * 294 * self [ IN ] - VFSManager object 295 * oid [ IN ] - object id 296 * obj [ IN ] - Vpath representing the object's name (scheme is "ncbi-acc" for accessions, "ncbi-file" for dbGaP files; 297 * the name itself is the 'path' component 298 */ 299 VFS_EXTERN rc_t CC VFSManagerRegisterObject(struct VFSManager* self, uint32_t oid, const struct VPath* obj); 300 301 /* VFSManagerGetObjectId 302 * look up an object id by an object name 303 * 304 * self [ IN ] - VFSManager object 305 * obj [ IN ] - Vpath representing the object's name (scheme is "ncbi-acc" for accessions, "ncbi-file" for dbGaP files; 306 * the name itself is the 'path' component 307 * oid [ OUT ] - object id 308 */ 309 VFS_EXTERN rc_t CC VFSManagerGetObjectId(const struct VFSManager* self, const struct VPath* obj, uint32_t* oid); 310 311 /* VFSManagerGetObject 312 * look up an object name by an object id 313 * 314 * self [ IN ] - VFSManager object 315 * oid [ IN ] - object id 316 * obj [ OUT ] - Vpath representing the object's name (scheme is "ncbi-acc" for accessions, "ncbi-file" for dbGaP files; 317 * the name itself is the 'path' component 318 */ 319 VFS_EXTERN rc_t CC VFSManagerGetObject(const struct VFSManager* self, uint32_t oid, struct VPath** obj); 320 321 /* SetAdCaching 322 * Enable Caching to Accession as Directory in cwd 323 */ 324 VFS_EXTERN 325 rc_t CC VFSManagerSetAdCaching(struct VFSManager* self, bool enabled); 326 327 328 /* CheckAd 329 * Verify that inPath is path/to/Accession-as-Directory (AD) 330 * if inPath is AD - resolve run in AD as outPath and return true 331 * otherwise - return false, don't set outPath 332 */ 333 VFS_EXTERN bool CC VFSManagerCheckAd(const struct VFSManager * self, 334 const struct VPath * inPath, const struct VPath ** outPath); 335 336 /* CheckEnvAndAd 337 * Verify that inPath is path/to/Accession-as-Directory (AD) 338 * if inPath is AD - resolve run in AD as outPath and return true 339 * otherwise - return false, don't set outPath 340 * 341 * Verify magic env.vars first 342 */ 343 VFS_EXTERN bool CC VFSManagerCheckEnvAndAd(const struct VFSManager * self, 344 const struct VPath * inPath, const struct VPath ** outPath); 345 346 347 /* LogNamesServiceErrors 348 * Enable/disable logging of error messages coming from names service 349 */ 350 VFS_EXTERN rc_t CC VFSManagerLogNamesServiceErrors(struct VFSManager* self, 351 bool enabled); 352 VFS_EXTERN rc_t CC VFSManagerGetLogNamesServiceErrors(VFSManager * self, 353 bool * enabled); 354 355 356 #ifdef __cplusplus 357 } 358 #endif 359 360 #endif /* _h_kfs_manager_ */ 361