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 27 #ifndef _h_vfs_resolver_ 28 #define _h_vfs_resolver_ 29 30 #ifndef _h_vfs_extern_ 31 #include <vfs/extern.h> 32 #endif 33 34 #ifndef _h_klib_defs_ 35 #include <klib/defs.h> 36 #endif 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 43 /*-------------------------------------------------------------------------- 44 * forwards 45 */ 46 struct KFile; 47 struct VPath; 48 struct String; 49 struct KConfig; 50 struct KRepository; 51 struct VFSManager; 52 53 54 /*-------------------------------------------------------------------------- 55 * VResolver 56 */ 57 typedef struct VResolver VResolver; 58 59 60 /* Make 61 * ask the VFS manager to make a resolver 62 */ 63 VFS_EXTERN rc_t CC VFSManagerMakeResolver ( struct VFSManager const * self, 64 VResolver ** new_resolver, struct KConfig const * cfg ); 65 VFS_EXTERN rc_t CC KRepositoryMakeResolver ( struct KRepository const * self, 66 VResolver ** new_resolver, struct KConfig const * cfg ); 67 68 69 /* AddRef 70 * Release 71 */ 72 VFS_EXTERN rc_t CC VResolverAddRef ( const VResolver * self ); 73 VFS_EXTERN rc_t CC VResolverRelease ( const VResolver * self ); 74 75 76 /* VRemoteProtocols 77 * accepted protocol list 78 * there is a simple set of protocols 79 * where multiple protocols are involved, 80 * they are ordered by preference from LSB toward MSB 81 */ 82 typedef uint32_t VRemoteProtocols; 83 enum 84 { 85 /* version 1.1 protocols */ 86 eProtocolNone = 0 87 , eProtocolDefault = eProtocolNone 88 , eProtocolHttp = 1 89 , eProtocolFasp = 2 90 91 /* version 1.2 protocols */ 92 , eProtocolHttps = 3 93 94 /* version 3.0 protocols */ 95 , eProtocolFile = 4 96 , eProtocolS3 = 5 /* Amazon Simple Storage Service */ 97 , eProtocolGS = 6 /* Google Cloud Storage */ 98 99 /* value 7 are available for future */ 100 101 , eProtocolLast 102 , eProtocolMax = eProtocolLast - 1 103 , eProtocolMask = 7 104 105 , eProtocolMaxPref = 6 106 107 /* macros for building multi-protocol constants 108 ordered by preference from least to most significant bits */ 109 #define VRemoteProtocolsMake2( p1, p2 ) \ 110 ( ( ( VRemoteProtocols ) ( p1 ) & eProtocolMask ) | \ 111 ( ( ( VRemoteProtocols ) ( p2 ) & eProtocolMask ) << ( 3 * 1 ) ) ) 112 113 #define VRemoteProtocolsMake3( p1, p2, p3 ) \ 114 ( VRemoteProtocolsMake2 ( p1, p2 ) | \ 115 ( ( ( VRemoteProtocols ) ( p3 ) & eProtocolMask ) << ( 3 * 2 ) ) ) 116 117 #define VRemoteProtocolsMake4( p1, p2, p3, p4 ) \ 118 ( VRemoteProtocolsMake3 ( p1, p2, p3 ) | \ 119 ( ( ( VRemoteProtocols ) ( p4 ) & eProtocolMask ) << ( 3 * 3 ) ) ) 120 121 , eProtocolFaspHttp = VRemoteProtocolsMake2 ( eProtocolFasp, eProtocolHttp ) 122 , eProtocolHttpFasp = VRemoteProtocolsMake2 ( eProtocolHttp, eProtocolFasp ) 123 , eProtocolHttpsHttp = VRemoteProtocolsMake2 ( eProtocolHttps, eProtocolHttp ) 124 , eProtocolHttpHttps = VRemoteProtocolsMake2 ( eProtocolHttp, eProtocolHttps ) 125 , eProtocolFaspHttps = VRemoteProtocolsMake2 ( eProtocolFasp, eProtocolHttps ) 126 , eProtocolHttpsFasp = VRemoteProtocolsMake2 ( eProtocolHttps, eProtocolFasp ) 127 , eProtocolFaspHttpHttps = VRemoteProtocolsMake3 ( eProtocolFasp, eProtocolHttp, eProtocolHttps ) 128 , eProtocolHttpFaspHttps = VRemoteProtocolsMake3 ( eProtocolHttp, eProtocolFasp, eProtocolHttps ) 129 , eProtocolFaspHttpsHttp = VRemoteProtocolsMake3 ( eProtocolFasp, eProtocolHttps, eProtocolHttp ) 130 , eProtocolHttpHttpsFasp = VRemoteProtocolsMake3 ( eProtocolHttp, eProtocolHttps, eProtocolFasp ) 131 , eProtocolHttpsFaspHttp = VRemoteProtocolsMake3 ( eProtocolHttps, eProtocolFasp, eProtocolHttp ) 132 , eProtocolHttpsHttpFasp = VRemoteProtocolsMake3 ( eProtocolHttps, eProtocolHttp, eProtocolFasp ) 133 , eProtocolFileFaspHttpHttps= VRemoteProtocolsMake4 ( eProtocolFile, eProtocolFasp, eProtocolHttp, eProtocolHttps ) 134 }; 135 136 /* Parse 137 * parses a comma-separated list of case-insensitive protocols: 138 * 'http', 'https', 'fasp' 139 * 140 * trims white-space, ignores unrecognized and empty terms 141 * 142 * returns an ordered list of valid protocols 143 */ 144 VFS_EXTERN VRemoteProtocols CC VRemoteProtocolsParse ( struct String const * protos ); 145 146 /* Query 147 * resolve object location to either an existing local path, 148 * or a pair of remote URL + local cache location. 149 * 150 * "protocols" [ IN ] - the desired protocols for remote resolution 151 * 152 * "query" [ IN ] - a path that can represent: 153 * accession : a recognizable accession from NCBI or known organization 154 * obj-id : a dbGaP object id 155 * name : a dbGaP filename 156 * path : a filesystem path 157 * url : a remote location 158 * 159 * "local" [ OUT, NULL OKAY ] - optional return parameter for local path: 160 * accession : resolve to local user or site path 161 * obj-id : resolve to local user protected path 162 * name : resolve to local user protected path 163 * url : set to NULL 164 * 165 * "remote" [ OUT, NULL OKAY ] - optional return parameter for remote path: 166 * accession : resolve to URL 167 * obj-id : resolve to URL 168 * name : resolve to URL 169 * url : set to duplicate 170 * 171 * "cache" [ OUT, NULL OKAY ] - optional return parameter for cache path: 172 * accession : resolve to user cache path 173 * obj-id : resolve to user cache path 174 * path : set to NULL 175 * url : resolve to user cache path 176 * 177 * any of the output parameters may be NULL, but not all, i.e. there 178 * must be at least one non-NULL return parameter. 179 * 180 * if you DON'T want local resolution, pass NULL for "local" and 181 * the query will be resolved remotely. if you don't want remote 182 * resolution, pass NULL for "remote". 183 * 184 * a query that is resolved locally will always return NULL for 185 * "remote" and "cache", if the parameters are provided. 186 */ 187 VFS_EXTERN rc_t CC VResolverQuery ( const VResolver * self, 188 VRemoteProtocols protocols, struct VPath const * query, 189 struct VPath const ** local, struct VPath const ** remote, 190 struct VPath const ** cache ); 191 192 /* Local - DEPRECATED 193 * Find an existing local file/directory that is named by the accession. 194 * rcState of rcNotFound means it does not exist. 195 * 196 * other rc code for failure are possible. 197 * 198 * Accession must be an ncbi-acc scheme or a simple name with no 199 * directory paths. 200 */ 201 VFS_EXTERN rc_t CC VResolverLocal ( const VResolver * self, 202 struct VPath const * accession, struct VPath const ** path ); 203 204 205 /* Remote - DEPRECATED 206 * Find an existing remote file that is named by the accession. 207 * 208 * rcState of rcNotFound means it did not exist and can not be 209 * downloaded. Probably a bad accession name. 210 * 211 * Need a specific rc for no network configured. 212 * Need a specific rc for network access permitted. 213 * 214 * Other rc code for failure are possible. 215 * 216 * Accession must be an ncbi-acc scheme or a simple name with no 217 * directory paths. 218 * 219 */ 220 VFS_EXTERN rc_t CC VResolverRemote ( const VResolver * self, 221 VRemoteProtocols protocols, struct VPath const * accession, 222 struct VPath const ** path /* , struct KFile const ** opt_file_rtn */ ); 223 224 /* Cache - DEPRECATED 225 * Find a cache directory that might or might not contain a partially 226 * downloaded file. 227 * 228 * Accession must be an ncbi-acc scheme, an http url or a simple name with no 229 * directory paths. All three should return the same directory URL as a VPath. (?) 230 * Or should it be a directory or a file url depending upon finding a partial 231 * download? This would require co-ordination with all download mechanisms that 232 * we permit. 233 * 234 * With refseq holding wgs objects we have a case were the downloaded file is not 235 * named the same as the original accession as the file archive you want is a 236 * container for other files. 237 * 238 * Find local will give a path that has a special scheme in these cases. 239 * Find remote will give the url for the container that contains the accession 240 * so using the returned VPath from resolve remote is better than the original 241 * accession in this one case. I think... 242 */ 243 VFS_EXTERN rc_t CC VResolverCache ( const VResolver * self, 244 struct VPath const * url, struct VPath const ** path, uint64_t file_size ); 245 246 247 /* EnableState 248 * modifies how the various properties are interpreted 249 */ 250 typedef uint32_t VResolverEnableState; 251 enum 252 { 253 vrUseConfig = 0, /* take enable/disable state from KConfig */ 254 vrAlwaysEnable = 1, /* always enable, regardless of KConfig */ 255 vrAlwaysDisable = 2 /* always disable, regardless of KConfig */ 256 }; 257 258 259 /* LocalEnable 260 * modify settings for using local repositories, 261 * meaning site, user-public and user-protected. 262 * 263 * "enable" [ IN ] - enable or disable local access, 264 * or follow settings in KConfig 265 * 266 * returns the previous state of "remote-enabled" property 267 * 268 * NB - in VDB-2, the state is associated with library code 269 * shared libraries in separate closures will have separate 270 * state. this can only occur if dynamic ( manual ) loading of 271 * shared libraries is used, and will not occur with normal 272 * usage. in VDB-3 the state will be stored with the process, 273 * not the library. 274 */ 275 VFS_EXTERN VResolverEnableState CC VResolverLocalEnable ( const VResolver * self, 276 VResolverEnableState enable ); 277 278 279 /* RemoteEnable 280 * modify settings for using remote repositories 281 * 282 * "enable" [ IN ] - enable or disable remote access, 283 * or follow settings in KConfig 284 * 285 * returns the previous state of "remote-enabled" property 286 * 287 * NB - in VDB-2, the state is associated with library code 288 * shared libraries in separate closures will have separate 289 * state. this can only occur if dynamic ( manual ) loading of 290 * shared libraries is used, and will not occur with normal 291 * usage. in VDB-3 the state will be stored with the process, 292 * not the library. 293 */ 294 VFS_EXTERN VResolverEnableState CC VResolverRemoteEnable ( const VResolver * self, 295 VResolverEnableState enable ); 296 297 298 /* CacheEnable 299 * modify settings for caching files in user repositories 300 * 301 * "enable" [ IN ] - enable or disable user repository cache, 302 * or follow settings in KConfig 303 * 304 * returns the previous state of "cache-enabled" property 305 * 306 * NB - in VDB-2, the state is associated with library code 307 * shared libraries in separate closures will have separate 308 * state. this can only occur if dynamic ( manual ) loading of 309 * shared libraries is used, and will not occur with normal 310 * usage. in VDB-3 the state will be stored with the process, 311 * not the library. 312 */ 313 VFS_EXTERN VResolverEnableState CC VResolverCacheEnable ( const VResolver * self, 314 VResolverEnableState enable ); 315 316 317 #ifdef __cplusplus 318 } 319 #endif 320 321 #endif /* _h_vfs_resolver_ */ 322