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_kfg_repository_ 28 #define _h_kfg_repository_ 29 30 31 #ifndef _h_kfg_extern_ 32 #include <kfg/extern.h> 33 #endif 34 35 #ifndef _h_klib_vector_ 36 #include <klib/vector.h> /* Vector */ 37 #endif 38 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 45 /*-------------------------------------------------------------------------- 46 * forwards 47 */ 48 struct KConfig; 49 struct KNgcObj; 50 51 /*-------------------------------------------------------------------------- 52 * KRepository 53 * presents structured access to a storage repository 54 * as modeled in KConfig. 55 * 56 * all objects are obtained via KRepositoryMgr ( see below ) 57 */ 58 typedef struct KRepository KRepository; 59 60 61 /* AddRef 62 * Release 63 */ 64 KFG_EXTERN rc_t CC KRepositoryAddRef ( const KRepository *self ); 65 KFG_EXTERN rc_t CC KRepositoryRelease ( const KRepository *self ); 66 67 68 /* Category 69 * SubCategory 70 * tells what the repository category or sub-category are 71 * or returns "bad" if the repository object is not usable. 72 */ 73 typedef uint32_t KRepCategory; 74 enum 75 { 76 krepBadCategory, 77 krepUserCategory, 78 krepSiteCategory, 79 krepRemoteCategory 80 }; 81 82 typedef uint32_t KRepSubCategory; 83 enum 84 { 85 krepBadSubCategory, 86 krepMainSubCategory, 87 krepAuxSubCategory, 88 krepProtectedSubCategory 89 }; 90 91 KFG_EXTERN KRepCategory CC KRepositoryCategory ( const KRepository *self ); 92 KFG_EXTERN KRepSubCategory CC KRepositorySubCategory ( const KRepository *self ); 93 94 95 /* Name 96 * get the repository name 97 * attempts to copy NUL-terminated name into provided buffer 98 * 99 * "buffer" [ OUT ] and "bsize" [ IN ] - name output parameter 100 * 101 * "name_size" [ OUT, NULL OKAY ] - returns the name size in 102 * bytes, excluding any NUL termination. 103 */ 104 KFG_EXTERN rc_t CC KRepositoryName ( const KRepository *self, 105 char *buffer, size_t bsize, size_t *name_size ); 106 107 108 /* DisplayName 109 * get the repository display name, 110 * if different from its actual name 111 * 112 * attempts to copy NUL-terminated name into provided buffer 113 * 114 * "buffer" [ OUT ] and "bsize" [ IN ] - name output parameter 115 * 116 * "name_size" [ OUT, NULL OKAY ] - returns the name size in 117 * bytes, excluding any NUL termination. 118 */ 119 KFG_EXTERN rc_t CC KRepositoryDisplayName ( const KRepository *self, 120 char *buffer, size_t bsize, size_t *name_size ); 121 122 123 /* Root 124 * read the root path as a POSIX path or URL 125 * 126 * attempts to copy NUL-terminated path into provided buffer 127 * 128 * "buffer" [ OUT ] and "bsize" [ IN ] - path output parameter 129 * 130 * "root_size" [ OUT, NULL OKAY ] - returns the path size in 131 * bytes, excluding any NUL termination. 132 */ 133 KFG_EXTERN rc_t CC KRepositoryRoot ( const KRepository *self, 134 char *buffer, size_t bsize, size_t *root_size ); 135 136 137 /* SetRoot 138 * set the root path 139 * 140 * "root" [ IN ] and "root_size" [ IN ] - path input parameter 141 */ 142 KFG_EXTERN rc_t CC KRepositorySetRoot( KRepository *self, 143 const char *root, size_t root_size ); 144 145 146 /* RootHistory 147 * read the root-history as a semicolon separated list of POSIX paths 148 * 149 * attempts to copy NUL-terminated path into provided buffer 150 * 151 * "buffer" [ OUT ] and "bsize" [ IN ] - path output parameter 152 * 153 * "roothistory_size" [ OUT, NULL OKAY ] - returns the root-history 154 * size in bytes, excluding any NUL termination. 155 */ 156 KFG_EXTERN rc_t CC KRepositoryRootHistory ( const KRepository *self, 157 char *buffer, size_t bsize, size_t *roothistory_size ); 158 159 160 /* SetRootHistory 161 * set the root-history list of paths 162 * 163 * "roothistory" [ IN ] and "roothistory_size" [ IN ] - path input parameter 164 */ 165 KFG_EXTERN rc_t CC KRepositorySetRootHistory( KRepository *self, 166 const char *roothistory, size_t roothistory_size ); 167 168 169 /* AppendToRootHistory 170 * append to the root-history 171 * 172 * "roothistory" [ IN ] and "roothistory_size" [ IN ] - path input parameter 173 * if item == NULL, add the current root to the root-history 174 */ 175 KFG_EXTERN rc_t CC KRepositoryAppendToRootHistory( KRepository *self, 176 const char *item ); 177 178 179 /* Resolver 180 * read the url of the CGI-resolver 181 * 182 * attempts to copy NUL-terminated path into provided buffer 183 * 184 * "buffer" [ OUT ] and "bsize" [ IN ] - path output parameter 185 * 186 * "written" [ OUT, NULL OKAY ] - returns the url size in 187 * bytes, excluding any NUL termination. 188 */ 189 KFG_EXTERN rc_t CC KRepositoryResolver ( const KRepository *self, 190 char *buffer, size_t bsize, size_t *written ); 191 192 193 /* Disabled 194 * discover whether the repository is enabled 195 */ 196 KFG_EXTERN bool CC KRepositoryDisabled ( const KRepository *self ); 197 198 199 /* Set Disabled 200 * changes the status of a repository, writes status into kfg-file on disk 201 * disabled = true ... disables the repository 202 * disabled = false ... enables the repository 203 */ 204 KFG_EXTERN rc_t CC KRepositorySetDisabled ( const KRepository *self, bool disabled ); 205 206 207 /* CacheEnabled 208 * discover whether the repository supports caching 209 */ 210 KFG_EXTERN bool CC KRepositoryCacheEnabled ( const KRepository *self ); 211 212 213 /* DownloadTicket 214 * return any associated download ticket 215 * 216 * attempts to copy NUL-terminated ticket into provided buffer 217 * 218 * "buffer" [ OUT ] and "bsize" [ IN ] - ticket output parameter 219 * 220 * "ticket_size" [ OUT, NULL OKAY ] - returns the ticket size in 221 * bytes, excluding any NUL termination. 222 */ 223 KFG_EXTERN rc_t CC KRepositoryDownloadTicket ( const KRepository *self, 224 char *buffer, size_t bsize, size_t *ticket_size ); 225 226 227 /* EncryptionKey 228 * return any associated encryption key 229 * 230 * attempts to copy NUL-terminated key into provided buffer 231 * 232 * "buffer" [ OUT ] and "bsize" [ IN ] - encryption key output parameter 233 * 234 * "key_size" [ OUT, NULL OKAY ] - returns the key size in 235 * bytes, excluding any NUL termination. 236 */ 237 KFG_EXTERN rc_t CC KRepositoryEncryptionKey ( const KRepository *self, 238 char *buffer, size_t bsize, size_t *key_size ); 239 240 241 /* EncryptionKeyFile 242 * return path to any associated encryption key file 243 * 244 * attempts to copy NUL-terminated path into provided buffer 245 * 246 * "buffer" [ OUT ] and "bsize" [ IN ] - key file path output parameter 247 * 248 * "path_size" [ OUT, NULL OKAY ] - returns the path size in 249 * bytes, excluding any NUL termination. 250 */ 251 KFG_EXTERN rc_t CC KRepositoryEncryptionKeyFile ( const KRepository *self, 252 char *buffer, size_t bsize, size_t *path_size ); 253 254 255 /* Description 256 * return any associated descriptive text 257 * 258 * attempts to copy NUL-terminated description into provided buffer 259 * 260 * "buffer" [ OUT ] and "bsize" [ IN ] - description text output parameter 261 * 262 * "desc_size" [ OUT, NULL OKAY ] - returns the text size in 263 * bytes, excluding any NUL termination. 264 */ 265 KFG_EXTERN rc_t CC KRepositoryDescription ( const KRepository *self, 266 char *buffer, size_t bsize, size_t *desc_size ); 267 268 269 /* ProjectId 270 * return project id for protected user repository 271 * return RC when repository is not user protected 272 * 273 * "projectId" [ OUT ] - returns the project id 274 */ 275 KFG_EXTERN rc_t CC KRepositoryProjectId 276 ( const KRepository * self, uint32_t * projectId ); 277 278 279 /* Description 280 * register an encrypted object in association with the repository's encryption key 281 */ 282 KFG_EXTERN rc_t CC KRepositoryRegisterObject ( const KRepository *self, const char* object_id ); 283 284 285 /*-------------------------------------------------------------------------- 286 * KRepositoryVector 287 * uses Vector API 288 * holds zero or more KRepository objects 289 */ 290 typedef struct Vector KRepositoryVector; 291 292 293 /* Whack 294 * destroy your vector 295 */ 296 KFG_EXTERN rc_t CC KRepositoryVectorWhack ( KRepositoryVector *self ); 297 298 299 /*-------------------------------------------------------------------------- 300 * KRepositoryMgr 301 * manages structured access to repositories 302 */ 303 typedef struct KRepositoryMgr KRepositoryMgr; 304 305 typedef uint32_t RepositorySelect; 306 enum 307 { 308 user = 1, 309 site = 2, 310 remote = 4, 311 }; 312 313 /* Make 314 * create a repository manager 315 * uses values from "self" 316 * 317 * mgr [ OUT ] 318 */ 319 KFG_EXTERN rc_t CC KConfigMakeRepositoryMgrRead ( struct KConfig const *self, const KRepositoryMgr **mgr ); 320 KFG_EXTERN rc_t CC KConfigMakeRepositoryMgrUpdate ( struct KConfig *self, KRepositoryMgr **mgr ); 321 322 323 /* AddRef 324 * Release 325 */ 326 KFG_EXTERN rc_t CC KRepositoryMgrAddRef ( const KRepositoryMgr *self ); 327 KFG_EXTERN rc_t CC KRepositoryMgrRelease ( const KRepositoryMgr *self ); 328 329 330 /* UserRepositories 331 * retrieve all user repositories in a Vector 332 */ 333 KFG_EXTERN rc_t CC KRepositoryMgrUserRepositories ( const KRepositoryMgr *self, 334 KRepositoryVector *user_repositories ); 335 336 337 /* SiteRepositories 338 * retrieve all site repositories in a Vector 339 */ 340 KFG_EXTERN rc_t CC KRepositoryMgrSiteRepositories ( const KRepositoryMgr *self, 341 KRepositoryVector *site_repositories ); 342 343 344 /* RemoteRepositories 345 * retrieve all remote repositories in a Vector 346 */ 347 KFG_EXTERN rc_t CC KRepositoryMgrRemoteRepositories ( const KRepositoryMgr *self, 348 KRepositoryVector *remote_repositories ); 349 350 /* CurrentProtectedRepository 351 * returns the currently active user protected repository 352 */ 353 KFG_EXTERN rc_t CC KRepositoryMgrCurrentProtectedRepository ( const KRepositoryMgr *self, 354 const KRepository **p_protected ); 355 356 /* GetProtectedRepository 357 * retrieves a (read-only) user protected repository by its associated project-id 358 */ 359 KFG_EXTERN rc_t CC KRepositoryMgrGetProtectedRepository ( const KRepositoryMgr *self, 360 uint32_t projectId, 361 const KRepository **p_protected ); 362 363 364 /* Getter/Setter for the global disabled-node on the main-category 365 */ 366 KFG_EXTERN bool CC KRepositoryMgrCategoryDisabled ( const KRepositoryMgr *self, KRepCategory category ); 367 KFG_EXTERN rc_t CC KRepositoryMgrCategorySetDisabled ( const KRepositoryMgr *self, KRepCategory category, bool disabled ); 368 369 370 /* ImportNgc 371 * import ngc file into current configuration 372 * 373 * self [ IN ] - KConfig object 374 * path [ IN ] - path to the ngc file 375 * pathToProtectedRepository [ IN, NULL OKAY ] - optional - the 376 * special value NULL is interpreted as ${HOME}/ncbi/dbGaP-$(Project #) 377 * newRepoParentPath [ OUT, NULL OKAY ] - optional - 378 * path to the new protected repository: should not be released! 379 */ 380 KFG_EXTERN rc_t CC KConfigImportNgc( struct KConfig * self, 381 const char *ngcPath, const char *pathToProtectedRepository, 382 const char **newRepoParentPath); 383 384 385 enum 386 { 387 /* on input, these bits represent authority to perform operation. 388 on success, they represent operations performed. 389 on failure, they represent reason for failure. */ 390 391 INP_CREATE_REPOSITORY = ( 1 << 0 ), /* permission to create a new entry */ 392 INP_UPDATE_DNLD_TICKET = ( 1 << 1 ), /* permission to modifify a download ticket */ 393 INP_UPDATE_ENC_KEY = ( 1 << 2 ), /* permission to modify an encryption key */ 394 INP_UPDATE_DESC = ( 1 << 3 ), /* permission to modify a description */ 395 INP_UPDATE_ROOT = ( 1 << 4 ), /* permission to modify root path */ 396 397 INP_UPDATE_APPS = ( 1 << 5 ), /* modify apps : 398 is used as return value only: 399 permission is not required - apps update it will be always performed */ 400 }; 401 402 /* ImportNgcObj 403 * import of a KNgcObj 404 * 405 * the KNgcObj has to be created with KNgcObjMakeFromFile() kfg/ngc.h 406 * the permission-flags define what the functions is allowd to do 407 * result flags show what was done according to the permissions 408 */ 409 KFG_EXTERN rc_t CC KRepositoryMgrImportNgcObj( KRepositoryMgr *self, 410 const struct KNgcObj * ngc, const char * location, uint32_t permissions, uint32_t * result_flags ); 411 412 413 /* HasRemoteAccess 414 * whether remote access is available (has an enabled remote repository) 415 */ 416 KFG_EXTERN bool CC KRepositoryMgrHasRemoteAccess ( const KRepositoryMgr *self ); 417 418 419 #ifdef __cplusplus 420 } 421 #endif 422 423 #endif /* _h_kfg_repository_ */ 424