1 #ifndef _h_diagnose_diagnose_ 2 #define _h_diagnose_diagnose_ 3 4 /*=========================================================================== 5 * 6 * PUBLIC DOMAIN NOTICE 7 * National Center for Biotechnology Information 8 * 9 * This software/database is a "United States Government Work" under the 10 * terms of the United States Copyright Act. It was written as part of 11 * the author's official duties as a United States Government employee and 12 * thus cannot be copyrighted. This software/database is freely available 13 * to the public for use. The National Library of Medicine and the U.S. 14 * Government have not placed any restriction on its use or reproduction. 15 * 16 * Although all reasonable efforts have been taken to ensure the accuracy 17 * and reliability of the software and data, the NLM and the U.S. 18 * Government do not and cannot warrant the performance or results that 19 * may be obtained by using this software or data. The NLM and the U.S. 20 * Government disclaim all warranties, express or implied, including 21 * warranties of performance, merchantability or fitness for any particular 22 * purpose. 23 * 24 * Please cite the author in any work or product based on this material. 25 * 26 * =========================================================================== 27 * 28 */ 29 30 #ifndef _h_diagnose_extern_ 31 #include <diagnose/extern.h> 32 #endif 33 34 #ifndef _h_klib_defs_ 35 #include <klib/defs.h> /* rc_t */ 36 #endif 37 38 #include <stdarg.h> /* va_list */ 39 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 46 struct KConfig; 47 struct KFile; 48 struct KNSManager; 49 struct VFSManager; 50 51 52 typedef struct KDiagnose KDiagnose; 53 typedef struct KDiagnoseError KDiagnoseError; 54 typedef struct KDiagnoseTest KDiagnoseTest; 55 typedef struct KDiagnoseTestDesc KDiagnoseTestDesc; 56 57 58 /**************************** Make/AddRef/Release *****************************/ 59 60 DIAGNOSE_EXTERN rc_t CC KDiagnoseMakeExt ( KDiagnose ** test, 61 struct KConfig * kfg, struct KNSManager * kmg, struct VFSManager * vmgr, rc_t (CC *quitting)(void)); 62 DIAGNOSE_EXTERN rc_t CC KDiagnoseAddRef ( const KDiagnose * self ); 63 DIAGNOSE_EXTERN rc_t CC KDiagnoseRelease ( const KDiagnose * self ); 64 65 /********************************** Feedback **********************************/ 66 67 /* 68 * TestHandlerSet: set a test callback 69 * the callback is called when each test is started or finished 70 * 71 * state - state of the test 72 * test - test being executed. 73 * test remains valid when KDiagnose is valid; 74 * KDiagnoseTestAddRef if you want to keep it after KDiagnose is released 75 */ 76 typedef enum { 77 eKDTS_NotStarted,/* test not started yet */ 78 eKDTS_Started, /* test started */ 79 eKDTS_Succeed, /* test finished successfully */ 80 eKDTS_Failed, /* test finished with failure */ 81 eKDTS_Skipped, /* test execution was skipped */ 82 eKDTS_Warning, /* test finished successfully but has a warning for user */ 83 eKDTS_Paused, /* KDiagnosePause was called */ 84 eKDTS_Resumed, /* KDiagnoseResume was called */ 85 eKDTS_Canceled, /* KDiagnoseCancel was called */ 86 } EKDiagTestState; 87 88 /* test is NULL when state is one of: 89 * eKDTS_Paused 90 * eKDTS_Resumed 91 * eKDTS_Canceled 92 */ 93 DIAGNOSE_EXTERN rc_t CC KDiagnoseTestHandlerSet ( KDiagnose * self, 94 void ( CC * callback ) 95 ( EKDiagTestState state, const KDiagnoseTest * test, void * data ), 96 void * data 97 ); 98 99 /********************************** Logging **********************************/ 100 101 #define KVERBOSITY_NONE -3 102 #define KVERBOSITY_ERROR -2 103 #define KVERBOSITY_INFO -1 104 #define KVERBOSITY_MAX 0 105 DIAGNOSE_EXTERN rc_t CC KDiagnoseSetVerbosity ( KDiagnose * self, 106 int verbosity ); 107 108 109 DIAGNOSE_EXTERN rc_t CC KDiagnoseLogHandlerSet ( KDiagnose * self, 110 rc_t ( CC * logger ) ( int verbosity, 111 unsigned type, /* TBD */ 112 const char * fmt, va_list args ) 113 ); 114 115 DIAGNOSE_EXTERN rc_t CC KDiagnoseLogHandlerSetKOutMsg ( KDiagnose * self ); 116 117 /********************************* Executing **********************************/ 118 119 /* All 120 * Default function to execute - diagnose the system. 121 * Check everything and warn when something is not right. 122 * Do not fail when it might not cause failure. 123 * set 'advanced' to 0 124 */ 125 DIAGNOSE_EXTERN rc_t CC KDiagnoseAll ( KDiagnose * self, uint64_t advanced ); 126 127 /* Acc 128 * Diagnose user system, make sure 'acc' (optional) can be accessed in the 129 * scope of projectId ( 'projectId' = 0 : public accession ). 130 * Return non-0 rc when it cannot be accessed or downloaded 131 * set 'advanced' to 0 132 */ 133 DIAGNOSE_EXTERN rc_t CC KDiagnoseAcc ( KDiagnose * self, const char * acc, 134 uint32_t projectId, bool checkHttp, bool checkAspera, bool checkDownload, 135 uint64_t advanced ); 136 137 /* Kart 138 * Diagnose that the kart file can be accessed. 139 * Check 'numberOfKartItemsToCheck' rows ( 0 means 'all' ) 140 * set 'advanced' to 0 141 */ 142 DIAGNOSE_EXTERN rc_t CC KDiagnoseKart ( KDiagnose * self, 143 const struct KFile * kart, uint32_t numberOfKartItemsToCheck, 144 bool checkHttp, bool checkAspera, uint64_t advanced ); 145 146 /***************************** Process management *****************************/ 147 148 DIAGNOSE_EXTERN rc_t CC KDiagnosePause ( KDiagnose * self ); 149 DIAGNOSE_EXTERN rc_t CC KDiagnoseResume ( KDiagnose * self ); 150 DIAGNOSE_EXTERN rc_t CC KDiagnoseCancel ( KDiagnose * self ); 151 152 /************************ Diagnostics results: errors *************************/ 153 154 DIAGNOSE_EXTERN rc_t CC KDiagnoseGetErrorCount ( const KDiagnose * self, 155 uint32_t * count ); 156 157 DIAGNOSE_EXTERN rc_t CC KDiagnoseGetError ( const KDiagnose * self, 158 uint32_t idx, const KDiagnoseError ** error ); 159 160 DIAGNOSE_EXTERN rc_t CC KDiagnoseErrorAddRef ( const KDiagnoseError * self ); 161 DIAGNOSE_EXTERN rc_t CC KDiagnoseErrorRelease ( const KDiagnoseError * self ); 162 163 /* GetMsg: 164 * Get Error Message. 165 * Returned string remains valid while "self" is valid 166 */ 167 DIAGNOSE_EXTERN rc_t CC KDiagnoseErrorGetMsg ( const KDiagnoseError * self, 168 const char ** message ); 169 170 /******************** Diagnostics results: executed tests *********************/ 171 172 /* GetTests: 173 * Get executed tests 174 */ 175 DIAGNOSE_EXTERN rc_t CC KDiagnoseGetTests ( const KDiagnose * self, 176 const KDiagnoseTest ** test ); 177 178 /* Level 179 * 180 * Get test level in tests hierarchy. 181 * 0 is the highest level 182 * tests of 'level 1' are run from test of 'level 0' etc 183 */ 184 DIAGNOSE_EXTERN rc_t CC KDiagnoseTestLevel ( const KDiagnoseTest * self, 185 uint32_t * level ); 186 187 /* Number 188 * 189 * Get hiererchical number of test inside of est level in tests hierarchy. 190 * E.g., 0.2.2 191 */ 192 DIAGNOSE_EXTERN rc_t CC KDiagnoseTestNumber ( const KDiagnoseTest * self, 193 const char ** number ); 194 195 /* Name 196 * 197 * Get test name. 198 */ 199 DIAGNOSE_EXTERN rc_t CC KDiagnoseTestName ( const KDiagnoseTest * self, 200 const char ** name ); 201 202 /* Code 203 * 204 * Get test's code. 205 */ 206 DIAGNOSE_EXTERN rc_t CC KDiagnoseTestCode ( const KDiagnoseTest * self, 207 uint64_t * code ); 208 209 /* Message 210 * 211 * Get test message (is set when test is finished) 212 */ 213 DIAGNOSE_EXTERN rc_t CC KDiagnoseTestMessage ( const KDiagnoseTest * self, 214 const char ** message ); 215 216 /* State 217 * 218 * Get test state ( changes during test execution ) 219 */ 220 DIAGNOSE_EXTERN rc_t CC KDiagnoseTestState ( const KDiagnoseTest * self, 221 EKDiagTestState * state ); 222 223 DIAGNOSE_EXTERN rc_t CC KDiagnoseTestNext ( const KDiagnoseTest * self, 224 const KDiagnoseTest ** test ); 225 226 DIAGNOSE_EXTERN rc_t CC KDiagnoseTestChild ( const KDiagnoseTest * self, 227 uint32_t idx, const KDiagnoseTest ** test ); 228 229 /********************************** Anvanced **********************************/ 230 231 /* Advanced 232 * Run KDiagnose tests 233 * 234 * tests is combination of DIAGNOSE_* values 235 * 236 * When "tests | KDIAGN_FAIL != 0" - KDiagnoseAdvanced will return non-0 rc 237 * When KDiagnoseCancel is called - KDiagnose will return rcCanceled 238 * 239 * If 'tests' contain KDIAGN_REPO_GAP 240 * and/or DIAGNOSE_NETWORK_HTTPS/DIAGNOSE_NETWORK_ASPERA 241 * - we will try to check existing dbGaP configuration and access to dbGaP 242 * servers and issue WARNINGS if something is not correct. 243 */ 244 DIAGNOSE_EXTERN rc_t CC KDiagnoseAdvanced ( KDiagnose * self, uint64_t tests ); 245 246 #define KDIAGN_FAIL 0x8000000000000000 247 248 #define KDIAGN_REPO_REMOTE 0x1 249 #define KDIAGN_REPO_SITE 0x2 250 #define KDIAGN_REPO_USER_PUBLIC 0x4 251 #define KDIAGN_REPO_GAP 0x8 252 #define KDIAGN_KFG_ASCP 0x10 253 254 #define KDIAGN_ACCESS_NCBI_HTTP 0x20 255 #define KDIAGN_ACCESS_NCBI_HTTPS 0x40 256 #define KDIAGN_ACCESS_NCBI_FTP 0x80 257 #define KDIAGN_ACCESS_NCBI_VERSION 0x100 258 259 #define KDIAGN_HTTP 0x200 260 #define KDIAGN_HTTP_RUN ( 0x400 | KDIAGN_HTTP ) 261 #define KDIAGN_HTTP_CGI 0x800 262 #define KDIAGN_HTTP_SMALL_ACCESS 0x1000 263 #define KDIAGN_HTTP_SMALL_VFS 0x2000 264 265 #define KDIAGN_ASCP 0x4000 266 #define KDIAGN_ASCP_RUN ( 0x8000 | KDIAGN_ASCP ) 267 #define KDIAGN_ASCP_CGI 0x10000 268 #define KDIAGN_ASCP_DOWNLOAD 0x20000 269 270 #define KDIAGN_HTTP_VS_ASCP 0x40000 271 272 #define KDIAGN_DOWNLOAD_HTTP 0x80000 273 #define KDIAGN_DOWNLOAD_ASCP 0x100000 274 275 #define KDIAGN_REQUIRE_HTTP_AND_ASCP 0x200000 276 277 #define KDIAGN_TRY_TO_WARN 0x400000 278 279 #define KDIAGN_AS_IS 0x800000 280 281 #define KDIAGN_KFG_NO_GAP ( KDIAGN_REPO_REMOTE | KDIAGN_REPO_SITE | \ 282 KDIAGN_REPO_USER_PUBLIC | KDIAGN_KFG_ASCP ) 283 284 #define KDIAGN_CONFIG ( KDIAGN_KFG_NO_GAP | KDIAGN_REPO_GAP ) 285 286 #define KDIAGN_ACCESS_NCBI ( KDIAGN_ACCESS_NCBI_HTTP | \ 287 KDIAGN_ACCESS_NCBI_HTTPS | KDIAGN_ACCESS_NCBI_FTP | \ 288 KDIAGN_ACCESS_NCBI_VERSION) 289 290 #define KDIAGN_NETWORK ( KDIAGN_ACCESS_NCBI | \ 291 KDIAGN_HTTP | KDIAGN_HTTP_RUN | KDIAGN_HTTP_CGI | \ 292 KDIAGN_ASCP | KDIAGN_ASCP_RUN | KDIAGN_ASCP_CGI | \ 293 KDIAGN_HTTP_VS_ASCP ) 294 295 #define KDIAGN_ALL ( ~ KDIAGN_FAIL ) 296 297 /******************************************************************************/ 298 299 /*#define DIAGNOSE_NETWORK_NCBI 8 300 #define DIAGNOSE_NETWORK_HTTPS 16 301 #define DIAGNOSE_NETWORK_ASPERA 32 302 #define DIAGNOSE_NETWORK_DB_GAP 64 303 #define DIAGNOSE_NETWORK \ 304 ( DIAGNOSE_NETWORK_NCBI | DIAGNOSE_NETWORK_HTTPS | DIAGNOSE_NETWORK_ASPERA \ 305 | DIAGNOSE_NETWORK_DB_GAP ) 306 307 #define KDIAGN_ALL ( DIAGNOSE_CONFIG | DIAGNOSE_NETWORK )*/ 308 309 310 /* DbGap 311 * Diagnose user system, projects with 'projectId' can be accessed. 312 * The last 'projectId' in the argument list is 0 313 * 314 * Configuration WILL BE checked for VALIDIRY of 315 * projectId's project and access to gbGaP servers. 316 * KDiagnoseDbGap WILL FAIL if configuration is not complete or no gbGaP server 317 * can be accessed. 318 * 319 DIAGNOSE_EXTERN rc_t CC KDiagnoseDbGap ( KDiagnose * self, uint64_t tests, 320 uint32_t projectId, ... );*/ 321 /******************************************************************************/ 322 323 324 /* GetDesc: 325 * Get description of available tests 326 * Returned object remains valid while "self" is valid 327 */ 328 DIAGNOSE_EXTERN rc_t CC KDiagnoseGetDesc ( const KDiagnose * self, 329 const KDiagnoseTestDesc ** desc ); 330 331 /* KDiagnoseTestDesc...: 332 * Get description KDiagnoseTestDesc 333 * Returned object remains valid while "self" is valid 334 */ 335 336 /* Name: 337 * test name 338 */ 339 DIAGNOSE_EXTERN rc_t CC KDiagnoseTestDescName ( const KDiagnoseTestDesc * self, 340 const char ** name ); 341 342 /* Desc: 343 * test description 344 */ 345 DIAGNOSE_EXTERN rc_t CC KDiagnoseTestDescDesc ( const KDiagnoseTestDesc * self, 346 const char ** desc ); 347 348 /* Desc: 349 * test code to be used to form 'tests' argument of KDiagnoseAdvanced() 350 */ 351 DIAGNOSE_EXTERN rc_t CC KDiagnoseTestDescCode ( const KDiagnoseTestDesc * self, 352 uint64_t * code ); 353 354 /* Level: 355 * test level in tests hierarchy. 356 * 0 is the highest level 357 * tests of 'level 1' are subtests of 'level 0' etc 358 */ 359 DIAGNOSE_EXTERN rc_t CC KDiagnoseTestDescLevel ( const KDiagnoseTestDesc * self, 360 uint32_t * level ); 361 362 /* Next: 363 * next test of the same level 364 */ 365 DIAGNOSE_EXTERN rc_t CC KDiagnoseTestDescNext ( const KDiagnoseTestDesc * self, 366 const KDiagnoseTestDesc ** next ); 367 368 /* Child: 369 * the first child test of next level 370 */ 371 DIAGNOSE_EXTERN rc_t CC KDiagnoseTestDescChild ( const KDiagnoseTestDesc * self, 372 const KDiagnoseTestDesc ** child ); 373 374 /* Depends: 375 * the test 'self' cannot be executed if test 'depends' fails 376 * 377 DIAGNOSE_EXTERN rc_t CC KDiagnoseTestDescDepends ( 378 const KDiagnoseTestDesc * self, const KDiagnoseTestDesc * depends );*/ 379 380 381 #ifdef __cplusplus 382 } 383 #endif 384 385 /******************************************************************************/ 386 387 #endif /* _h_diagnose_diagnose_ */ 388