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