i2p/haiku-beta6
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation updates for Storage Kit classes

Browse Source 
* Added \since to each method and parameter.
* Whitespace cleanup.
* Some other minor cleanups and updates.
This commit is contained in:
John Scipione
2014-06-18 19:41:14 -04:00
parent a30a4a41f9
commit b885e90eb9
20 changed files with 3210 additions and 1756 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/storage/AppFileInfo.dox
+156 -185
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2011 Haiku, Inc. All rights reserved.
* Copyright 2011-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -7,8 +7,8 @@
* Ingo Weinhold, [email protected]
*
* Corresponds to:
* headers/os/storage/AppFileInfo.h rev 42274
* src/kits/storage/AppFileInfo.cpp rev 42274
* headers/os/storage/AppFileInfo.h hrev47402
* src/kits/storage/AppFileInfo.cpp hrev47402
*/
@@ -46,19 +46,23 @@
object will next look at the resource of the BFile. You can tell the
BFileInfo object to look only in the attributes or resources with the
SetInfoLocation() method.
\since BeOS R3
*/
/*!
\fn BAppFileInfo::BAppFileInfo()
\brief Creates an uninitialized BAppFileInfo object.
\since BeOS R3
*/
/*!
\fn BAppFileInfo::BAppFileInfo(BFile* file)
\brief Creates an BAppFileInfo object and initializes it to the supplied
file.
file.
The caller retains ownership of the supplied BFile object. It must not
be deleted during the life time of the BAppFileInfo. It is not deleted
@@ -66,6 +70,8 @@
\param file The BFile object that the BAppFileInfo object shall be
initialized to.
\since BeOS R3
*/
@@ -74,6 +80,8 @@
\brief Frees all resources associated with this object.
The supplied BFile object is not deleted if one is specified.
\since BeOS R3
*/
@@ -91,6 +99,8 @@
\returns an status code.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \c NULL \a file or \a file is not properly initialized.
\since BeOS R3
*/
@@ -107,17 +117,19 @@
\brief Gets the MIME type of the associated file.
\param type A pointer to a pre-allocated character buffer of size
\c B_MIME_TYPE_LENGTH or larger into which the MIME type of the
file will be written.
\c B_MIME_TYPE_LENGTH or larger into which the MIME type of the
file will be written.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE \c NULL \a type or the type string stored in the
attribute/resources is longer than \c B_MIME_TYPE_LENGTH.
attribute/resources is longer than \c B_MIME_TYPE_LENGTH.
\retval B_BAD_TYPE The attribute/resources the type string is stored in
has the wrong type.
has the wrong type.
\retval B_ENTRY_NOT_FOUND No type is set on the file.
\since BeOS R3
*/
@@ -128,13 +140,15 @@
If \a type is \c NULL if the file's MIME type is unset.
\param type The MIME type to be assigned to the file. It must not be
longer than \c B_MIME_TYPE_LENGTH (including the terminating null).
The MIME type may be \c NULL.
longer than \c B_MIME_TYPE_LENGTH (including the terminating \0).
The MIME type may be \c NULL.
\returns a status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE \a type is longer than \c B_MIME_TYPE_LENGTH.
\since BeOS R3
*/
@@ -154,17 +168,19 @@
\brief Gets the application signature of the associated file.
\param signature A pointer to a pre-allocated character buffer of size
\c B_MIME_TYPE_LENGTH or larger into which the application
signature of the file will be written.
\c B_MIME_TYPE_LENGTH or larger into which the application
signature of the file will be written.
\returns a status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE \c NULL \a signature or the signature stored in the
attribute/resources is longer than \c B_MIME_TYPE_LENGTH.
attribute/resources is longer than \c B_MIME_TYPE_LENGTH.
\retval B_BAD_TYPE The attribute/resources the signature is stored in have
the wrong type.
the wrong type.
\retval B_ENTRY_NOT_FOUND No signature is set on the file.
\since BeOS R3
*/
@@ -175,13 +191,15 @@
If \a signature is \c NULL the file's application signature is unset.
\param signature The application signature to be assigned to the file.
Must not be longer than \c B_MIME_TYPE_LENGTH (including the
terminating \c NUL). The \a signature may be \c NULL.
Must not be longer than \c B_MIME_TYPE_LENGTH (including the
terminating \0). The \a signature may be \c NULL.
\returns a status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE \a signature is longer than \c B_MIME_TYPE_LENGTH.
\since BeOS R3
*/
@@ -201,17 +219,19 @@
\brief Gets the catalog entry of the associated file used for localization.
\param catalogEntry A pointer to a pre-allocated character buffer of size
\c B_MIME_TYPE_LENGTH * 3 or larger into which the catalog entry
of the file will be written.
\c B_MIME_TYPE_LENGTH * 3 or larger into which the catalog entry
of the file will be written.
\returns a status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE \c NULL \a catalogEntry or the entry stored in the
attribute/resources is longer than \c B_MIME_TYPE_LENGTH * 3.
attribute/resources is longer than \c B_MIME_TYPE_LENGTH * 3.
\retval B_BAD_TYPE The attribute/resources the entry is stored in have
the wrong type.
the wrong type.
\retval B_ENTRY_NOT_FOUND No catalog entry is set on the file.
\since Haiku R1
*/
@@ -222,15 +242,17 @@
If \a catalogEntry is \c NULL the file's catalog entry is unset.
\param catalogEntry The catalog entry to be assigned to the file.
Of the form "x-vnd.Haiku-app:context:name". Must not be longer than
\c B_MIME_TYPE_LENGTH * 3 (including the terminating \c NUL).
The \a catalogEntry may be \c NULL.
Of the form "x-vnd.Haiku-app:context:name". Must not be longer than
\c B_MIME_TYPE_LENGTH * 3 (including the terminating \0).
The \a catalogEntry may be \c NULL.
\returns a status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE \a catalogEntry is longer than
\c B_MIME_TYPE_LENGTH * 3.
\c B_MIME_TYPE_LENGTH * 3.
\since Haiku R1
*/
@@ -250,15 +272,17 @@
\brief Gets the application \a flags of the associated file.
\param flags A pointer to a pre-allocated \c uint32 into which the
application flags of the file are written.
application flags of the file are written.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE \c NULL \a flags.
\retval B_BAD_TYPE The attribute/resources the flags are stored in have
the wrong type.
the wrong type.
\retval B_ENTRY_NOT_FOUND No application flags are set on the file.
\since BeOS R3
*/
@@ -271,6 +295,8 @@
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object was not properly initialized.
\since BeOS R3
*/
@@ -281,6 +307,8 @@
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object was not properly initialized.
\since Haiku R1
*/
@@ -303,24 +331,26 @@
\c B_STRING_TYPE in \a types.
\param types A pointer to a pre-allocated BMessage into which the
MIME types supported by the application will be written.
MIME types supported by the application will be written.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE \c NULL \a types.
\retval B_BAD_TYPE The attribute/resources that the supported types
are stored in have the wrong type.
are stored in have the wrong type.
\retval B_ENTRY_NOT_FOUND No supported types are set on the file.
\since BeOS R3
*/
/*!
\fn status_t BAppFileInfo::SetSupportedTypes(const BMessage* types,
bool updateMimeDB, bool syncAll)
\brief Sets the MIME types that are supported by the application and allows
you to specify whether or not the supported types in the MIME DB shall
be updated as well.
\brief Sets the MIME types that are supported by the application
and allows you to specify whether or not the supported types
in the MIME DB shall be updated as well.
If \a types is \c NULL then the application's supported types are unset.
@@ -338,15 +368,17 @@
is \c true.
\param types The supported types to be assigned to the file.
May be \c NULL.
May be \c NULL.
\param updateMimeDB \c true to update the supported types in the MIME DB,
\c false otherwise.
\c false otherwise.
\param syncAll \c true to also synchronize the no-longer supported
types, \c false otherwise.
types, \c false otherwise.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\since BeOS R3
*/
@@ -354,8 +386,8 @@
\fn status_t BAppFileInfo::SetSupportedTypes(const BMessage* types,
bool syncAll)
\brief Sets the MIME types that are supported by the application and allows
you to specify whether or not the no longer supported types shall be
updated as well.
you to specify whether or not the no longer supported types shall be
updated as well.
If \a types is \c NULL then the application's supported types are unset.
@@ -372,13 +404,15 @@
from the list of supporting applications.
\param types The supported types to be assigned to the file.
May be \c NULL.
May be \c NULL.
\param syncAll \c true to also synchronize the no-longer supported
types, \c false otherwise.
types, \c false otherwise.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\since BeOS R3
*/
@@ -390,10 +424,12 @@
\see SetSupportedType(const BMessage*, bool) for detailed information.
\param types The supported types to be assigned to the file.
May be \c NULL.
May be \c NULL.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\since BeOS R3
*/
@@ -408,6 +444,8 @@
\returns \c true if \a type is a valid MIME type and it is supported by
the application, \c false otherwise.
\since BeOS R3
*/
@@ -424,6 +462,8 @@
\returns \c true if \a type is a valid MIME type and it is explicitly
supported by the application, \c false otherwise.
\since BeOS R3
*/
@@ -440,21 +480,23 @@
/*!
\fn status_t BAppFileInfo::GetIcon(BBitmap* icon, icon_size which) const
\brief Gets the icon of the associated file and puts it into a pre-allocated
BBitmap.
\brief Gets the icon of the associated file and puts it into a
pre-allocated BBitmap.
\param icon A pointer to a pre-allocated BBitmap of the correct dimension
to store the requested icon (16x16 for the \c B_MINI_ICON and 32x32
for the \c B_LARGE_ICON).
to store the requested icon (16x16 for the \c B_MINI_ICON and 32x32
for the \c B_LARGE_ICON).
\param which Specifies the size of the icon to be retrieved:
\c B_MINI_ICON for the mini and \c B_LARGE_ICON for the large icon.
For HVIF icons this parameter has no effect.
\c B_MINI_ICON for the mini and \c B_LARGE_ICON for the large icon.
For HVIF icons this parameter has no effect.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE \c NULL \a icon, unsupported icon size \a which or
bitmap dimensions (\a icon) and icon size (\a which) do not match.
bitmap dimensions (\a icon) and icon size (\a which) do not match.
\since BeOS R3
*/
@@ -464,12 +506,14 @@
\param data The pointer in which the flat icon data will be returned.
\param size The pointer in which the size of the data found will be
returned.
returned.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE \c NULL \a data or \c NULL size.
\since BeOS R3
*/
@@ -481,20 +525,23 @@
If \a icon is \c NULL then the icon of the file is unset.
\param icon A pointer to the BBitmap containing the icon to be set.
May be \c NULL to specify no icon.
May be \c NULL to specify no icon.
\param which Specifies the size of the icon to be set: \c B_MINI_ICON for
16x16 mini icon and \c B_LARGE_ICON for the 32x32 large icon.
For HVIF icons this parameter has no effect.
16x16 mini icon and \c B_LARGE_ICON for the 32x32 large icon.
For HVIF icons this parameter has no effect.
\param updateMimeDB \c true to also set the icon for the application in the
MIME DB. \c false otherwise.
MIME DB. \c false otherwise.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE Unknown icon size \a which or bitmap dimensions
(\a icon) and icon size (\a which) do not match.
(\a icon) and icon size (\a which) do not match.
\since Haiku R1
*/
/*!
\fn status_t BAppFileInfo::SetIcon(const BBitmap* icon, icon_size which)
\brief Sets the icon of the associated file from a BBitmap.
@@ -505,16 +552,18 @@
application signature.
\param icon A pointer to the BBitmap containing the icon to be set.
May be \c NULL to specify no icon.
May be \c NULL to specify no icon.
\param which Specifies the size of the icon to be set: \c B_MINI_ICON for
16x16 mini icon and \c B_LARGE_ICON for the 32x32 large icon.
For HVIF icons this parameter has no effect.
16x16 mini icon and \c B_LARGE_ICON for the 32x32 large icon.
For HVIF icons this parameter has no effect.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE Unknown icon size \a which or bitmap dimensions
(\a icon) and icon size (\a which) do not match.
(\a icon) and icon size (\a which) do not match.
\since BeOS R3
*/
@@ -526,15 +575,17 @@
If \a data is \c NULL then the icon of the file is unset.
\param data A pointer to the data buffer containing the vector icon
to be set. May be \c NULL.
to be set. May be \c NULL.
\param size Specifies the size of buffer pointed to by \a data.
\param updateMimeDB \c true to also set the icon for the application in the
MIME DB. \c false otherwise.
MIME DB. \c false otherwise.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE \c NULL data.
\since Haiku R1
*/
@@ -548,13 +599,15 @@
application signature.
\param data A pointer to the data buffer containing the vector icon
to be set. May be \c NULL.
to be set. May be \c NULL.
\param size Specifies the size of buffer pointed to by \a data.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE \c NULL data.
\since Haiku R1
*/
@@ -562,23 +615,25 @@
\fn status_t BAppFileInfo::GetIconForType(const char* type, BBitmap* icon,
icon_size size) const
\brief Gets the icon the application provides for a given MIME type and
puts it into a BBitmap.
puts it into a BBitmap.
\note If \a type is \c NULL, the application's icon is retrieved.
\param type The MIME type in question. May be \c NULL.
\param icon A pointer to a pre-allocated BBitmap of the correct dimension
to store the requested icon (16x16 for the mini and 32x32 for the
large icon).
to store the requested icon (16x16 for the mini and 32x32 for the
large icon).
\param size Specifies the size of the icon to be retrieved:
\c B_MINI_ICON for the mini and \c B_LARGE_ICON for the large icon.
\c B_MINI_ICON for the mini and \c B_LARGE_ICON for the large icon.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE \c NULL \a icon, unsupported icon size
\a which or bitmap dimensions (\a icon) and icon size (\a which) do
not match.
\a which or bitmap dimensions (\a icon) and icon size (\a which)
do not match.
\since BeOS R3
*/
@@ -586,7 +641,7 @@
\fn status_t BAppFileInfo::GetIconForType(const char* type, uint8** data,
size_t* size) const
\brief Gets the icon the application provides for a given MIME type and
puts it into a buffer.
puts it into a buffer.
\note If \a type is set to \c NULL the the application's icon is retrieved.
@@ -599,7 +654,9 @@
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE \c NULL \a data and/or \a size. Or the supplied
\a type is not a valid MIME type.
\a type is not a valid MIME type.
\since Haiku R1
*/
@@ -607,7 +664,7 @@
\fn status_t BAppFileInfo::SetIconForType(const char* type,
const BBitmap* icon, icon_size which, bool updateMimeDB)
\brief Sets the icon the application provides for a given MIME type from a
BBitmap.
BBitmap.
\note If \a type is \c NULL then the icon is set.
\note If \a icon is \c NULL then the icon is unset.
@@ -618,18 +675,20 @@
\param type The MIME type in question. May be \c NULL.
\param icon A pointer to the BBitmap containing the icon to be set.
May be \c NULL.
May be \c NULL.
\param which Specifies the size of the icon to be set: \c B_MINI_ICON
for the mini and \c B_LARGE_ICON for the large icon.
for the mini and \c B_LARGE_ICON for the large icon.
\param updateMimeDB \c true to also set the icon for the type in the MIME
DB. \c false otherwise.
DB. \c false otherwise.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE Either the icon size \a which is unknown,
the bitmap dimensions (\a icon) and icon size (\a which) do not
match, or the provided \a type is not a valid MIME type.
the bitmap dimensions (\a icon) and icon size (\a which) do not
match, or the provided \a type is not a valid MIME type.
\since Haiku R1
*/
@@ -637,7 +696,7 @@
\fn status_t BAppFileInfo::SetIconForType(const char* type,
const BBitmap* icon, icon_size which)
\brief Sets the icon the application provides for a given MIME type from a
BBitmap.
BBitmap.
\note If \a type is \c NULL then the icon is set.
\note If \a icon is \c NULL then the icon is unset.
@@ -656,8 +715,10 @@
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE Either the icon size \a which is unknown,
the bitmap dimensions (\a icon) and icon size (\a which) do not
match, or the provided \a type is not a valid MIME type.
the bitmap dimensions (\a icon) and icon size (\a which) do not
match, or the provided \a type is not a valid MIME type.
\since BeOS R3
*/
@@ -665,7 +726,7 @@
\fn status_t BAppFileInfo::SetIconForType(const char* type,
const uint8* data, size_t size, bool updateMimeDB)
\brief Sets the icon the application provides for a given MIME type from a
buffer.
buffer.
\note If \a type is \c NULL then the icon is set.
\note If \a data is \c NULL then the icon is unset.
@@ -676,15 +737,17 @@
\param type The MIME type in question. May be \c NULL.
\param data A pointer to the data containing the icon to be set.
May be \c NULL.
May be \c NULL.
\param size Specifies the size of buffer provided in \a data.
\param updateMimeDB \c true to also set the icon for the type in the MIME
DB. \c false otherwise.
DB. \c false otherwise.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE The provided \a type is not a valid MIME type.
\since Haiku R1
*/
@@ -692,7 +755,7 @@
\fn status_t BAppFileInfo::SetIconForType(const char* type,
const uint8* data, size_t size)
\brief Sets the icon the application provides for a given MIME type from a
buffer.
buffer.
\note If \a type is \c NULL then the icon is set.
\note If \a data is \c NULL then the icon is unset.
@@ -703,13 +766,15 @@
\param type The MIME type in question. May be \c NULL.
\param data A pointer to the data containing the icon to be set.
May be \c NULL.
May be \c NULL.
\param size Specifies the size of buffer provided in \a data.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE The provided \a type is not a valid MIME type.
\since Haiku R1
*/
@@ -740,6 +805,8 @@
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE \c NULL \a info.
\since BeOS R3
*/
@@ -759,6 +826,8 @@
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\since BeOS R3
*/
@@ -783,6 +852,8 @@
- \c B_USE_BOTH_LOCATIONS: Store the data in attributes and resources.
\param location The location where the metadata shall be stored.
\since BeOS R3
*/
@@ -793,6 +864,8 @@
\returns \c true if the metadata are (also) stored in the file's
attributes, \c false otherwise.
\since BeOS R3
*/
@@ -803,111 +876,9 @@
\returns \c true if the metadata are (also) stored in the file's
resources, \c false otherwise.
\since BeOS R3
*/
//! @}
/*!
\fn BAppFileInfo & BAppFileInfo::operator=(const BAppFileInfo &)
\brief Privatized assignment operator to prevent usage.
*/
/*!
\fn BAppFileInfo::BAppFileInfo(const BAppFileInfo &)
\brief Privatized copy constructor to prevent usage.
*/
/*!
\fn status_t BAppFileInfo::GetMetaMime(BMimeType* meta) const
\brief Initializes a BMimeType to the signature of the associated file.
\warning The parameter \a meta is not checked.
\param meta A pointer to a pre-allocated BMimeType that shall be
initialized to the signature of the associated file.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \c NULL \a meta
\retval B_ENTRY_NOT_FOUND The file has not signature or the signature is
(not installed in the MIME database.) no valid MIME string.
*/
/*!
\fn status_t BAppFileInfo::_ReadData(const char* name, int32 id,
type_code type, void* buffer, size_t bufferSize,
size_t &bytesRead, void** allocatedBuffer) const
\brief Reads data from an attribute or resource.
\note The data is read from the location specified by \a fWhere.
\warning The object must be properly initialized. The parameters are
\b NOT checked.
\param name The name of the attribute/resource to be read.
\param id The resource ID of the resource to be read. It is ignored
when < 0.
\param type The type of the attribute/resource to be read.
\param buffer A pre-allocated buffer for the data to be read.
\param bufferSize The size of the supplied buffer.
\param bytesRead A reference parameter, set to the number of bytes
actually read.
\param allocatedBuffer If not \c NULL, the method allocates a buffer
large enough too store the whole data and writes a pointer to it
into this variable. If \c NULL, the supplied buffer is used.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_ENTRY_NOT_FOUND The entry was not found.
\retval B_NO_MEMORY Ran out of memory allocating the buffer.
\retval B_BAD_VALUE \a type did not match.
*/
/*!
\fn status_t BAppFileInfo::_WriteData(const char* name, int32 id,
type_code type, const void* buffer, size_t bufferSize, bool findID)
\brief Writes data to an attribute or resource.
\note The data is written to the location(s) specified by \a fWhere.
\warning The object must be properly initialized. The parameters are
\b NOT checked.
\param name The name of the attribute/resource to be written.
\param id The resource ID of the resource to be written.
\param type The type of the attribute/resource to be written.
\param buffer A buffer containing the data to be written.
\param bufferSize The size of the supplied buffer.
\param findID If set to \c true use the ID that is already assigned to the
\a name / \a type pair or take the first unused ID >= \a id.
If \c false, \a id is used.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_ERROR An error occurred while trying to write the data.
*/
/*!
\fn status_t BAppFileInfo::_RemoveData(const char* name, type_code type)
\brief Removes an attribute or resource.
\note The removal location is specified by \a fWhere.
\warning The object must be properly initialized. The parameters are
\b NOT checked.
\param name The name of the attribute/resource to be remove.
\param type The type of the attribute/resource to be removed.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT Not using attributes and not using resources.
\retval B_ENTRY_NOT_FOUND The attribute or resource was not found.
*/
docs/user/storage/Directory.dox
+128 -62
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2011 Haiku, Inc. All rights reserved.
* Copyright 2011-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -9,8 +9,8 @@
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/storage/Directory.h hrev43528
* src/kits/storage/Directory.cpp hrev43528
* headers/os/storage/Directory.h hrev47402
* src/kits/storage/Directory.cpp hrev47402
*/
@@ -27,12 +27,16 @@
\ingroup storage
\ingroup libbe
\brief A directory in the file system.
\since BeOS R3
*/
/*!
\fn BDirectory::BDirectory()
\brief Creates an uninitialized BDirectory object.
\since BeOS R3
*/
@@ -41,52 +45,64 @@
\brief Creates a copy of the supplied BDirectory object.
\param dir The BDirectory object to be copied.
\since BeOS R3
*/
/*!
\fn BDirectory::BDirectory(const entry_ref* ref)
\brief Creates a BDirectory and initializes it to the directory referred
to by the supplied entry_ref.
to by the supplied entry_ref.
\param ref The entry_ref that refers to the directory.
\since BeOS R3
*/
/*!
\fn BDirectory::BDirectory(const node_ref* nref)
\brief Creates a BDirectory and initializes it to the directory referred
to by the supplied node_ref.
to by the supplied node_ref.
\param nref The node_ref that refers to the directory.
\since BeOS R3
*/
/*!
\fn BDirectory::BDirectory(const BEntry* entry)
\brief Creates a BDirectory and initializes it to the directory referred
to by the supplied BEntry.
to by the supplied BEntry.
\param entry The BEntry that refers to the directory.
\since BeOS R3
*/
/*!
\fn BDirectory::BDirectory(const char* path)
\brief Creates a BDirectory and initializes it to the directory referred
to by the supplied \a path name.
to by the supplied \a path name.
\param path The \a path name of the directory.
\since BeOS R3
*/
/*!
\fn BDirectory::BDirectory(const BDirectory* dir, const char* path)
\brief Creates a BDirectory and initializes it to the directory referred
to by the supplied path name relative to the specified BDirectory.
to by the supplied path name relative to the specified BDirectory.
\param dir The base BDirectory object.
\param path The \a path of the directory relative to \a dir
\since BeOS R3
*/
@@ -96,13 +112,15 @@
If the BDirectory is properly initialized, the directory's file descriptor
is closed.
\since BeOS R3
*/
/*!
\fn status_t BDirectory::SetTo(const entry_ref* ref)
\brief Re-initializes the BDirectory to the directory referred to by the
supplied entry_ref.
supplied entry_ref.
\param ref The entry_ref referring to the directory.
@@ -116,13 +134,15 @@
\retval B_BUSY A node was busy.
\retval B_FILE_ERROR A general file error.
\retval B_NO_MORE_FDS The application has run out of file descriptors.
\since BeOS R3
*/
/*!
\fn status_t BDirectory::SetTo(const node_ref* nref)
\brief Re-initializes the BDirectory to the directory referred to by the
supplied node_ref.
supplied node_ref.
\param nref The node_ref referring to the directory.
@@ -136,13 +156,15 @@
\retval B_BUSY A node was busy.
\retval B_FILE_ERROR A general file error.
\retval B_NO_MORE_FDS The application has run out of file descriptors.
\since BeOS R3
*/
/*!
\fn status_t BDirectory::SetTo(const BEntry* entry)
\brief Re-initializes the BDirectory to the directory referred to by the
supplied BEntry.
supplied BEntry.
\param entry The BEntry referring to the directory.
@@ -156,13 +178,15 @@
\retval B_BUSY A node was busy.
\retval B_FILE_ERROR A general file error.
\retval B_NO_MORE_FDS The application has run out of file descriptors.
\since BeOS R3
*/
/*!
\fn status_t BDirectory::SetTo(const char* path)
\brief Re-initializes the BDirectory to the directory referred to by the
supplied path name.
supplied path name.
\param path The directory's \a path name.
@@ -178,13 +202,15 @@
\retval B_FILE_ERROR A general file error.
\retval B_NO_MORE_FDS The application has run out of file descriptors.
\retval B_NOT_A_DIRECTORY \a path includes a non-directory.
\since BeOS R3
*/
/*!
\fn status_t BDirectory::SetTo(const BDirectory* dir, const char* path)
\brief Re-initializes the BDirectory to the directory referred to by the
supplied path name relative to the specified BDirectory.
supplied path name relative to the specified BDirectory.
\param dir The base directory.
\param path The directory path name relative to \a dir.
@@ -201,13 +227,15 @@
\retval B_FILE_ERROR A general file error.
\retval B_NO_MORE_FDS The application has run out of file descriptors.
\retval B_NOT_A_DIRECTORY \a path includes a non-directory.
\since BeOS R3
*/
/*!
\fn status_t BDirectory::GetEntry(BEntry* entry) const
\brief Gets a BEntry object referring to the directory. If the
initialization of \a entry fails, it is Unset().
initialization of \a entry fails, it is Unset().
\param entry A pointer to the \a entry that will refer to the directory.
@@ -221,6 +249,8 @@
\retval B_BUSY A node was busy.
\retval B_FILE_ERROR A general file error.
\retval B_NO_MORE_FDS The application has run out of file descriptors.
\since BeOS R3
*/
@@ -229,7 +259,9 @@
\brief Returns whether the directory is the root directory of a volume.
\returns \c true if the BDirectory is properly initialized and represents
a root directory of a volume, \c false otherwise.
a root directory of a volume, \c false otherwise.
\since BeOS R3
*/
@@ -237,18 +269,18 @@
\fn status_t BDirectory::FindEntry(const char* path, BEntry* entry,
bool traverse) const
\brief Finds an entry referred to by a path relative to the directory
represented by this BDirectory.
represented by this BDirectory.
\a path may represent an absolute path. If the BDirectory is not properly
initialized then the entry is relative to the current directory. If the
entry couldn't be found, \a entry is Unset().
\note The functionality of this method differs from
BEntry::SetTo(BDirectory *, const char *, bool) in that it doesn't
require the entry to exist, whereas this method does.
BEntry::SetTo(BDirectory *, const char *, bool) in that it doesn't
require the entry to exist, whereas this method does.
\param path The entry's \a path name. May be relative to this directory
or an absolute path.
or an absolute path.
\param entry A pointer to a BEntry to be initialized with the found entry.
\param traverse Whether or not to follow a symbolic link.
@@ -266,69 +298,77 @@
\retval B_NOT_A_DIRECTORY \a path includes a non-directory.
\sa BEntry::SetTo(BDirectory *, const char *, bool)
\since BeOS R3
*/
/*!
\fn bool BDirectory::Contains(const char* path, int32 nodeFlags) const
\brief Returns whether or not this directory or any of its subdirectories
at any level contain the entry referred to by the supplied path name.
at any level contain the entry referred to by the supplied path
name.
Only entries that match the node flavor specified by \a nodeFlags are
considered.
If the BDirectory is not properly initialized, the method returns \c false.
A non-absolute path is considered relative to the current directory.
If the BDirectory is not properly initialized, the method returns
\c false. A non-absolute path is considered relative to the current
directory.
\note R5's implementation always returns \c true given an absolute path
or an unitialized directory. This implementation is not compatible
with that behavior. Instead it converts the path into a BEntry and
passes it to the other version of Contains().
\note BeOS R5's implementation always returns \c true given an absolute
path or an initialized directory. This implementation is not
compatible with that behavior. Instead it converts the path into
a BEntry and passes it to the other version of Contains().
\param path The entry's \a path name. May be relative to this directory
or may be an absolute \a path.
or may be an absolute \a path.
\param nodeFlags Any of the following:
- \c B_FILE_NODE: The entry must be a file.
- \c B_DIRECTORY_NODE: The entry must be a directory.
- \c B_SYMLINK_NODE: The entry must be a symbolic link.
- \c B_ANY_NODE: The entry may be of any kind.
- \c B_FILE_NODE: The entry must be a file.
- \c B_DIRECTORY_NODE: The entry must be a directory.
- \c B_SYMLINK_NODE: The entry must be a symbolic link.
- \c B_ANY_NODE: The entry may be of any kind.
\returns \c true if the entry exists and its kind does match \a nodeFlags
and the BDirectory is properly initialized and does contain the entry
at any level, \c false otherwise.
and the BDirectory is properly initialized and does contain the
entry at any level, \c false otherwise.
\since BeOS R3
*/
/*!
\fn bool BDirectory::Contains(const BEntry* entry, int32 nodeFlags) const
\brief Returns whether or not this directory or any of its subdirectories
at any level contain the entry referred to by the supplied BEntry.
at any level contain the entry referred to by the supplied BEntry.
Only entries that match the node flavor specified by \a nodeFlags are
considered.
\note If the paths are identical, this method returns \c true to stay
consistent with BeOS 5.
consistent with BeOS 5.
\param entry a BEntry referring to the entry
\param nodeFlags Any of the following:
- \c B_FILE_NODE: The entry must be a file.
- \c B_DIRECTORY_NODE: The entry must be a directory.
- \c B_SYMLINK_NODE: The entry must be a symbolic link.
- \c B_ANY_NODE: The entry may be of any kind.
- \c B_FILE_NODE: The entry must be a file.
- \c B_DIRECTORY_NODE: The entry must be a directory.
- \c B_SYMLINK_NODE: The entry must be a symbolic link.
- \c B_ANY_NODE: The entry may be of any kind.
\returns \c true if the BDirectory is properly initialized and the
entry of the matching kind was found, \c false otherwise.
entry of the matching kind was found, \c false otherwise.
\since BeOS R3
*/
/*!
\fn status_t BDirectory::GetStatFor(const char* path, struct stat* st) const
\brief Returns the stat structure of the entry referred to by the supplied
path name.
path name.
\param path The entry's path name. May be relative to this directory or
absolute, or \c NULL to get the directories stat info.
absolute, or \c NULL to get the directories stat info.
\param st A pointer to the stat structure to be filled in by this method.
\returns A status code.
@@ -343,6 +383,8 @@
\retval B_FILE_ERROR A general file error.
\retval B_NO_MORE_FDS The application has run out of file descriptors.
\retval B_NOT_A_DIRECTORY \a path includes a non-directory.
\since BeOS R3
*/
@@ -353,7 +395,7 @@
Unlike GetNextDirents() this method ignores "." and "..".
\note The iterator used by this method is the same one used by
GetNextRef(), GetNextDirents(), Rewind() and CountEntries().
GetNextRef(), GetNextDirents(), Rewind() and CountEntries().
\param entry A pointer to a BEntry to be initialized to the found entry
\param traverse Specifies whether or not to follow a symbolic link.
@@ -368,6 +410,8 @@
\retval B_BUSY A node was busy.
\retval B_FILE_ERROR A general file error.
\retval B_NO_MORE_FDS The application has run out of file descriptors.
\since BeOS R3
*/
@@ -378,10 +422,10 @@
Unlike GetNextDirents() this method ignores "." and "..".
\note The iterator used be this method is the same one used by
GetNextEntry(), GetNextDirents(), Rewind() and CountEntries().
GetNextEntry(), GetNextDirents(), Rewind() and CountEntries().
\param ref A pointer to an entry_ref to be filled in with the data
from the found entry.
from the found entry.
\returns A status code.
\retval B_OK Everything went fine.
@@ -393,27 +437,31 @@
\retval B_BUSY A node was busy.
\retval B_FILE_ERROR A general file error.
\retval B_NO_MORE_FDS The application has run out of file descriptors.
\since BeOS R3
*/
/*!
\fn int32 BDirectory::GetNextDirents(dirent* buf, size_t bufSize, int32 count)
\fn int32 BDirectory::GetNextDirents(dirent* buf, size_t bufSize,
int32 count)
\brief Returns the next entries of the BDirectory object as a pointer
to dirent structures.
to dirent structures.
Unlike GetNextEntry() and GetNextRef(), this method returns also
the entries "." and "..".
\note The iterator used by this method is the same one used by
GetNextEntry(), GetNextRef(), Rewind() and CountEntries().
GetNextEntry(), GetNextRef(), Rewind() and CountEntries().
\param buf A pointer to a buffer filled with dirent structures containing
the found entries.
the found entries.
\param bufSize The size of \a buf.
\param count The maximum number of entries to be returned.
\returns The number of dirent structures stored in the buffer, 0 when
there are no more entries to be returned or a status code on error.
there are no more entries to be returned or a status code on
error.
\retval B_BAD_VALUE \c NULL \a buf.
\retval B_PERMISSION_DENIED Directory permissions didn't allow operation.
\retval B_NO_MEMORY Insufficient memory for operation.
@@ -422,6 +470,8 @@
\retval B_BUSY A node was busy.
\retval B_FILE_ERROR A general file error.
\retval B_NO_MORE_FDS The application has run out of file descriptors.
\since BeOS R3
*/
@@ -442,6 +492,8 @@
\sa BDirectory::GetNextRef()
\sa BDirectory::GetNextDirents()
\sa BDirectory::CountEntries()
\since BeOS R3
*/
@@ -454,7 +506,7 @@
the entries and Rewind()s again. The entries "." and ".." are not counted.
\returns The number of entries in the directory (not counting "." and
"..") or a status code on error.
"..") or a status code on error.
\retval B_PERMISSION_DENIED Directory permissions didn't allow operation.
\retval B_NO_MEMORY Insufficient memory for operation.
\retval B_LINK_LIMIT Indicates a cyclic loop within the file system.
@@ -466,6 +518,8 @@
\sa BDirectory::GetNextRef()
\sa BDirectory::GetNextDirents()
\sa BDirectory::Rewind()
\since BeOS R3
*/
@@ -477,9 +531,9 @@
an error status code.
\param path The new path name of the directory. May be a relative
path to this directory or an absolute path.
path to this directory or an absolute path.
\param dir A pointer to a BDirectory to be initialized to the newly
created directory. May be \c NULL.
created directory. May be \c NULL.
\returns A status code.
\retval B_OK Everything went fine.
@@ -492,6 +546,8 @@
\retval B_FILE_ERROR A general file error.
\retval B_FILE_EXISTS An entry with that name does already exist.
\retval B_NO_MORE_FDS The application has run out of file descriptors.
\since BeOS R3
*/
@@ -506,9 +562,9 @@
mode.
\param path The new file's path name. May be relative to this
directory or an absolute path.
directory or an absolute path.
\param file A pointer to a BFile to be initialized to the newly
created file. May be \c NULL.
created file. May be \c NULL.
\param failIfExists Whether or not to fail if the file already exists.
\returns A status code.
@@ -521,10 +577,12 @@
\retval B_BUSY A node was busy.
\retval B_FILE_ERROR A general file error.
\retval B_FILE_EXISTS A file with that name does already exist and
\c true has been passed for \a failIfExists.
\c true has been passed for \a failIfExists.
\retval B_IS_A_DIRECTORY A directory with the supplied name already
exists.
exists.
\retval B_NO_MORE_FDS The application has run out of file descriptors.
\since BeOS R3
*/
@@ -536,10 +594,10 @@
This method fails if an entry with the supplied name already exists.
\param path the new symbolic link's path name. May be relative to this
directory or absolute.
directory or absolute.
\param linkToPath the path the symbolic link shall point to.
\param link a pointer to a BSymLink to be initialized to the newly
created symbolic link. May be \c NULL.
created symbolic link. May be \c NULL.
\returns A status code.
\retval B_OK Everything went fine.
@@ -552,6 +610,8 @@
\retval B_FILE_ERROR A general file error.
\retval B_FILE_EXISTS An entry with that name does already exist.
\retval B_NO_MORE_FDS The application has run out of file descriptors.
\since BeOS R3
*/
@@ -566,6 +626,8 @@
\param dir The original BDirectory object.
\returns A reference to this BDirectory object.
\since BeOS R3
*/
@@ -577,6 +639,8 @@
member directly.
\returns the file descriptor, or -1 if not properly initialized.
\since Haiku R1
*/
@@ -586,7 +650,7 @@
\param path The directory path name.
\param mode A permission specification, which shall be used for the
newly created directories.
newly created directories.
\returns A status code.
\retval B_OK Everything went fine.
@@ -598,6 +662,8 @@
\retval B_BUSY A node was busy.
\retval B_FILE_ERROR A general file error.
\retval B_NOT_A_DIRECTORY An entry other than a directory with that name
already exists.
already exists.
\retval B_NO_MORE_FDS The application has run out of file descriptors.
\since BeOS R3
*/
docs/user/storage/Entry.dox
+119 -126
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2011 Haiku, Inc. All rights reserved.
* Copyright 2011-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -8,8 +8,8 @@
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/storage/Entry.h hrev43528
* src/kits/storage/Entry.cpp hrev43528
* headers/os/storage/Entry.h hrev47402
* src/kits/storage/Entry.cpp hrev47402
*/
@@ -45,28 +45,34 @@
the old name (the upside in this case is that abstract entries may be
represented by entry_refs without preallocating an internal filesystem node
for them).
\since BeOS R3
*/
/*!
\fn entry_ref::entry_ref()
\brief Creates an uninitialized entry_ref object.
\since BeOS R3
*/
/*!
\fn entry_ref::entry_ref(dev_t dev, ino_t dir, const char* name)
\brief Creates an entry_ref object initialized to the given file name in
the given directory on the given device.
the given directory on the given device.
\a name may refer to either a pre-existing file in the given directory, or
a non-existent file. No explicit checking is done to verify validity of the
given arguments, but later use of the entry_ref will fail if \p dev is not
a valid device or \a dir is a not a directory on \p dev.
\param dev the device on which the entry's parent directory resides
\param dir the directory in which the entry resides
\param name the leaf name of the entry, which is not required to exist
\param dev The \a device on which the entry's parent directory resides.
\param dir The directory in which the entry resides.
\param name The leaf name of the entry, which is not required to exist.
\since BeOS R3
*/
@@ -75,41 +81,51 @@
\brief Returns a copy of the passed in entry_ref object.
\param ref A reference to an entry_ref to copy.
\since BeOS R3
*/
/*!
\fn entry_ref::~entry_ref()
\brief Destroys the object and frees the storage allocated for the leaf
name, if necessary.
name, if necessary.
\since BeOS R3
*/
/*!
\fn status_t entry_ref::set_name(const char* name)
\brief Set the entry_ref's leaf name, freeing the storage allocated for any
previous name and then making a copy of the new name.
previous name and then making a copy of the new name.
\param name Pointer to a null-terminated string containing the new name for
the entry. May be \c NULL.
the entry. May be \c NULL.
\since BeOS R3
*/
/*!
\fn bool entry_ref::operator==(const entry_ref& ref) const
\brief Compares the entry_ref object with the passed in entry_ref,
returning \c true if they are equal.
returning \c true if they are equal.
\returns \c true if he entry_refs are equal, \c false otherwise.
\since BeOS R3
*/
/*!
\fn bool entry_ref::operator!=(const entry_ref& ref) const
\brief Compares the entry_ref object with the passed in entry_ref,
returning \c true if they are NOT equal.
returning \c true if they are NOT equal.
\returns \c true if the entry_refs are NOT equal, \c false otherwise.
\since BeOS R3
*/
@@ -120,6 +136,8 @@
\param ref The entry_ref to copy.
\returns A pointer to the resulting entry_ref copy.
\since BeOS R5
*/
@@ -128,6 +146,7 @@
The device id of the storage device on which the entry resides.
\since BeOS R3
*/
@@ -135,6 +154,8 @@
\var ino_t entry_ref::directory
The inode number of the directory in which the entry resides.
\since BeOS R3
*/
@@ -142,6 +163,8 @@
\var char *entry_ref::name
The leaf name of the entry
\since BeOS R3
*/
@@ -170,10 +193,13 @@ BEntry entry("/boot/home/fido");
Should be followed by a call to one of the SetTo() methods, or an
assignment.
- SetTo(const BDirectory*, const char*, bool)
- SetTo(const entry_ref*, bool)
- SetTo(const char*, bool)
- operator=(const BEntry&)
\sa SetTo(const BDirectory*, const char*, bool)
\sa SetTo(const entry_ref*, bool)
\sa SetTo(const char*, bool)
\sa operator=(const BEntry&)
\since BeOS R3
*/
@@ -191,6 +217,8 @@ BEntry entry("/boot/home/fido");
\param traverse Whether or not to traverse symbolic links.
\see BEntry::SetTo(const BDirectory*, const char *, bool)
\since BeOS R3
*/
@@ -207,6 +235,8 @@ BEntry entry("/boot/home/fido");
\param traverse Whether or not symlinks are to be traversed.
\sa BEntry::SetTo(const entry_ref*, bool)
\since BeOS R3
*/
@@ -223,6 +253,8 @@ BEntry entry("/boot/home/fido");
\param traverse Whether or not symlinks are to be traversed.
\sa BEntry::SetTo(const char*, bool)
\since BeOS R3
*/
@@ -233,6 +265,8 @@ BEntry entry("/boot/home/fido");
\param entry the entry to be copied
\sa operator=(const BEntry&)
\since BeOS R3
*/
@@ -241,6 +275,8 @@ BEntry entry("/boot/home/fido");
\brief Frees all of the allocated resources of the BEntry.
\sa Unset()
\since BeOS R3
*/
@@ -251,7 +287,9 @@ BEntry entry("/boot/home/fido");
\returns A status code.
\retval B_OK Success
\retval B_NO_INIT The object has been Unset() or is uninitialized.
*/
\since BeOS R3
/*!
@@ -259,6 +297,8 @@ BEntry entry("/boot/home/fido");
\brief Returns whether or not the entry exists in the filesystem.
\returns \c true if the entry exists, \c false if not.
\since BeOS R3
*/
@@ -276,6 +316,8 @@ BEntry entry("/boot/home/fido");
information is copied.
\returns \c B_OK on success, or an error code on failure.
\since BeOS R3
*/
@@ -283,20 +325,22 @@ BEntry entry("/boot/home/fido");
\fn status_t BEntry::SetTo(const BDirectory* dir, const char* path,
bool traverse)
\brief Reinitializes the BEntry to the path or directory path combination,
resolving symlinks if traverse is \c true.
resolving symlinks if traverse is \c true.
\param dir The base directory in which the \a path resides.
\param path Relative path based off of \a dir.
\param traverse Whether or not to traverse symbolic links.
\returns \c B_OK on success, or an error code on failure.
\since BeOS R3
*/
/*!
\fn status_t BEntry::SetTo(const entry_ref* ref, bool traverse)
\brief Reinitializes the BEntry to the passed in entry_ref object
resolving symlinks if traverse is \c true.
resolving symlinks if traverse is \c true.
\param ref The entry_ref referring to the given file.
\param traverse Whether or not symlinks are to be traversed.
@@ -304,13 +348,15 @@ BEntry entry("/boot/home/fido");
\returns \c B_OK on success, or an error code on failure.
\sa BEntry::BEntry(const entry_ref* ref, bool traverse)
\since BeOS R3
*/
/*!
\fn status_t BEntry::SetTo(const char* path, bool traverse)
\brief Reinitializes the BEntry object to the path, resolving symlinks if
traverse is \c true.
traverse is \c true.
\param path The path of the file.
\param traverse Whether or not symlinks are to be traversed.
@@ -318,12 +364,16 @@ BEntry entry("/boot/home/fido");
\returns \c B_OK on success, or an error code on failure.
\sa BEntry::BEntry(const char* path, bool traverse)
\since BeOS R3
*/
/*!
void BEntry::Unset()
\brief Reinitializes the BEntry to an uninitialized BEntry object
\since BeOS R3
*/
@@ -335,6 +385,8 @@ BEntry entry("/boot/home/fido");
result is copied.
\returns \c B_OK on success, or an error code on failure.
\since BeOS R3
*/
@@ -346,6 +398,8 @@ BEntry entry("/boot/home/fido");
result is copied.
\returns \c B_OK on success, or an error code on failure.
\since BeOS R3
*/
@@ -382,12 +436,14 @@ if (err != B_ENTRY_NOT_FOUND)
\endcode
\param entry A pointer to a pre-allocated BEntry object into which the
result is stored.
result is stored.
\returns A status code.
\retval B_OK Success
\retval B_ENTRY_NOT_FOUND Attempted to get the parent of the root
directory.
directory.
\since BeOS R3
*/
@@ -398,12 +454,14 @@ if (err != B_ENTRY_NOT_FOUND)
If the function fails, the argument is Unset().
\param dir A pointer to a pre-allocated BDirectory object into which the
result is copied.
result is copied.
\returns A status code.
\retval B_OK Success
\retval B_ENTRY_NOT_FOUND Attempted to get the parent of the root
directory.
directory.
\since BeOS R3
*/
@@ -415,32 +473,36 @@ if (err != B_ENTRY_NOT_FOUND)
entire string. A length of \c B_FILE_NAME_LENGTH is recommended.
\param buffer A pointer to a pre-allocated string into which the result
is copied.
is copied.
\returns \c B_OK on success, or an error code on failure.
\since BeOS R3
*/
/*!
\fn status_t BEntry::Rename(const char* path, bool clobber)
\brief Renames the BEntry to \a path replacing an existing entry
if \a clobber is \c true.
if \a clobber is \c true.
\note The BEntry object must refer to an existing file, if it is abstract,
this method will fail.
this method will fail.
\param path A pointer to a string containing the new name for the entry.
It may be an absolute or relative path. If it is a relative path the
entry is renamed within its current directory.
It may be an absolute or relative path. If it is a relative path
the entry is renamed within its current directory.
\param clobber If \c false and a file with the name given by \c path
already exists, the method will fail. If \c true and such a file
exists, it will be overwritten.
already exists, the method will fail. If \c true and such a file
exists, it will be overwritten.
\returns A status code.
\retval B_OK Success
\retval B_ENTRY_EXISTS The new location already exists and \c clobber
is \c false.
is \c false.
\retval B_ENTRY_NOT_FOUND Attempted to rename an abstract entry.
\since BeOS R3
*/
@@ -454,19 +516,21 @@ if (err != B_ENTRY_NOT_FOUND)
this method will fail.
\param dir A pointer to a pre-allocated BDirectory into which the entry
should be moved.
should be moved.
\param path (optional) new leaf name for the entry. May be a simple leaf
or a relative path; either way, \c path is reckoned off of \c dir. If
\c NULL, the entry retains its previous leaf name.
or a relative path; either way, \c path is reckoned off of \c dir.
If \c NULL, the entry retains its previous leaf name.
\param clobber If \c false and an entry already exists at the specified
destination, the method will fail. If \c true and such an entry exists,
it will be overwritten.
Spdestination, the method will fail. If \c true and such an entry
exists, it will be overwritten.
\returns A status code.
\retval B_OK Success
\retval B_ENTRY_EXISTS The new location already exists and \c clobber
is \c false.
is \c false.
\retval B_ENTRY_NOT_FOUND Attempted to rename an abstract entry.
\since BeOS R3
*/
@@ -480,28 +544,36 @@ if (err != B_ENTRY_NOT_FOUND)
no longer refers to any actual data in the filesystem.
\returns \c B_OK on success, or an error code on failure.
\since BeOS R3
*/
/*!
\fn bool BEntry::operator==(const BEntry& item) const
\brief Returns \c true if the BEntry and \a item refer to the same entry
or if they are both uninitialized.
or if they are both uninitialized.
\returns Whether or not the items refer to the same entry.
\retval true Both BEntry objects refer to the same entry or they are
both uninitialized.
both uninitialized.
\retval false The BEntry objects refer to different entries.
\since BeOS R3
*/
/*!
\fn bool BEntry::operator!=(const BEntry& item) const
\brief Returns false if the BEntry and \c item refer to the same entry or
if they are both uninitialized.
if they are both uninitialized.
\returns Whether or not the items do NOT refer to the same entry.
\retval true The BEntry objects refer to different entries.
\retval false Both BEntry objects refer to the same entry or they are
both uninitialized.
both uninitialized.
\since BeOS R3
*/
@@ -510,91 +582,8 @@ if (err != B_ENTRY_NOT_FOUND)
\brief Reinitializes the BEntry to be a copy of \a item.
\returns A pointer to the copy.
*/
/*!
\fn status_t BEntry::set_stat(struct stat& st, uint32 what)
\brief Updates the BEntry with the data from the stat structure according
to the \a what mask.
\param st The stat structure to set.
\param what A mask
\returns A status code.
\retval B_OK Everything went fine.
\retval B_FILE_ERROR There was an error writing to the BEntry object.
*/
/*!
\fn status_t BEntry::_SetTo(int dirFD, const char* path, bool traverse)
\brief Sets the entry to point to the entry specified by the path \a path
relative to the given directory.
If \a traverse is \c true and the given entry is a symbolic link, the
object is recursively set to point to the entry pointed to by the symlink.
If \a path is an absolute path, \a dirFD is ignored.
If \a dirFD is -1, \a path is considered relative to the current directory
(unless it is an absolute path).
The ownership of the file descriptor \a dirFD is transferred to the
method, regardless of whether it succeeds or fails. The caller must not
close the FD afterwards.
\param dirFD File descriptor of a directory relative to which path is to
be considered. May be -1 if the current directory shall be considered.
\param path Pointer to a path relative to the given directory.
\param traverse If \c true and the given entry is a symbolic link, the
object is recursively set to point to the entry linked to by the
symbolic link.
\returns \c B_OK on success, or an error code on failure.
*/
/*!
\fn status_t BEntry::_SetName(const char* name)
\brief Handles string allocation, deallocation, and copying for the
leaf name of the entry.
\param name The leaf \a name of the entry.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \a name is \c NULL.
\retval B_NO_MEMORY Ran out of memory trying to allocate \a name.
*/
/*!
\fn status_t BEntry::_Rename(BEntry& target, bool clobber)
\brief Renames the entry referred to by this object to the location
specified by \a target.
If an entry exists at the target location, the method fails, unless
\a clobber is \c true, in which case that entry is overwritten (doesn't
work for non-empty directories, though).
If the operation was successful, this entry is made a clone of the
supplied one and the supplied one is uninitialized.
\param target The entry specifying the target location.
\param clobber If \c true, the an entry existing at the target location
will be overwritten.
\return \c B_OK, if everything went fine, another error code otherwise.
*/
/*!
\fn void BEntry::_Dump(const char* name)
\brief Debugging function, dumps the given entry to stdout.
\param name A pointer to a string to be printed along with the dump for
identification purposes.
\since BeOS R3
*/
@@ -610,6 +599,8 @@ if (err != B_ENTRY_NOT_FOUND)
\retval B_BAD_VALUE \c NULL \a path or \a ref.
\retval B_ENTRY_NOT_FOUND A (non-leaf) path component does not exist.
\retval B_NO_MEMORY Insufficient memory for successful completion.
\since BeOS R4
*/
@@ -622,4 +613,6 @@ if (err != B_ENTRY_NOT_FOUND)
\retval true a < b
\retval false a >= b
\since Haiku R1
*/
docs/user/storage/EntryList.dox
+35 -19
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2011 Haiku, Inc. All rights reserved.
* Copyright 2011-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -7,8 +7,8 @@
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/storage/EntryList.h rev 42794
* src/kits/storage/EntryList.cpp rev 42794
* headers/os/storage/EntryList.h hrev47402
* src/kits/storage/EntryList.cpp hrev47402
*/
@@ -28,6 +28,8 @@
Defines a general interface for iterating through a list of entries
i.e. files in a folder.
\since BeOS R3
*/
@@ -36,6 +38,8 @@
\brief Creates a BEntryList object.
Does nothing at this time.
\since Haiku R1
*/
@@ -44,6 +48,8 @@
\brief Frees all resources associated with the BEntryList object.
Does nothing at this time.
\since Haiku R1
*/
@@ -56,15 +62,17 @@
\param entry a pointer to a BEntry to be initialized with the found entry.
\param traverse specifies whether to follow it, if the found entry
is a symbolic link.
is a symbolic link.
\note The iterator used by this method is the same one used by
GetNextRef(), GetNextDirents(), Rewind() and CountEntries().
GetNextRef(), GetNextDirents(), Rewind() and CountEntries().
\retval B_OK if successful
\retval B_ENTRY_NOT_FOUND when at the end of the list
\retval B_ERROR or another error code (depending on the implementation
of the derived class).
of the derived class).
\since BeOS R3
*/
@@ -75,21 +83,23 @@
Places an entry_ref to the next entry in the list into \a ref.
\param ref a pointer to an entry_ref to be filled in with the data of the
found entry.
found entry.
\note The iterator used by this method is the same one used by
GetNextEntry(), GetNextDirents(), Rewind() and CountEntries().
GetNextEntry(), GetNextDirents(), Rewind() and CountEntries().
\retval B_OK if successful
\retval B_ENTRY_NOT_FOUND when at the end of the list
\retval B_ERROR or another error code (depending on the implementation
of the derived class).
of the derived class).
\since BeOS R3
*/
/*!
\fn int32 BEntryList::GetNextDirents(struct dirent *buf, size_t length,
int32 count)
int32 count)
\brief Returns the BEntryList's next entries as dirent structures.
Reads a number of entries into the array of dirent structures pointed
@@ -98,18 +108,20 @@
\a buf with given length \a length (in bytes), whichever is smallest.
\param buf A pointer to a buffer to be filled with dirent structures of
the found entries.
the found entries.
\param length The length of the \a buf array.
\param count the maximum number of entries to be read.
\note The iterator used by this method is the same one used by
GetNextEntry(), GetNextRef(), Rewind() and CountEntries().
GetNextEntry(), GetNextRef(), Rewind() and CountEntries().
\returns
- The number of dirent structures stored in the buffer or 0 when
there are no more entries to be read.
- an error code (depending on the implementation of the derived class)
if an error occurred.
- The number of dirent structures stored in the buffer or 0 when
there are no more entries to be read.
- an error code (depending on the implementation of the derived class)
if an error occurred.
\since BeOS R3
*/
@@ -119,7 +131,9 @@
\retval B_OK if successful
\retval B_ERROR or another error code (depending on the implementation
of the derived class).
of the derived class).
\since BeOS R3
*/
@@ -130,5 +144,7 @@
\retval B_OK if successful
\retval B_ENTRY_NOT_FOUND when at the end of the list
\retval B_ERROR or another error code (depending on the implementation
of the derived class).
*/
of the derived class).
\since BeOS R3
*/
docs/user/storage/File.dox
+89 -59
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2009-2012 Haiku, Inc. All rights reserved.
* Copyright 2009-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -8,8 +8,8 @@
* Ingo Weinhold, [email protected]
*
* Corresponds to:
* headers/os/storage/File.h hrev45060
* src/kits/storage/File.cpp hrev45060
* headers/os/storage/File.h hrev47402
* src/kits/storage/File.cpp hrev47402
*/
@@ -33,6 +33,8 @@
Symbolic links are automatically transversed by opening a BFile.
The node that the BFile ends up opening will be the file or directory
that the link points to, not the symbolic link file itself.
\since BeOS R3
*/
@@ -47,6 +49,8 @@
- SetTo(const char* path, uint32 openMode)
- SetTo(const BDirectory* dir, const char* path, uint32 openMode)
- operator=(const BFile &file)
\since BeOS R3
*/
@@ -57,57 +61,67 @@
If \a file is uninitialized, the newly constructed BFile will be too.
\param file The BFile object to be copied.
\since BeOS R3
*/
/*!
\fn BFile::BFile(const entry_ref* ref, uint32 openMode)
\brief Creates a BFile and initializes it to the file referred to by
the supplied entry_ref and according to the specified open mode.
the supplied entry_ref and according to the specified open mode.
\param ref The entry_ref referring to the file.
\param openMode The mode in which the file should be opened.
\see SetTo(const entry_ref* ref, uint32 openMode)
\since BeOS R3
*/
/*!
\fn BFile::BFile(const BEntry* entry, uint32 openMode)
\brief Creates a BFile and initializes it to the file referred to by
the supplied BEntry and according to the specified open mode.
the supplied BEntry and according to the specified open mode.
\param entry The BEntry referring to the file.
\param openMode The mode in which the file should be opened.
\see SetTo(const BEntry* entry, uint32 openMode)
\since BeOS R3
*/
/*!
\fn BFile::BFile(const char* path, uint32 openMode)
\brief Creates a BFile and initializes it to the file referred to by
the supplied path name and according to the specified open mode.
the supplied path name and according to the specified open mode.
\param path The file's path name.
\param openMode The mode in which the file should be opened.
\see SetTo(const char* path, uint32 openMode)
\since BeOS R3
*/
/*!
\fn BFile::BFile(const BDirectory *dir, const char* path, uint32 openMode)
\brief Creates a BFile and initializes it to the file referred to by
the supplied path name relative to the specified BDirectory and
according to the specified open mode.
the supplied path name relative to the specified BDirectory and
according to the specified open mode.
\param dir The BDirectory, relative to which the file's path name is
given.
given.
\param path The file's path name relative to \a dir.
\param openMode The mode in which the file should be opened.
\see SetTo(const BDirectory* dir, const char* path, uint32 openMode)
\since BeOS R3
*/
@@ -116,27 +130,30 @@
\brief Destroys the BFile object and frees all allocated resources.
If the file is properly initialized, the file descriptor is closed.
\since BeOS R3
*/
/*!
\fn status_t BFile::SetTo(const entry_ref* ref, uint32 openMode)
\brief Re-initializes the BFile to the file referred to by the
supplied entry_ref and according to the specified open mode.
supplied entry_ref and according to the specified open mode.
\param ref The entry_ref referring to the file.
\param openMode The mode in which the file should be opened
\a openMode must be a bitwise or of exactly one of the flags.
- \c B_READ_ONLY: The file is opened read only.
- \c B_WRITE_ONLY: The file is opened write only.
- \c B_READ_WRITE: The file is opened for random read/write access.
and any number of the flags
- \c B_CREATE_FILE: A new file will be created, if it does not already
exist.
- \c B_FAIL_IF_EXISTS: If the file does already exist and
\c B_CREATE_FILE is set, SetTo() fails.
- \c B_ERASE_FILE: An already existing file is truncated to zero size.
- \c B_OPEN_AT_END: Seek() to the end of the file after opening.
\a openMode must be a bitwise or of exactly one of the flags.
- \c B_READ_ONLY: The file is opened read only.
- \c B_WRITE_ONLY: The file is opened write only.
- \c B_READ_WRITE: The file is opened for random read/write access.
and any number of the flags
- \c B_CREATE_FILE: A new file will be created, if it does not
already exist.
- \c B_FAIL_IF_EXISTS: If the file does already exist and
\c B_CREATE_FILE is set, SetTo() fails.
- \c B_ERASE_FILE: An already existing file is truncated to zero
size.
- \c B_OPEN_AT_END: Seek() to the end of the file after opening.
\returns A status code.
\retval B_OK Everything went fine.
@@ -149,13 +166,15 @@
\retval B_BUSY A node was busy.
\retval B_FILE_ERROR A general file error.
\retval B_NO_MORE_FDS The application has run out of file descriptors.
\since BeOS R3
*/
/*!
\fn status_t BFile::SetTo(const BEntry* entry, uint32 openMode)
\brief Re-initializes the BFile to the file referred to by the
supplied BEntry and according to the specified open mode.
supplied BEntry and according to the specified open mode.
\param entry the BEntry referring to the file
\param openMode the mode in which the file should be opened
@@ -173,14 +192,16 @@
\retval B_NO_MORE_FDS The application has run out of file descriptors.
\todo Implemented using SetTo(entry_ref*, uint32). Check, if necessary
to re-implement!
to re-implement!
\since BeOS R3
*/
/*!
\fn status_t BFile::SetTo(const char* path, uint32 openMode)
\brief Re-initializes the BFile to the file referred to by the
supplied path name and according to the specified open mode.
supplied path name and according to the specified open mode.
\param path The file's path name.
\param openMode The mode in which the file should be opened.
@@ -196,19 +217,20 @@
\retval B_BUSY A node was busy.
\retval B_FILE_ERROR A general file error.
\retval B_NO_MORE_FDS The application has run out of file descriptors.
*/
\since BeOS R3
*/
/*!
\fn status_t BFile::SetTo(const BDirectory* dir, const char* path,
uint32 openMode)
uint32 openMode)
\brief Re-initializes the BFile to the file referred to by the
supplied path name relative to the specified BDirectory and
according to the specified open mode.
supplied path name relative to the specified BDirectory and
according to the specified open mode.
\param dir The BDirectory, relative to which the file's path name is
given.
given.
\param path The file's path name relative to \a dir.
\param openMode The mode in which the file should be opened.
@@ -225,7 +247,9 @@
\retval B_NO_MORE_FDS The application has run out of file descriptors.
\todo Implemented using SetTo(BEntry*, uint32). Check, if necessary
to re-implement!
to re-implement!
\since BeOS R3
*/
@@ -237,6 +261,8 @@
- \c true, if the BFile has been initialized properly and the file has
been been opened for reading,
- \c false, otherwise.
\since BeOS R3
*/
@@ -248,6 +274,8 @@
- \c true, if the BFile has been initialized properly and the file has
been opened for writing,
- \c false, otherwise.
\since BeOS R3
*/
@@ -259,20 +287,24 @@
\param size The number of bytes that shall be read.
\returns The number of bytes read or an error code.
\since BeOS R3
*/
/*!
\fn ssize_t BFile::ReadAt(off_t location, void* buffer, size_t size)
\brief Reads a number of bytes from a certain position within the file
into a buffer.
into a buffer.
\param location The position (in bytes) within the file from which the
data shall be read.
data shall be read.
\param buffer The buffer the data from the file shall be written to.
\param size The number of bytes that shall be read.
\returns The number of bytes read or an error code.
\since BeOS R3
*/
@@ -284,20 +316,24 @@
\param size The number of bytes that shall be written.
\returns The number of bytes actually written or an error code.
\since BeOS R3
*/
/*!
\fn ssize_t BFile::WriteAt(off_t location, const void* buffer, size_t size)
\brief \brief Writes a number of bytes from a buffer at a certain position
into the file.
\brief Writes a number of bytes from a buffer at a certain position
into the file.
\param location The position (in bytes) within the file at which the data
shall be written.
shall be written.
\param buffer The buffer containing the data to be written to the file.
\param size The number of bytes that shall be written.
\returns The number of bytes actually written or an error code.
\since BeOS R3
*/
@@ -311,16 +347,18 @@
or Write() invocations will be undefined.
\param offset New read/write position, depending on \a seekMode relative
to the beginning or the end of the file or the current position.
to the beginning or the end of the file or the current position.
\param seekMode
- \c SEEK_SET: move relative to the beginning of the file
- \c SEEK_CUR: move relative to the current position
- \c SEEK_END: move relative to the end of the file
- \c SEEK_SET: move relative to the beginning of the file.
- \c SEEK_CUR: move relative to the current position.
- \c SEEK_END: move relative to the end of the file.
\returns The new read/write position relative to the beginning of the
file or an error code.
file or an error code.
\retval B_ERROR Trying to seek before the beginning of the file.
\retval B_FILE_ERROR The file is not properly initialized.
\since BeOS R3
*/
@@ -329,9 +367,11 @@
\brief Gets the current read/write position within the file.
\returns The current read/write position relative to the beginning of the
file or an error code.
file or an error code.
\retval B_ERROR After a Seek() before the beginning of the file.
\retval B_FILE_ERROR The file has not been initialized.
\since BeOS R3
*/
@@ -344,15 +384,17 @@
truncated.
\note There's no problem with setting the size of a BFile opened in
\c B_READ_ONLY mode, unless the file resides on a read only volume.
\c B_READ_ONLY mode, unless the file resides on a read only volume.
\param size The new file size.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NOT_ALLOWED Trying to set the size of a file on a read only
volume.
volume.
\retval B_DEVICE_FULL There's not enough space left on the volume.
\since BeOS R3
*/
@@ -365,6 +407,8 @@
\returns A status code.
\see BStatable::GetSize()
\since BeOS R3
*/
@@ -378,20 +422,6 @@
\param file The original BFile to assign from.
\returns A reference to the assigned BFile.
*/
/*!
\fn int BFile::get_fd() const
\brief Gets the file descriptor of the BFile.
To be used instead of accessing the BNode's private \c fFd member directly.
\returns The file descriptor, or -1 if not properly initialized.
*/
/*!
\fn void BFile::close_fd()
\brief Overrides BNode::close_fd() for binary compatibility with BeOS R5.
\since BeOS R3
*/
docs/user/storage/FilePanel.dox
+116 -24
View File
@@ -1,13 +1,13 @@
/*
* Copyright 2009-2012 Haiku, Inc. All rights reserved.
* Copyright 2009-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/storage/FilePanel.h hrev45162
* src/kits/tracker/FilePanel.cpp hrev45162
* headers/os/storage/FilePanel.h hrev47402
* src/kits/tracker/FilePanel.cpp hrev47402
*/
@@ -23,6 +23,8 @@
\enum file_panel_mode
\ingroup storage
\brief Whether the file panel is a save or open panel.
\since BeOS R3
*/
@@ -30,12 +32,16 @@
\var file_panel_mode B_OPEN_PANEL
Open panel
\since BeOS R3
*/
/*!
\var file_panel_mode B_SAVE_PANEL
\since BeOS R3
Save panel
*/
@@ -43,7 +49,9 @@
/*!
\enum file_panel_button
\ingroup storage
\brief List of buttons used by the file panel
\brief List of buttons used by the file panel.
\since BeOS R3
*/
@@ -51,6 +59,8 @@
\var file_panel_button B_CANCEL_BUTTON
Cancel button
\since BeOS R3
*/
@@ -58,6 +68,8 @@
\var file_panel_button B_DEFAULT_BUTTON
Default button
\since BeOS R3
*/
@@ -66,6 +78,8 @@
\ingroup storage
\ingroup libbe
\brief Allows you to filter the items displayed in a file panel.
\since BeOS R3
*/
@@ -73,7 +87,7 @@
\fn virtual bool BRefFilter::Filter(const entry_ref* ref, BNode* node,
struct stat_beos* stat, const char* mimeType)
\brief Hook method that's called on each file in the target directory
displayed by a file panel.
displayed by a file panel.
\param ref The file currently under consideration.
\param node The node currently under consideration.
@@ -81,9 +95,11 @@
\param mimeType The MIME type of the file.
\returns Whether or not the entry is a valid candidate for an open/save
dialog.
dialog.
\see BFilePanel::SetRefFilter()
\since BeOS R3
*/
@@ -172,6 +188,8 @@
destroyed, it is hidden instead. You can then delete the BFilePanel
object or leave it be and simply call Show() to use the panel next time
you need it.
\since BeOS R3
*/
@@ -189,22 +207,28 @@
SetRefFilter(), and SetHideWhenDone() methods.
\param mode Set to \c B_OPEN_PANEL for an open panal or \c B_SAVE_PANEL
for a save panel. Default is \c B_OPEN_PANEL.
for a save panel. Default is \c B_OPEN_PANEL.
\param target The BMessenger object that sends messages to the BLooper
or BHandler controlled by the file panel.
or BHandler controlled by the file panel.
\param ref The directory to display, by default the current working
directory.
\param nodeFlavors One or more option flags, this applies to open panels only.
- \c B_FILE_NODE Can select files and symlinks to files.
- \c B_DIRECTORY_NODE Can select directories and symlinks to directories.
- \c B_SYMLINK_NODE Can select symlinks only.
directory.
\param nodeFlavors One or more option flags, this applies to open panels
only.
- \c B_FILE_NODE Can select files and symlinks to files.
- \c B_DIRECTORY_NODE Can select directories and symlinks to
directories.
- \c B_SYMLINK_NODE Can select symlinks only.
\param multipleSelection Whether or not the user is allowed to select more
than one item to open. Save panels should always set this to \c false.
than one item to open. Save panels should always set this to
\c false.
\param message Message sent by the file panel on confirms or cancels.
\param filter Hook method to call.
\param modal Whether or not the panel is modal, defaults to \c false.
\param hideWhenDone Set to \c false to keep the panel even after the user
confirms or cancels. The close button will hide the panel regardless.
confirms or cancels. The close button will hide the panel
regardless.
\since BeOS R3
*/
@@ -214,18 +238,24 @@
If file panel is currently being displayed it is closed. The BRefFilter
object references by this panel is not destroyed by this method.
\since BeOS R3
*/
/*!
\fn void BFilePanel::Show()
\brief Displays the file panel on screen.
\since BeOS R3
*/
/*!
\fn void BFilePanel::Hide()
\brief Hides the file panel.
\since BeOS R3
*/
@@ -234,6 +264,10 @@
\brief Determines whether or not the file panel is shown.
\returns \c true if visible, \c false if hidden.
\see Show()
\since BeOS R3
*/
@@ -246,6 +280,8 @@
\param message The message to send.
\see BMessenger::SendMessage()
\since BeOS R3
*/
@@ -253,8 +289,10 @@
\fn file_panel_mode BFilePanel::PanelMode() const
\brief Gets the panel mode, either \c B_OPEN_PANEL or \c B_SAVE_PANEL.
\returns \c B_OPEN_PANEL if the panel is an open panel or \c B_SAVE_PANEL
if the panel is a save panel.
\returns \c B_OPEN_PANEL if the panel is an open panel, or \c B_SAVE_PANEL
if the panel is a save panel.
\since BeOS R3
*/
@@ -263,6 +301,8 @@
\brief Gets the panel's target messenger object.
\returns The BMessenger object that sends messages for this panel.
\since BeOS R3
*/
@@ -271,6 +311,8 @@
\brief Sets the target messenger.
\param target the target BMessenger object to set.
\since BeOS R3
*/
@@ -279,13 +321,17 @@
\brief Sets the target messenge.
\param message The BMessage object to send on confirm.
\since BeOS R3
*/
/*!
\fn void BFilePanel::Refresh()
\brief Refresh the directory or the panel causing the entries to be re-run
through the BRefFilter::Filter() method.
through the BRefFilter::Filter() method.
\since BeOS R3
*/
@@ -296,6 +342,8 @@
\returns The BRefFilter set to the panel.
\see BRefFilter::Filter()
\since BeOS R3
*/
@@ -306,6 +354,8 @@
\param filter The BRefFilter object to set.
\see BRefFilter::Filter()
\since BeOS R3
*/
@@ -316,6 +366,8 @@
\param button The button to set the label of.
\param text The text to set the button label to.
\since BeOS R3
*/
@@ -324,6 +376,8 @@
\brief Gets the entry ref of the panel and sets \a ref to point to it.
\param ref The \c entry_ref pointer you want set.
\since BeOS R3
*/
@@ -332,42 +386,52 @@
\brief Set some save text to display in the save dialog.
\param text The text to display.
\since BeOS R3
*/
/*!
\fn void BFilePanel::SetPanelDirectory(const entry_ref* ref)
\brief Sets the entry ref of the panel to the directory contained
by \a ref.
by \a ref.
\param ref The entry contained by the desired panel directory.
\since BeOS R3
*/
/*!
\fn void BFilePanel::SetPanelDirectory(const char* path)
\brief Sets the entry ref of the panel to the directory referenced
by \a path.
by \a path.
\param path The path of the desired directory.
\since BeOS R3
*/
/*!
\fn void BFilePanel::SetPanelDirectory(const BEntry* entry)
\brief Sets the entry ref of the panel to the directory referenced
by \a entry.
by \a entry.
\param entry The BEntry object pointing to the desired directory.
\since BeOS R3
*/
/*!
\fn void BFilePanel::SetPanelDirectory(const BDirectory* dir)
\brief Sets the entry ref of the panel to the directory referenced
by \a dir.
by \a dir.
\param dir The BDirectory object pointing to the desired directory.
\since BeOS R3
*/
@@ -376,6 +440,8 @@
\brief Gets a pointer to the BWindow object used by the file panel.
\returns A pointer to the BWindow object used by the file panel.
\since BeOS R3
*/
@@ -384,6 +450,8 @@
\brief Sets the entry ref back to the top of the list.
\see SelectionChanged()
\since BeOS R3
*/
@@ -396,7 +464,10 @@
\retval B_ERROR Couldn't attain a lock on the window.
\retval B_ENTRY_NOT_FOUND End of the entry list.
\see Rewind()
\see SelectionChanged()
\since BeOS R3
*/
@@ -405,6 +476,8 @@
\brief Sets whether or not the panel should hide on confirm or cancel.
\param on \c true to hide, \c false to not hide when done.
\since BeOS R3
*/
@@ -415,23 +488,42 @@
Panel always hides if the user clicks the window's close button.
\returns \c true if panel will hide, \c false if panel will not hide.
\see SetHideWhenDone()
\since BeOS R3
*/
/*!
\name Hook Methods
*/
//! @{
/*!
\fn void BFilePanel::WasHidden()
\brief Hook method that gets called when the file panel is hidden due to
a user action.
a user action.
WasHidden() is not called if you call Hide() manually.
\since BeOS R3
*/
/*!
\fn void BFilePanel::SelectionChanged()
\brief Hook method that gets called when the entry ref references by the
file panel changes.
file panel changes.
\see GetNextSelectedRef()
\see Rewind()
\since BeOS R3
*/
//! @}
docs/user/storage/FindDirectory.dox
+1045 -278
View File
File diff suppressed because it is too large Load Diff
docs/user/storage/Mime.dox
+112 -38
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2013 Haiku Inc. All rights reserved.
* Copyright 2013-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -7,8 +7,8 @@
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/storage/Mime.h hrev45224
* src/kits/storage/Mime.cpp hrev45224
* headers/os/storage/Mime.h hrev47402
* src/kits/storage/Mime.cpp hrev47402
*/
@@ -24,6 +24,8 @@
\enum icon_size
\ingroup storage
\brief Legacy BeOS icon size constants.
\since BeOS R3
*/
@@ -31,6 +33,8 @@
\var icon_size B_LARGE_ICON
32x32 "Large" icon.
\since BeOS R3
*/
@@ -38,34 +42,39 @@
\var icon_size B_MINI_ICON
16x16 "Mini" icon.
\since BeOS R3
*/
/*!
\var B_UPDATE_MIME_INFO_NO_FORCE
\brief Files that already have a \c BEOS:TYPE attribute won't be updated.
Files that already have a \c BEOS:TYPE attribute won't be updated.
\since Haiku R1
*/
/*!
\var B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE
\brief Files that already have a \c BEOS:TYPE attribute will be updated
too, but \c BEOS:TYPE itself will remain untouched.
Files that already have a \c BEOS:TYPE attribute will be updated too, but
\c BEOS:TYPE itself will remain untouched.
\since Haiku R1
*/
/*!
\var B_UPDATE_MIME_INFO_FORCE_UPDATE_ALL
\brief Similar to \c B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE, but the
\c BEOS:TYPE attribute will be updated too.
Similar to \c B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE, but the \c BEOS:TYPE
attribute will be updated too.
\since Haiku R1
*/
/*!
\fn int update_mime_info(const char *path, int recursive, int synchronous,
\fn int update_mime_info(const char* path, int recursive, int synchronous,
int force)
\brief Updates the MIME information (i.e MIME type) for one or more files.
@@ -78,21 +87,23 @@
\param path The path to a file or directory, or \c NULL.
\param recursive Triggers recursive behavior if not \c NULL.
\param synchronous If not \c NULL update_mime_info() waits until the
operation is finished, otherwise it returns immediately and the
update is done asynchronously.
operation is finished, otherwise it returns immediately and the
update is done asynchronously.
\param force Specifies how to handle files that already have MIME
information. See enum definitions for more information.
- \c B_UPDATE_MIME_INFO_NO_FORCE
- \c B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE
- \c B_UPDATE_MIME_INFO_FORCE_UPDATE_ALL
information. See enum definitions for more information:
- \c B_UPDATE_MIME_INFO_NO_FORCE
- \c B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE
- \c B_UPDATE_MIME_INFO_FORCE_UPDATE_ALL
\returns A status code. \c B_OK if everything went fine, an error code
otherwise.
\return A status code, \c B_OK if everything went fine, an error code
otherwise.
\since BeOS R3
*/
/*!
\fn status_t create_app_meta_mime(const char *path, int recursive,
\fn status_t create_app_meta_mime(const char* path, int recursive,
int synchronous, int force)
\brief Creates a MIME database entry for one or more applications.
@@ -105,65 +116,128 @@
\param path The path to an application file, a directory, or \c NULL.
\param recursive Trigger recursive behavior if not \c NULL.
\param synchronous Waits until the operation is finished if not \c NULL,
otherwise it returns immediately and the operation is done
asynchronously.
otherwise it returns immediately and the operation is done
asynchronously.
\param force Entries are created even if they do already exist if not
\c NULL.
\c NULL.
\returns A status code. \c B_OK if everything went fine, an error code
otherwise.
\return A status code, \c B_OK if everything went fine, an error code
otherwise.
\since BeOS R3
*/
/*!
\fn status_t get_device_icon(const char *device, void *icon, int32 size)
\fn status_t get_device_icon(const char* device, void* icon, int32 size)
\brief Retrieves an icon associated with a given device.
\param device The path to the device.
\param icon A pointer to a buffer the icon data shall be written to.
\param size The size of the icon to retrieve. Currently 16
(\c B_MINI_ICON) and 32 (\c B_LARGE_ICON) are supported.
(\c B_MINI_ICON) and 32 (\c B_LARGE_ICON) are supported.
\returns A status code.
\retval B_OK Everything went fine.
\return A status code, \c B_OK if everything went fine, an error code
otherwise.
\retval B_OK Retrieved the icon successfully.
\retval B_BAD_VALUE \a device or \a icon was \c NULL.
\retval B_NO_MEMORY Ran out of memory allocating bitmap.
\since BeOS R3
*/
/*!
\fn status_t get_device_icon(const char *device, BBitmap *icon,
\fn status_t get_device_icon(const char* device, BBitmap* icon,
icon_size which)
\brief Retrieves an icon associated with a given device into a BBitmap.
\brief Retrieves an icon associated with a given device into a BBitmap,
C++ only.
\param device The path to the device.
\param icon A pointer to a pre-allocated BBitmap of the correct dimension
to store the requested icon (16x16 for the mini and 32x32 for the
large icon).
to store the requested icon (16x16 for the mini and 32x32 for the
large icon).
\param which The size of the icon to retrieve. Currently 16
(\c B_MINI_ICON) and 32 (\c B_LARGE_ICON) are supported.
(\c B_MINI_ICON) and 32 (\c B_LARGE_ICON) are supported.
\returns A status code. \c B_OK if everything went fine, an error code
otherwise.
\return A status code, \c B_OK if everything went fine, an error code
otherwise.
\retval B_OK Retrieved the icon successfully.
\retval B_BAD_VALUE \a device or \a icon was \c NULL.
\since Haiku R1
*/
/*!
\fn status_t get_device_icon(const char* device, uint8** _data,
size_t* _size, type_code* _type);
\brief Undocumented.
\brief Try to get the icon by name first, if that fails try to get the
vector icon, C++ only.
\param device The path to the device.
\param _data A pointer to a pointer to an array of uint8 pixel data to
fill out.
\param _size The size of the icon to fill out. If vector, it is filled in
with the width in pixels, if bitmap, one of the following constants:
- \c B_MINI_ICON
- \c B_LARGE_ICON
\param _type The icon type code to fill out, one of the following:
- \c B_MINI_ICON_TYPE
- \c B_LARGE_ICON_TYPE
- \c B_VECTOR_ICON_TYPE
\return A status code, \c B_OK if everything went fine, an error code
otherwise.
\retval B_OK Retrieved the icon successfully.
\retval B_BAD_VALUE \a device, \a _data, \a _size, or _type was \c NULL.
\since Haiku R1
*/
/*!
\fn status_t get_named_icon(const char* name, BBitmap* icon,
icon_size which);
\brief Undocumented.
\brief Get the icon by name, C++ only.
\param name The name of the icon to get.
\param icon A pointer to a pre-allocated BBitmap of the correct dimension
to store the requested icon (16x16 for the mini and 32x32 for the
large icon).
\param which The size of the icon to retrieve. Currently 16
(\c B_MINI_ICON) and 32 (\c B_LARGE_ICON) are supported.
\return A status code, \c B_OK if everything went fine, an error code
otherwise.
\retval B_OK Retrieved the icon successfully.
\retval B_BAD_VALUE \a name or \a icon was \c NULL.
\since Haiku R1
*/
/*!
\fn status_t get_named_icon(const char* name, uint8** _data,
\fn status_t get_named_icon(const char* name, uint8** _data,
size_t* _size, type_code* _type);
\brief Undocumented.
\brief Get the icon by name, C++ only.
\param name The name of the icon to get.
\param _data A pointer to a pointer to an array of uint8 pixel data to
fill out.
\param _size The size of the icon to fill out. If vector, it is filled in
with the width in pixels, if bitmap, one of the following constants:
- \c B_MINI_ICON
- \c B_LARGE_ICON
\param _type The icon type code to fill out, one of the following:
- \c B_MINI_ICON_TYPE
- \c B_LARGE_ICON_TYPE
- \c B_VECTOR_ICON_TYPE
\return A status code, \c B_OK if everything went fine, an error code
otherwise.
\retval B_OK Retrieved the icon successfully.
\retval B_BAD_VALUE \a name, \a _data, \a _size, or \c _type was \c NULL.
\since Haiku R1
*/
docs/user/storage/MimeType.dox
+348 -264
View File
File diff suppressed because it is too large Load Diff
docs/user/storage/Node.dox
+293 -295
View File
@@ -1,15 +1,14 @@
/*
* Copyright 2002-2011 Haiku Inc. All rights reserved.
* Copyright 2002-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Tyler Dauwalder, [email protected]
* John Scipione, [email protected]
* Ingo Weinhold, [email protected]
*
* Corresponds to:
* headers/os/storage/Node.h rev 42803
* src/kits/storage/Node.cpp rev 42803
* headers/os/storage/Node.h hrev47402
* src/kits/storage/Node.cpp hrev47402
*/
@@ -17,7 +16,7 @@
\file Node.h
\ingroup storage
\ingroup libbe
\brief Provides the BNode class and node_ref structure.
\brief Provides the BNode class and node_ref struct.
*/
@@ -26,50 +25,102 @@
\ingroup storage
\ingroup libbe
\brief Reference structure to a particular vnode on a device.
\since BeOS R3
*/
/*!
\fn node_ref::node_ref()
\brief Creates an uninitialized node_ref object.
\since BeOS R3
*/
/*!
\fn node_ref::node_ref(const node_ref &ref)
\fn node_ref::node_ref(const node_ref& other)
\brief Creates a copy of the given node_ref object.
\param ref the node_ref to be copied.
\param other the node_ref to be copied.
\since BeOS R3
*/
/*!
\fn bool node_ref::operator==(const node_ref &ref) const
\name Operators
*/
//! @{
/*!
\fn bool node_ref::operator==(const node_ref& other) const
\brief Tests whether this node_ref and the supplied one are equal.
\param ref the node_ref to be compared with.
\param other The node_ref to be compared against.
\return \c true, if the objects are equal, \c false otherwise.
\since BeOS R3
*/
/*!
\fn bool node_ref::operator!=(const node_ref &ref) const
\brief Tests whether this node_ref and the supplied one are not equal.
\fn bool node_ref::operator!=(const node_ref& other) const
\brief Tests whether this node_ref and the supplied one are NOT equal.
\param ref the node_ref to be compared with.
\param other The node_ref to be compared against.
\return \c true, if the objects are \b not equal, \c false otherwise.
\return \c true, if the objects are \b NOT equal, \c false otherwise.
\since BeOS R3
*/
/*!
\fn node_ref& node_ref::operator=(const node_ref &ref)
\fn bool node_ref::operator<(const node_ref& other) const
\brief Tests whether this node_ref is less than the supplied one.
\param other The node_ref to be compared against.
\return \c true, if this node_ref is less than \a other,
\c false otherwise.
\since Haiku R1
*/
/*!
\fn node_ref& node_ref::operator=(const node_ref& other)
\brief Makes this node ref a copy of the supplied one.
\param ref the node_ref to be copied.
\param other The node_ref to be copied.
\return a reference to this object.
\return A reference to this object.
\since BeOS R3
*/
//! @}
/*!
\var node_ref::device
\brief The device number on which the node is located.
\since BeOS R3
*/
/*!
\var node_ref::node
\brief The node's inode number.
\since BeOS R3
*/
@@ -83,107 +134,96 @@
attributes belonging to filesystem entries. The BNode is unaware of the
name that refers to it in the filesystem (i.e. its entry), instead, a
BNode is concerned solely with the entry's data and attributes.
*/
/*!
\var BNode::fFd
File descriptor for the given node.
*/
/*!
\var BNode::fAttrFd
File descriptor for the attribute directory of the node.
Initialized lazily.
*/
/*!
\var BNode::fCStatus
The object's initialization status.
\since BeOS R3
*/
/*!
\fn BNode::BNode()
\brief Creates an uninitialized BNode object.
\see SetTo()
\since BeOS R3
*/
/*!
\fn BNode::BNode(const entry_ref *ref)
\fn BNode::BNode(const entry_ref* ref)
\brief Creates a BNode object and initializes it to the specified
entry_ref.
entry_ref.
\param ref the entry_ref referring to the entry.
\param ref The entry_ref referring to the node.
\since BeOS R3
*/
/*!
\fn BNode::BNode(const BEntry *entry)
\fn BNode::BNode(const BEntry* entry)
\brief Creates a BNode object and initializes it to the specified
filesystem entry.
filesystem entry.
\param entry the BEntry representing the entry.
\param entry The BEntry referring to the node.
\since BeOS R3
*/
/*!
\fn BNode::BNode(const char *path)
\fn BNode::BNode(const char* path)
\brief Creates a BNode object and initializes it to the entry referred
to by the specified path.
to by the specified path.
\param path the path referring to the entry.
\param path The \a path referring to the node.
\since BeOS R3
*/
/*!
\fn BNode::BNode(const BDirectory *dir, const char *path)
\fn BNode::BNode(const BDirectory* dir, const char* path)
\brief Creates a BNode object and initializes it to the entry referred
to by the specified path rooted in the specified directory.
to by the specified path rooted in the specified directory.
\param dir the BDirectory, relative to which the entry's path name is
given.
\param path the entry's path name relative to \a dir.
\param dir The base BDirectory.
\param path The \a path name relative to \a dir.
\since BeOS R3
*/
/*!
\fn BNode::BNode(const BNode &node)
\fn BNode::BNode(const BNode& other)
\brief Creates a copy of the given BNode.
\param node the BNode to be copied.
\param other The BNode to be copied.
\since BeOS R3
*/
/*!
\fn BNode::~BNode()
\brief Frees all resources associated with the BNode.
\since BeOS R3
*/
/*!
\fn status_t BNode::InitCheck() const
\brief Checks whether the object has been properly initialized or not.
\returns B_OK if the object has been properly initialized, or an error
code otherwise.
*/
/*!
\fn status_t BNode::GetStat(struct stat *st) const
\fn status_t BNode::GetStat(struct stat* stat) const
\brief Fills in the given stat structure with the <tt>stat()</tt>
information for this object.
information for this object.
\param st a pointer to a stat structure to be filled in.
\param stat A pointer to a stat structure to be filled in.
\return \c B_OK on success or an error code otherwise.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE: \c NULL \a st.
\retval B_BAD_VALUE: \c NULL \a stat.
\since Haiku R1
*/
@@ -194,12 +234,14 @@
Remember to call close() on the file descriptor when you're through
with it.
\returns a valid file descriptor, or -1 if something went wrong.
\returns A valid file descriptor, or -1 if something went wrong.
\since Haiku R1
*/
/*!
\name Assignment Methods
\name Constructor Helpers
*/
@@ -207,59 +249,89 @@
/*!
\fn BNode& BNode::operator=(const BNode &node)
\brief Initializes the object as a copy of the \a node.
\fn status_t BNode::InitCheck() const
\brief Checks whether the object has been properly initialized or not.
\param node the BNode to be copied.
\returns \c B_OK if the object has been properly initialized, or
\c B_NO_INIT otherwise.
\returns a reference to this BNode object.
\since BeOS R3
*/
/*!
\fn status_t BNode::SetTo(const entry_ref *ref)
\fn status_t BNode::SetTo(const entry_ref* ref)
\brief Initializes the object to the specified entry_ref.
\param ref the entry_ref referring to the entry.
\param ref The entry_ref referring to the entry.
\return \c B_OK on success or an error code otherwise.
\retval B_OK: Everything went fine.
\retval B_BAD_VALUE: \c NULL \a ref.
\retval B_BAD_VALUE: \a ref was \c NULL.
\retval B_ENTRY_NOT_FOUND: The entry could not be found.
\retval B_BUSY: The entry is locked.
\retval B_BUSY: The entry was locked.
\since BeOS R3
*/
/*!
\fn status_t BNode::SetTo(const BEntry *entry)
\fn status_t BNode::SetTo(const BEntry* entry)
\brief Initializes the object to the specified filesystem \a entry.
\param entry the BEntry representing the entry.
\param entry The BEntry representing the entry.
\return \c B_OK on success or an error code otherwise.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \c NULL \a entry.
\retval B_ENTRY_NOT_FOUND The entry could not be found.
\retval B_BUSY The entry is locked.
\retval B_BAD_VALUE \a entry was \c NULL.
\retval B_ENTRY_NOT_FOUND The \a entry could not be found.
\retval B_BUSY The \a entry was locked.
\since BeOS R3
*/
/*!
\fn status_t BNode::SetTo(const BDirectory *dir, const char *path)
\brief Initializes the object to the entry referred by the
specified \a path relative to the the specified directory.
\fn status_t BNode::SetTo(const char* path)
\brief Initializes the object to the specified \a path.
\param dir the base BDirectory.
\param path the entry's path name relative to \a dir
\param path The entry's path name; \a path can be relative or absolute,
and can contain "." and ".." elements. If path is relative, it uses
the current working directory as the base directory.
\return \c B_OK on success or an error code otherwise.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \c NULL \a entry.
\retval B_BAD_VALUE \a path was \c NULL.
\retval B_ENTRY_NOT_FOUND The entry could not be found.
\retval B_BUSY The entry is locked.
\retval B_BUSY The entry of was locked.
\since BeOS R3
*/
/*!
\fn status_t BNode::SetTo(const BDirectory* dir, const char* path)
\brief Initializes the object to the entry referred by the
specified \a path relative to the the specified directory.
\param dir The base BDirectory.
\param path The path name relative to \a dir.
\return \c B_OK on success or an error code otherwise.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \a dir was \c NULL.
\retval B_ENTRY_NOT_FOUND The entry could not be found.
\retval B_BUSY The entry was locked.
\since BeOS R3
*/
/*!
\fn void BNode::Unset()
\brief Returns the object to an uninitialized state.
\since BeOS R3
*/
@@ -277,11 +349,14 @@
/*!
\fn status_t BNode::Lock()
\brief Attains an exclusive lock on the data referred to by this node
so that it may not be modified by any other objects or methods.
so that it may not be modified by any other objects or methods.
\return \c B_OK on success or an error code otherwise.
\retval B_OK Everything went fine.
\retval B_FILE_ERROR The object is not initialized.
\retval B_BUSY The node is already locked.
\since BeOS R3
*/
@@ -289,9 +364,12 @@
\fn status_t BNode::Unlock()
\brief Unlocks the date referred to by this node.
\return \c B_OK on success or an error code otherwise.
\retval B_OK Everything went fine.
\retval B_FILE_ERROR The object is not initialized.
\retval B_BAD_VALUE The node is not locked.
\since BeOS R3
*/
@@ -299,8 +377,11 @@
\fn status_t BNode::Sync()
\brief Immediately performs any pending disk actions on the node.
\return \c B_OK on success or an error code otherwise.
\retval B_OK Everything went fine.
\retval B_FILE_ERROR Something went wrong.
\since BeOS R3
*/
@@ -316,163 +397,192 @@
/*!
\fn ssize_t BNode::WriteAttr(const char *attr, type_code type,
off_t offset, const void *buffer, size_t len)
\fn ssize_t BNode::WriteAttr(const char* attr, type_code type,
off_t offset, const void* buffer, size_t length)
\brief Writes data from a buffer to an attribute.
Write \a len bytes of data from \a buffer to the attribute specified
Write \a length bytes of data from \a buffer to the attribute specified
by \a name after erasing any data that existed previously. The type
specified by \a type \em is remembered, and may be queried with
GetAttrInfo(). The value of \a offset is currently ignored.
\param attr the name of the attribute.
\param type the type of the attribute.
\param offset the index at which to write the data (currently ignored).
\param buffer the buffer containing the data to be written.
\param len the number of bytes to be written.
\param attr The name of the attribute.
\param type The type of the attribute.
\param offset The index at which to write the data (currently ignored).
\param buffer The buffer containing the data to be written.
\param length The number of bytes to be written.
\returns the number of bytes actually written.
\retval B_BAD_VALUE \a attr or \a buffer is \c NULL.
\retval B_FILE_ERROR The object is not initialized or the node it refers to
is read only.
\return The number of bytes actually written.
\retval B_BAD_VALUE \a attr or \a buffer was \c NULL.
\retval B_FILE_ERROR The object was not initialized or the node it refers
to was read only.
\retval B_NOT_ALLOWED The node resides on a read only volume.
\retval B_DEVICE_FULL Insufficient disk space.
\retval B_NO_MEMORY Insufficient memory to complete the operation.
\retval B_DEVICE_FULL There was insufficient disk space to complete the
operation.
\retval B_NO_MEMORY There was insufficient memory to complete the
operation.
\since BeOS R3
*/
/*!
\fn ssize_t BNode::ReadAttr(const char *attr, type_code type,
off_t offset, void *buffer, size_t len) const
\fn ssize_t BNode::ReadAttr(const char* attr, type_code type,
off_t offset, void* buffer, size_t length) const
\brief Reads data from an attribute into \a buffer.
Reads \a len bytes of data from the attribute given by \a name into
Reads \a length bytes of data from the attribute given by \a name into
\a buffer. \a type and \a offset are currently ignored.
\param attr the name of the attribute.
\param type the type of the attribute (currently ignored).
\param offset the index from which to read the data (currently ignored).
\param buffer the buffer for the data to be read.
\param len the number of bytes to be read.
\param attr The name of the attribute.
\param type The type of the attribute (currently ignored).
\param offset The index from which to read the data (currently ignored).
\param buffer The buffer for the data to be read.
\param length The number of bytes to be read.
\returns the number of bytes actually read
\retval B_BAD_VALUE \a attr or \a buffer is \c NULL.
\retval B_FILE_ERROR The object is not initialized.
\retval B_ENTRY_NOT_FOUND The node has no attribute \a attr.
\return The number of bytes actually read.
\retval B_BAD_VALUE \a attr or \a buffer was \c NULL.
\retval B_FILE_ERROR The object was not initialized.
\retval B_ENTRY_NOT_FOUND The node had no attribute \a attr.
\since BeOS R3
*/
/*!
\fn status_t BNode::RemoveAttr(const char *name)
\fn status_t BNode::RemoveAttr(const char* name)
\brief Deletes the attribute given by \a name.
\param name the name of the attribute to remove.
\param name The name of the attribute to remove.
\return \c B_OK on success or an error code otherwise.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \a name is \c NULL.
\retval B_FILE_ERROR The object is not initialized or the node it
refers to read only.
\retval B_ENTRY_NOT_FOUND The node has no attribute \a name.
\retval B_NOT_ALLOWED The node resides on a read only volume.
\retval B_BAD_VALUE \a name was \c NULL.
\retval B_FILE_ERROR The object was not initialized or the node it
referred to was read-only.
\retval B_ENTRY_NOT_FOUND The node had no attribute \a name.
\retval B_NOT_ALLOWED The node resided on a read-only volume.
\since BeOS R3
*/
/*!
\fn status_t BNode::RenameAttr(const char *oldname, const char *newname)
\brief Moves the attribute given by \a oldname to \a newname.
\fn status_t BNode::RenameAttr(const char* oldName, const char* newName)
\brief Moves the attribute given by \a oldName to \a newName.
If \a newname already exists, the data is clobbered.
If \a newName already exists, the data is clobbered.
\param oldname the name of the attribute to be renamed.
\param newname the new name for the attribute.
\param oldName The name of the attribute to be renamed.
\param newName The new name for the attribute.
\return \c B_OK on success or an error code otherwise.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \a oldname or \a newname is \c NULL.
\retval B_FILE_ERROR The object is not initialized or the node it
refers to is read only.
\retval B_ENTRY_NOT_FOUND The node has no attribute \a oldname.
\retval B_NOT_ALLOWED The node resides on a read only volume.
\retval B_BAD_VALUE \a oldName or \a newName was \c NULL.
\retval B_FILE_ERROR The object was not initialized or the node it
referred to was read only.
\retval B_ENTRY_NOT_FOUND The node had no attribute \a oldName.
\retval B_NOT_ALLOWED The node resided on a read-only volume.
\since BeOS R3
*/
/*!
\fn status_t BNode::GetAttrInfo(const char *name,
struct attr_info *info) const
\fn status_t BNode::GetAttrInfo(const char* name,
struct attr_info* info) const
\brief Fills in the pre-allocated attr_info struct pointed to by \a info
with information about the attribute specified by \a name.
with information about the attribute specified by \a name.
\param name the name of the attribute
\param info the attr_info structure to be filled in
\param name The name of the attribute.
\param info The attr_info structure to be filled in.
\return \c B_OK on success or an error code otherwise.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \a name is \c NULL.
\retval B_FILE_ERROR The object is not initialized.
\retval B_ENTRY_NOT_FOUND The node has no attribute \a name.
\retval B_BAD_VALUE \a name was \c NULL.
\retval B_FILE_ERROR The object was not initialized.
\retval B_ENTRY_NOT_FOUND The node had no attribute \a name.
\since BeOS R3
*/
/*!
\fn status_t BNode::GetNextAttrName(char *buffer)
\fn status_t BNode::GetNextAttrName(char* buffer)
\brief Copies the name of the attribute into \c buffer and then advances
the pointer to the next attribute.
the pointer to the next attribute.
The name of the node is first copied into \a buffer, which should be at
least \c B_ATTR_NAME_LENGTH characters long. The copied node name is
\c NUL terminated. Once the name is copied the attribute list pointer
\0 terminated. Once the name is copied the attribute list pointer
is advanced to the next attribute in the list. When GetNextAttrName()
reaches the end of the list it returns \c B_ENTRY_NOT_FOUND.
\param buffer A buffer to copy the name of the attribute into.
\return \c B_OK on success or an error code otherwise.
\retval B_OK The Attribute name was copied and there are more attribute
names to copy.
\retval B_BAD_VALUE passed in \a buffer is \c NULL.
\retval B_FILE_ERROR The object is not initialized.
\retval B_ENTRY_NOT_FOUND There are no more attributes, the last attribute
name has already been copied.
names to copy.
\retval B_BAD_VALUE passed in \a buffer was \c NULL.
\retval B_FILE_ERROR The object was not initialized.
\retval B_ENTRY_NOT_FOUND There were no more attributes, the last attribute
name had already been copied.
\since BeOS R3
*/
/*!
\fn status_t BNode::RewindAttrs()
\brief Resets the object's attribute pointer to the first attribute in the
list.
list.
\return \c B_OK on success or an error code otherwise.
\retval B_OK Everything went fine.
\retval B_FILE_ERROR Some other error occurred.
\since BeOS R3
*/
/*!
\fn status_t BNode::WriteAttrString(const char *name, const BString *data)
\fn status_t BNode::WriteAttrString(const char* name, const BString* data)
\brief Writes the specified string to the specified attribute, clobbering
any previous data.
any previous data.
\param name the name of the attribute.
\param data the BString to be written to the attribute.
\return \c B_OK on success or an error code otherwise.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \c NULL \a name or \a data
\retval B_FILE_ERROR The object is not initialized or the node it refers to
is read only.
\retval B_NOT_ALLOWED The node resides on a read only volume.
\retval B_DEVICE_FULL Insufficient disk space.
\retval B_NO_MEMORY Insufficient memory to complete the operation.
\retval B_BAD_VALUE \a name or \a data was \c NULL.
\retval B_FILE_ERROR The object was not initialized or the node it
referred to was read-only.
\retval B_NOT_ALLOWED The node resided on a read-only volume.
\retval B_DEVICE_FULL There was insufficient disk space to complete the
operation.
\retval B_NO_MEMORY There was insufficient memory to complete the
operation.
\since Haiku R1
*/
/*!
\fn status_t BNode::ReadAttrString(const char *name, BString *result) const
\fn status_t BNode::ReadAttrString(const char* name, BString* result) const
\brief Reads the data of the specified attribute into the pre-allocated
\a result.
\a result.
\param name the name of the attribute.
\param result the BString to be set to the value of the attribute.
\return \c B_OK on success or an error code otherwise.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \a name or \a result is \c NULL.
\retval B_FILE_ERROR The object is not initialized.
\retval B_ENTRY_NOT_FOUND The node has no attribute \a attr.
\retval B_BAD_VALUE \a name or \a result was \c NULL.
\retval B_FILE_ERROR The object was not initialized.
\retval B_ENTRY_NOT_FOUND The node had no attribute \a attr.
\since Haiku R1
*/
@@ -480,23 +590,37 @@
/*!
\name Comparison Methods
\name Operators
*/
//! @{
/*!
\fn BNode& BNode::operator=(const BNode& other)
\brief Initializes the object as a copy of \a other.
\param other the BNode to be copied.
\returns A reference to this BNode object.
\since BeOS R3
*/
/*!
\fn bool BNode::operator==(const BNode &node) const
\brief Tests whether this and the supplied BNode object are equal.
Two BNode objects are said to be equal if they're set to the same node,
or if they're both \c B_NO_INIT.
or if they're both unintialized
\param node the BNode to be compared with.
\param node The BNode to be compared against.
\return \c true, if the BNode objects are equal, \c false otherwise.
\since BeOS R3
*/
@@ -505,139 +629,13 @@
\brief Tests whether this and the supplied BNode object are not equal.
Two BNode objects are said to be equal if they're set to the same node,
or if they're both \c B_NO_INIT.
or if they're both unintialized.
\param node the BNode to be compared with
\param node The BNode to be compared with
\return \c false, if the BNode objects are equal, \c true otherwise.
*/
//! @}
/*!
\name Private Methods
*/
//! @{
/*!
\fn status_t BNode::set_fd(int fd)
\brief Sets the node's file descriptor.
Used by each implementation (i.e. BNode, BFile, BDirectory, etc.) to set
the node's file descriptor. This allows each subclass to use the various
file-type specific system calls for opening file descriptors.
\note This method calls close_fd() to close previously opened FDs. Thus
derived classes should take care to first call set_fd() and set
class specific resources freed in their close_fd() version
thereafter.
\param fd the file descriptor this BNode should be set to (may be -1).
\returns \c B_OK if everything went fine, or an error code if something
went wrong.
*/
/*!
\fn void BNode::close_fd()
\brief Closes the node's file descriptor(s).
To be implemented by subclasses to close the file descriptor using the
proper system call for the given file-type. This implementation calls
_kern_close(fFd) and also _kern_close(fAttrDir) if necessary.
*/
/*!
\fn void BNode::set_status(status_t newStatus)
\brief Sets the BNode's status.
To be used by derived classes instead of accessing the BNode's private
\c fCStatus member directly.
\param newStatus the new value for the status variable.
*/
/*!
\fn status_t BNode::_SetTo(int fd, const char *path, bool traverse)
\brief Initializes the BNode's file descriptor to the node referred to
by the given FD and path combo.
\a path must either be \c NULL, an absolute or a relative path.
In the first case, \a fd must not be \c NULL; the node it refers to will
be opened. If absolute, \a fd is ignored. If relative and \a fd is >= 0,
it will be reckoned off the directory identified by \a fd, otherwise off
the current working directory.
The method will first try to open the node with read and write permission.
If that fails due to a read-only FS or because the user has no write
permission for the node, it will re-try opening the node read-only.
The \a fCStatus member will be set to the return value of this method.
\param fd Either a directory FD or a value < 0. In the latter case \a path
must be specified.
\param path Either \a NULL in which case \a fd must be given, absolute, or
relative to the directory specified by \a fd (if given) or to the
current working directory.
\param traverse If the node identified by \a fd and \a path is a symlink
and \a traverse is \c true, the symlink will be resolved recursively.
\returns \c B_OK if everything went fine, or an error code if something
went wrong.
*/
/*!
\fn status_t BNode::_SetTo(const entry_ref *ref, bool traverse)
\brief Initializes the BNode's file descriptor to the node referred to
by the given entry_ref.
The method will first try to open the node with read and write permission.
If that fails due to a read-only FS or because the user has no write
permission for the node, it will re-try opening the node read-only.
The \a fCStatus member will be set to the return value of this method.
\param ref An entry_ref identifying the node to be opened.
\param traverse If the node identified by \a ref is a symlink and
\a traverse is \c true, the symlink will be resolved recursively.
\returns \c B_OK if everything went fine, or an error code if something
went wrong.
*/
/*!
\fn status_t BNode::set_stat(struct stat &st, uint32 what)
\brief Modifies a certain setting for this node based on \a what and the
corresponding value in \a st.
Inherited from and called by BStatable.
\param st a stat structure containing the value to be set.
\param what specifies what setting to be modified.
\returns \c B_OK if everything went fine, or an error code if something
went wrong.
*/
/*!
\fn status_t BNode::InitAttrDir()
\brief Verifies that the BNode has been properly initialized, and then
(if necessary) opens the attribute directory on the node's file
descriptor, storing it in fAttrDir.
\returns \c B_OK if everything went fine, or an error code if something
went wrong.
\since BeOS R3
*/
docs/user/storage/NodeInfo.dox
+72 -44
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2013 Haiku Inc. All rights reserved.
* Copyright 2013-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -8,8 +8,8 @@
* Ingo Weinhold, [email protected]
*
* Corresponds to:
* headers/os/storage/NodeInfo.h hrev45253
* src/kits/storage/NodeInfo.cpp hrev45253
* headers/os/storage/NodeInfo.h hrev47402
* src/kits/storage/NodeInfo.cpp hrev47402
*/
@@ -30,6 +30,8 @@
BNodeInfo provides a nice wrapper to all sorts of useful meta data such as
the MIME-type, the file's icon and the application that will open
the file.
\since BeOS R3
*/
@@ -39,16 +41,20 @@
After created a BNodeInfo with this, you should call SetTo().
\see SetTo(BNode *node)
\see SetTo(BNode* node)
\since BeOS R3
*/
/*!
\fn BNodeInfo::BNodeInfo(BNode *node)
\fn BNodeInfo::BNodeInfo(BNode* node)
\brief Creates a BNodeInfo object and initializes it to the supplied
\a node.
\param node The \a node to gather information on.
\param node The \a node to initialize to and gather information.
\since BeOS R3
*/
@@ -57,6 +63,8 @@
\brief Frees the object and associated resources.
The internal BNode object is not deleted.
\since BeOS R3
*/
@@ -69,7 +77,7 @@
/*!
\fn status_t BNodeInfo::SetTo(BNode *node)
\fn status_t BNodeInfo::SetTo(BNode* node)
\brief Initializes the BNodeInfo to the supplied \a node.
The BNodeInfo object does not copy the supplied \a node object, it uses it
@@ -82,6 +90,8 @@
\returns A status code.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE The node was not properly initialized.
\since BeOS R3
*/
@@ -92,6 +102,8 @@
\returns A status code.
\retval B_OK The object was properly initialized.
\retval B_BAD_VALUE The object was \b not properly initialized.
\since BeOS R3
*/
@@ -107,7 +119,7 @@
/*!
\fn status_t BNodeInfo::GetType(char *type) const
\fn status_t BNodeInfo::GetType(char* type) const
\brief Writes the MIME-type of the node into \a type.
The source of the type information is the \c BEOS:TYPE attribute of the
@@ -125,18 +137,20 @@
attribute is longer than \c B_MIME_TYPE_LENGTH.
\retval B_BAD_TYPE The stored type string attribute has the wrong type.
\retval B_ENTRY_NOT_FOUND No type is set on the node.
\since BeOS R3
*/
/*!
\fn status_t BNodeInfo::SetType(const char *type)
\fn status_t BNodeInfo::SetType(const char* type)
\brief Sets the MIME-type of the node. If \a type is \c NULL the
\c BEOS:TYPE attribute is removed instead.
The \a type string is written into the \c BEOS:TYPE attribute of the node.
If \a type is \c NULL, the \c BEOS:TYPE attribute is removed instead. The
\a type parameter may not by longer than \c B_MIME_TYPE_LENGTH in length
including the terminating \c NUL character.
including the terminating \0 character.
\param type The MIME-type to be assigned to the \a node. Must not be
longer than \c B_MIME_TYPE_LENGTH (including the terminating
@@ -146,6 +160,8 @@
\retval B_OK Everything went fine.
\retval B_NO_INIT The object was not properly initialized.
\retval B_BAD_VALUE \a type is longer than \c B_MIME_TYPE_LENGTH.
\since BeOS R3
*/
@@ -153,7 +169,7 @@
/*!
\name Icon methods
\name Icon
*/
@@ -161,28 +177,30 @@
/*!
\fn status_t BNodeInfo::GetIcon(BBitmap *icon, icon_size k) const
\fn status_t BNodeInfo::GetIcon(BBitmap* icon, icon_size which) const
\brief Gets the icon of the node.
The icon stored in the \c BEOS:L:STD_ICON attribute (large) or
\c BEOS:M:STD_ICON attribute (mini) is retrieved.
\param icon A pointer to a pre-allocated BBitmap object of the correct
dimension to store the requested icon: 16x16 for the mini or
32x32 for the large icon.
\param k The size of the icon to be retrieved: \c B_MINI_ICON for a 16x16
dimension to store the requested icon: 16x16 for the mini or
32x32 for the large icon.
\param which The size of the icon to be retrieved: \c B_MINI_ICON for a 16x16
icon and \c B_LARGE_ICON for a 32x32 icon.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object was not properly initialized.
\retval B_BAD_VALUE \c NULL \a icon, unsupported icon size \a k or bitmap
dimensions (\a icon) and icon size (\a k) do not match.
dimensions (\a icon) and icon size (\a k) do not match.
\since BeOS R3
*/
/*!
\fn status_t BNodeInfo::SetIcon(const BBitmap *icon, icon_size k)
\fn status_t BNodeInfo::SetIcon(const BBitmap* icon, icon_size which)
\brief Sets the icon of the node. If \a icon is \c NULL, the attribute is
removed instead.
@@ -191,15 +209,17 @@
attribute is removed instead.
\param icon A pointer to a BBitmap object containing the icon to be set.
May be \c NULL.
\param k The size of the icon to be set: \c B_MINI_ICON for the mini or
May be \c NULL.
\param which The size of the icon to be set: \c B_MINI_ICON for the mini or
\c B_LARGE_ICON for the large icon.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\retval B_BAD_VALUE Unknown icon size \a k or bitmap dimensions (\a icon)
and icon size (\a k) do not match.
and icon size (\a k) do not match.
\since BeOS R3
*/
@@ -213,17 +233,19 @@
retrieved.
\param data A pointer in which a pointer to the icon data
will be returned.
will be filled in.
\param size A pointer in which the size of the found icon data
will be returned.
will be filled in.
\param type A pointer in which the type of the found icon data
will be returned.
will be filled in.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object was not properly initialized.
\retval B_BAD_VALUE \c NULL \a data, \c NULL \a size or \c NULL \a type.
\retval B_NO_MEMORY No memory to allocate the \a data buffer.
\since Haiku R1
*/
@@ -240,12 +262,14 @@
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object was not properly initialized.
\since Haiku R1
*/
/*!
\fn status_t BNodeInfo::GetTrackerIcon(BBitmap *icon,
icon_size iconSize) const
\fn status_t BNodeInfo::GetTrackerIcon(BBitmap* icon,
icon_size which) const
\brief Gets the icon displayed by Tracker for the icon.
This method tries really hard to find an icon for the node:
@@ -268,7 +292,7 @@
The first action that provides an icon is used. In the case that none of
them yield an icon this method fails, this is very unlikely though.
\remarks You can set \a iconSize to get a scaled icon instead of using
\remarks You can set \a which to get a scaled icon instead of using
a predefined icon_size constant, pass in an integer casted
to icon_size. For example to get a 64x64 icon pass in:
\code
@@ -276,44 +300,48 @@
\endcode
\param icon A pointer to a pre-allocated BBitmap of the correct dimension
to store the requested icon (16x16 for the mini and 32x32 for the
large icon).
\param iconSize The size of the icon to be retrieved: \c B_MINI_ICON
for a 16x16 icon or \c B_LARGE_ICON for a 32x32 icon.
to store the requested icon (16x16 for the mini and 32x32 for the
large icon).
\param which The size of the icon to be retrieved: \c B_MINI_ICON
for a 16x16 icon or \c B_LARGE_ICON for a 32x32 icon.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object was not properly initialized.
\retval B_BAD_VALUE \c NULL \a icon, unsupported icon size \a iconSize
or bitmap dimensions (\a icon) and icon size (\a iconSize) do
\retval B_BAD_VALUE \c NULL \a icon, unsupported icon size \a which
or bitmap dimensions (\a icon) and icon size (\a which) do
not match.
\since BeOS R3
*/
/*!
\fn status_t BNodeInfo::GetTrackerIcon(const entry_ref *ref,
BBitmap *icon, icon_size iconSize)
\fn status_t BNodeInfo::GetTrackerIcon(const entry_ref* ref,
BBitmap* icon, icon_size which)
\brief Gets the icon displayed by Tracker for the node referred to by
\a ref.
This methods works similarly to the non-static version but \a ref
identifies the node. \a icon must be pre-allocated to the size requested
using \a iconSize before being passed to this method.
using \a which before being passed to this method.
\param ref An entry_ref referring to the node for which the icon is
retrieved.
\param icon A pointer to a pre-allocated BBitmap object of the correct
dimension to store the requested icon (16x16 for the mini and 32x32
for the large icon).
\param iconSize The size of the icon to be retrieved: \c B_MINI_ICON
\param which The size of the icon to be retrieved: \c B_MINI_ICON
for a 16x16 icon or \c B_LARGE_ICON for a 32x32 icon.
\returns A status code.
\retval B_OK: Everything went fine.
\retval B_NO_INIT: The object is not properly initialized.
\retval B_BAD_VALUE: \c NULL ref or \a icon, unsupported icon size
\a iconSize or bitmap dimensions (\a icon) and icon size
(\a iconSize) do not match.
\a which or bitmap dimensions (\a icon) and icon size
(\a which) do not match.
\since BeOS R3
*/
@@ -321,7 +349,7 @@
/*!
\name Preferred application methods
\name Preferred Application
*/
@@ -329,7 +357,7 @@
/*!
\fn status_t BNodeInfo::GetPreferredApp(char *signature,
\fn status_t BNodeInfo::GetPreferredApp(char* signature,
app_verb verb) const
\brief Gets the preferred application of the node.
@@ -352,7 +380,7 @@
/*!
\fn status_t BNodeInfo::SetPreferredApp(const char *signature,
\fn status_t BNodeInfo::SetPreferredApp(const char* signature,
app_verb verb)
\brief Sets the preferred application of the node. If \a signature is
\c NULL, the \c BEOS:PREF_APP attribute is removed instead.
@@ -379,7 +407,7 @@
/*!
\name Application hint methods
\name Application Hint
*/
@@ -387,7 +415,7 @@
/*!
\fn status_t BNodeInfo::GetAppHint(entry_ref *ref) const
\fn status_t BNodeInfo::GetAppHint(entry_ref* ref) const
\brief Fills out \a ref with a pointer to a hint about the application
that will open this node.
@@ -409,7 +437,7 @@
/*!
\fn status_t BNodeInfo::SetAppHint(const entry_ref *ref)
\fn status_t BNodeInfo::SetAppHint(const entry_ref* ref)
\brief Sets the application that will open the file type of the node. If
\a ref is \c NULL, the \c BEOS:PPATH attribute is removed instead.
docs/user/storage/NodeMonitor.dox
+129 -57
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2003-2013 Haiku Inc. All rights reserved.
* Copyright 2003-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -9,8 +9,8 @@
* Clemens Zeidler, [email protected]
*
* Corresponds to:
* headers/os/storage/NodeMonitor.h hrev45253
* src/kits/storage/NodeMonitor.cpp hrev45253
* headers/os/storage/NodeMonitor.h hrev47402
* src/kits/storage/NodeMonitor.cpp hrev47402
*/
@@ -21,7 +21,7 @@
\brief Provides functions and constants for monitoring changes to a node.
The are three main node monitoring functions are watch_volume(),
watch_node() and stop_watching().
watch_node(), and stop_watching().
- watch_volume() starts watching a volume and sends a message
when a requested event occurs.
- watch_node() starts or stops watching a node, or watches for volumes
@@ -31,219 +31,279 @@
*/
//// Flags for the watch_node() call.
/*!
\var B_STOP_WATCHING
\brief Unsubscribe from watching a node.
Flag for watch_node(). Unsubscribe from watching a node.
Flag for watch_node().
\attention \c B_STOP_WATCHING does not apply to volume watching, you must
call stop_watching() instead.
\since BeOS R3
*/
/*!
\var B_WATCH_NAME
\brief Subscribe to watching for change to the name of a node.
Flag for watch_volume() and watch_node(). Subscribe to watching for
change to the name of a node.
Flag for watch_volume() and watch_node().
\since BeOS R3
*/
/*!
\var B_WATCH_STAT
\brief Subscribe to watching for changes to the stat information of a node.
Flag for watch_volume() and watch_node(). Subscribe to watching for
changes to the stat information of a node.
Flag for watch_volume() and watch_node().
\since BeOS R3
*/
/*!
\var B_WATCH_ATTR
\brief Subscribe to watching for changes to the attributes of a node.
Flag for watch_volume() and watch_node(). Subscribe to watching for
changes to the attributes of a node.
Flag for watch_volume() and watch_node().
\since BeOS R3
*/
/*!
\var B_WATCH_DIRECTORY
\brief Subscribe to watching for changes to the contents of a directory.
Flag for watch_node(). Subscribe to watching for changes to the contents
of a directory.
Flag for watch_node().
\since BeOS R3
*/
/*!
\var B_WATCH_ALL
\brief Flag for watch_node().
Flag for watch_node(). Subscribe to watching for changes to all
information of a node except \c B_WATCH_MOUNT.
Subscribe to watching for changes to all information of a node except
\c B_WATCH_MOUNT.
\since BeOS R3
*/
/*!
\var B_WATCH_MOUNT
\brief Subscribe to watching for when a volume is mounted or unmounted.
Flag for watch_node(). Subscribe to watching for when a volume is mounted
or unmounted. You may prefer to use BVolumeRoster for volume watching
instead.
You may prefer to use BVolumeRoster for volume watching instead.
Flag for watch_node().
\since BeOS R3
*/
/*!
\var B_WATCH_INTERIM_STAT
\brief To avoid a flood of messages for small and frequent write operations
on an open file the file system can limit the number of
notifications and mark them with the \c B_WATCH_INTERIM_STAT flag.
\internal Implementation detail. Not in Be Book.
\internal Implementation detail, not in Be Book.
To avoid a flood of messages for small and frequent write operations on an
open file the file system can limit the number of notifications and mark
them with the \c B_WATCH_INTERIM_STAT flag.
\since Haiku R1
*/
//// The "opcode" field of the B_NODE_MONITOR notification message you get.
/*!
\def B_ENTRY_CREATED
\var B_ENTRY_CREATED
\c B_NODE_MONITOR notification message "opcode" is set when entry is
created.
\since BeOS R3
*/
/*!
\def B_ENTRY_REMOVED
\var B_ENTRY_REMOVED
\c B_NODE_MONITOR notification message "opcode" is set when entry is
removed.
\since BeOS R3
*/
/*!
\def B_ENTRY_MOVED
\var B_ENTRY_MOVED
\c B_NODE_MONITOR notification message "opcode" is set when entry is
moved.
\since BeOS R3
*/
/*!
\def B_STAT_CHANGED
\var B_STAT_CHANGED
\c B_NODE_MONITOR notification message "opcode" set when stat info
changes. More information can be found in the "fields" field.
\since BeOS R3
*/
/*!
\def B_ATTR_CHANGED
\var B_ATTR_CHANGED
\c B_NODE_MONITOR notification message "opcode" set when attribute
changes. More information can be found in the "cause" field.
\since BeOS R3
*/
/*!
\def B_DEVICE_MOUNTED
\var B_DEVICE_MOUNTED
\c B_NODE_MONITOR notification message "opcode" set when device is
mounted.
\since BeOS R3
*/
/*!
\def B_DEVICE_UNMOUNTED
\var B_DEVICE_UNMOUNTED
\c B_NODE_MONITOR notification message "opcode" set when device is
unmounted.
\since BeOS R3
*/
/*!
\def B_ATTR_CREATED
\var B_ATTR_CREATED
\c B_ATTR_CHANGED notification message "cause" set when attribute is
created. (Haiku only)
created.
\since Haiku R1
*/
/*!
\def B_ATTR_REMOVED
\var B_ATTR_REMOVED
\c B_ATTR_CHANGED notification message "cause" set when attribute is
removed. (Haiku only)
removed.
\since Haiku R1
*/
/*!
\var B_STAT_MODE
\brief Set when stat mode changes.
\c B_STAT_CHANGED notification messages "fields" flag set when stat mode
changes.
\c B_STAT_CHANGED notification messages "fields" flag.
\since Haiku R1
*/
/*!
\var B_STAT_UID
\brief Set when UID changes.
\c B_STAT_CHANGED notification messages "fields" flag set when UID
changes.
\c B_STAT_CHANGED notification messages "fields" flag.
\since Haiku R1
*/
/*!
\var B_STAT_GID
\brief Set when GID changes.
\c B_STAT_CHANGED notification messages "fields" flag set when GID
changes.
\c B_STAT_CHANGED notification messages "fields" flag.
\since Haiku R1
*/
/*!
\var B_STAT_SIZE
\brief Set when stat size changes.
\c B_STAT_CHANGED notification messages "fields" flag set when stat size
changes.
\c B_STAT_CHANGED notification messages "fields" flag.
\since Haiku R1
*/
/*!
\var B_STAT_ACCESS_TIME
\brief Set when access time changes.
\c B_STAT_CHANGED notification messages "fields" flag set when access time
changes.
\c B_STAT_CHANGED notification messages "fields" flag.
\since Haiku R1
*/
/*!
\var B_STAT_MODIFICATION_TIME
\brief Set when modification time changes.
\c B_STAT_CHANGED notification messages "fields" flag set when
modification time changes.
\c B_STAT_CHANGED notification messages "fields" flag.
\since Haiku R1
*/
/*!
\var B_STAT_CREATION_TIME
\brief Set when creation time changes.
\c B_STAT_CHANGED notification messages "fields" flag set when creation
time changes.
\c B_STAT_CHANGED notification messages "fields" flag.
\since Haiku R1
*/
/*!
\var B_STAT_CHANGE_TIME
\brief Set when access, modification or creation time changes.
\c B_STAT_CHANGED notification messages "fields" flag set when access,
modification or creation time changes.
\c B_STAT_CHANGED notification messages "fields" flag.
\since Haiku R1
*/
/*!
\var B_STAT_INTERIM_UPDATE
\brief Set when file is written to.
\internal Implementation detail. Not in Be Book.
\internal Implementation detail, not in Be Book.
\c B_STAT_CHANGED notification messages "fields" flag set when file is
written to.
\c B_STAT_CHANGED notification messages "fields" flag.
\since Haiku R1
*/
@@ -271,12 +331,14 @@
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \a flags did not include one of \c B_WATCH_NAME,
\c B_WATCH_STAT, or \c B_WATCH_ATTR.
\since Haiku R1
*/
/*!
\fn status_t watch_volume(dev_t volume, uint32 flags,
const BHandler *handler, const BLooper *looper)
const BHandler* handler, const BLooper* looper)
\brief Subscribes \a handler or \a looper to watch node changes on
\a volume.
@@ -303,11 +365,13 @@
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \a flags did not include one of \c B_WATCH_NAME,
\c B_WATCH_STAT, or \c B_WATCH_ATTR.
\since Haiku R1
*/
/*!
\fn status_t watch_node(const node_ref *node, uint32 flags,
\fn status_t watch_node(const node_ref* node, uint32 flags,
BMessenger target)
\brief Subscribes or unsubscribes \a target to node and/or mount watching.
@@ -341,12 +405,14 @@
\param target BMessenger object referring to the \a target.
\return \c B_OK if everything went fine, an error code otherwise.
\since BeOS R3
*/
/*!
\fn status_t watch_node(const node_ref *node, uint32 flags,
const BHandler *handler, const BLooper *looper)
\fn status_t watch_node(const node_ref* node, uint32 flags,
const BHandler* handler, const BLooper* looper)
\brief Subscribes or unsubscribes \a handler or \a looper to node and/or
mount watching.
@@ -383,6 +449,8 @@
\c NULL. Then the handler's looper is the target looper.
\return \c B_OK if everything went fine, an error code otherwise.
\since BeOS R3
*/
@@ -403,11 +471,13 @@
\retval B_OK Stopped sending notification messages to the \a target.
\retval B_BAD_VALUE \a target was invalid.
\retval B_ENTRY_NOT_FOUND Node not found.
\since BeOS R3
*/
/*!
\fn status_t stop_watching(const BHandler *handler, const BLooper *looper)
\fn status_t stop_watching(const BHandler* handler, const BLooper* looper)
\brief Unsubscribes \a handler or \a looper target from node and mount
monitoring.
@@ -427,4 +497,6 @@
\retval B_OK Stopped sending notification messages to the target.
\retval B_BAD_VALUE Target from \a handler or \a looper was invalid.
\retval B_ENTRY_NOT_FOUND Node not found.
\since BeOS R3
*/
docs/user/storage/Path.dox
+63 -42
View File
@@ -9,8 +9,8 @@
* Ingo Weinhold, [email protected]
*
* Corresponds to:
* headers/os/storage/Path.h hrev45260
* src/kits/storage/Path.cpp hrev45260
* headers/os/storage/Path.h hrev47402
* src/kits/storage/Path.cpp hrev47402
*/
@@ -27,6 +27,8 @@
\ingroup storage
\ingroup libbe
\brief A class representing a file system path.
\since BeOS R3
*/
@@ -43,6 +45,8 @@
\brief Creates a copy of the given BPath object.
\param path the object to be copied.
\since BeOS R3
*/
@@ -52,6 +56,8 @@
specified by the passed in entry_ref struct.
\param ref the entry_ref to initialize from.
\since BeOS R5
*/
@@ -61,6 +67,8 @@
specified by the passed in BEntry object.
\param entry the BEntry object to initialize from.
\since BeOS R4
*/
@@ -81,6 +89,8 @@
- The presence of "." or ".." ("/boot/ltj/../ltj/./gwar")
- Redundant slashes ("/boot//ltj")
- A trailing slash ("/boot/ltj/")
\since BeOS R3
*/
@@ -100,17 +110,21 @@
- The presence of "." or ".." ("/boot/ltj/../ltj/./gwar")
- Redundant slashes ("/boot//ltj")
- A trailing slash ("/boot/ltj/")
\since BeOS R3
*/
/*!
\fn BPath::~BPath()
\brief Destroys the BPath object and frees any associated resources.
\since BeOS R3
*/
/*!
\name Constructor helper methods
\name Constructor Helpers
*/
@@ -123,6 +137,8 @@
\return \c B_OK, if the BPath object was properly initialized, an error
code otherwise.
\since BeOS R3
*/
@@ -136,6 +152,8 @@
\retval B_OK Initialization was successful.
\retval B_BAD_VALUE \a ref was \c NULL.
\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.
\since BeOS R5
*/
@@ -149,6 +167,8 @@
\retval B_OK Initialization was successful.
\retval B_BAD_VALUE \a ref was \c NULL.
\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.
\since BeOS R4
*/
@@ -174,6 +194,8 @@
\retval B_OK Initialization was successful.
\retval B_BAD_VALUE \a ref was \c NULL.
\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.
\since BeOS R3
*/
@@ -197,6 +219,8 @@
\retval B_OK Initialization was successful.
\retval B_BAD_VALUE \a ref was \c NULL.
\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.
\since BeOS R3
*/
@@ -205,6 +229,8 @@
\brief Returns the object to an uninitialized state.
Frees any resources it allocated and marks the object as uninitialized.
\since BeOS R3
*/
@@ -212,7 +238,7 @@
/*!
\name Path manipulation methods
\name Path Manipulation
*/
@@ -239,6 +265,8 @@
\retval B_OK Initialization was successful.
\retval B_BAD_VALUE \a ref was \c NULL.
\retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH.
\since BeOS R3
*/
@@ -246,7 +274,7 @@
/*!
\name Path information methods
\name Path Information
*/
@@ -259,6 +287,8 @@
\returns The path name of the object, or \c NULL if it is not properly
initialized.
\since BeOS R3
*/
@@ -271,6 +301,8 @@
\returns The leaf portion of the path or \c NULL if it is not properly
initialized.
\since BeOS R3
*/
@@ -305,7 +337,7 @@
/*!
\name Operator overload methods
\name Operators
*/
@@ -322,6 +354,8 @@
\param item the BPath object to compare.
\return \c true, if the paths are equal, \c false otherwise.
\since BeOS R3
*/
@@ -334,6 +368,8 @@
\param path The path to compare.
\return \c true, if the path names are equal, \c false otherwise.
\since BeOS R3
*/
@@ -347,6 +383,8 @@
\param item the BPath object to compare.
\return \c true, if the path names are \b not equal, \c false otherwise.
\since BeOS R3
*/
@@ -359,6 +397,8 @@
\param path The path to compare.
\return \c true, if the path names are \b not equal, \c false otherwise.
\since BeOS R3
*/
@@ -369,6 +409,8 @@
\param item The BPath object to copy
\return A pointer to the newly initialized BPath object.
\since BeOS R3
*/
@@ -381,6 +423,8 @@
\param path the path to be assign to this object.
\return A pointer to the newly initialized BPath object.
\since BeOS R3
*/
@@ -388,7 +432,7 @@
/*!
\name BFlattenable method implementations
\name BFlattenable Method Implementations
*/
@@ -400,6 +444,8 @@
\brief Implements BFlattenable::IsFixedSize(). Always returns \c false.
\return \c false
\since BeOS R3
*/
@@ -408,6 +454,8 @@
\brief Implements BFlattenable::TypeCode(). Always returns \c B_REF_TYPE.
\return \c B_REF_TYPE
\since BeOS R3
*/
@@ -418,6 +466,8 @@
\return The size of the flattened entry_ref struct that represents the
path in bytes.
\since BeOS R3
*/
@@ -432,6 +482,8 @@
\returns A status code.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \a buffer was \c NULL or of insufficient size.
\since BeOS R3
*/
@@ -443,6 +495,8 @@
\param code The type code to test.
\return \c true if code is \c B_REF_TYPE, \c false otherwise.
\since BeOS R3
*/
@@ -461,42 +515,9 @@
\returns A status code.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \a buffer was \c NULL or didn't contain an entry_ref.
\since BeOS R3
*/
//! @}
/// private methods, won't show up in docs
/*!
status_t BPath::_SetPath(const char* path)
\brief Sets the supplied path.
The path is copied, if \a path is \c NULL the path of the object is set to
\c NULL as well. The old path is deleted.
\param path the path to be set
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_MEMORY Insufficient memory.
*/
/*!
bool BPath::_MustNormalize(const char* path, status_t* _error)
\brief Checks a path to see if normalization is required.
The following items require normalization:
- Relative pathnames (after concatenation; e.g. "boot/ltj")
- The presence of "." or ".." ("/boot/ltj/../ltj/./gwar")
- Redundant slashes ("/boot//ltj")
- A trailing slash ("/boot/ltj/")
\param _error A pointer to an error variable that will be set if the input
is not a valid path.
\return \c true if \a path requires normalization, \c false otherwise.
*/
docs/user/storage/PathFinder.dox
+156 -108
View File
@@ -1,13 +1,14 @@
/*
* Copyright 2013, Haiku, Inc. All rights reserved.
* Copyright 2013-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* John Scipione, [email protected]
* Ingo Weinhold, [email protected]
*
* Corresponds to:
* headers/os/storage/PathFinder.h hrev46390
* src/kits/storage/PathFinder.cpp hrev46390
* headers/os/storage/PathFinder.h hrev47402
* src/kits/storage/PathFinder.cpp hrev47402
*/
@@ -29,6 +30,8 @@
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
*/
@@ -36,7 +39,7 @@
\fn BPathFinder::BPathFinder(const void* codePointer,
const char* dependency)
\brief Creates an object referring to an installation location based on a
loaded image file.
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
@@ -53,23 +56,25 @@
arguments, subsequent calls to FindPath() will return an error.
\param codePointer A pointer to code or static data belonging to the image
based on which FindPath() shall compute the path. The special value
\c B_APP_IMAGE_SYMBOL (the default) can be used to refer to the program
image, and \c B_CURRENT_IMAGE_SYMBOL for the caller's image.
based on which FindPath() shall compute the path. The special value
\c B_APP_IMAGE_SYMBOL (the default) can be used to refer to the
program image, and \c B_CURRENT_IMAGE_SYMBOL for the caller's image.
\param dependency The name of the package's "requires" entry to be used for
resolving the installation location. Can be \c NULL (the default).
resolving the installation location. Can be \c NULL (the default).
\since Haiku R1
*/
/*!
\fn BPathFinder::BPathFinder(const char* path, const char* dependency)
\brief Creates an object referring to an installation location based on a
given path.
given \a path.
When initialized with this constructor a FindPath() method called afterward
evaluates the path constant passed to it based on \a path. In most cases
that means first determining the path of the installation location from the
given path.
given \a path.
If \a dependency is specified, instead of determining the installation
location path from the given path, the installation location path of the
@@ -80,48 +85,55 @@
arguments, subsequent calls to FindPath() will return an error.
\param path A path based on which FindPath() shall compute the path.
\param dependency The name of the package's "requires" entry to be used for
resolving the installation location. Can be \c NULL.
\param dependency The name of the package's "requires" entry to be used
for resolving the installation location. Can be \c NULL.
\since Haiku R1
*/
/*!
\fn BPathFinder::BPathFinder(const entry_ref& ref, const char* dependency)
\brief Creates an object referring to an installation location based on a
given entry_ref.
given entry_ref.
The constructor converts the given entry_ref \a ref to a path and then
initializes the object like
BPathFinder::BPathFinder(const char*, const char*).
\param ref A reference to be resolved to a path based on which FindPath()
shall compute the path.
\param dependency The name of the package's "requires" entry to be used for
resolving the installation location. Can be \c NULL.
shall compute the path.
\param dependency The name of the package's "requires" entry to be used
for resolving the installation location. Can be \c NULL.
\see BPathFinder::BPathFinder(const char*, const char*)
\since Haiku R1
*/
/*!
\fn BPathFinder::BPathFinder(const BResolvableExpression& expression,
const char* dependency)
\brief Creates an object referring to an installation location based on the
path of a package satisfying the given resolvable expression.
\brief 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 \a 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.
\note When using this constructor linking against libpackage.so is
required.
\param expression A resolvable expression to be resolved to the path of the
latest package satisfying it, based on which FindPath() shall compute
the path.
\param dependency The name of the package's "requires" entry to be used for
resolving the installation location. Can be \c NULL.
\param expression A resolvable expression to be resolved to the path of
the latest package satisfying it, based on which FindPath() shall
compute the path.
\param dependency The name of the package's "requires" entry to be used
for resolving the installation location. Can be \c NULL.
\see BPathFinder::BPathFinder(const char*, const char*)
\since Haiku R1
*/
@@ -129,14 +141,15 @@
\fn status_t BPathFinder::SetTo(const void* codePointer,
const char* dependency)
\brief Reinitializes the object to refer to an installation location based
on a loaded image file.
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 \a 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.
determines the path of the image (i.e. executable, library, or add-on)
file associated with \a 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 \a dependency is specified, instead of determining the installation
location path from the image path, the installation location path of the
@@ -147,25 +160,28 @@
error.
\param codePointer A pointer to code or static data belonging to the image
based on which FindPath() shall compute the path. The special value
\c B_APP_IMAGE_SYMBOL (the default) can be used to refer to the program
image, and \c B_CURRENT_IMAGE_SYMBOL for the caller's image.
based on which FindPath() shall compute the path. The special value
\c B_APP_IMAGE_SYMBOL (the default) can be used to refer to the
program image, and \c B_CURRENT_IMAGE_SYMBOL for the caller's image.
\param dependency The name of the package's "requires" entry to be used for
resolving the installation location. Can be \c NULL (the default).
resolving the installation location. Can be \c NULL (the default).
\return A status code.
\retval B_OK Everything went fine.
\since Haiku R1
*/
/*!
\fn status_t BPathFinder::SetTo(const char* path, const char* dependency)
\brief Reinitializes the object to refer to an installation location based
on a given path.
on a given \a path.
When reinitialized with this method a FindPath() method called afterward
evaluates the path constant passed to it based on \a path. In most cases
that means first determining the path of the installation location from the
given path.
that means first determining the path of the installation location from
the given \a path.
If \a dependency is specified, instead of determining the installation
location path from the given path, the installation location path of the
@@ -178,9 +194,11 @@
\param path A path based on which FindPath() shall compute the path.
\param dependency The name of the package's "requires" entry to be used for
resolving the installation location. Can be \c NULL.
\return A status code.
\retval B_OK Everything went fine.
resolving the installation location. Can be \c NULL.
\return \c B_OK Everything if went fine or an error code otherwise.
\since Haiku R1
*/
@@ -188,17 +206,21 @@
\fn status_t BPathFinder::SetTo(const entry_ref& ref,
const char* dependency)
\brief Reinitializes the object to refer to an installation location based
on a given entry_ref.
on a given entry_ref.
This method converts the given entry_ref \a ref to a path and then calls
calls BPathFinder::SetTo(const char*, const char*).
\param ref A reference to be resolved to a path based on which FindPath()
shall compute the path.
\param dependency The name of the package's "requires" entry to be used for
resolving the installation location. Can be \c NULL.
shall compute the path.
\param dependency The name of the package's "requires" entry to be used
for resolving the installation location. Can be \c NULL.
\see status_t BPathFinder::SetTo(const char*, const char*)
\return \c B_OK Everything if went fine or an error code otherwise.
\since Haiku R1
*/
@@ -221,6 +243,10 @@
resolving the installation location. Can be \c NULL.
\see status_t BPathFinder::SetTo(const char*, const char*)
\return \c B_OK Everything if went fine or an error code otherwise.
\since Haiku R1
*/
@@ -258,27 +284,30 @@
resolved to is returned.
\param architecture The name of the architecture to be used for resolving
architecture dependent paths. Can be \c NULL, in which case the
architecture associated with the initial path is used.
\a architecture dependent paths. Can be \c NULL, in which case the
\a architecture associated with the initial path is used.
\param baseDirectory Constant indicating which path to retrieve.
\param subPath Relative subpath that shall be appended. Can be \c NULL.
\param flags Bitwise OR of any of the following flags:
- \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't exist,
create it as a directory (including all missing ancestors).
- \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's parent
doesn't exist, create the parent directory (including all missing
ancestors).
- \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist,
fail with \c B_ENTRY_NOT_FOUND.
- \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't
exist, create it as a directory (including all missing ancestors).
- \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's
parent doesn't exist, create the parent directory (including all
missing ancestors).
- \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist,
fail with \c B_ENTRY_NOT_FOUND.
\param _path The variable to be set to the resulting path on success.
\return A status code.
\retval B_OK Everything went fine.
\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified
and the image file doesn't belong to a package, or \c dependency was
specified, but isn't a "requires" entry of the package, or
\c B_FIND_PATH_EXISTING_ONLY was specified and the resulting path
doesn't exist.
path didn't exist, e.g. \c B_FIND_PATH_PACKAGE_PATH was specified
and the image file didn't belong to a package, or \c dependency
was specified, but wasn't a "requires" entry of the package, or
\c B_FIND_PATH_EXISTING_ONLY was specified and the resulting path
didn't exist.
\since Haiku R1
*/
@@ -294,22 +323,25 @@
\param baseDirectory Constant indicating which path to retrieve.
\param subPath Relative subpath that shall be appended. Can be \c NULL.
\param flags Bitwise OR of any of the following flags:
- \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't exist,
create it as a directory (including all missing ancestors).
- \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's parent
doesn't exist, create the parent directory (including all missing
ancestors).
- \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist,
fail with \c B_ENTRY_NOT_FOUND.
- \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't
exist, create it as a directory (including all missing ancestors).
- \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's
parent doesn't exist, create the parent directory (including all
missing ancestors).
- \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist,
fail with \c B_ENTRY_NOT_FOUND.
\param _path The variable to be set to the resulting path on success.
\return A status code.
\retval B_OK Everything went fine.
\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified
and the image file doesn't belong to a package, or \c dependency was
specified, but isn't a "requires" entry of the package, or
\c B_FIND_PATH_EXISTING_ONLY was specified and the resulting path
doesn't exist.
path didn't exist, e.g. \c B_FIND_PATH_PACKAGE_PATH was specified
and the image file didn't belong to a package, or \c dependency
was specified, but wasn't a "requires" entry of the package, or
\c B_FIND_PATH_EXISTING_ONLY was specified and the resulting path
didn't exist.
\since Haiku R1
*/
@@ -325,12 +357,13 @@
\param baseDirectory Constant indicating which path to retrieve.
\param subPath Relative subpath that shall be appended. Can be \c NULL.
\param _path The variable to be set to the resulting path on success.
\return A status code.
\retval B_OK Everything went fine.
\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified
and the image file doesn't belong to a package, or \c dependency was
specified, but isn't a "requires" entry of the package.
path didn't exist, e.g. \c B_FIND_PATH_PACKAGE_PATH was specified
and the image file didn't belong to a package, or \c dependency was
specified, but wasn't a "requires" entry of the package.
*/
@@ -348,9 +381,11 @@
\return A status code.
\retval B_OK Everything went fine.
\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified
and the image file doesn't belong to a package, or \c dependency was
specified, but isn't a "requires" entry of the package.
path didn't exist, e.g. \c B_FIND_PATH_PACKAGE_PATH was specified
and the image file didn't belong to a package, or \c dependency
was specified, but wasn't a "requires" entry of the package.
\since Haiku R1
*/
@@ -373,26 +408,29 @@
valid arguments for this function.
\param architecture The name of the architecture to be used for resolving
architecture dependent paths. Can be \c NULL, in which case the caller's
architecture is used.
\a architecture dependent paths. Can be \c NULL, in which case the
caller's \a architecture is used.
\param baseDirectory Constant indicating which paths to retrieve.
\param subPath Relative subpath that shall be appended. Can be \c NULL.
\param flags Bitwise OR of any of the following flags:
- \c B_FIND_PATH_CREATE_DIRECTORY: If a resulting path doesn't exist,
create it as a directory (including all missing ancestors).
- \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If a resulting path's parent
doesn't exist, create the parent directory (including all missing
ancestors).
- \c B_FIND_PATH_EXISTING_ONLY: If a resulting path doesn't exist, skip
it. If none of the paths exist, fail with \c B_ENTRY_NOT_FOUND.
- \c B_FIND_PATH_CREATE_DIRECTORY: If a resulting path doesn't
exist, create it as a directory (including all missing ancestors).
- \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If a resulting path's
parent doesn't exist, create the parent directory (including all
missing ancestors).
- \c B_FIND_PATH_EXISTING_ONLY: If a resulting path doesn't exist,
skip it. If none of the paths exist, fail with \c B_ENTRY_NOT_FOUND.
\param _paths The BStringList variable where the retrieved paths shall be
stored. The list is emptied before adding the paths. It is also emptied
on error.
stored. The list is emptied before adding the paths. It is also
emptied on error.
\return A status code.
\retval B_OK Everything went fine.
\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was specified and
none of the resulting paths do exist.
paths didn't exist, e.g. \c B_FIND_PATH_EXISTING_ONLY was
specified and none of the resulting paths existed.
\since Haiku R1
*/
@@ -408,21 +446,25 @@
\param baseDirectory Constant indicating which paths to retrieve.
\param subPath Relative subpath that shall be appended. Can be \c NULL.
\param flags Bitwise OR of any of the following flags:
- \c B_FIND_PATH_CREATE_DIRECTORY: If a resulting path doesn't exist,
create it as a directory (including all missing ancestors).
- \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If a resulting path's parent
doesn't exist, create the parent directory (including all missing
ancestors).
- \c B_FIND_PATH_EXISTING_ONLY: If a resulting path doesn't exist, skip
it. If none of the paths exist, fail with \c B_ENTRY_NOT_FOUND.
- \c B_FIND_PATH_CREATE_DIRECTORY: If a resulting path doesn't
exist, create it as a directory (including all missing ancestors).
- \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If a resulting path's
parent doesn't exist, create the parent directory (including all
missing ancestors).
- \c B_FIND_PATH_EXISTING_ONLY: If a resulting path doesn't exist,
skip it. If none of the paths exist, fail with
\c B_ENTRY_NOT_FOUND.
\param _paths The BStringList variable where the retrieved paths shall be
stored. The list is emptied before adding the paths. It is also emptied
on error.
stored. The list is emptied before adding the paths. It is also
emptied on error.
\return A status code.
\retval B_OK Everything went fine.
\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was specified and
none of the resulting paths do exist.
paths didn't exist, e.g. \c B_FIND_PATH_EXISTING_ONLY was specified
and none of the resulting paths existed.
\since Haiku R1
*/
@@ -438,13 +480,16 @@
\param baseDirectory Constant indicating which paths to retrieve.
\param subPath Relative subpath that shall be appended. Can be \c NULL.
\param _paths The BStringList variable where the retrieved paths shall be
stored. The list is emptied before adding the paths. It is also emptied
on error.
stored. The list is emptied before adding the paths. It is also
emptied on error.
\return A status code.
\retval B_OK Everything went fine.
\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was specified and
none of the resulting paths do exist.
paths didn't exist, e.g. \c B_FIND_PATH_EXISTING_ONLY was specified
and none of the resulting paths existed.
\since Haiku R1
*/
@@ -459,11 +504,14 @@
\param baseDirectory Constant indicating which paths to retrieve.
\param _paths The BStringList variable where the retrieved paths shall be
stored. The list is emptied before adding the paths. It is also emptied
on error.
stored. The list is emptied before adding the paths. It is also
emptied on error.
\return A status code.
\retval B_OK Everything went fine.
\retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the
paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was specified and
none of the resulting paths do exist.
paths didn't exist, e.g. \c B_FIND_PATH_EXISTING_ONLY was specified
and none of the resulting paths existed.
\since Haiku R1
*/
docs/user/storage/Query.dox
+71 -81
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2002-2013 Haiku Inc. All rights reserved.
* Copyright 2002-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -9,8 +9,8 @@
* Ingo Weinhold, [email protected]
*
* Corresponds to:
* headers/os/storage/Query.h hrev45283
* src/kits/storage/Query.cpp hrev45283
* headers/os/storage/Query.h hrev47402
* src/kits/storage/Query.cpp hrev47402
*/
@@ -28,6 +28,8 @@
\ingroup libbe
\brief Provides an interface for creating file system queries and
implements BEntryList methods for iterating through the results.
\since BeOS R3
*/
@@ -36,12 +38,16 @@
\brief Creates an uninitialized BQuery object.
\see SetPredicate()
\since BeOS R3
*/
/*!
\fn BQuery::~BQuery()
\brief Destroys the BQuery object and frees any associated resources.
\since BeOS R3
*/
@@ -50,6 +56,8 @@
\brief Resets the object to a uninitialized state.
\return \c B_OK
\since BeOS R3
*/
@@ -69,11 +77,13 @@
\retval B_NO_INIT The object predicate or the volume wasn't set.
\retval B_BAD_VALUE The object predicate was invalid.
\retval B_NOT_ALLOWED Fetch() already called.
\since BeOS R3
*/
/*!
\name Predicate push methods
\name Predicate Push
Methods to push data onto the predicate stack.
@@ -101,6 +111,8 @@
\retval B_OK Everything went fine.
\retval B_NO_MEMORY Not enough memory.
\retval B_NOT_ALLOWED PushAttribute() was called after Fetch().
\since BeOS R3
*/
@@ -114,6 +126,8 @@
\retval B_OK Everything went fine.
\retval B_NO_MEMORY Not enough memory.
\retval B_NOT_ALLOWED PushOp() was called after Fetch().
\since BeOS R3
*/
@@ -127,6 +141,8 @@
\retval B_OK Everything went fine.
\retval B_NO_MEMORY Not enough memory.
\retval B_NOT_ALLOWED PushUInt32() was called after Fetch().
\since BeOS R3
*/
@@ -140,6 +156,8 @@
\retval B_OK Everything went fine.
\retval B_NO_MEMORY Not enough memory.
\retval B_NOT_ALLOWED PushInt32() was called after Fetch().
\since BeOS R3
*/
@@ -153,6 +171,8 @@
\retval B_OK Everything went fine.
\retval B_NO_MEMORY Not enough memory.
\retval B_NOT_ALLOWED PushUInt64() was called after Fetch().
\since BeOS R3
*/
@@ -166,6 +186,8 @@
\retval B_OK Everything went fine.
\retval B_NO_MEMORY Not enough memory.
\retval B_NOT_ALLOWED PushInt64() was called after Fetch().
\since BeOS R3
*/
@@ -179,6 +201,8 @@
\retval B_OK Everything went fine.
\retval B_NO_MEMORY Not enough memory.
\retval B_NOT_ALLOWED PushFloat() was called after Fetch().
\since BeOS R3
*/
@@ -192,6 +216,8 @@
\retval B_OK Everything went fine.
\retval B_NO_MEMORY Not enough memory.
\retval B_NOT_ALLOWED PushDouble() was called after Fetch().
\since BeOS R3
*/
@@ -207,6 +233,8 @@
\retval B_OK Everything went fine.
\retval B_NO_MEMORY Not enough memory.
\retval B_NOT_ALLOWED PushString() was called after Fetch().
\since BeOS R3
*/
@@ -224,6 +252,8 @@
\retval B_NOT_ALLOWED PushDate() was called after Fetch().
\see parsedate()
\since Haiku R1
*/
@@ -231,7 +261,7 @@
/*!
\name Assignment methods
\name Assignment
*/
@@ -252,6 +282,8 @@
\return A status code.
\retval B_OK Everything went fine.
\retval B_NOT_ALLOWED SetVolume() was called after Fetch().
\since BeOS R3
*/
@@ -272,6 +304,8 @@
\retval B_OK Everything went fine.
\retval B_NO_MEMORY Not enough memory.
\retval B_NOT_ALLOWED SetPredicate() was called after Fetch().
\since BeOS R3
*/
@@ -291,6 +325,8 @@
\retval B_OK Everything went fine.
\retval B_NO_MEMORY Not enough memory.
\retval B_NOT_ALLOWED SetTarget() was called after Fetch().
\since BeOS R3
*/
@@ -298,7 +334,7 @@
/*!
\name Query information methods
\name Query Information
*/
@@ -308,7 +344,12 @@
/*!
\fn bool BQuery::IsLive() const
\brief Gets whether the query associated with this object is live.
\return \c true, if the query is live, \c false otherwise.
\sa SetTarget()
\since BeOS R3
*/
@@ -318,6 +359,10 @@
\return The device ID of the volume or \c B_NO_INIT if the volume wasn't
set.
\since BeOS R3
\since Haiku R1
*/
@@ -331,6 +376,10 @@
SetPredicate().
\return The length of the predicate string or 0 if an error occurred.
\see SetPredicate()
\since BeOS R3
*/
@@ -338,7 +387,7 @@
/*!
\name Get predicate methods
\name Get Predicate
These methods fetch a string representation regardless of whether the
predicate has been constructed using the predicate stack or via
@@ -364,6 +413,8 @@
\retval B_OK Everything went fine.
\retval B_NO_INIT The predicate of the BQuery object wasn't set.
\retval B_BAD_VALUE \a buffer was \c NULL or too short.
\since BeOS R3
*/
@@ -379,6 +430,8 @@
\retval B_OK Everything went fine.
\retval B_NO_INIT The predicate of the BQuery object wasn't set.
\retval B_BAD_VALUE \a predicate was \c NULL.
\since Haiku R1
*/
@@ -386,7 +439,7 @@
/*!
\name BEntryList interface methods
\name BEntryList Interface
These methods are used to traverse the results of a query as a BEntryList.
@@ -411,6 +464,8 @@
\retval B_ENTRY_NOT_FOUND At end of list.
\retval B_BAD_VALUE The predicate included unindexed attributes.
\retval B_NOT_ALLOWED Fetch() was not previously called on the object.
\since BeOS R3
*/
@@ -426,6 +481,8 @@
\retval B_ENTRY_NOT_FOUND At end of list.
\retval B_BAD_VALUE The predicate included unindexed attributes.
\retval B_NOT_ALLOWED Fetch() was not previously called on the object.
\since BeOS R3
*/
@@ -448,6 +505,8 @@
are no more entries to be read, or an error code.
\retval B_BAD_VALUE The predicate included unindexed attributes.
\retval B_FILE_ERROR Fetch() was not previously called on the object.
\since BeOS R3
*/
@@ -460,6 +519,8 @@
\return A status code.
\retval B_OK Everything went fine.
\retval B_FILE_ERROR Fetch() was not previously called on the object.
\since BeOS R3
*/
@@ -468,80 +529,9 @@
\brief Unimplemented.
\return \c B_ERROR.
\since BeOS R3
*/
//! @}
/// private methods, won't show up in docs
/*!
\fn bool BQuery::_HasFetched() const
\brief Gets whether Fetch() has already been called on this object.
\return \c true, if Fetch() was already called, \c false otherwise.
*/
/*!
\fn status_t BQuery::_PushNode(QueryNode* node, bool deleteOnError)
\brief Pushes a node onto the predicate stack.
If the stack has not been allocate until this time, this method does
allocate it.
If the supplied node is \c NULL, it is assumed that there was not enough
memory to allocate the node and thus \c B_NO_MEMORY is returned.
In case the method fails, the caller retains the ownership of the supplied
node and thus is responsible for deleting it, if \a deleteOnError is
\c false. If it is \c true, the node is deleted, if an error occurs.
\param node The node to push.
\param deleteOnError Whether or not to delete the node if an error occurs.
\return A status code.
\retval B_OK Everything went fine.
\retval B_NO_MEMORY \a node was \c NULL or there was insufficient memory to
allocate the predicate stack or push the node.
\retval B_NOT_ALLOWED _PushNode() was called after Fetch().
*/
/*!
\fn status_t BQuery::_SetPredicate(const char* expression)
\brief Helper method to set the predicate.
Does not check whether Fetch() has already been invoked.
\param expression The predicate string to set.
\return A status code.
\retval B_OK Everything went fine.
\retval B_NO_MEMORY There was insufficient memory to store the predicate.
*/
/*!
\fn status_t BQuery::_EvaluateStack()
Evaluates the predicate stack.
The method does nothing (and returns \c B_OK), if the stack is \c NULL.
If the stack is not \c null and Fetch() has already been called, this
method fails.
\return A status code.
\retval B_OK Everything went fine.
\retval B_NO_MEMORY There was insufficient memory.
\retval B_NOT_ALLOWED _EvaluateStack() was called after Fetch().
*/
/*!
\fn void BQuery::_ParseDates(BString& parsedPredicate)
\brief Fills out \a parsedPredicate with a parsed predicate string.
\param parsedPredicate The predicate string to fill out.
*/
docs/user/storage/Resources.dox
+82 -14
View File
@@ -8,8 +8,8 @@
* Ingo Weinhold, [email protected]
*
* Corresponds to:
* headers/os/storage/Resources.h hrev45283
* src/kits/storage/Resources.cpp hrev45283
* headers/os/storage/Resources.h hrev47402
* src/kits/storage/Resources.cpp hrev47402
*/
@@ -37,6 +37,8 @@
never be invalid. It always serves as a resources container, even if
it is not associated with a file. It is always possible to WriteTo()
the resources BResources contains to a file (a valid one of course).
\since BeOS R3
*/
@@ -45,6 +47,8 @@
\brief Creates an uninitialized BResources object.
\see SetTo()
\since BeOS R3
*/
@@ -64,6 +68,8 @@
\param file The file to create a BResource object from.
\param clobber If \c true, the data of the file are erased.
\since BeOS R3
*/
@@ -80,6 +86,8 @@
\param path A path referring to the file to create a BResource object
from.
\param clobber If \c true, the data of the file are erased.
\since Haiku R1
*/
@@ -96,6 +104,8 @@
\param ref An entry_ref referring to the file to create a BResource object
from.
\param clobber If \c true, the data of the file are erased.
\since Haiku R1
*/
@@ -105,11 +115,13 @@
Sync() is first called to make sure that the changes are written back to
the file.
\since BeOS R3
*/
/*!
\name SetTo methods
\name SetTo
What happens, if \a clobber is \c true, depends on the type of the file.
If the file is capable of containing resources, that is, is a resource
@@ -141,6 +153,8 @@
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \a file was \c NULL or uninitialized.
\retval B_ERROR Failed to initialize the object.
\since BeOS R3
*/
@@ -158,6 +172,8 @@
\retval B_BAD_VALUE \a path was \c NULL.
\retval B_ENTRY_NOT_FOUND The file referenced by \a path couldn't be found.
\retval B_ERROR Failed to initialize the object.
\since Haiku R1
*/
@@ -175,6 +191,8 @@
\retval B_BAD_VALUE \a ref was \c NULL.
\retval B_ENTRY_NOT_FOUND The file referenced by \a ref couldn't be found.
\retval B_ERROR Failed to initialize the object.
\since Haiku R1
*/
@@ -192,6 +210,8 @@
\retval B_OK Everything went fine.
\retval B_ENTRY_NOT_FOUND The file referenced by \a ref couldn't be found.
\retval B_ERROR Failed to initialize the object.
\since Haiku R1
*/
@@ -215,6 +235,8 @@
\retval B_BAD_VALUE \a codeOrDataPointer was \c NULL.
\retval B_ENTRY_NOT_FOUND The image or the file couldn't be found.
\retval B_ERROR Failed to initialize the object.
\since Haiku R1
*/
@@ -222,7 +244,7 @@
/*!
\name Constructor helper methods
\name Constructor Helpers
*/
@@ -237,6 +259,8 @@
written back to the file.
\note This method is not found in BeOS R5.
\since Haiku R1
*/
@@ -253,6 +277,8 @@
\return \c B_OK if the objects is properly initialized,
\c B_NO_MEMORY otherwise.
\since Haiku R1
*/
@@ -260,7 +286,7 @@
/*!
\name LoadResources methods
\name LoadResources
A resource is loaded into memory only once. A second call with the same
parameters will result in the same pointer. The BResources object is the
@@ -283,8 +309,10 @@
shall be written.
\return A pointer to the resource data if everything went fine, or
\c NULL if the file does not have a resource that matches the
parameters or an error occurred.
\c NULL if the file does not have a resource that matches the
parameters or an error occurred.
\since BeOS R4
*/
@@ -303,8 +331,10 @@
shall be written.
\return A pointer to the resource data if everything went fine, or
\c NULL if the file does not have a resource that matches the
parameters or an error occurred.
\c NULL if the file does not have a resource that matches the
parameters or an error occurred.
\since BeOS R4
*/
@@ -321,6 +351,8 @@
of errors that occurred.
\retval B_OK Everything went fine.
\retval B_BAD_FILE The resource map is empty???
\since BeOS R4
*/
@@ -332,6 +364,8 @@
\brief Gets a reference to the internal BFile object.
\return A reference to the internal BFile object.
\since BeOS R4
*/
@@ -357,6 +391,8 @@
\retval B_FILE_ERROR A file error occurred.
\retval B_IO_ERROR An error occurred while writing the resources.
\retval B_NOT_ALLOWED The file was opened read only.
\since BeOS R4
*/
@@ -373,6 +409,8 @@
\retval B_BAD_VALUE \a fromFile was \c NULL.
\retval B_FILE_ERROR A file error occurred.
\retval B_IO_ERROR An error occurred while writing the resources.
\since BeOS R4
*/
@@ -389,6 +427,8 @@
\param file The file that the resources shall be written to.
\return \c B_OK if everything went fine or an error code otherwise.
\since BeOS R4
*/
@@ -416,6 +456,8 @@
\retval B_FILE_ERROR A file error occurred.
\retval B_NO_MEMORY Not enough memory for the operation.
\retval B_NOT_ALLOWED The file was opened read only.
\since BeOS R3
*/
@@ -429,6 +471,8 @@
\return \c true if the file contains a matching resource,
\c false otherwise.
\since BeOS R3
*/
@@ -442,6 +486,8 @@
\return \c true, if the file contains a matching resource,
\c false otherwise.
\since BeOS R3
*/
@@ -462,6 +508,8 @@
\return \c true, if a matching resource could be found,
\c false otherwise.
\since BeOS R3
*/
@@ -482,6 +530,8 @@
\return \c true, if a matching resource could be found,
\c false otherwise.
\since BeOS R3
*/
@@ -500,6 +550,8 @@
\return \c true, if a matching resource could be found,
\c false otherwise.
\since BeOS R3
*/
@@ -518,6 +570,8 @@
\return \c true, if a matching resource could be found,
\c false otherwise.
\since BeOS R3
*/
@@ -540,6 +594,8 @@
\return \c true, if a matching resource could be found,
\c false otherwise.
\since BeOS R4
*/
@@ -557,6 +613,8 @@
\retval B_ERROR An error occurred while removing the resource.
\retval B_FILE_ERROR A file error occurred.
\retval B_NOT_ALLOWED The file was opened read only.
\since BeOS R4
*/
@@ -573,11 +631,13 @@
\retval B_ERROR An error occurred while removing the resource.
\retval B_FILE_ERROR A file error occurred.
\retval B_NOT_ALLOWED The file was opened read only.
\since BeOS R3
*/
/*!
\name Deprecated methods
\name Deprecated Methods
These methods are deprecated and should not be used as there is a better
method. See the method description for the replacement method to use.
@@ -603,7 +663,7 @@
\param id The ID of the resource to write data to.
\param data The data to be written.
\param offset The byte offset relative to the beginning of the resource at
which the data shall be written.
which the data shall be written.
\param length The size of the data to be written.
\return A status code.
@@ -612,6 +672,8 @@
identify an existing resource.
\retval B_ERROR Error writing data.
\retval B_NO_MEMORY Not enough memory for this operation.
\since BeOS R3
*/
@@ -632,7 +694,7 @@
\param id The ID of the resource to be read.
\param data A pointer to a buffer into which the data shall be read
\param offset The byte offset relative to the beginning of the resource
from which the data shall be read.
from which the data shall be read.
\param length The size of the data to be read.
\return A status code.
@@ -641,6 +703,8 @@
identify an existing resource.
\retval B_ERROR Error reading data.
\retval B_NO_MEMORY Not enough memory for this operation.
\since BeOS R3
*/
@@ -658,10 +722,12 @@
\param type The type of the resource to find.
\param id The ID of the resource to find.
\param lengthFound A pointer to a variable into which the size of the
resource data shall be written.
resource data shall be written.
\return A pointer to the resource data if everything went fine or \c NULL
if an error occurred.
\since BeOS R3
*/
@@ -679,10 +745,12 @@
\param type The type of the resource to find.
\param name The name of the resource to find.
\param lengthFound A pointer to a variable into which the size of the
resource data shall be written.
resource data shall be written.
\return A pointer to the resource data if everything went fine or \c NULL
if an error occurred.
\since BeOS R3
*/
docs/user/storage/Statable.dox
+64 -18
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2002-2013 Haiku Inc. All rights reserved.
* Copyright 2002-2013 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -8,8 +8,8 @@
* Ingo Weinhold, [email protected]
*
* Corresponds to:
* headers/os/storage/Statable.h hrev45306
* src/kits/storage/Statable.cpp hrev45306
* headers/os/storage/Statable.h hrev47402
* src/kits/storage/Statable.cpp hrev47402
*/
@@ -46,22 +46,26 @@
GetVolume() method.
- Get a node_ref of a node to pass into watch_node() via the GetNodeRef()
method.
\since BeOS R3
*/
/*!
\fn status_t BStatable::GetStat(struct stat *st) const
\fn status_t BStatable::GetStat(struct stat* stat) const
\brief Fills out the stat structure for the node.
This method may be used to access the stat structure of a node directly.
\param st The stat structure to be filled in.
\param stat The stat structure to be filled in.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_MEMORY Could not allocate enough memory.
\retval B_BAD_VALUE The node does not exist.
\retval B_NOT_ALLOWED Node or volume was read only.
\since BeOS R3
*/
@@ -71,6 +75,8 @@
\return \c true, if the node is properly initialized and is a file,
\c false otherwise.
\since BeOS R5
*/
@@ -80,6 +86,8 @@
\return \c true, if the node is properly initialized and is a directory,
\c false otherwise.
\since BeOS R5
*/
@@ -89,26 +97,33 @@
\return \c true, if the node is properly initialized and is a symlink,
\c false otherwise.
\since BeOS R5
*/
/*!
\fn status_t BStatable::GetNodeRef(node_ref *ref) const
\fn status_t BStatable::GetNodeRef(node_ref* ref) const
\brief Fills out \a ref with the \c node_ref of the node.
\param ref the node_ref to be set.
\see GetStat() for return codes.
\since BeOS R3
*/
/*!
\fn status_t BStatable::GetOwner(uid_t *owner) const
\fn status_t BStatable::GetOwner(uid_t* owner) const
\brief Fills out the node's UID into \a owner.
\param owner A pointer to a \c uid_t to be set.
\see SetOwner()
\see GetStat() for return codes.
\since BeOS R3
*/
@@ -119,16 +134,21 @@
\param owner The UID to set the node to.
\see GetStat() for return codes.
\since BeOS R3
*/
/*!
\fn status_t BStatable::GetGroup(gid_t *group) const
\fn status_t BStatable::GetGroup(gid_t* group) const
\brief Fills out the node's GID into \a group.
\param group a pointer to a \c gid_t variable to be set.
\see SetGroup()
\see GetStat() for return codes.
\since BeOS R3
*/
@@ -139,47 +159,59 @@
\param group The GID to set the node to.
\see GetStat() for return codes.
\since BeOS R3
*/
/*!
\fn status_t BStatable::GetPermissions(mode_t *perms) const
\fn status_t BStatable::GetPermissions(mode_t* permissions) const
\brief Fills out \a perms with the permissions of the node.
\param perms A pointer to a \c mode_t variable to be set.
\param permissions The permissions to get from the node.
\see SetPermissions()
\see GetStat() for return codes.
\since BeOS R3
*/
/*!
\fn status_t BStatable::SetPermissions(mode_t perms)
\fn status_t BStatable::SetPermissions(mode_t permissions)
\brief Sets the node's permissions to \a perms.
\param perms The permissions to set the node to.
\param permissions The permissions to set the node to.
\see GetStat() for return codes.
\since BeOS R3
*/
/*!
\fn status_t BStatable::GetSize(off_t *size) const
\fn status_t BStatable::GetSize(off_t* size) const
\brief Fills out the size of the node's data (not counting attributes)
into \a size.
\param size A pointer to a \c off_t variable to be set.
\see GetStat() for return codes.
\since BeOS R3
*/
/*!
\fn status_t BStatable::GetModificationTime(time_t *mtime) const
\fn status_t BStatable::GetModificationTime(time_t* mtime) const
\brief Fills out \a mtime with the last modification time of the node.
\param mtime A pointer to a \c time_t variable to be set.
\see SetModificationTime()
\see GetStat() for return codes.
\since BeOS R3
*/
@@ -190,16 +222,21 @@
\param mtime The modification time to set the node to.
\see GetStat() for return codes.
\since BeOS R3
*/
/*!
\fn status_t BStatable::GetCreationTime(time_t *ctime) const
\fn status_t BStatable::GetCreationTime(time_t* ctime) const
\brief Fills out \a ctime with the creation time of the node.
\param ctime A pointer to a \c time_t variable to be set.
\see SetCreationTime()
\see GetStat() for return codes.
\since BeOS R3
*/
@@ -210,15 +247,20 @@
\param ctime The creation time to set the node to.
\see GetStat() for return codes.
\since BeOS R3
*/
/*!
\fn status_t BStatable::GetAccessTime(time_t *atime) const
\fn status_t BStatable::GetAccessTime(time_t* atime) const
\brief Fills out \a atime with the access time of the node.
\see GetModificationTime()
\see SetAccessTime()
\see GetStat() for return codes.
\since BeOS R3
*/
@@ -228,15 +270,19 @@
\see GetModificationTime()
\see GetStat() for return codes.
\since BeOS R3
*/
/*!
\fn status_t BStatable::GetVolume(BVolume *vol) const
\fn status_t BStatable::GetVolume(BVolume* volume) const
\brief Fills out \a vol with the the volume that the node lives on.
\param vol A pointer to a BVolume object to be set.
\param volume A pointer to a BVolume object to be set.
\see BVolume
\see GetStat() for return codes.
\since Haiku R1
*/
docs/user/storage/SymLink.dox
+36 -23
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2002-2013 Haiku Inc. All rights reserved.
* Copyright 2002-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -8,8 +8,8 @@
* Ingo Weinhold, [email protected]
*
* Corresponds to:
* headers/os/storage/SymLink.h hrev45306
* src/kits/storage/SymLink.cpp hrev45306
* headers/os/storage/SymLink.h hrev47402
* src/kits/storage/SymLink.cpp hrev47402
*/
@@ -27,58 +27,72 @@
\ingroup libbe
\brief Provides an interface for creating, manipulating, and accessing
the contents of symbolic links.
\since BeOS R3
*/
/*!
\fn BSymLink::BSymLink()
\brief Creates an uninitialized BSymLink object.
\since BeOS R3
*/
/*!
\fn BSymLink::BSymLink(const BSymLink &link)
\fn BSymLink::BSymLink(const BSymLink& other)
\brief Creates a copy of the supplied BSymLink object.
\param link The BSymLink object to be copied.
\param other The BSymLink object to be copied.
\since BeOS R3
*/
/*!
\fn BSymLink::BSymLink(const entry_ref *ref)
\fn BSymLink::BSymLink(const entry_ref* ref)
\brief Creates a BSymLink object and initializes it to the symbolic link
referred to by the supplied entry_ref.
\param ref the entry_ref referring to the symbolic link.
\since BeOS R3
*/
/*!
\fn BSymLink::BSymLink(const BEntry *entry)
\fn BSymLink::BSymLink(const BEntry* entry)
\brief Creates a BSymLink object and initializes it to the symbolic link
referred to by the supplied BEntry.
\param entry The BEntry referring to the symbolic link.
\since BeOS R3
*/
/*!
\fn BSymLink::BSymLink(const char *path)
\fn BSymLink::BSymLink(const char* path)
\brief Creates a BSymLink object and initializes it to the symbolic link
referred to by the supplied path name.
\param path The path of the symbolic link.
\since BeOS R3
*/
/*!
\fn BSymLink::BSymLink(const BDirectory *dir, const char *path)
\fn BSymLink::BSymLink(const BDirectory* dir, const char* path)
\brief Creates a BSymLink object and initializes it to the symbolic link
referred to by the supplied path name relative to the specified
BDirectory.
\param dir The base BDirectory.
\param path The path of the symbolic link relative to \a dir.
\since BeOS R3
*/
@@ -88,11 +102,13 @@
If the BSymLink was properly initialized, the file descriptor of the
symbolic link is also closed.
\since BeOS R3
*/
/*!
\fn ssize_t BSymLink::ReadLink(char *buffer, size_t size)
\fn ssize_t BSymLink::ReadLink(char* buffer, size_t size)
\brief Reads the contents of the symbolic link into \a buffer.
The string written to the buffer is guaranteed to be \c NULL terminated.
@@ -104,11 +120,13 @@
\retval B_BAD_VALUE \a buf was \c NULL or the object didn't refer to a
symbolic link.
\retval B_FILE_ERROR The object was not initialized.
\since BeOS R3
*/
/*!
\fn ssize_t BSymLink::MakeLinkedPath(const char *dirPath, BPath *path)
\fn ssize_t BSymLink::MakeLinkedPath(const char* dirPath, BPath* path)
\brief Combines a directory path and the contents of this symbolic link to
form an absolute path.
@@ -120,11 +138,13 @@
refer to a symbolic link.
\retval B_FILE_ERROR The object was not initialized.
\retval B_NAME_TOO_LONG The resulting path name was too long to fit.
\since BeOS R3
*/
/*!
\fn ssize_t BSymLink::MakeLinkedPath(const BDirectory *dir, BPath *path)
\fn ssize_t BSymLink::MakeLinkedPath(const BDirectory* dir, BPath* path)
\brief Combines a directory path and the contents of this symbolic link to
form an absolute path.
@@ -136,6 +156,8 @@
refer to a symbolic link.
\retval B_FILE_ERROR The object was not initialized.
\retval B_NAME_TOO_LONG The resulting path name was too long to fit.
\since BeOS R3
*/
@@ -145,15 +167,6 @@
/return \c true if the object is properly initialized and the symbolic
link refers to an absolute path, \c false otherwise.
*/
/*!
\fn int BSymLink::get_fd() const
\brief Returns the file descriptor of the BSymLink.
This method should be used instead of accessing the private \c fFd member
of the BNode directly.
\return The object's file descriptor, or -1 if not properly initialized.
\since BeOS R3
*/
docs/user/storage/Volume.dox
+73 -14
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2002-2013 Haiku Inc. All rights reserved.
* Copyright 2002-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -9,8 +9,8 @@
* Ingo Weinhold, [email protected]
*
* Corresponds to:
* headers/os/storage/Volume.h hrev45306
* src/kits/storage/Volume.cpp hrev45306
* headers/os/storage/Volume.h hrev47402
* src/kits/storage/Volume.cpp hrev47402
*/
@@ -31,6 +31,8 @@
The class is a simple wrapper for a \c dev_t and the function
fs_stat_dev(). The sole exception is the SetName() method which
sets the name of the volume.
\since BeOS R3
*/
@@ -41,6 +43,8 @@
InitCheck() will return \c B_NO_INIT.
\see SetTo()
\since BeOS R3
*/
@@ -53,11 +57,13 @@
successful.
\param device The device ID of the volume.
\since BeOS R3
*/
/*!
\fn BVolume::BVolume(const BVolume &volume)
\fn BVolume::BVolume(const BVolume& volume)
\brief Creates a copy of the supplied BVolume object.
Afterwards the object refers to the same device the supplied object
@@ -65,17 +71,21 @@
either.
\param volume The volume object to be copied.
\since BeOS R3
*/
/*!
\fn BVolume::~BVolume()
\brief Destroys the object and frees all associated resources.
\since BeOS R3
*/
/*!
\name Constructor helper methods
\name Constructor Helpers
*/
@@ -88,6 +98,8 @@
\return \c B_OK if the object was properly initialized, or an error code
otherwise.
\since BeOS R3
*/
@@ -97,8 +109,11 @@
the supplied device ID.
\param device The device ID of the volume to set.
\return \c B_OK if the object was properly initialized, or an error code
otherwise.
\since BeOS R3
*/
@@ -107,6 +122,8 @@
\brief Brings the BVolume object to an uninitialized state.
InitCheck() will return \c B_NO_INIT.
\since BeOS R3
*/
@@ -114,7 +131,7 @@
/*!
\name Volume information methods
\name Volume Information
*/
@@ -126,7 +143,9 @@
\brief Returns the device ID of the volume the object refers to.
\return Returns the device ID of the volume the object refers to
or -1 if the object was not properly initialized.
or -1 if the object was not properly initialized.
\since BeOS R3
*/
@@ -136,12 +155,14 @@
object into \a directory.
\param directory A pointer to a pre-allocated BDirectory to be initialized
to the volume's root directory.
to the volume's root directory.
\return A status code.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \a directory was \c NULL or the object was not properly
initialized.
\since BeOS R3
*/
@@ -151,6 +172,10 @@
\return The volume's total storage capacity (in bytes), or \c B_BAD_VALUE
if the object is not properly initialized.
\see FreeBytes()
\since BeOS R3
*/
@@ -160,6 +185,8 @@
\return The amount of unused space on the volume (in bytes), or
\c B_BAD_VALUE if the object is not properly initialized.
\since BeOS R3
*/
@@ -170,6 +197,8 @@
\return The block size in bytes, \c B_NO_INIT if the volume is not
initialized or other errors forwarded from the file system.
\since Haiku R1
*/
@@ -177,7 +206,7 @@
/*!
\name Volume name methods
\name Volume Name
*/
@@ -196,6 +225,10 @@
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \a name was \c NULL or the object was not properly
initialized.
\see SetName()
\since BeOS R3
*/
@@ -220,6 +253,8 @@
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \a name was \c NULL or the object was not properly
initialized.
\since Haiku R1
*/
@@ -227,7 +262,7 @@
/*!
\name Volume icon methods
\name Volume Icon
*/
@@ -239,11 +274,13 @@
\brief Writes the volume's icon into the supplied BBitmap.
\param icon A pointer to a pre-allocated BBitmap of the correct dimension
to store the requested icon (16x16 for the mini and 32x32 for the
large icon).
to store the requested icon (16x16 for the mini and 32x32 for the
large icon).
\param which The icon size to be retrieved: \c B_MINI_ICON for the mini or
\c B_LARGE_ICON for the large icon.
\since BeOS R4
*/
@@ -263,6 +300,8 @@
\see fs_stat_dev() for more return codes.
\see get_device_icon() for more return codes.
\since Haiku R1
*/
@@ -270,7 +309,7 @@
/*!
\name Volume capability methods
\name Volume Capabilities
*/
@@ -283,6 +322,8 @@
\return \c true, if the volume was properly initialized and is removable,
\c false otherwise.
\since BeOS R3
*/
@@ -292,6 +333,8 @@
\return \c true, if the volume was properly initialized and is read-only,
\c false otherwise.
\since BeOS R3
*/
@@ -301,6 +344,8 @@
\return \c true, if the volume was properly initialized and is persistent,
\c false otherwise.
\since BeOS R3
*/
@@ -310,6 +355,8 @@
return \c true, if the volume was properly initialized and is shared,
\c false otherwise.
\since BeOS R3
*/
@@ -319,6 +366,8 @@
\return \c true, if the volume was properly initialized and supports
MIME-types, \c false otherwise.
\since BeOS R3
*/
@@ -328,6 +377,8 @@
\return \c true, if the volume was properly initialized and supports
attributes, \c false otherwise.
\since BeOS R3
*/
@@ -337,6 +388,8 @@
\return \c true, if the volume was properly initialized and supports
queries, \c false otherwise.
\since BeOS R3
*/
@@ -344,7 +397,7 @@
/*!
\name Operator overload methods
\name Operators
*/
@@ -362,6 +415,8 @@
\param volume The volume to be tested for equality.
\return \c true, if the objects are equal, \c false otherwise.
\since BeOS R3
*/
@@ -377,6 +432,8 @@
\param volume The volume to be tested for inequality.
\return \c true, if the objects and unequal, \c false otherwise.
\since BeOS R3
*/
@@ -388,6 +445,8 @@
\param volume The volume to be assigned.
\return A reference to this object.
\since BeOS R3
*/
docs/user/storage/VolumeRoster.dox
+23 -5
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2002-2013 Haiku Inc. All rights reserved.
* Copyright 2002-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -8,8 +8,8 @@
* Ingo Weinhold, [email protected]
*
* Corresponds to:
* headers/os/storage/VolumeRoster.h hrev45306
* src/kits/storage/VolumeRoster.cpp hrev45306
* headers/os/storage/VolumeRoster.h hrev47402
* src/kits/storage/VolumeRoster.cpp hrev47402
*/
@@ -31,12 +31,16 @@
This class wraps the next_dev() function for iterating through the
list of available volumes and watch_node()/stop_watching() for
watching volumes.
\since BeOS R3
*/
/*!
\fn BVolumeRoster::BVolumeRoster()
\brief Creates a BVolumeRoster object. The object is ready to be used.
\since BeOS R3
*/
@@ -45,6 +49,8 @@
\brief Deletes the volume roster and frees all associated resources.
If a watch was activated (by StartWatching()), it is deactivated.
\since BeOS R3
*/
@@ -60,6 +66,8 @@
\return A status code.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE The last volume in the list was already returned.
\since BeOS R3
*/
@@ -68,6 +76,8 @@
\brief Rewinds the list of available volumes back to the first item.
The next call to GetNextVolume() will return the first available volume.
\since BeOS R3
*/
@@ -80,10 +90,12 @@
volume is to rename "/boot" -- but, please refrain from doing this.
\param volume A pointer to a pre-allocated BVolume to be initialized to
refer to the boot volume.
refer to the boot volume.
\return A status code, \c B_OK if everything went fine or an error code
otherwise.
\since BeOS R3
*/
@@ -111,6 +123,8 @@
operation.
\see watch_node()
\since BeOS R3
*/
@@ -119,6 +133,8 @@
\brief Stops watching volumes initiated by StartWatching().
\see stop_watching()
\since BeOS R3
*/
@@ -127,5 +143,7 @@
\brief Returns the messenger currently watching the volume list.
\return A messenger to the target currently watching the volume list, or
an invalid messenger if not watching.
an invalid messenger if not watching.
\since BeOS R3
*/