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