1/* 2 * Copyright 2013, Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Documentation by: 6 * Ingo Weinhold, ingo_weinhold@gmx.de 7 * 8 * Corresponds to: 9 * headers/os/storage/PathFinder.h hrev46390 10 * src/kits/storage/PathFinder.cpp hrev46390 11 */ 12 13 14/*! 15 \file PathFinder.h 16 \ingroup storage 17 \ingroup libbe 18 \brief Provides the BPathFinder class interface. 19*/ 20 21 22/*! 23 \class BPathFinder 24 \ingroup storage 25 \ingroup libbe 26 \brief Helper class to retrieve paths in the file system layout. 27 28 The BPathFinder provides two sets of methods for retrieving paths: 29 FindPath() for getting a single path in an installation location specified 30 via a constructor or a SetTo() invocation, and the static FindPaths() for 31 getting a list of paths for all installation locations. 32*/ 33 34 35/*! 36 \fn BPathFinder::BPathFinder(const void* codePointer, 37 const char* dependency) 38 \brief Creates an object referring to an installation location based on a 39 loaded image file. 40 41 When initialized with this constructor a FindPath() method called afterward 42 determines the path of the image (i.e. executable, library, or add-on) file 43 associated with \a codePointer, a pointer to a location in the code or 44 static data of an image loaded in the caller's team. Based on that path the 45 path constant passed to FindPath() will be evaluated. In most cases that 46 means first determining the path of the installation location from the path. 47 48 If \a dependency is specified, instead of determining the installation 49 location path from the image path, the installation location path of the 50 dependency \a dependency of the package containing the image file is used. 51 52 If the initialization fails, e.g. due to insufficient memory or invalid 53 arguments, subsequent calls to FindPath() will return an error. 54 55 \param codePointer A pointer to code or static data belonging to the image 56 based on which FindPath() shall compute the path. The special value 57 \c B_APP_IMAGE_SYMBOL (the default) can be used to refer to the program 58 image, and \c B_CURRENT_IMAGE_SYMBOL for the caller's image. 59 \param dependency The name of the package's "requires" entry to be used for 60 resolving the installation location. Can be \c NULL (the default). 61*/ 62 63 64/*! 65 \fn BPathFinder::BPathFinder(const char* path, const char* dependency) 66 \brief Creates an object referring to an installation location based on a 67 given path. 68 69 When initialized with this constructor a FindPath() method called afterward 70 evaluates the path constant passed to it based on \a path. In most cases 71 that means first determining the path of the installation location from the 72 given path. 73 74 If \a dependency is specified, instead of determining the installation 75 location path from the given path, the installation location path of the 76 dependency \a dependency of the package containing the file referred to by 77 \a path is used. 78 79 If the initialization fails, e.g. due to insufficient memory or invalid 80 arguments, subsequent calls to FindPath() will return an error. 81 82 \param path A path based on which FindPath() shall compute the path. 83 \param dependency The name of the package's "requires" entry to be used for 84 resolving the installation location. Can be \c NULL. 85*/ 86 87 88/*! 89 \fn BPathFinder::BPathFinder(const entry_ref& ref, const char* dependency) 90 \brief Creates an object referring to an installation location based on a 91 given entry_ref. 92 93 The constructor converts the given entry_ref \a ref to a path and then 94 initializes the object like 95 BPathFinder::BPathFinder(const char*, const char*). 96 97 \param ref A reference to be resolved to a path based on which FindPath() 98 shall compute the path. 99 \param dependency The name of the package's "requires" entry to be used for 100 resolving the installation location. Can be \c NULL. 101 102 \see BPathFinder::BPathFinder(const char*, const char*) 103*/ 104 105 106/*! 107 \fn BPathFinder::BPathFinder(const BResolvableExpression& expression, 108 const char* dependency) 109 \brief Creates an object referring to an installation location based on the 110 path of a package satisfying the given resolvable expression. 111 112 The constructor finds the latest package that satisfies the resolvable 113 expression \a expression and then uses its path to initialize the object 114 like BPathFinder::BPathFinder(const char*, const char*). 115 116 \note When using this constructor linking against libpackage.so is required. 117 118 \param expression A resolvable expression to be resolved to the path of the 119 latest package satisfying it, based on which FindPath() shall compute 120 the path. 121 \param dependency The name of the package's "requires" entry to be used for 122 resolving the installation location. Can be \c NULL. 123 124 \see BPathFinder::BPathFinder(const char*, const char*) 125*/ 126 127 128/*! 129 \fn status_t BPathFinder::SetTo(const void* codePointer, 130 const char* dependency) 131 \brief Reinitializes the object to refer to an installation location based 132 on a loaded image file. 133 134 When reinitialized with this method a FindPath() method called afterward 135 determines the path of the image (i.e. executable, library, or add-on) file 136 associated with \a codePointer, a pointer to a location in the code or 137 static data of an image loaded in the caller's team. Based on that path the 138 path constant passed to FindPath() will be evaluated. In most cases that 139 means first determining the path of the installation location from the path. 140 141 If \a dependency is specified, instead of determining the installation 142 location path from the image path, the installation location path of the 143 dependency \a dependency of the package containing the image file is used. 144 145 If the initialization fails, e.g. due to insufficient memory or invalid 146 arguments, this method and subsequent calls to FindPath() will return an 147 error. 148 149 \param codePointer A pointer to code or static data belonging to the image 150 based on which FindPath() shall compute the path. The special value 151 \c B_APP_IMAGE_SYMBOL (the default) can be used to refer to the program 152 image, and \c B_CURRENT_IMAGE_SYMBOL for the caller's image. 153 \param dependency The name of the package's "requires" entry to be used for 154 resolving the installation location. Can be \c NULL (the default). 155 \return A status code. 156 \retval B_OK Everything went fine. 157*/ 158 159 160/*! 161 \fn status_t BPathFinder::SetTo(const char* path, const char* dependency) 162 \brief Reinitializes the object to refer to an installation location based 163 on a given path. 164 165 When reinitialized with this method a FindPath() method called afterward 166 evaluates the path constant passed to it based on \a path. In most cases 167 that means first determining the path of the installation location from the 168 given path. 169 170 If \a dependency is specified, instead of determining the installation 171 location path from the given path, the installation location path of the 172 dependency \a dependency of the package containing the file referred to by 173 \a path is used. 174 175 If the initialization fails, e.g. due to insufficient memory or invalid 176 arguments, this method and subsequent calls to FindPath() will return an 177 error. 178 179 \param path A path based on which FindPath() shall compute the path. 180 \param dependency The name of the package's "requires" entry to be used for 181 resolving the installation location. Can be \c NULL. 182 \return A status code. 183 \retval B_OK Everything went fine. 184*/ 185 186 187/*! 188 \fn status_t BPathFinder::SetTo(const entry_ref& ref, 189 const char* dependency) 190 \brief Reinitializes the object to refer to an installation location based 191 on a given entry_ref. 192 193 This method converts the given entry_ref \a ref to a path and then calls 194 calls BPathFinder::SetTo(const char*, const char*). 195 196 \param ref A reference to be resolved to a path based on which FindPath() 197 shall compute the path. 198 \param dependency The name of the package's "requires" entry to be used for 199 resolving the installation location. Can be \c NULL. 200 201 \see status_t BPathFinder::SetTo(const char*, const char*) 202*/ 203 204 205/*! 206 \fn status_t BPathFinder::SetTo(const BResolvableExpression& expression, 207 const char* dependency) 208 \brief Reinitializes the object to refer to an installation location based 209 on a given resolvable expression. 210 211 This method finds the latest package that satisfies the resolvable 212 expression \a expression and then passes its path to 213 BPathFinder::SetTo(const char*, const char*). 214 215 \note When using this method linking against libpackage.so is required. 216 217 \param expression A resolvable expression to be resolved to the path of the 218 latest package satisfying it, based on which FindPath() shall compute 219 the path. 220 \param dependency The name of the package's "requires" entry to be used for 221 resolving the installation location. Can be \c NULL. 222 223 \see status_t BPathFinder::SetTo(const char*, const char*) 224*/ 225 226 227/*! 228 \fn status_t BPathFinder::FindPath(const char* architecture, 229 path_base_directory baseDirectory, const char* subPath, uint32 flags, 230 BPath& _path) 231 \brief Retrieves a path in the file system layout based. 232 233 Depending on how the object was initialized this method starts with a path 234 (from an image file or as given) and based on it evaluates \a baseDirectory. 235 In most cases that means first determining the path of the installation 236 location from the path, then appending the relative path corresponding to 237 the given \a baseDirectory constant, and finally appending \a subPath, if 238 given. 239 240 If a dependency string was passed to the previous constructor or SetTo() 241 method, instead of determining the installation location path from the 242 initial path, the installation location path of the dependency of the 243 package containing the file the initial path refers to is used. 244 245 If \a baseDirectory specifies a path that is architecture dependent, 246 \a architecture is used for constructing the path. If \a architecture is 247 \c NULL, the architecture associated with the initial path (as returned by 248 guess_architecture_for_path()) is used. Note that if an image was specified, 249 this is the same as the caller's architecture (as returned by 250 get_architecture()). 251 252 If \c B_FIND_PATH_IMAGE_PATH or \c B_FIND_PATH_PACKAGE_PATH are 253 specified, \a subPath is ignored. In the former case, which is only valid, 254 if an image was specified for initialization, \a dependency is ignored as 255 well and the path of the image file is returned. In the latter case the path 256 of the package containing the file the initial path refers to, respectively, 257 if \a dependency was specified, that of the package \a dependency was 258 resolved to is returned. 259 260 \param architecture The name of the architecture to be used for resolving 261 architecture dependent paths. Can be \c NULL, in which case the 262 architecture associated with the initial path is used. 263 \param baseDirectory Constant indicating which path to retrieve. 264 \param subPath Relative subpath that shall be appended. Can be \c NULL. 265 \param flags Bitwise OR of any of the following flags: 266 - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't exist, 267 create it as a directory (including all missing ancestors). 268 - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's parent 269 doesn't exist, create the parent directory (including all missing 270 ancestors). 271 - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist, 272 fail with \c B_ENTRY_NOT_FOUND. 273 \param _path The variable to be set to the resulting path on success. 274 \return A status code. 275 \retval B_OK Everything went fine. 276 \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the 277 path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified 278 and the image file doesn't belong to a package, or \c dependency was 279 specified, but isn't a "requires" entry of the package, or 280 \c B_FIND_PATH_EXISTING_ONLY was specified and the resulting path 281 doesn't exist. 282*/ 283 284 285/*! 286 \fn status_t BPathFinder::FindPath(path_base_directory baseDirectory, 287 const char* subPath, uint32 flags, BPath& _path) 288 \brief Retrieves a path in the file system layout based. 289 290 Equivalent to a call to BPathFinder::FindPath(const char*, 291 path_base_directory, const char*, uint32, BPath&) with a \c NULL 292 architecture. 293 294 \param baseDirectory Constant indicating which path to retrieve. 295 \param subPath Relative subpath that shall be appended. Can be \c NULL. 296 \param flags Bitwise OR of any of the following flags: 297 - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't exist, 298 create it as a directory (including all missing ancestors). 299 - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's parent 300 doesn't exist, create the parent directory (including all missing 301 ancestors). 302 - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist, 303 fail with \c B_ENTRY_NOT_FOUND. 304 \param _path The variable to be set to the resulting path on success. 305 \return A status code. 306 \retval B_OK Everything went fine. 307 \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the 308 path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified 309 and the image file doesn't belong to a package, or \c dependency was 310 specified, but isn't a "requires" entry of the package, or 311 \c B_FIND_PATH_EXISTING_ONLY was specified and the resulting path 312 doesn't exist. 313*/ 314 315 316/*! 317 \fn status_t BPathFinder::FindPath(path_base_directory baseDirectory, 318 const char* subPath, BPath& _path) 319 \brief Retrieves a path in the file system layout based. 320 321 Equivalent to a call to BPathFinder::FindPath(const char*, 322 path_base_directory, const char*, uint32, BPath&) with a \c NULL 323 architecture and 0 flags. 324 325 \param baseDirectory Constant indicating which path to retrieve. 326 \param subPath Relative subpath that shall be appended. Can be \c NULL. 327 \param _path The variable to be set to the resulting path on success. 328 \return A status code. 329 \retval B_OK Everything went fine. 330 \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the 331 path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified 332 and the image file doesn't belong to a package, or \c dependency was 333 specified, but isn't a "requires" entry of the package. 334*/ 335 336 337/*! 338 \fn status_t BPathFinder::FindPath(path_base_directory baseDirectory, 339 BPath& _path) 340 \brief Retrieves a path in the file system layout based. 341 342 Equivalent to a call to BPathFinder::FindPath(const char*, 343 path_base_directory, const char*, uint32, BPath&) with a \c NULL 344 architecture, 0 flags, and \c NULL subpath. 345 346 \param baseDirectory Constant indicating which path to retrieve. 347 \param _path The variable to be set to the resulting path on success. 348 \return A status code. 349 \retval B_OK Everything went fine. 350 \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the 351 path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified 352 and the image file doesn't belong to a package, or \c dependency was 353 specified, but isn't a "requires" entry of the package. 354*/ 355 356 357/*! 358 \fn status_t BPathFinder::FindPaths(const char* architecture, 359 path_base_directory baseDirectory, const char* subPath, uint32 flags, 360 BStringList& _paths) 361 \brief Retrieves a list of paths in the file system layout. 362 363 For each installation location -- in the order most specific to most 364 generic, non-packaged before packaged -- the function evaluates 365 \a baseDirectory to a path and appends \a subPath, if given. 366 367 If \a baseDirectory specifies a path that is architecture dependent, 368 \a architecture is used for constructing each path. If \a architecture is 369 \c NULL, the caller's architecture (as returned by get_architecture()) is 370 used. 371 372 \c B_FIND_PATH_PACKAGE_PATH and \c B_FIND_PATH_IMAGE_PATH are not 373 valid arguments for this function. 374 375 \param architecture The name of the architecture to be used for resolving 376 architecture dependent paths. Can be \c NULL, in which case the caller's 377 architecture is used. 378 \param baseDirectory Constant indicating which paths to retrieve. 379 \param subPath Relative subpath that shall be appended. Can be \c NULL. 380 \param flags Bitwise OR of any of the following flags: 381 - \c B_FIND_PATH_CREATE_DIRECTORY: If a resulting path doesn't exist, 382 create it as a directory (including all missing ancestors). 383 - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If a resulting path's parent 384 doesn't exist, create the parent directory (including all missing 385 ancestors). 386 - \c B_FIND_PATH_EXISTING_ONLY: If a resulting path doesn't exist, skip 387 it. If none of the paths exist, fail with \c B_ENTRY_NOT_FOUND. 388 \param _paths The BStringList variable where the retrieved paths shall be 389 stored. The list is emptied before adding the paths. It is also emptied 390 on error. 391 \return A status code. 392 \retval B_OK Everything went fine. 393 \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the 394 paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was specified and 395 none of the resulting paths do exist. 396*/ 397 398 399/*! 400 \fn status_t BPathFinder::FindPaths(path_base_directory baseDirectory, 401 const char* subPath, uint32 flags, BStringList& _paths) 402 \brief Retrieves a list of paths in the file system layout. 403 404 Equivalent to a call to BPathFinder::FindPaths(const char*, 405 path_base_directory, const char*, uint32, BStringList&) with a \c NULL 406 architecture. 407 408 \param baseDirectory Constant indicating which paths to retrieve. 409 \param subPath Relative subpath that shall be appended. Can be \c NULL. 410 \param flags Bitwise OR of any of the following flags: 411 - \c B_FIND_PATH_CREATE_DIRECTORY: If a resulting path doesn't exist, 412 create it as a directory (including all missing ancestors). 413 - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If a resulting path's parent 414 doesn't exist, create the parent directory (including all missing 415 ancestors). 416 - \c B_FIND_PATH_EXISTING_ONLY: If a resulting path doesn't exist, skip 417 it. If none of the paths exist, fail with \c B_ENTRY_NOT_FOUND. 418 \param _paths The BStringList variable where the retrieved paths shall be 419 stored. The list is emptied before adding the paths. It is also emptied 420 on error. 421 \return A status code. 422 \retval B_OK Everything went fine. 423 \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the 424 paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was specified and 425 none of the resulting paths do exist. 426*/ 427 428 429/*! 430 \fn status_t BPathFinder::FindPaths(path_base_directory baseDirectory, 431 const char* subPath, BStringList& _paths) 432 \brief Retrieves a list of paths in the file system layout. 433 434 Equivalent to a call to BPathFinder::FindPaths(const char*, 435 path_base_directory, const char*, uint32, BStringList&) with a \c NULL 436 architecture and 0 flags. 437 438 \param baseDirectory Constant indicating which paths to retrieve. 439 \param subPath Relative subpath that shall be appended. Can be \c NULL. 440 \param _paths The BStringList variable where the retrieved paths shall be 441 stored. The list is emptied before adding the paths. It is also emptied 442 on error. 443 \return A status code. 444 \retval B_OK Everything went fine. 445 \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the 446 paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was specified and 447 none of the resulting paths do exist. 448*/ 449 450 451/*! 452 \fn status_t BPathFinder::FindPaths(path_base_directory baseDirectory, 453 BStringList& _paths) 454 \brief Retrieves a list of paths in the file system layout. 455 456 Equivalent to a call to BPathFinder::FindPaths(const char*, 457 path_base_directory, const char*, uint32, BStringList&) with a \c NULL 458 architecture, 0 flags, and \c NULL subpath. 459 460 \param baseDirectory Constant indicating which paths to retrieve. 461 \param _paths The BStringList variable where the retrieved paths shall be 462 stored. The list is emptied before adding the paths. It is also emptied 463 on error. 464 \return A status code. 465 \retval B_OK Everything went fine. 466 \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the 467 paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was specified and 468 none of the resulting paths do exist. 469*/ 470