docs/user/storage/PathFinder.dox

   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 */