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 #ifndef _h_vfs_manager_
27 #define _h_vfs_manager_
28 
29 #ifndef _h_vfs_extern_
30 #include <vfs/extern.h>
31 #endif
32 
33 #ifndef _h_klib_defs_
34 #include <klib/defs.h>
35 #endif
36 
37 
38 #ifndef _h_kfs_defs_
39 #include <kfs/defs.h>
40 #endif
41 
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
45 
46 
47 /*--------------------------------------------------------------------------
48  * forwards
49  */
50 struct KFile;
51 struct VPath;
52 struct VResolver;
53 struct KDirectory;
54 struct KNSManager;
55 
56 /* temporary */
57 
58 
59 /*--------------------------------------------------------------------------
60  * VFSManager
61  */
62 typedef struct VFSManager VFSManager;
63 
64 #define VFS_KRYPTO_PASSWORD_MAX_SIZE 4096
65 
66 
67 /* AddRef
68  * Release
69  *  ignores NULL references
70  */
71 VFS_EXTERN rc_t CC VFSManagerAddRef ( const VFSManager *self );
72 VFS_EXTERN rc_t CC VFSManagerRelease ( const VFSManager *self );
73 
74 /* OpenFileRead
75  *  opens an existing file with read-only access
76  *
77  *  "f" [ OUT ] - return parameter for newly opened file
78  *
79  *  "path" [ IN ] VPath representing the path, URL or URN of the desired file
80  */
81 VFS_EXTERN rc_t CC VFSManagerOpenFileRead ( const VFSManager *self,
82                                            struct KFile const **f,
83                                            const struct VPath * path );
84 
85 VFS_EXTERN rc_t CC VFSManagerOpenFileReadWithBlocksize ( const VFSManager *self,
86                                            struct KFile const **f,
87                                            const struct VPath * path,
88                                            uint32_t blocksize,
89                                            bool promote );
90 
91 VFS_EXTERN rc_t CC VFSManagerOpenDirectoryRead ( const VFSManager *self,
92     struct KDirectory const **d, const struct VPath * path );
93 
94 /* it forces decryption to be used for kdb */
95 VFS_EXTERN rc_t CC VFSManagerOpenDirectoryReadDecrypt ( const VFSManager *self,
96     struct KDirectory const **d, const struct VPath * path );
97 
98 /* VPath has already been resolved to a URL and an optional cache file */
99 VFS_EXTERN rc_t CC VFSManagerOpenDirectoryReadDecryptRemote (const struct VFSManager *self,
100     struct KDirectory const **d, const struct VPath * path, const struct VPath * cache);
101 
102 VFS_EXTERN rc_t CC VFSManagerOpenDirectoryUpdate ( const VFSManager *self,
103     struct KDirectory **d, const struct VPath * path );
104 
105 /* OpenFileWrite
106  *  opens an existing file with write access
107  *
108  *  "f" [ OUT ] - return parameter for newly opened file
109  *
110  *  "update" [ IN ] - if true, open in read/write mode
111  *  otherwise, open in write-only mode
112  *
113  *  "path" [ IN ] VPath representing the path, URL or URN of the desired file
114  */
115 VFS_EXTERN rc_t CC VFSManagerOpenFileWrite (const VFSManager *self,
116                                             struct KFile **f,
117                                             bool update,
118                                             const struct VPath * path);
119 
120 /* CreateFile
121  *  opens a file with write access
122  *
123  *  "f" [ OUT ] - return parameter for newly opened file
124  *
125  *  "update" [ IN ] - if true, open in read/write mode
126  *  otherwise, open in write-only mode
127  *
128  *  "access" [ IN ] - standard Unix access mode, e.g. 0664
129  *
130  *  "mode" [ IN ] - a creation mode ( see explanation above ).
131  *
132  *  "path" [ IN ] VPath representing the path, URL or URN of the desired file
133  */
134 VFS_EXTERN rc_t CC VFSManagerCreateFile (const VFSManager *self,
135                                          struct KFile **f,
136                                          bool update, uint32_t access,
137                                          KCreateMode mode,
138                                          const struct VPath * path );
139 
140 
141 /* Remove
142  *  remove an accessible object from its directory
143  *
144  *  "force" [ IN ] - if true and target is a directory,
145  *  remove recursively
146  *
147  *  "path" [ IN ] - NUL terminated string in directory-native
148  *  character set denoting target object
149  */
150 VFS_EXTERN rc_t CC VFSManagerRemove (const VFSManager *self, bool force,
151                                      const struct VPath * path );
152 
153 
154 /* Make
155  */
156 VFS_EXTERN rc_t CC VFSManagerMake ( VFSManager ** pmanager );
157 
158 /* GetCWD
159  */
160 VFS_EXTERN rc_t CC VFSManagerGetCWD (const VFSManager * self, struct KDirectory ** cwd);
161 
162 VFS_EXTERN rc_t CC VFSManagerGetResolver ( const VFSManager * self, struct VResolver ** resolver );
163 
164 VFS_EXTERN rc_t CC VFSManagerGetKNSMgr ( const VFSManager * self, struct KNSManager ** kns );
165 
166 
167 VFS_EXTERN rc_t CC VFSManagerGetKryptoPassword (const VFSManager * self, char * new_password, size_t max_size, size_t * size);
168 
169 /*
170   NULL value for self
171   RC (rcVFS, rcEncryptionKey, rcUpdating, rcSelf, rcNull);
172 
173   NULL value for password or 0 value for size
174   RC (rcVFS, rcEncryptionKey, rcUpdating, rcParam, rcNull);
175 
176   size greater than VFS_KRYPTO_PASSWORD_MAX_SIZE
177   RC (rcVFS, rcEncryptionKey, rcUpdating, rcSize, rcExcessive);
178 
179   illegal CR or LF (NL) in the password
180   RC (rcVFS, rcEncryptionKey, rcUpdating, rcEncryptionKey, rcInvalid);
181 
182   path/file name for password too long for function as written
183   RC (rcVFS, rcEncryptionKey, rcUpdating, rcPath, rcExcessive);
184 
185   existing password path/file name is not a file
186   RC (rcVFS, rcEncryptionKey, rcUpdating, rcPath, rcIncorrect);
187 
188   unknown file type for configured path/file name
189   RC (rcVFS, rcEncryptionKey, rcUpdating, rcPath, rcCorrupt);
190 
191   incomplete writes to temporary password file
192   RC (rcVFS, rcEncryptionKey, rcWriting, rcFile, rcInsufficient);
193 
194   other errors from KFS and KLIB
195 */
196 
197 /* pwd_dir[pwd_dir_size] -
198     Output parameters for path to directory containing the password file.
199     pwd_dir is not updated if pwd_dir == NULL or pwd_dir_size == 0
200                   or pwd_dir_size is insufficient to copy the path
201  */
202 VFS_EXTERN rc_t CC VFSManagerUpdateKryptoPassword (const VFSManager * self,
203                                                    const char * password,
204                                                    size_t size,
205                                                    char * pwd_dir,
206                                                    size_t pwd_dir_size);
207 
208 
209 VFS_EXTERN rc_t CC VFSManagerResolveSpec ( const VFSManager * self,
210                                            const char * spec,
211                                            struct VPath ** path_to_build,
212                                            const struct KFile ** remote_file,
213                                            const struct VPath ** local_cache,
214                                            bool resolve_acc );
215 
216 struct KDirectory;
217 
218 VFS_EXTERN rc_t CC VFSManagerResolveSpecIntoDir ( const VFSManager * self,
219                                                   const char * spec,
220                                                   const struct KDirectory ** dir,
221                                                   bool resolve_acc );
222 
223 /*--------------------------------------------------------------------------
224  * KConfig
225  *  placing some KConfig code that relies upon VFS here
226  */
227 struct KConfig;
228 struct KConfigNode;
229 
230 /* ReadVPath
231  *  read a VPath node value
232  *
233  * self [ IN ] - KConfig object
234  * path [ IN ] - path to the node
235  * result [ OUT ] - return value (rc != 0 if cannot be converted)
236  *
237  */
238 VFS_EXTERN rc_t CC KConfigReadVPath ( struct KConfig const* self, const char* path, struct VPath** result );
239 
240 /* ReadVPath
241  *  read a VPath node value
242  *
243  * self [ IN ] - KConfigNode object
244  * result [ OUT ] - return value (rc != 0 if cannot be converted)
245  *
246  */
247 VFS_EXTERN rc_t CC KConfigNodeReadVPath ( struct KConfigNode const *self, struct VPath** result );
248 
249 /* ResolvePath
250  *
251  * take a VPath and resolve to a final form apropriate for KDB
252  *
253  * that is take a relative path and resolve it against the CWD
254  * or take an accession and resolve into the local or remote
255  * VResolver file based on config. It is just a single resolution percall
256  *
257  * flags
258  *      can disable all Accession resolution
259  *      can let VPath With no scheme be treated as a possible accession
260  *
261  */
262 
263 /* bit values for flags */
264     /* allow no local accession resolution */
265 #define vfsmgr_rflag_no_acc_local (1<<0)
266     /* allow no remote accession resolution */
267 #define vfsmgr_rflag_no_acc_remote (1<<1)
268     /* never do VResolver Accession resolution */
269 #define vfsmgr_rflag_no_acc  (vfsmgr_rflag_no_acc_local|vfsmgr_rflag_no_acc_remote)
270     /* use VResolver Accession resolution for simple names with no scheme */
271 
272 #define vfsmgr_rflag_kdb_acc (1<<2)
273     /* over ridden by vfsmgr_rflag_no_acc */
274 
275 
276 VFS_EXTERN rc_t CC VFSManagerResolvePath (const VFSManager * self,
277                                           uint32_t flags,
278                                           const struct  VPath * in_path,
279                                           struct VPath ** out_path);
280 
281 VFS_EXTERN rc_t CC VFSManagerResolvePathRelative (const VFSManager * self,
282                                                   uint32_t flags,
283                                                   const struct  VPath * base_path,
284                                                   const struct  VPath * in_path,
285                                                   struct VPath ** out_path);
286 
287 /*
288  * Registering bindings between dbGaP object Ids and object names
289  */
290 
291 /* VFSManagerRegisterObject
292  *  registers a binding between an object Id and an object name (object = accession or dbGaP file)
293  *
294  * self [ IN ] - VFSManager object
295  * oid [ IN ] - object id
296  * obj [ IN ] - Vpath representing the object's name (scheme is "ncbi-acc" for accessions, "ncbi-file" for dbGaP files;
297  *              the name itself is the 'path' component
298  */
299 VFS_EXTERN rc_t CC VFSManagerRegisterObject(struct VFSManager* self, uint32_t oid, const struct VPath* obj);
300 
301 /* VFSManagerGetObjectId
302  *  look up an object id by an object name
303  *
304  * self [ IN ] - VFSManager object
305  * obj [ IN ] - Vpath representing the object's name (scheme is "ncbi-acc" for accessions, "ncbi-file" for dbGaP files;
306  *              the name itself is the 'path' component
307  * oid [ OUT ] - object id
308  */
309 VFS_EXTERN rc_t CC VFSManagerGetObjectId(const struct VFSManager* self, const struct VPath* obj, uint32_t* oid);
310 
311 /* VFSManagerGetObject
312  *  look up an object name by an object id
313  *
314  * self [ IN ] - VFSManager object
315  * oid [ IN ] - object id
316  * obj [ OUT ] - Vpath representing the object's name (scheme is "ncbi-acc" for accessions, "ncbi-file" for dbGaP files;
317  *              the name itself is the 'path' component
318  */
319 VFS_EXTERN rc_t CC VFSManagerGetObject(const struct VFSManager* self, uint32_t oid, struct VPath** obj);
320 
321 /* SetAdCaching
322  *  Enable Caching to Accession as Directory in cwd
323  */
324 VFS_EXTERN
325 rc_t CC VFSManagerSetAdCaching(struct VFSManager* self, bool enabled);
326 
327 
328 /* CheckAd
329  *  Verify that inPath is path/to/Accession-as-Directory (AD)
330  *  if inPath is AD - resolve run in AD as outPath and return true
331  *  otherwise - return false, don't set outPath
332  */
333 VFS_EXTERN bool CC VFSManagerCheckAd(const struct VFSManager * self,
334     const struct VPath * inPath, const struct VPath ** outPath);
335 
336 /* CheckEnvAndAd
337  *  Verify that inPath is path/to/Accession-as-Directory (AD)
338  *  if inPath is AD - resolve run in AD as outPath and return true
339  *  otherwise - return false, don't set outPath
340  *
341  *  Verify magic env.vars first
342  */
343 VFS_EXTERN bool CC VFSManagerCheckEnvAndAd(const struct VFSManager * self,
344     const struct VPath * inPath, const struct VPath ** outPath);
345 
346 
347 /* LogNamesServiceErrors
348  *  Enable/disable logging of error messages coming from names service
349  */
350 VFS_EXTERN rc_t CC VFSManagerLogNamesServiceErrors(struct VFSManager* self,
351     bool enabled);
352 VFS_EXTERN rc_t CC VFSManagerGetLogNamesServiceErrors(VFSManager * self,
353     bool * enabled);
354 
355 
356 #ifdef __cplusplus
357 }
358 #endif
359 
360 #endif /* _h_kfs_manager_ */
361