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.7 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 /** Base directory for user-specific non-essential runtime files (including file 128 * objects such as sockets and named pipes). 129 * @param handle Handle to data cache, initialized with xdgInitHandle(). 130 * @return a path as described by the standards, or NULL if no path has been 131 * set. */ 132 const char * xdgRuntimeDirectory(xdgHandle *handle); 133 134 /*@}*/ 135 136 #ifdef __cplusplus 137 } // extern "C" 138 #endif 139 140 #endif /*XDG_BASEDIR_H*/ 141