1/* 2 * Copyright 2011, Haiku inc. 3 * Distributed under the terms of the MIT Licence. 4 * 5 * Documentation by: 6 * Adrien Destugues <pulkomandy@pulkomandy.ath.cx> 7 * Corresponds to: 8 * /trunk/headers/os/storage/FindDirectory.h rev 42600 9 * /trunk/src/kits/storage/FindDirectory.cpp rev 42600 10 */ 11 12 13/*! 14 \file FindDirectory.h 15 \ingroup storage 16 \brief Provides the find_dirctory function. 17 18 Haiku provides a set of directories for applications to use. These can be 19 accessed using the find_directory function. It is very important to use the 20 function at runtime and not hardcode the path, as it may change in future 21 versions of Haiku, and already changed in past ones. Using this function 22 makes your application more future-proof, and makes sure everyone puts data 23 in the same place, which makes the system cleaner and easier to manage. 24 25 Note this function can be accessed from C code, to make it easy to use also 26 in ported applications. 27*/ 28 29/*! 30 \enum directory_which 31 \brief Directory constants to use with find_directory. 32 33 There are four kind of directories. Volume-local directories exist on each 34 volume. They may be at a different place in each of them, for example the 35 trash location depends on the filesystem. System and common directories are 36 system-wide. They live on only one volume. The difference is system is 37 only meant for internal system management and shouldn't be used by 38 applications. The common directories have a similar hierarchy, and they are 39 ignored when the user disable user add-ons in the boot menu. User 40 directories have a different value depending on the UID of the application 41 calling the function. They are usually located in the user home directory. 42 43 Use common directories for system-wide filessuch as drivers. Use user 44 directories for application settings, since each user may want different 45 settings. 46*/ 47 48/*! 49 \var directory_which B_DESKTOP_DIRECTORY 50 The desktop for a given volume. 51 52 \var directory_which B_TRASH_DIRECTORY 53 The trash for a given volume. 54 55 \var directory_which B_SYSTEM_DIRECTORY 56 The system directory. 57 58 \var directory_which B_SYSTEM_ADDONS_DIRECTORY 59 The system add-ons directory 60 61 \var directory_which B_SYSTEM_BOOT_DIRECTORY 62 The system boot directory. Contains the minimal set of files required for 63 booting Haiku. 64 65 \var directory_which B_SYSTEM_FONTS_DIRECTORY 66 The system fonts directory 67 68 \var directory_which B_SYSTEM_LIB_DIRECTORY 69 The system lib directory. 70 71 \var directory_which B_SYSTEM_SERVERS_DIRECTORY 72 The system servers directory. 73 74 \var directory_which B_SYSTEM_APPS_DIRECTORY 75 The system applications direcotry. Contains applications executable from 76 Tracker. 77 78 \var directory_which B_SYSTEM_BIN_DIRECTORY 79 The system bin directory. Contains command-line applications runnable from 80 Terminal. 81 82 \var directory_which B_SYSTEM_DOCUMENTATION_DIRECTORY 83 The system documentation directory. Contains manpages. 84 85 \var directory_which B_SYSTEM_PREFERENCES_DIRECTORY 86 The system preferences directory. 87 88 \var directory_which B_SYSTEM_TRANSLATORS_DIRECTORY 89 The system translator directory. 90 91 \var directory_which B_SYSTEM_MEDIA_NODES_DIRECTORY 92 The system media nodes directory. 93 94 \var directory_which B_SYSTEM_SOUNDS_DIRECTORY 95 The system sounds directory. 96 97 \var directory_which B_SYSTEM_DATA_DIRECTORY 98 The system data directory. 99 100 \var directory_which B_COMMON_DIRECTORY 101 The common directory. 102 103 \var directory_which B_COMMON_SYSTEM_DIRECTORY 104 \var directory_which B_COMMON_ADDONS_DIRECTORY 105 \var directory_which B_COMMON_BOOT_DIRECTORY 106 \var directory_which B_COMMON_FONTS_DIRECTORY 107 \var directory_which B_COMMON_LIB_DIRECTORY 108 \var directory_which B_COMMON_SERVERS_DIRECTORY 109 \var directory_which B_COMMON_BIN_DIRECTORY 110 \var directory_which B_COMMON_ETC_DIRECTORY 111 \var directory_which B_COMMON_DOCUMENTATION_DIRECTORY 112 \var directory_which B_COMMON_SETTINGS_DIRECTORY 113 \var directory_which B_COMMON_DEVELOP_DIRECTORY 114 The common development directory. Contains toolchains, include files, 115 and other tools related to application development. 116 117 \var directory_which B_COMMON_LOG_DIRECTORY 118 The common log directory. Log files are stored here. 119 120 \var directory_which B_COMMON_SPOOL_DIRECTORY 121 \var directory_which B_COMMON_TEMP_DIRECTORY 122 \var directory_which B_COMMON_VAR_DIRECTORY 123 \var directory_which B_COMMON_TRANSLATORS_DIRECTORY 124 \var directory_which B_COMMON_MEDIA_NODES_DIRECTORY 125 \var directory_which B_COMMON_SOUNDS_DIRECTORY 126 \var directory_which B_COMMON_DATA_DIRECTORY 127 The common data directory. You may store application data here, such as 128 resources (graphics, music) for your application. 129 130 \var directory_which B_COMMON_CACHE_DIRECTORY 131 The common cache directory. You may store temporary data here, such as 132 thumbnails for a picture viewer application, or a web browser data cache. 133 134 \var directory_which B_USER_DIRECTORY 135 The user home directory. Do NOT store application settings here as on unix, 136 instead use B_USER_SETTINGS_DIRECTORY. 137 138 \var directory_which B_USER_CONFIG_DIRECTORY 139 \var directory_which B_USER_ADDONS_DIRECTORY 140 \var directory_which B_USER_BOOT_DIRECTORY 141 \var directory_which B_USER_FONTS_DIRECTORY 142 \var directory_which B_USER_LIB_DIRECTORY 143 \var directory_which B_USER_SETTINGS_DIRECTORY 144 The user settings directory. You may store your application settings here. 145 Create a subdirectory for your application if you have multiple files to 146 store, else, put a single file. The file or directory should have the same 147 name as your application, so the user knows what it's used for. 148 149 \var directory_which B_USER_DESKBAR_DIRECTORY 150 The user deskbar directory. You may add a link to your application here, so 151 it shows up in the user deskbar's leaf menu. 152 153 \var directory_which B_USER_PRINTERS_DIRECTORY 154 \var directory_which B_USER_TRANSLATORS_DIRECTORY 155 \var directory_which B_USER_MEDIA_NODES_DIRECTORY 156 \var directory_which B_USER_SOUNDS_DIRECTORY 157 \var directory_which B_USER_DATA_DIRECTORY 158 \var directory_which B_USER_CACHE_DIRECTORY 159 160 \var directory_which B_APPS_DIRECTORY 161 \var directory_which B_PREFERENCES_DIRECTORY 162 \var directory_which B_UTILITIES_DIRECTORY 163*/ 164 165/*! 166 \fn status_t find_directory(directory_which which, dev_t volume, bool createIt, char* pathString, int32 length) 167 \brief C interface to find_directory 168 169 Fills up to \a length characters of \a pathString with the path to \a which 170 on \a volume. Creates the directory if it doesn't exists and \a creqteIt is 171 set. 172*/ 173 174/*! 175 \fn status_t find_directory(directory_which which, BPath* path, bool createIt = false, BVolume* volume = NULL) 176 \brief C++ interface to find_directory 177 178 Set \a path to \a which on \a volume. 179*/ 180