src/uobject/vfs.h

   1 /*
   2  *  Functions for handling UObject package search paths.
   3  *  Copyright © 2009-2011 Nick Bowler
   4  *
   5  *  This program is free software: you can redistribute it and/or modify
   6  *  it under the terms of the GNU General Public License as published by
   7  *  the Free Software Foundation, either version 3 of the License, or
   8  *  (at your option) any later version.
   9  *
  10  *  This program is distributed in the hope that it will be useful,
  11  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  *  GNU General Public License for more details.
  14  *
  15  *  You should have received a copy of the GNU General Public License
  16  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17  */
  18 #ifndef U_OBJECT_VFS_H_
  19 #define U_OBJECT_VFS_H_
  20
  21 #include <upkg.h>
  22
  23 /*
  24  * Insert a local package to the VFS.  A "local package" is an explicit
  25  * association of a name to a file, and thus can be located outside the normal
  26  * search path.  Local packages are searched before any other location.
  27  *
  28  * Returns a pointer to an internal copy of name on success, or NULL on
  29  * failure.  The returned name must not be modified or freed.  If name is
  30  * NULL, it is determined automatically from the filename.
  31  */
  32 const char *u_pkg_vfs_add_local(const char *name, const char *file);
  33
  34 /*
  35  * Remove a local package from the VFS by name.
  36  */
  37 void u_pkg_vfs_del_local(const char *name);
  38
  39 /*
  40  * Set the global VFS search path - a LT_PATHSEP-delimited sequence of
  41  * directories to be searched for packages after local packages.
  42  *
  43  * Returns 0 on success, or -1 on failure.
  44  */
  45 int u_pkg_vfs_set_search_path(const char *path);
  46
  47 /*
  48  * Appends a directory to the global VFS search path.  This directory will
  49  * be searched after any directories already in the path.
  50  *
  51  * Returns 0 on success, or -1 on failure.
  52  */
  53 int u_pkg_vfs_add_search_dir(const char *path);
  54
  55 /*
  56  * Get the global VFS search path.
  57  */
  58 const char *u_pkg_vfs_get_search_path(void);
  59
  60 /*
  61  * Opens a package file by name.  First, local packages are searched for a
  62  * match.  If a local match is found, the global search path is never
  63  * consulted.  If no local match is found, the directories in the global search
  64  * path are examined, in order.
  65  *
  66  * When searching the global search path, the first file found which both
  67  * matches the given name and can be opened successfully is used.  A file
  68  * foo.EXT matches the name if foo is equal to name (without regard to case)
  69  * and EXT is one of u, utx, uax, umx or unr.  If multiple extensions
  70  * are valid, they are tried in this order.
  71  *
  72  * Note that the particular file extension used does not make any difference
  73  * as to what sort of objects can be contained in a package.
  74  *
  75  * Returns the opened package on success, or NULL on failure.
  76  */
  77 struct upkg *u_pkg_vfs_open_by_name(const char *name);
  78
  79 /*
  80  * Initialize the UObject VFS system.  Returns 0 on success, -1 otherwise.
  81  * The VFS system can be safely initialized multiple times.
  82  */
  83 int u_pkg_vfs_init(void);
  84
  85 /*
  86  * Shutdown the UObject VFS system.
  87  * The VFS system is only shut down when this function has been called as
  88  * many times as u_pkg_vfs_init.
  89  */
  90 void u_pkg_vfs_exit(void);
  91
  92 #endif