include/basedir.h

   1 /* Copyright (c) 2007 Mark Nevill
   2  *
   3  * Permission is hereby granted, free of charge, to any person
   4  * obtaining a copy of this software and associated documentation
   5  * files (the "Software"), to deal in the Software without
   6  * restriction, including without limitation the rights to use,
   7  * copy, modify, merge, publish, distribute, sublicense, and/or sell
   8  * copies of the Software, and to permit persons to whom the
   9  * Software is furnished to do so, subject to the following
  10  * conditions:
  11  *
  12  * The above copyright notice and this permission notice shall be
  13  * included in all copies or substantial portions of the Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
  17  * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  18  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  19  * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  20  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  22  * OTHER DEALINGS IN THE SOFTWARE.
  23  */
  24
  25 /** @mainpage
  26  *
  27  * <div style="margin: 2em 5em 2em 5em; border: 1px solid #CCC; padding: 1em; background: #E8EEF2;">
  28  * Various specifications specify files and file formats. The <a
  29  * href="http://standards.freedesktop.org/basedir-spec/basedir-spec-0.6.html">
  30  * XDG Base Directory specification</a> defines where these files should
  31  * be looked for by defining one or more base directories relative to
  32  * which files should be located.
  33  * </div>
  34  *
  35  * This library implements functions to list the directories according
  36  * to the specification and provides a few higher-level functions for
  37  * use with the specification.
  38  */
  39
  40 /** @file basedir.h
  41   * Functions for using the XDG Base Directory specification. */
  42
  43 #ifndef XDG_BASEDIR_H
  44 #define XDG_BASEDIR_H
  45
  46 #ifdef __cplusplus
  47 extern "C" {
  48 #endif
  49
  50 /** Version of XDG Base Directory specification implemented in this library. */
  51 #define XDG_BASEDIR_SPEC 0.6
  52
  53 /** @name XDG data cache management */
  54 /*@{*/
  55
  56 /** Handle to XDG data cache.
  57   * Handles are initialized with xdgInitHandle() and
  58   * freed with xdgWipeHandle(). */
  59 typedef struct /*_xdgHandle*/ {
  60         /** Reserved for internal use, do not modify. */
  61         void *reserved;
  62 } xdgHandle;
  63
  64 /** Initialize a handle to an XDG data cache and initialize the cache.
  65   * Use xdgWipeHandle() to free the handle.
  66   * @return a pointer to the handle if initialization was successful, else 0 */
  67 xdgHandle * xdgInitHandle(xdgHandle *handle);
  68
  69 /** Wipe handle of XDG data cache.
  70   * Wipe handle initialized using xdgInitHandle(). */
  71 void xdgWipeHandle(xdgHandle *handle);
  72
  73 /** Update the data cache.
  74   * This should not be done frequently as it reallocates the cache.
  75   * Even if updating the cache fails the handle remains valid and can
  76   * be used to access XDG data as it was before xdgUpdateData() was called.
  77   * @return 0 if update failed, non-0 if successful.*/
  78 int xdgUpdateData(xdgHandle *handle);
  79
  80 /*@}*/
  81 /** @name Basic XDG Base Directory Queries */
  82 /*@{*/
  83
  84 /** Base directory for user specific data files.
  85   * @param handle Handle to data cache, initialized with xdgInitHandle().
  86   * @return a path as described by the standards. */
  87 const char * xdgDataHome(xdgHandle *handle);
  88
  89 /** Base directory for user specific configuration files.
  90   * @param handle Handle to data cache, initialized with xdgInitHandle().
  91   * @return a path as described by the standards. */
  92 const char * xdgConfigHome(xdgHandle *handle);
  93
  94 /** Preference-ordered set of base directories to search for data files
  95   * in addition to the $XDG_DATA_HOME base directory.
  96   * @param handle Handle to data cache, initialized with xdgInitHandle().
  97   * @return A null-terminated list of directory strings. */
  98 const char * const * xdgDataDirectories(xdgHandle *handle);
  99
 100 /** Preference-ordered set of base directories to search for data files
 101   * with $XDG_DATA_HOME prepended.
 102   * The base directory defined by $XDG_DATA_HOME is considered more
 103   * important than any of the base directories defined by $XDG_DATA_DIRS.
 104   * @param handle Handle to data cache, initialized with xdgInitHandle().
 105   * @return A null-terminated list of directory strings. */
 106 const char * const * xdgSearchableDataDirectories(xdgHandle *handle);
 107
 108 /** Preference-ordered set of base directories to search for configuration
 109   * files in addition to the $XDG_CONFIG_HOME base directory.
 110   * @param handle Handle to data cache, initialized with xdgInitHandle().
 111   * @return A null-terminated list of directory strings. */
 112 const char * const * xdgConfigDirectories(xdgHandle *handle);
 113
 114 /** Preference-ordered set of base directories to search for configuration
 115   * files with $XDG_CONFIG_HOME prepended.
 116   * The base directory defined by $XDG_CONFIG_HOME is considered more
 117   * important than any of the base directories defined by $XDG_CONFIG_DIRS.
 118   * @param handle Handle to data cache, initialized with xdgInitHandle().
 119   * @return A null-terminated list of directory strings. */
 120 const char * const * xdgSearchableConfigDirectories(xdgHandle *handle);
 121
 122 /** Base directory for user specific non-essential data files.
 123   * @param handle Handle to data cache, initialized with xdgInitHandle().
 124   * @return a path as described by the standards. */
 125 const char * xdgCacheHome(xdgHandle *handle);
 126
 127 /*@}*/
 128
 129 #ifdef __cplusplus
 130 } // extern "C"
 131 #endif
 132
 133 #endif /*XDG_BASEDIR_H*/