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 28 #ifndef _h_vdb_dependencies_ 29 #define _h_vdb_dependencies_ 30 31 32 #ifndef _h_vdb_extern_ 33 #include <vdb/extern.h> 34 #endif 35 36 #ifndef _h_klib_rc_ 37 #include <klib/rc.h> 38 #endif 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 45 /*-------------------------------------------------------------------------- 46 * forwards 47 */ 48 struct VDatabase; 49 struct VTable; 50 51 52 /*-------------------------------------------------------------------------- 53 * VDBDependencies 54 * information about VDatabase dependencies 55 * 56 * object contains zero or more dependencies 57 * 58 * each dependency has a number of properties, accessible via index 59 */ 60 typedef struct VDBDependencies VDBDependencies; 61 62 63 /* AddRef 64 * Release 65 * all objects are reference counted 66 * NULL references are ignored */ 67 VDB_EXTERN rc_t CC VDBDependenciesAddRef ( const VDBDependencies *self ); 68 VDB_EXTERN rc_t CC VDBDependenciesRelease ( const VDBDependencies *self ); 69 70 /* ListDependencies 71 * create dependencies object: list dependencies 72 * 73 * Cache could be updated after the fuction call, if caching is enabled. 74 * 75 * "dep" [ OUT ] - return for VDBDependencies object 76 * 77 * "missing" [ IN ] - if true, list only missing dependencies 78 * otherwise, list all dependencies 79 */ 80 VDB_EXTERN rc_t CC VDatabaseListDependencies ( struct VDatabase const *self, 81 const VDBDependencies **dep, bool missing ); 82 83 /* ListDependenciesWithCaching 84 * create dependencies object: list dependencies 85 * 86 * Allows to control cache update inside the function. 87 * 88 * "dep" [ OUT ] - return for VDBDependencies object 89 * 90 * "missing" [ IN ] - if true, list only missing dependencies 91 * otherwise, list all dependencies 92 * 93 * "disableCaching" [ IN ] - if true, disable caching inside of the function 94 * otherwise, do not change the caching state 95 */ 96 VDB_EXTERN rc_t CC VDatabaseListDependenciesWithCaching ( 97 struct VDatabase const *self, 98 const VDBDependencies **dep, bool missing, 99 bool disableCaching ); 100 101 /* FindDependencies 102 * create dependencies object: list dependencies 103 * 104 * Don't resolve remote location if dependency was found locally. 105 * 106 * "dep" [ OUT ] - return for VDBDependencies object 107 */ 108 VDB_EXTERN rc_t CC VDatabaseFindDependencies(struct VDatabase const *self, 109 const VDBDependencies **dep); 110 111 112 /* Count 113 * retrieve the number of dependencies 114 * 115 * "count" [ OUT ] - return parameter for dependencies count 116 */ 117 VDB_EXTERN rc_t CC VDBDependenciesCount ( const VDBDependencies *self, 118 uint32_t *count ); 119 120 121 /* Type 122 * describe the dependency object type ( see kbd/manager.h ) 123 * 124 * "type" [ OUT ] - a KDBPathType 125 * 126 * "idx" [ IN ] - zero-based index of dependency 127 */ 128 VDB_EXTERN rc_t CC VDBDependenciesType ( const VDBDependencies *self, 129 uint32_t *type, uint32_t idx ); 130 131 132 /* Local 133 * retrieve local property 134 * 135 * "local" [ OUT ] - true if object is stored internally 136 * 137 * "idx" [ IN ] - zero-based index of dependency 138 */ 139 VDB_EXTERN rc_t CC VDBDependenciesLocal ( const VDBDependencies *self, 140 bool *local, uint32_t idx ); 141 142 143 /* SeqId 144 * retrieve sequence id of object 145 * 146 * "seq_id" [ OUT ] - returned pointer should not be freed. 147 * becomes invalid after VDBDependenciesRelease 148 * 149 * "idx" [ IN ] - zero-based index of dependency 150 */ 151 VDB_EXTERN rc_t CC VDBDependenciesSeqId ( const VDBDependencies *self, 152 const char **seq_id, uint32_t idx ); 153 154 155 /* Name 156 * retrieve object name 157 * 158 * "name" [ OUT ] - returner pointed should not be freed. 159 * it becomes invalid after VDBDependenciesRelease 160 * 161 * "idx" [ IN ] - zero-based index of dependency 162 */ 163 VDB_EXTERN rc_t CC VDBDependenciesName ( const VDBDependencies *self, 164 const char **name, uint32_t idx ); 165 166 167 /* Circular 168 * retrieve circular property 169 * reference sequences may be circular 170 * 171 * "circular" [ OUT ] - true if dependency is a circular reference table 172 * 173 * "idx" [ IN ] - zero-based index of dependency 174 */ 175 VDB_EXTERN rc_t CC VDBDependenciesCircular ( const VDBDependencies *self, 176 bool *circular, uint32_t idx ); 177 178 179 /* Path 180 * returns [Local] path for resolved dependency, 181 * returns NULL for local and missing dependency. 182 * 183 * "path" [ OUT ] - returned pointer should not be freed. 184 * it becomes invalid after VDBDependenciesRelease 185 * 186 * "idx" [ IN ] - zero-based index of dependency 187 */ 188 VDB_EXTERN rc_t CC VDBDependenciesPath ( const VDBDependencies *self, 189 const char **path, uint32_t idx ); 190 191 /* VPath 192 * returns [Local] path for resolved dependency, 193 * returns NULL for local and missing dependency. 194 * 195 * "path" [ OUT ] 196 * 197 * "idx" [ IN ] - zero-based index of dependency 198 */ 199 VDB_EXTERN rc_t CC VDBDependenciesVPath(const VDBDependencies *self, 200 const struct VPath **path, uint32_t idx); 201 202 /* PathRemote 203 * returns Remote path for dependency, 204 * returns NULL for not found dependency. 205 * 206 * "path" [ OUT ] - returned pointer should not be freed. 207 * it becomes invalid after VDBDependenciesRelease 208 * 209 * "idx" [ IN ] - zero-based index of dependency 210 */ 211 VDB_EXTERN rc_t CC VDBDependenciesPathRemote ( const VDBDependencies *self, 212 const char **path, uint32_t idx ); 213 214 /* PathCache 215 * returns Cache path for dependency, 216 * returns NULL for not found dependency. 217 * 218 * "path" [ OUT ] - returned pointer should not be freed. 219 * it becomes invalid after VDBDependenciesRelease 220 * 221 * "idx" [ IN ] - zero-based index of dependency 222 */ 223 VDB_EXTERN rc_t CC VDBDependenciesPathCache ( const VDBDependencies *self, 224 const char **path, uint32_t idx ); 225 226 227 /* RemoteAndCache 228 * returns Cache and remote path and rc_t for dependency. 229 * 230 * "idx" [ IN ] - zero-based index of dependency 231 */ 232 VDB_EXTERN rc_t CC VDBDependenciesRemoteAndCache(const VDBDependencies *self, 233 uint32_t idx, rc_t *remoteRc, const struct VPath **remote, 234 rc_t *cacheRc, const struct VPath **cache); 235 236 237 /* Error 238 * trying to analyze rc code and object 239 * in order to recognize dependencies error 240 * 241 * db OR table - only one is required 242 */ 243 VDB_EXTERN bool CC UIError( rc_t rc, 244 struct VDatabase const *db, struct VTable const *table); 245 246 /* report error(s) via PLOGERR based on an object 247 * log_list - if true logs the missing items list also 248 */ 249 VDB_EXTERN void CC UIDatabaseLOGError( rc_t rc, 250 struct VDatabase const *db, bool log_list ); 251 VDB_EXTERN void CC UITableLOGError( rc_t rc, 252 struct VTable const *table, bool log_list ); 253 254 /* return human-readable string explaining rc code. 255 * the string should not be freed 256 */ 257 VDB_EXTERN const char* CC UIDatabaseGetErrorString(rc_t rc); 258 259 #ifdef __cplusplus 260 } 261 #endif 262 263 264 #endif /* _h_vdb_dependencies_ */ 265