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