Public Member Functions | Static Public Member Functions | List of all members
BPathFinder Class Reference

Helper class to retrieve paths in the file system layout. More...

Public Member Functions

 BPathFinder (const void *codePointer=NULL, const char *dependency=NULL)
 Creates an object referring to an installation location based on a loaded image file. More...
 
 BPathFinder (const char *path, const char *dependency=NULL)
 Creates an object referring to an installation location based on a given path. More...
 
 BPathFinder (const entry_ref &ref, const char *dependency=NULL)
 Creates an object referring to an installation location based on a given entry_ref. More...
 
 BPathFinder (const BResolvableExpression &expression, const char *dependency=NULL)
 Creates an object referring to an installation location based on the path of a package satisfying the given resolvable expression. More...
 
status_t FindPath (const char *architecture, path_base_directory baseDirectory, const char *subPath, uint32 flags, BPath &_path)
 Retrieves a path in the file system layout based. More...
 
status_t FindPath (path_base_directory baseDirectory, const char *subPath, uint32 flags, BPath &_path)
 Retrieves a path in the file system layout based. More...
 
status_t FindPath (path_base_directory baseDirectory, const char *subPath, BPath &_path)
 Retrieves a path in the file system layout based. More...
 
status_t FindPath (path_base_directory baseDirectory, BPath &_path)
 Retrieves a path in the file system layout based. More...
 
status_t SetTo (const void *codePointer=NULL, const char *dependency=NULL)
 Reinitializes the object to refer to an installation location based on a loaded image file. More...
 
status_t SetTo (const char *path, const char *dependency=NULL)
 Reinitializes the object to refer to an installation location based on a given path. More...
 
status_t SetTo (const entry_ref &ref, const char *dependency=NULL)
 Reinitializes the object to refer to an installation location based on a given entry_ref. More...
 
status_t SetTo (const BResolvableExpression &expression, const char *dependency=NULL)
 Reinitializes the object to refer to an installation location based on a given resolvable expression. More...
 

Static Public Member Functions

static status_t FindPaths (const char *architecture, path_base_directory baseDirectory, const char *subPath, uint32 flags, BStringList &_paths)
 Retrieves a list of paths in the file system layout. More...
 
static status_t FindPaths (path_base_directory baseDirectory, const char *subPath, uint32 flags, BStringList &_paths)
 Retrieves a list of paths in the file system layout. More...
 
static status_t FindPaths (path_base_directory baseDirectory, const char *subPath, BStringList &_paths)
 Retrieves a list of paths in the file system layout. More...
 
static status_t FindPaths (path_base_directory baseDirectory, BStringList &_paths)
 Retrieves a list of paths in the file system layout. More...
 

Detailed Description

Helper class to retrieve paths in the file system layout.

The BPathFinder provides two sets of methods for retrieving paths: FindPath() for getting a single path in an installation location specified via a constructor or a SetTo() invocation, and the static FindPaths() for getting a list of paths for all installation locations.

Since
Haiku R1

Constructor & Destructor Documentation

◆ BPathFinder() [1/4]

BPathFinder::BPathFinder ( const void *  codePointer = NULL,
const char *  dependency = NULL 
)

Creates an object referring to an installation location based on a loaded image file.

When initialized with this constructor a FindPath() method called afterward determines the path of the image (i.e. executable, library, or add-on) file associated with codePointer, a pointer to a location in the code or static data of an image loaded in the caller's team. Based on that path the path constant passed to FindPath() will be evaluated. In most cases that means first determining the path of the installation location from the path.

If dependency is specified, instead of determining the installation location path from the image path, the installation location path of the dependency dependency of the package containing the image file is used.

If the initialization fails, e.g. due to insufficient memory or invalid arguments, subsequent calls to FindPath() will return an error.

Parameters
codePointerA pointer to code or static data belonging to the image based on which FindPath() shall compute the path. The special value B_APP_IMAGE_SYMBOL (the default) can be used to refer to the program image, and B_CURRENT_IMAGE_SYMBOL for the caller's image.
dependencyThe name of the package's "requires" entry to be used for resolving the installation location. Can be NULL (the default).
Since
Haiku R1

◆ BPathFinder() [2/4]

BPathFinder::BPathFinder ( const char *  path,
const char *  dependency = NULL 
)

Creates an object referring to an installation location based on a given path.

When initialized with this constructor a FindPath() method called afterward evaluates the path constant passed to it based on path. In most cases that means first determining the path of the installation location from the given path.

If dependency is specified, instead of determining the installation location path from the given path, the installation location path of the dependency dependency of the package containing the file referred to by path is used.

If the initialization fails, e.g. due to insufficient memory or invalid arguments, subsequent calls to FindPath() will return an error.

Parameters
pathA path based on which FindPath() shall compute the path.
dependencyThe name of the package's "requires" entry to be used for resolving the installation location. Can be NULL.
Since
Haiku R1

◆ BPathFinder() [3/4]

BPathFinder::BPathFinder ( const entry_ref ref,
const char *  dependency = NULL 
)

Creates an object referring to an installation location based on a given entry_ref.

The constructor converts the given entry_ref ref to a path and then initializes the object like BPathFinder::BPathFinder(const char*, const char*).

Parameters
refA reference to be resolved to a path based on which FindPath() shall compute the path.
dependencyThe name of the package's "requires" entry to be used for resolving the installation location. Can be NULL.
See also
BPathFinder::BPathFinder(const char*, const char*)
Since
Haiku R1

◆ BPathFinder() [4/4]

BPathFinder::BPathFinder ( const BResolvableExpression &  expression,
const char *  dependency = NULL 
)

Creates an object referring to an installation location based on the path of a package satisfying the given resolvable expression.

The constructor finds the latest package that satisfies the resolvable expression expression and then uses its path to initialize the object like BPathFinder::BPathFinder(const char*, const char*).

Note
When using this constructor linking against libpackage.so is required.
Parameters
expressionA resolvable expression to be resolved to the path of the latest package satisfying it, based on which FindPath() shall compute the path.
dependencyThe name of the package's "requires" entry to be used for resolving the installation location. Can be NULL.
See also
BPathFinder::BPathFinder(const char*, const char*)
Since
Haiku R1

Member Function Documentation

◆ FindPath() [1/4]

status_t BPathFinder::FindPath ( const char *  architecture,
path_base_directory  baseDirectory,
const char *  subPath,
uint32  flags,
BPath _path 
)

Retrieves a path in the file system layout based.

Depending on how the object was initialized this method starts with a path (from an image file or as given) and based on it evaluates baseDirectory. In most cases that means first determining the path of the installation location from the path, then appending the relative path corresponding to the given baseDirectory constant, and finally appending subPath, if given.

If a dependency string was passed to the previous constructor or SetTo() method, instead of determining the installation location path from the initial path, the installation location path of the dependency of the package containing the file the initial path refers to is used.

If baseDirectory specifies a path that is architecture dependent, architecture is used for constructing the path. If architecture is NULL, the architecture associated with the initial path (as returned by guess_architecture_for_path()) is used. Note that if an image was specified, this is the same as the caller's architecture (as returned by get_architecture()).

If B_FIND_PATH_IMAGE_PATH or B_FIND_PATH_PACKAGE_PATH are specified, subPath is ignored. In the former case, which is only valid, if an image was specified for initialization, dependency is ignored as well and the path of the image file is returned. In the latter case the path of the package containing the file the initial path refers to, respectively, if dependency was specified, that of the package dependency was resolved to is returned.

Parameters
architectureThe name of the architecture to be used for resolving architecture dependent paths. Can be NULL, in which case the architecture associated with the initial path is used.
baseDirectoryConstant indicating which path to retrieve.
subPathRelative subpath that shall be appended. Can be NULL.
flagsBitwise OR of any of the following flags:
  • B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't exist, create it as a directory (including all missing ancestors).
  • B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's parent doesn't exist, create the parent directory (including all missing ancestors).
  • B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist, fail with B_ENTRY_NOT_FOUND.
_pathThe variable to be set to the resulting path on success.
Returns
A status code.
Return values
B_OKEverything went fine.
B_ENTRY_NOT_FOUNDA file system entry required for retrieving the path didn't exist, e.g. B_FIND_PATH_PACKAGE_PATH was specified and the image file didn't belong to a package, or dependency was specified, but wasn't a "requires" entry of the package, or B_FIND_PATH_EXISTING_ONLY was specified and the resulting path didn't exist.
Since
Haiku R1

◆ FindPath() [2/4]

status_t BPathFinder::FindPath ( path_base_directory  baseDirectory,
const char *  subPath,
uint32  flags,
BPath _path 
)

Retrieves a path in the file system layout based.

Equivalent to a call to BPathFinder::FindPath(const char*, path_base_directory, const char*, uint32, BPath&) with a NULL architecture.

Parameters
baseDirectoryConstant indicating which path to retrieve.
subPathRelative subpath that shall be appended. Can be NULL.
flagsBitwise OR of any of the following flags:
  • B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't exist, create it as a directory (including all missing ancestors).
  • B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's parent doesn't exist, create the parent directory (including all missing ancestors).
  • B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist, fail with B_ENTRY_NOT_FOUND.
_pathThe variable to be set to the resulting path on success.
Returns
A status code.
Return values
B_OKEverything went fine.
B_ENTRY_NOT_FOUNDA file system entry required for retrieving the path didn't exist, e.g. B_FIND_PATH_PACKAGE_PATH was specified and the image file didn't belong to a package, or dependency was specified, but wasn't a "requires" entry of the package, or B_FIND_PATH_EXISTING_ONLY was specified and the resulting path didn't exist.
Since
Haiku R1

◆ FindPath() [3/4]

status_t BPathFinder::FindPath ( path_base_directory  baseDirectory,
const char *  subPath,
BPath _path 
)

Retrieves a path in the file system layout based.

Equivalent to a call to BPathFinder::FindPath(const char*, path_base_directory, const char*, uint32, BPath&) with a NULL architecture and 0 flags.

Parameters
baseDirectoryConstant indicating which path to retrieve.
subPathRelative subpath that shall be appended. Can be NULL.
_pathThe variable to be set to the resulting path on success.
Returns
A status code.
Return values
B_OKEverything went fine.
B_ENTRY_NOT_FOUNDA file system entry required for retrieving the path didn't exist, e.g. B_FIND_PATH_PACKAGE_PATH was specified and the image file didn't belong to a package, or dependency was specified, but wasn't a "requires" entry of the package.

◆ FindPath() [4/4]

status_t BPathFinder::FindPath ( path_base_directory  baseDirectory,
BPath _path 
)

Retrieves a path in the file system layout based.

Equivalent to a call to BPathFinder::FindPath(const char*, path_base_directory, const char*, uint32, BPath&) with a NULL architecture, 0 flags, and NULL subpath.

Parameters
baseDirectoryConstant indicating which path to retrieve.
_pathThe variable to be set to the resulting path on success.
Returns
A status code.
Return values
B_OKEverything went fine.
B_ENTRY_NOT_FOUNDA file system entry required for retrieving the path didn't exist, e.g. B_FIND_PATH_PACKAGE_PATH was specified and the image file didn't belong to a package, or dependency was specified, but wasn't a "requires" entry of the package.
Since
Haiku R1

◆ FindPaths() [1/4]

status_t BPathFinder::FindPaths ( const char *  architecture,
path_base_directory  baseDirectory,
const char *  subPath,
uint32  flags,
BStringList &  _paths 
)
static

Retrieves a list of paths in the file system layout.

For each installation location – in the order most specific to most generic, non-packaged before packaged – the function evaluates baseDirectory to a path and appends subPath, if given.

If baseDirectory specifies a path that is architecture dependent, architecture is used for constructing each path. If architecture is NULL, the caller's architecture (as returned by get_architecture()) is used.

B_FIND_PATH_PACKAGE_PATH and B_FIND_PATH_IMAGE_PATH are not valid arguments for this function.

Parameters
architectureThe name of the architecture to be used for resolving architecture dependent paths. Can be NULL, in which case the caller's architecture is used.
baseDirectoryConstant indicating which paths to retrieve.
subPathRelative subpath that shall be appended. Can be NULL.
flagsBitwise OR of any of the following flags:
  • B_FIND_PATH_CREATE_DIRECTORY: If a resulting path doesn't exist, create it as a directory (including all missing ancestors).
  • B_FIND_PATH_CREATE_PARENT_DIRECTORY: If a resulting path's parent doesn't exist, create the parent directory (including all missing ancestors).
  • B_FIND_PATH_EXISTING_ONLY: If a resulting path doesn't exist, skip it. If none of the paths exist, fail with B_ENTRY_NOT_FOUND.
_pathsThe BStringList variable where the retrieved paths shall be stored. The list is emptied before adding the paths. It is also emptied on error.
Returns
A status code.
Return values
B_OKEverything went fine.
B_ENTRY_NOT_FOUNDA file system entry required for retrieving the paths didn't exist, e.g. B_FIND_PATH_EXISTING_ONLY was specified and none of the resulting paths existed.
Since
Haiku R1

◆ FindPaths() [2/4]

status_t BPathFinder::FindPaths ( path_base_directory  baseDirectory,
const char *  subPath,
uint32  flags,
BStringList &  _paths 
)
static

Retrieves a list of paths in the file system layout.

Equivalent to a call to BPathFinder::FindPaths(const char*, path_base_directory, const char*, uint32, BStringList&) with a NULL architecture.

Parameters
baseDirectoryConstant indicating which paths to retrieve.
subPathRelative subpath that shall be appended. Can be NULL.
flagsBitwise OR of any of the following flags:
  • B_FIND_PATH_CREATE_DIRECTORY: If a resulting path doesn't exist, create it as a directory (including all missing ancestors).
  • B_FIND_PATH_CREATE_PARENT_DIRECTORY: If a resulting path's parent doesn't exist, create the parent directory (including all missing ancestors).
  • B_FIND_PATH_EXISTING_ONLY: If a resulting path doesn't exist, skip it. If none of the paths exist, fail with B_ENTRY_NOT_FOUND.
_pathsThe BStringList variable where the retrieved paths shall be stored. The list is emptied before adding the paths. It is also emptied on error.
Returns
A status code.
Return values
B_OKEverything went fine.
B_ENTRY_NOT_FOUNDA file system entry required for retrieving the paths didn't exist, e.g. B_FIND_PATH_EXISTING_ONLY was specified and none of the resulting paths existed.
Since
Haiku R1

◆ FindPaths() [3/4]

status_t BPathFinder::FindPaths ( path_base_directory  baseDirectory,
const char *  subPath,
BStringList &  _paths 
)
static

Retrieves a list of paths in the file system layout.

Equivalent to a call to BPathFinder::FindPaths(const char*, path_base_directory, const char*, uint32, BStringList&) with a NULL architecture and 0 flags.

Parameters
baseDirectoryConstant indicating which paths to retrieve.
subPathRelative subpath that shall be appended. Can be NULL.
_pathsThe BStringList variable where the retrieved paths shall be stored. The list is emptied before adding the paths. It is also emptied on error.
Returns
A status code.
Return values
B_OKEverything went fine.
B_ENTRY_NOT_FOUNDA file system entry required for retrieving the paths didn't exist, e.g. B_FIND_PATH_EXISTING_ONLY was specified and none of the resulting paths existed.
Since
Haiku R1

◆ FindPaths() [4/4]

status_t BPathFinder::FindPaths ( path_base_directory  baseDirectory,
BStringList &  _paths 
)
static

Retrieves a list of paths in the file system layout.

Equivalent to a call to BPathFinder::FindPaths(const char*, path_base_directory, const char*, uint32, BStringList&) with a NULL architecture, 0 flags, and NULL subpath.

Parameters
baseDirectoryConstant indicating which paths to retrieve.
_pathsThe BStringList variable where the retrieved paths shall be stored. The list is emptied before adding the paths. It is also emptied on error.
Returns
A status code.
Return values
B_OKEverything went fine.
B_ENTRY_NOT_FOUNDA file system entry required for retrieving the paths didn't exist, e.g. B_FIND_PATH_EXISTING_ONLY was specified and none of the resulting paths existed.
Since
Haiku R1

◆ SetTo() [1/4]

status_t BPathFinder::SetTo ( const void *  codePointer = NULL,
const char *  dependency = NULL 
)

Reinitializes the object to refer to an installation location based on a loaded image file.

When reinitialized with this method a FindPath() method called afterward determines the path of the image (i.e. executable, library, or add-on) file associated with codePointer, a pointer to a location in the code or static data of an image loaded in the caller's team. Based on that path the path constant passed to FindPath() will be evaluated. In most cases that means first determining the path of the installation location from the path.

If dependency is specified, instead of determining the installation location path from the image path, the installation location path of the dependency dependency of the package containing the image file is used.

If the initialization fails, e.g. due to insufficient memory or invalid arguments, this method and subsequent calls to FindPath() will return an error.

Parameters
codePointerA pointer to code or static data belonging to the image based on which FindPath() shall compute the path. The special value B_APP_IMAGE_SYMBOL (the default) can be used to refer to the program image, and B_CURRENT_IMAGE_SYMBOL for the caller's image.
dependencyThe name of the package's "requires" entry to be used for resolving the installation location. Can be NULL (the default).
Returns
A status code.
Return values
B_OKEverything went fine.
Since
Haiku R1

◆ SetTo() [2/4]

status_t BPathFinder::SetTo ( const char *  path,
const char *  dependency = NULL 
)

Reinitializes the object to refer to an installation location based on a given path.

When reinitialized with this method a FindPath() method called afterward evaluates the path constant passed to it based on path. In most cases that means first determining the path of the installation location from the given path.

If dependency is specified, instead of determining the installation location path from the given path, the installation location path of the dependency dependency of the package containing the file referred to by path is used.

If the initialization fails, e.g. due to insufficient memory or invalid arguments, this method and subsequent calls to FindPath() will return an error.

Parameters
pathA path based on which FindPath() shall compute the path.
dependencyThe name of the package's "requires" entry to be used for resolving the installation location. Can be NULL.
Returns
B_OK Everything if went fine or an error code otherwise.
Since
Haiku R1

◆ SetTo() [3/4]

status_t BPathFinder::SetTo ( const entry_ref ref,
const char *  dependency = NULL 
)

Reinitializes the object to refer to an installation location based on a given entry_ref.

This method converts the given entry_ref ref to a path and then calls calls BPathFinder::SetTo(const char*, const char*).

Parameters
refA reference to be resolved to a path based on which FindPath() shall compute the path.
dependencyThe name of the package's "requires" entry to be used for resolving the installation location. Can be NULL.
See also
status_t BPathFinder::SetTo(const char*, const char*)
Returns
B_OK Everything if went fine or an error code otherwise.
Since
Haiku R1

◆ SetTo() [4/4]

status_t BPathFinder::SetTo ( const BResolvableExpression &  expression,
const char *  dependency = NULL 
)

Reinitializes the object to refer to an installation location based on a given resolvable expression.

This method finds the latest package that satisfies the resolvable expression expression and then passes its path to BPathFinder::SetTo(const char*, const char*).

Note
When using this method linking against libpackage.so is required.
Parameters
expressionA resolvable expression to be resolved to the path of the latest package satisfying it, based on which FindPath() shall compute the path.
dependencyThe name of the package's "requires" entry to be used for resolving the installation location. Can be NULL.
See also
status_t BPathFinder::SetTo(const char*, const char*)
Returns
B_OK Everything if went fine or an error code otherwise.
Since
Haiku R1