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
+88 -117
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,12 +46,16 @@
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
*/
@@ -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
*/
@@ -118,6 +128,8 @@
\retval B_BAD_TYPE The attribute/resources the type string is stored in
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).
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
*/
@@ -165,6 +179,8 @@
\retval B_BAD_TYPE The attribute/resources the signature is stored in have
the wrong type.
\retval B_ENTRY_NOT_FOUND No signature is set on the file.
\since BeOS R3
*/
@@ -176,12 +192,14 @@
\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.
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
*/
@@ -212,6 +230,8 @@
\retval B_BAD_TYPE The attribute/resources the entry is stored in have
the wrong type.
\retval B_ENTRY_NOT_FOUND No catalog entry is set on the file.
\since Haiku R1
*/
@@ -223,7 +243,7 @@
\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).
\c B_MIME_TYPE_LENGTH * 3 (including the terminating \0).
The \a catalogEntry may be \c NULL.
\returns a status code.
@@ -231,6 +251,8 @@
\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.
\since Haiku R1
*/
@@ -259,6 +281,8 @@
\retval B_BAD_TYPE The attribute/resources the flags are stored in have
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
*/
@@ -312,15 +340,17 @@
\retval B_BAD_TYPE The attribute/resources that the supported types
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.
@@ -347,6 +377,8 @@
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\since BeOS R3
*/
@@ -379,6 +411,8 @@
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT The object is not properly initialized.
\since BeOS R3
*/
@@ -394,6 +428,8 @@
\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,8 +480,8 @@
/*!
\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
@@ -455,6 +495,8 @@
\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.
\since BeOS R3
*/
@@ -470,6 +512,8 @@
\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
*/
@@ -493,8 +537,11 @@
\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.
\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.
@@ -515,6 +562,8 @@
\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.
\since BeOS R3
*/
@@ -535,6 +584,8 @@
\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
*/
@@ -555,6 +606,8 @@
\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
*/
@@ -577,8 +630,10 @@
\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
*/
@@ -600,6 +655,8 @@
\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.
\since Haiku R1
*/
@@ -630,6 +687,8 @@
\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.
\since Haiku R1
*/
@@ -658,6 +717,8 @@
\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.
\since BeOS R3
*/
@@ -685,6 +746,8 @@
\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
*/
@@ -710,6 +773,8 @@
\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
+80 -14
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,6 +45,8 @@
\brief Creates a copy of the supplied BDirectory object.
\param dir The BDirectory object to be copied.
\since BeOS R3
*/
@@ -50,6 +56,8 @@
to by the supplied entry_ref.
\param ref The entry_ref that refers to the directory.
\since BeOS R3
*/
@@ -59,6 +67,8 @@
to by the supplied node_ref.
\param nref The node_ref that refers to the directory.
\since BeOS R3
*/
@@ -68,6 +78,8 @@
to by the supplied BEntry.
\param entry The BEntry that refers to the directory.
\since BeOS R3
*/
@@ -77,6 +89,8 @@
to by the supplied \a path name.
\param path The \a path name of the directory.
\since BeOS R3
*/
@@ -87,6 +101,8 @@
\param dir The base BDirectory object.
\param path The \a path of the directory relative to \a dir
\since BeOS R3
*/
@@ -96,6 +112,8 @@
If the BDirectory is properly initialized, the directory's file descriptor
is closed.
\since BeOS R3
*/
@@ -116,6 +134,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
*/
@@ -136,6 +156,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
*/
@@ -156,6 +178,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
*/
@@ -178,6 +202,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
*/
@@ -201,6 +227,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
*/
@@ -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
*/
@@ -230,6 +260,8 @@
\returns \c true if the BDirectory is properly initialized and represents
a root directory of a volume, \c false otherwise.
\since BeOS R3
*/
@@ -266,24 +298,28 @@
\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.
@@ -294,8 +330,10 @@
- \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
*/
@@ -319,6 +357,8 @@
\returns \c true if the BDirectory is properly initialized and the
entry of the matching kind was found, \c false otherwise.
\since BeOS R3
*/
@@ -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
*/
@@ -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
*/
@@ -393,11 +437,14 @@
\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.
@@ -413,7 +460,8 @@
\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
*/
@@ -466,6 +518,8 @@
\sa BDirectory::GetNextRef()
\sa BDirectory::GetNextDirents()
\sa BDirectory::Rewind()
\since BeOS R3
*/
@@ -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
*/
@@ -525,6 +581,8 @@
\retval B_IS_A_DIRECTORY A directory with the supplied name already
exists.
\retval B_NO_MORE_FDS The application has run out of file descriptors.
\since BeOS R3
*/
@@ -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
*/
@@ -600,4 +664,6 @@
\retval B_NOT_A_DIRECTORY An entry other than a directory with that name
already exists.
\retval B_NO_MORE_FDS The application has run out of file descriptors.
\since BeOS R3
*/
docs/user/storage/Entry.dox
+94 -101
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,12 +45,16 @@
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
*/
@@ -64,9 +68,11 @@
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,6 +81,8 @@
\brief Returns a copy of the passed in entry_ref object.
\param ref A reference to an entry_ref to copy.
\since BeOS R3
*/
@@ -82,6 +90,8 @@
\fn entry_ref::~entry_ref()
\brief Destroys the object and frees the storage allocated for the leaf
name, if necessary.
\since BeOS R3
*/
@@ -92,6 +102,8 @@
\param name Pointer to a null-terminated string containing the new name for
the entry. May be \c NULL.
\since BeOS R3
*/
@@ -101,6 +113,8 @@
returning \c true if they are equal.
\returns \c true if he entry_refs are equal, \c false otherwise.
\since BeOS R3
*/
@@ -110,6 +124,8 @@
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
*/
@@ -290,6 +332,8 @@ BEntry entry("/boot/home/fido");
\param traverse Whether or not to traverse symbolic links.
\returns \c B_OK on success, or an error code on failure.
\since BeOS R3
*/
@@ -304,6 +348,8 @@ 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
*/
@@ -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
*/
@@ -388,6 +442,8 @@ if (err != B_ENTRY_NOT_FOUND)
\retval B_OK Success
\retval B_ENTRY_NOT_FOUND Attempted to get the parent of the root
directory.
\since BeOS R3
*/
@@ -404,6 +460,8 @@ if (err != B_ENTRY_NOT_FOUND)
\retval B_OK Success
\retval B_ENTRY_NOT_FOUND Attempted to get the parent of the root
directory.
\since BeOS R3
*/
@@ -418,6 +476,8 @@ if (err != B_ENTRY_NOT_FOUND)
is copied.
\returns \c B_OK on success, or an error code on failure.
\since BeOS R3
*/
@@ -430,8 +490,8 @@ if (err != B_ENTRY_NOT_FOUND)
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.
@@ -441,6 +501,8 @@ if (err != B_ENTRY_NOT_FOUND)
\retval B_ENTRY_EXISTS The new location already exists and \c clobber
is \c false.
\retval B_ENTRY_NOT_FOUND Attempted to rename an abstract entry.
\since BeOS R3
*/
@@ -456,17 +518,19 @@ if (err != B_ENTRY_NOT_FOUND)
\param dir A pointer to a pre-allocated BDirectory into which the entry
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.
\retval B_ENTRY_NOT_FOUND Attempted to rename an abstract entry.
\since BeOS R3
*/
@@ -480,6 +544,8 @@ 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
*/
@@ -488,9 +554,12 @@ if (err != B_ENTRY_NOT_FOUND)
\brief Returns \c true if the BEntry and \a item refer to the same entry
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.
\retval false The BEntry objects refer to different entries.
\since BeOS R3
*/
@@ -499,9 +568,12 @@ if (err != B_ENTRY_NOT_FOUND)
\brief Returns false if the BEntry and \c item refer to the same entry or
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.
\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
+19 -3
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
*/
@@ -65,6 +71,8 @@
\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).
\since BeOS R3
*/
@@ -84,6 +92,8 @@
\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).
\since BeOS R3
*/
@@ -110,6 +120,8 @@
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
*/
@@ -120,6 +132,8 @@
\retval B_OK if successful
\retval B_ERROR or another error code (depending on the implementation
of the derived class).
\since BeOS R3
*/
@@ -131,4 +145,6 @@
\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).
\since BeOS R3
*/
docs/user/storage/File.dox
+57 -27
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,6 +61,8 @@
If \a file is uninitialized, the newly constructed BFile will be too.
\param file The BFile object to be copied.
\since BeOS R3
*/
@@ -69,6 +75,8 @@
\param openMode The mode in which the file should be opened.
\see SetTo(const entry_ref* ref, uint32 openMode)
\since BeOS R3
*/
@@ -81,6 +89,8 @@
\param openMode The mode in which the file should be opened.
\see SetTo(const BEntry* entry, uint32 openMode)
\since BeOS R3
*/
@@ -93,6 +103,8 @@
\param openMode The mode in which the file should be opened.
\see SetTo(const char* path, uint32 openMode)
\since BeOS R3
*/
@@ -108,6 +120,8 @@
\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,6 +130,8 @@
\brief Destroys the BFile object and frees all allocated resources.
If the file is properly initialized, the file descriptor is closed.
\since BeOS R3
*/
@@ -131,11 +147,12 @@
- \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_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_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.
@@ -149,6 +166,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
*/
@@ -174,6 +193,8 @@
\todo Implemented using SetTo(entry_ref*, uint32). Check, if necessary
to re-implement!
\since BeOS R3
*/
@@ -196,7 +217,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
*/
@@ -226,6 +248,8 @@
\todo Implemented using SetTo(BEntry*, uint32). Check, if necessary
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,6 +287,8 @@
\param size The number of bytes that shall be read.
\returns The number of bytes read or an error code.
\since BeOS R3
*/
@@ -273,6 +303,8 @@
\param size The number of bytes that shall be read.
\returns The number of bytes read or an error code.
\since BeOS R3
*/
@@ -284,12 +316,14 @@
\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
\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
@@ -298,6 +332,8 @@
\param size The number of bytes that shall be written.
\returns The number of bytes actually written or an error code.
\since BeOS R3
*/
@@ -313,14 +349,16 @@
\param offset New read/write position, depending on \a seekMode relative
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.
\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
*/
@@ -332,6 +370,8 @@
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
*/
@@ -353,6 +393,8 @@
\retval B_NOT_ALLOWED Trying to set the size of a file on a read only
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
+101 -9
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
*/
@@ -84,6 +98,8 @@
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
*/
@@ -194,17 +212,23 @@
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.
\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_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
\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,6 +321,8 @@
\brief Sets the target messenge.
\param message The BMessage object to send on confirm.
\since BeOS R3
*/
@@ -286,6 +330,8 @@
\fn void BFilePanel::Refresh()
\brief Refresh the directory or the panel causing the entries to be re-run
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,6 +386,8 @@
\brief Set some save text to display in the save dialog.
\param text The text to display.
\since BeOS R3
*/
@@ -341,6 +397,8 @@
by \a ref.
\param ref The entry contained by the desired panel directory.
\since BeOS R3
*/
@@ -350,6 +408,8 @@
by \a path.
\param path The path of the desired directory.
\since BeOS R3
*/
@@ -359,6 +419,8 @@
by \a entry.
\param entry The BEntry object pointing to the desired directory.
\since BeOS R3
*/
@@ -368,6 +430,8 @@
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,15 +488,29 @@
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.
WasHidden() is not called if you call Hide() manually.
\since BeOS R3
*/
@@ -434,4 +521,9 @@
\see GetNextSelectedRef()
\see Rewind()
\since BeOS R3
*/
//! @}
docs/user/storage/FindDirectory.dox
+1009 -242
View File
File diff suppressed because it is too large Load Diff
docs/user/storage/Mime.dox
+92 -18
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,29 +42,34 @@
\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
*/
@@ -81,13 +90,15 @@
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.
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
\return A status code, \c B_OK if everything went fine, an error code
otherwise.
\since BeOS R3
*/
@@ -110,8 +121,10 @@
\param force Entries are created even if they do already exist if not
\c NULL.
\returns A status code. \c B_OK if everything went fine, an error code
\return A status code, \c B_OK if everything went fine, an error code
otherwise.
\since BeOS R3
*/
@@ -124,17 +137,21 @@
\param size The size of the icon to retrieve. Currently 16
(\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,
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
@@ -143,27 +160,84 @@
\param which The size of the icon to retrieve. Currently 16
(\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
\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,
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
+186 -102
View File
@@ -1,16 +1,15 @@
/*
* Copyright 2011 Haiku, Inc. All rights reserved.
* Copyright 2011-2014 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Tyler Dauwalder
* Ingo Weinhold, [email protected]
* Axel Dörfler, [email protected]
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/storage/MimeType.h hrev43528
* src/kits/storage/MimeType.cpp hrev43528
* headers/os/storage/MimeType.h hrev47402
* src/kits/storage/MimeType.cpp hrev47402
*/
@@ -26,19 +25,23 @@
\class BMimeType
\ingroup storage
\ingroup libbe
\brief A class that represents a MIME (Multipurpose Internet Mail
\brief A class that represents a MIME (Multi-purpose Internet Mail
Extensions) type string.
MIME types use, has grown beyond describing the content of email
to describe the content types of applications and file formats.
MIME types consist of a super type and a
MIME types consist of a supertype and a subtype.
\since BeOS R3
*/
/*!
\fn BMimeType::BMimeType()
\brief Creates an uninitialized BMimeType object.
\since BeOS R3
*/
@@ -52,12 +55,16 @@
\param mimeType The MIME string.
\sa SetTo() for further information.
\since BeOS R3
*/
/*!
\fn BMimeType::~BMimeType()
\brief Frees all resources associated with this object.
\since BeOS R3
*/
@@ -85,15 +92,19 @@
\returns A status code.
\retval B_OK Everything went fine.
\retval B_NO_INIT \c NULL \a mimeType string.
\retval B_BAD_VALUE Invalid \a mimeType string.
\retval B_NO_INIT BMimeType was uninitialized.
\retval B_NO_MEMORY Insufficient memory to copy the MIME string.
\since BeOS R3
*/
/*!
\fn void BMimeType::Unset()
\brief Returns the object to an uninitialized state.
\since BeOS R3
*/
@@ -103,6 +114,8 @@
\returns \c B_OK If the object is properly initialized, a specific
error code otherwise.
\since BeOS R3
*/
@@ -112,6 +125,8 @@
\return The MIME string, if the object is properly initialized, \c NULL
otherwise.
\since BeOS R3
*/
@@ -123,6 +138,8 @@
otherwise.
\sa SetTo() for further information.
\since BeOS R3
*/
@@ -132,6 +149,8 @@
\return \c true, if the object is properly initialized and represents a
supertype, \c false otherwise.
\since BeOS R3
*/
@@ -143,27 +162,32 @@
To add the MIME type to the database, call \c Install().
To remove the MIME type from the database, call \c Delete().
\returns A \c bool indicating whether or not this type is currently
\return A \c bool indicating whether or not this type is currently
installed in the MIME database.
\retval true The MIME type is currently installed in the database.
\retval false The MIME type is not currently installed in the database.
\since BeOS R3
*/
/*!
\fn status_t BMimeType::GetSupertype(BMimeType *superType) const
\brief Gets the supertype of the MIME type represented by this object.
\fn status_t BMimeType::GetSupertype(BMimeType* supertype) const
\brief Gets the \a supertype of the MIME type represented by this object.
The supplied object is initialized to this object's supertype. If this
The supplied object is initialized to this object's \a supertype. If this
BMimeType is not properly initialized, the supplied object will be Unset().
\param superType A pointer to the BMimeType object that shall be
initialized to this object's supertype.
\param supertype A pointer to the BMimeType object that shall be
initialized to this object's \a supertype.
\returns A status code.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \c NULL \a superType, this object is not initialized,
or this object is a supertype only.
\retval B_NO_INIT BMimeType was uninitialized.
\since BeOS R3
*/
@@ -180,6 +204,8 @@
\param type The BMimeType to be compared with.
\return \c true, if the objects are equal, \c false otherwise.
\since BeOS R3
*/
@@ -197,6 +223,8 @@
\param type The MIME string to be compared with.
\return \c true, if the MIME types are equal, \c false otherwise.
\since BeOS R4
*/
@@ -209,6 +237,8 @@
\returns \c true, if this MIME type is a supertype of or equals the
supplied one, \c false otherwise.
\since BeOS R3
*/
@@ -223,6 +253,10 @@
installed, so be sure to check \c IsInstalled() first.
\returns \c B_OK on success or another error code on failure.
\see Delete()
\since BeOS R3
*/
@@ -234,10 +268,12 @@
To add the MIME type to the database, call \c Install().
\note Calling \c BMimeType::Delete() does not uninitialize or otherwise
deallocate the \c BMimeType object; it simply removes the type from the
database.
deallocate the \c BMimeType object; it simply removes the type from
the database.
\returns \c B_OK on success or another error code on failure.
\since BeOS R3
*/
@@ -257,8 +293,11 @@
\returns A status code.
\retval B_OK Everything went fine.
\retval B_ENTRY_NOT_FOUND: No icon of the given size exists for the
\retval B_ENTRY_NOT_FOUND No icon of the given size exists for the
given type.
\retval B_NO_INIT BMimeType was uninitialized.
\since BeOS R3
*/
@@ -274,8 +313,11 @@
\returns A status code.
\retval B_OK Everything went fine.
\retval B_ENTRY_NOT_FOUND No icon of the given size exists for the given
type
\retval B_ENTRY_NOT_FOUND No icon of the given size found for the given
type.
\retval B_NO_INIT BMimeType was uninitialized.
\since BeOS R3
*/
@@ -301,10 +343,16 @@
\param verb \c app_verb value that specifies the type of access for
which you are requesting the preferred app. Currently, the only
supported app verb is \c B_OPEN.
\returns A status code.
\retval B_OK Success
\retval B_ENTRY_NOT_FOUND No preferred app exists for the given type
and app_verb.
\retval B_NO_INIT BMimeType was uninitialized.
\see SetPreferredApp()
\since BeOS R3
*/
@@ -360,6 +408,10 @@
the MIME type's associated file attributes is stored.
\returns \c B_OK on success or another error code on failure.
\see SetAttrInfo()
\since BeOS R3
*/
@@ -393,6 +445,10 @@
MIME type's associated file extensions will be stored.
\returns \c B_OK on success or another error code on failure.
\see SetFileExtensions()
\since BeOS R3
*/
@@ -410,7 +466,12 @@
\returns A status code.
\retval B_OK Success
\retval B_ENTRY_NOT_FOUND No short description exists for the given type
\retval B_ENTRY_NOT_FOUND No short description exists for the given type.
\retval B_NO_INIT BMimeType was uninitialized.
\see SetShortDescription()
\since BeOS R3
*/
@@ -429,6 +490,11 @@
\returns A status code.
\retval B_OK Success
\retval B_ENTRY_NOT_FOUND No long description exists for the given type.
\retval B_NO_INIT BMimeType was uninitialized.
\see SetLongDescription()
\since BeOS R3
*/
@@ -486,7 +552,11 @@
\param signatures Pointer to a pre-allocated BMessage into which the
signatures of the supporting applications will be copied.
\returns \c B_OK on success or another error code on failure.
\returns \c B_OK on success or an error code on failure.
\see SetSupportingApps()
\since BeOS R3
*/
@@ -508,6 +578,8 @@
\c B_LARGE_ICON and \c B_MINI_ICON are supported.
\returns \c B_OK on success or another error code on failure.
\since BeOS R3
*/
@@ -525,6 +597,8 @@
\param size Size of the provided buffer.
\returns \c B_OK on success or another error code on failure.
\since Haiku R1
*/
@@ -552,6 +626,8 @@
supported app verb is \c B_OPEN.
\returns \c B_OK on success or another error code on failure.*/
\since BeOS R3
*/
@@ -601,10 +677,12 @@
The \c BMessage::what value is ignored.
\param info Pointer to a pre-allocated and properly formatted BMessage
containing information about the file attributes typically associated
with the MIME type.
containing information about the file attributes typically
associated with the MIME type.
\returns \c B_OK on success or another error code on failure.
\since BeOS R3
*/
@@ -625,12 +703,12 @@
not \c ".html" or \c ".mp3" ).
- The \c what member of the BMessage is ignored.
\note any other fields present in the \c BMessage will currently be retained
and returned by calls to \c GetFileExtensions(); however, this may change in
the future, so it is recommended that you not rely on this behaviour, and
that no other fields be present. Also, note that no checking is performed to
verify the \c BMessage is properly formatted; it's up to you to do things
right.
\note Any other fields present in the \c BMessage will currently be
retained and returned by calls to \c GetFileExtensions(); however,
this may change in the future, so it is recommended that you not rely
on this behavior, and that no other fields be present. Also, note that
no checking is performed to verify the \c BMessage is properly
formatted; it's up to you to do things right.
Finally, bear in mind that \c SetFileExtensions() clobbers the existing set
of extensions. If you want to augment a type's extensions, you should
@@ -638,10 +716,12 @@
\c SetFileExtensions().
\param extensions Pointer to a pre-allocated, properly formatted BMessage
containing the new list of file extensions to associate with this MIME
type.
containing the new list of file extensions to associate with this
MIME type.
\returns \c B_OK on success or another error code on failure.
\since BeOS R3
*/
@@ -659,6 +739,8 @@
new short description.
\returns \c B_OK on success or another error code on failure.
\since BeOS R3
*/
@@ -676,21 +758,25 @@
long description
\returns \c B_OK on success or another error code on failure.
\since BeOS R3
*/
/*!
\fn status_t BMimeType::GetInstalledSupertypes(BMessage* supertypes)
\brief Fetches a BMessage listing all the MIME supertypes currently
\brief Fetches a BMessage listing all the MIME \a supertypes currently
installed in the MIME database.
The types are copied into the \c "super_types" field of the passed-in
\c BMessage. The \c BMessage must be pre-allocated.
\param supertypes Pointer to a pre-allocated \c BMessage into which the
MIME supertypes will be copied.
MIME \a supertypes will be copied.
\returns \c B_OK on success or another error code on failure.
\since BeOS R3
*/
@@ -706,6 +792,8 @@
MIME types will be copied.
\returns \c B_OK on success or another error code on failure.
\since BeOS R3
*/
@@ -713,17 +801,19 @@
\fn status_t BMimeType::GetInstalledTypes(const char* supertype,
BMessage* types)
\brief Fetches a BMessage listing all the MIME subtypes of the given
supertype currently installed in the MIME database.
\a supertype currently installed in the MIME database.
The types are copied into the \c "types" field of the passed-in \c BMessage.
The \c BMessage must be pre-allocated.
The types are copied into the \c "types" field of the passed-in
\c BMessage. The \c BMessage must be pre-allocated.
\param supertype Pointer to a string containing the MIME supertype whose
\param supertype Pointer to a string containing the MIME \a supertype whose
subtypes you wish to retrieve.
\param types Pointer to a pre-allocated \c BMessage into which the
appropriate MIME subtypes will be copied.
\returns \c B_OK on success or another error code on failure.
\since BeOS R3
*/
@@ -744,6 +834,8 @@
\sa GetSupportingApps() for details on the format of the data returned in
the \c BMessage pointed to by \c wild_ones.
\since BeOS R3
*/
@@ -756,8 +848,9 @@
\return \c true, if the given string represents a valid MIME type.
\sa SetTo() for further information.
*/
\since BeOS R3
*/
/*!
@@ -779,10 +872,12 @@
of the app hint is copied. If the function fails, the contents of
the \c entry_ref are undefined.
\return
- \c B_OK: Success
- \c B_ENTRY_NOT_FOUND: No app hint exists for the given type
- other error code: Failure
\return A status code, B_OK on success or an error code otherwise.
\retval B_OK The ref was retrieved successfully.
\retval B_ENTRY_NOT_FOUND No app hint existed for the given \a ref.
\retval B_NO_INIT BMimeType was uninitialized.
\since BeOS R3
*/
@@ -808,6 +903,12 @@
of the new app hint
\returns \c B_OK on success or another error code on failure.
\retval B_OK The ref was retrieved successfully.
\retval B_NO_INIT BMimeType was uninitialized.
\retval B_BAD_VALUE \a ref was \c NULL.
\retval B_NO_INIT BMimeType was uninitialized.
\since BeOS R3
*/
@@ -841,10 +942,13 @@
\param which Value that specifies which icon to return. Currently
\c B_LARGE_ICON and \c B_MINI_ICON are supported.
\returns A status code.
\returns A status code, \c B_OK on success or an error code otherwise.
\retval B_OK Success
\retval B_ENTRY_NOT_FOUND No icon of the given size exists for the
given type
given type.
\retval B_NO_INIT BMimeType was uninitialized.
\since BeOS R3
*/
@@ -862,12 +966,15 @@
\param _data Pointer in which the allocated icon data is returned. You need
to delete the buffer when you are done with it.
\param _size Pointer in which the size of the allocated icon data is
returned.
filled out.
\returns A status code.
\retval B_OK Success
\returns A status code, \c B_OK on success or an error code otherwise.
\retval B_OK Success.
\retval B_ENTRY_NOT_FOUND No icon of the given size exists for the
given type.
\retval B_NO_INIT BMimeType was uninitialized.
\since Haiku R1
*/
@@ -897,12 +1004,14 @@
\param type Pointer to a pre-allocated string containing the MIME type whose
custom icon you wish to set.
\param icon Pointer to a pre-allocated \c BBitmap of proper size and
colorspace containing the new icon, or \c NULL to clear the
current icon.
colorspace containing the new icon, or \c NULL to clear the current
icon.
\param which Value that specifies which icon to update. Currently
\c B_LARGE_ICON and \c B_MINI_ICON are supported.
\returns \c B_OK on success or another error code on failure.
\since BeOS R3
*/
@@ -939,6 +1048,8 @@
\c B_LARGE_ICON and \c B_MINI_ICON are supported.
\returns \c B_OK on success or another error code on failure.
\since Haiku R1
*/
@@ -953,6 +1064,11 @@
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \c NULL \a result or uninitialized BMimeType.
\retval B_ENTRY_NOT_FOUND The MIME type is not installed.
\retval B_NO_INIT BMimeType was uninitialized.
\see SetSnifferRule()
\since Haiku R1
*/
@@ -972,8 +1088,11 @@
\retval B_OK Everything went fine.
\retval B_BAD_VALUE Uninitialized BMimeType.
\retval B_BAD_MIME_SNIFFER_RULE The supplied sniffer rule is invalid.
\retval B_NO_INIT BMimeType was uninitialized.
\sa CheckSnifferRule().
\sa CheckSnifferRule()
\since Haiku R1
*/
@@ -1063,6 +1182,9 @@
\retval B_BAD_VALUE \c NULL \a rule.
\retval B_BAD_MIME_SNIFFER_RULE The supplied sniffer rule is not valid. A
description of the error is written to \a parseError, if supplied.
\retval B_NO_INIT BMimeType was uninitialized.
\since Haiku R1
*/
@@ -1085,6 +1207,9 @@
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \c NULL \a ref or \a result.
\retval B_NAME_NOT_FOUND \a ref refers to an abstract entry.
\retval B_NO_INIT BMimeType was uninitialized.
\since Haiku R1
*/
@@ -1101,6 +1226,9 @@
\returns A status code.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \c NULL \a buffer or \a result.
\retval B_NO_INIT BMimeType was uninitialized.
\since Haiku R1
*/
@@ -1119,6 +1247,9 @@
\returns A status code.
\retval B_OK Everything went fine.
\retval B_BAD_VALUE \c NULL \a ref or \a result.
\retval B_NO_INIT BMimeType was uninitialized.
\since Haiku R1
*/
@@ -1132,6 +1263,8 @@
\param target A BMessenger identifying the target for the update messages.
\returns \c B_OK on success or another error code on failure.
\since BeOS R4
*/
@@ -1143,6 +1276,8 @@
\param target A BMessenger identifying the target for the update messages.
\returns \c B_OK on success or another error code on failure.
\since BeOS R4
*/
@@ -1152,57 +1287,6 @@
\deprecated This method has the same semantics as SetTo().
Use SetTo() instead.
\since BeOS R3
*/
/*!
\fn status_t BMimeType::SetSupportedTypes(const BMessage *types,
bool fullSync)
\brief Sets the list of MIME types supported by the MIME type (which is
assumed to be an application signature).
If \a types is \c NULL the application's supported types are unset.
The supported MIME types must be stored in a field "types" of type
\c B_STRING_TYPE in \a types.
For each supported type the result of BMimeType::GetSupportingApps() will
afterwards include the signature of this application.
\a fullSync specifies whether or not any types that are no longer
listed as supported types as of this call to SetSupportedTypes() shall be
updated as well, i.e. whether this application shall be removed from their
lists of supporting applications.
If \a fullSync is \c false, this application will not be removed from the
previously supported types' supporting apps lists until the next call
to BMimeType::SetSupportedTypes() or BMimeType::DeleteSupportedTypes()
with a \c true \a fullSync parameter, the next call to BMimeType::Delete(),
or the next reboot.
\param types The supported types to be assigned to the file.
May be \c NULL.
\param fullSync \c true to also synchronize the previously supported
types, \c false otherwise.
\returns \c B_OK on success or another error code on failure.
*/
/*!
\fn status_t BMimeType::GetAssociatedTypes(const char *extension,
BMessage *types)
\brief Returns a list of mime types associated with the given file extension
The list of types is returned in the pre-allocated \c BMessage pointed to
by \a types. The types are stored in the message's "types" field, which
is an array of \c B_STRING_TYPE values.
\param extension The file extension of interest
\param types Pointer to a pre-allocated BMessage into which the result will
be stored
\returns \c B_OK on success or another error code on failure.
*/
docs/user/storage/Node.dox
+263 -265
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,34 +134,18 @@
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
*/
@@ -119,7 +154,9 @@
\brief Creates a BNode object and initializes it to the specified
entry_ref.
\param ref the entry_ref referring to the entry.
\param ref The entry_ref referring to the node.
\since BeOS R3
*/
@@ -128,7 +165,9 @@
\brief Creates a BNode object and initializes it to the specified
filesystem entry.
\param entry the BEntry representing the entry.
\param entry The BEntry referring to the node.
\since BeOS R3
*/
@@ -137,7 +176,9 @@
\brief Creates a BNode object and initializes it to the entry referred
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
*/
@@ -146,44 +187,43 @@
\brief Creates a BNode object and initializes it to the entry referred
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.
\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,12 +249,13 @@
/*!
\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
*/
@@ -220,12 +263,15 @@
\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
*/
@@ -233,12 +279,33 @@
\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_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 char* path)
\brief Initializes the object to the specified \a path.
\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 \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
*/
@@ -247,19 +314,24 @@
\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 entry's path name relative to \a dir
\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 \c NULL \a entry.
\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 is locked.
\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
*/
@@ -279,9 +351,12 @@
\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.
\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
*/
@@ -317,48 +398,54 @@
/*!
\fn ssize_t BNode::WriteAttr(const char* attr, type_code type,
off_t offset, const void *buffer, size_t len)
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
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
*/
@@ -366,32 +453,38 @@
\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
*/
@@ -401,13 +494,16 @@
\brief Fills in the pre-allocated attr_info struct pointed to by \a info
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
*/
@@ -418,18 +514,21 @@
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.
\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
*/
@@ -438,8 +537,11 @@
\brief Resets the object's attribute pointer to the first attribute in the
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
*/
@@ -451,13 +553,18 @@
\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
*/
@@ -469,10 +576,13 @@
\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
+53 -25
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
*/
@@ -40,6 +42,8 @@
After created a BNodeInfo with this, you should call SetTo().
\see SetTo(BNode* node)
\since BeOS R3
*/
@@ -48,7 +52,9 @@
\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
*/
@@ -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
*/
@@ -125,6 +137,8 @@
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
*/
@@ -136,7 +150,7 @@
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,7 +177,7 @@
/*!
\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
@@ -170,7 +186,7 @@
\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
\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.
@@ -178,11 +194,13 @@
\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.
\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.
@@ -192,7 +210,7 @@
\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
\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.
@@ -200,6 +218,8 @@
\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.
\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
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
@@ -278,42 +302,46 @@
\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
\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)
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
*/
@@ -379,7 +407,7 @@
/*!
\name Application hint methods
\name Application Hint
*/
docs/user/storage/NodeMonitor.dox
+124 -52
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,6 +331,8 @@
\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
*/
@@ -303,6 +365,8 @@
\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
*/
@@ -341,6 +405,8 @@
\param target BMessenger object referring to the \a target.
\return \c B_OK if everything went fine, an error code otherwise.
\since BeOS R3
*/
@@ -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,6 +471,8 @@
\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
*/
@@ -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
+139 -91
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
*/
@@ -54,22 +57,24 @@
\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.
\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).
\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,8 +85,10 @@
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
*/
@@ -96,32 +103,37 @@
\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.
\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
*/
@@ -132,11 +144,12 @@
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
@@ -148,24 +161,27 @@
\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.
\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).
\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
@@ -179,8 +195,10 @@
\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.
\return \c B_OK Everything if went fine or an error code otherwise.
\since Haiku R1
*/
@@ -195,10 +213,14 @@
\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.
\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_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
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
doesn't exist.
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_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
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
doesn't exist.
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
+74 -6
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
@@ -285,6 +311,8 @@
\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.
\since BeOS R4
*/
@@ -305,6 +333,8 @@
\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.
\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.
@@ -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
*/
@@ -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
*/
@@ -662,6 +726,8 @@
\return A pointer to the resource data if everything went fine or \c NULL
if an error occurred.
\since BeOS R3
*/
@@ -683,6 +749,8 @@
\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
+57 -11
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,6 +97,8 @@
\return \c true, if the node is properly initialized and is a symlink,
\c false otherwise.
\since BeOS R5
*/
@@ -99,6 +109,8 @@
\param ref the node_ref to be set.
\see GetStat() for return codes.
\since BeOS R3
*/
@@ -108,7 +120,10 @@
\param owner A pointer to a \c uid_t to be set.
\see SetOwner()
\see GetStat() for return codes.
\since BeOS R3
*/
@@ -119,6 +134,8 @@
\param owner The UID to set the node to.
\see GetStat() for return codes.
\since BeOS R3
*/
@@ -128,7 +145,10 @@
\param group a pointer to a \c gid_t variable to be set.
\see SetGroup()
\see GetStat() for return codes.
\since BeOS R3
*/
@@ -139,26 +159,33 @@
\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
*/
@@ -170,6 +197,8 @@
\param size A pointer to a \c off_t variable to be set.
\see GetStat() for return codes.
\since BeOS R3
*/
@@ -179,7 +208,10 @@
\param mtime A pointer to a \c time_t variable to be set.
\see SetModificationTime()
\see GetStat() for return codes.
\since BeOS R3
*/
@@ -190,6 +222,8 @@
\param mtime The modification time to set the node to.
\see GetStat() for return codes.
\since BeOS R3
*/
@@ -199,7 +233,10 @@
\param ctime A pointer to a \c time_t variable to be set.
\see SetCreationTime()
\see GetStat() for return codes.
\since BeOS R3
*/
@@ -210,6 +247,8 @@
\param ctime The creation time to set the node to.
\see GetStat() for return codes.
\since BeOS R3
*/
@@ -218,7 +257,10 @@
\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
+29 -16
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,20 +27,26 @@
\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
*/
@@ -50,6 +56,8 @@
referred to by the supplied entry_ref.
\param ref the entry_ref referring to the symbolic link.
\since BeOS R3
*/
@@ -59,6 +67,8 @@
referred to by the supplied BEntry.
\param entry The BEntry referring to the symbolic link.
\since BeOS R3
*/
@@ -68,6 +78,8 @@
referred to by the supplied path name.
\param path The path of the symbolic link.
\since BeOS R3
*/
@@ -79,6 +91,8 @@
\param dir The base BDirectory.
\param path The path of the symbolic link relative to \a dir.
\since BeOS R3
*/
@@ -88,6 +102,8 @@
If the BSymLink was properly initialized, the file descriptor of the
symbolic link is also closed.
\since BeOS R3
*/
@@ -104,6 +120,8 @@
\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
*/
@@ -120,6 +138,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
*/
@@ -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
+68 -9
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,6 +57,8 @@
successful.
\param device The device ID of the volume.
\since BeOS R3
*/
@@ -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
*/
@@ -127,6 +144,8 @@
\return Returns the device ID of the volume the object refers to
or -1 if the object was not properly initialized.
\since BeOS R3
*/
@@ -142,6 +161,8 @@
\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
*/
@@ -244,6 +279,8 @@
\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
+21 -3
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
*/
@@ -84,6 +94,8 @@
\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
*/
@@ -128,4 +144,6 @@
\return A messenger to the target currently watching the volume list, or
an invalid messenger if not watching.
\since BeOS R3
*/