Documentation updates for Storage Kit classes
* Added \since to each method and parameter. * Whitespace cleanup. * Some other minor cleanups and updates.
This commit is contained in:
John Scipione
+293
-295
@@ -1,15 +1,14 @@
|
||||
/*
|
||||
* Copyright 2002-2011 Haiku Inc. All rights reserved.
|
||||
* Copyright 2002-2014 Haiku, Inc. All rights reserved.
|
||||
* Distributed under the terms of the MIT License.
|
||||
*
|
||||
* Authors:
|
||||
* Tyler Dauwalder, [email protected]
|
||||
* John Scipione, [email protected]
|
||||
* Ingo Weinhold, [email protected]
|
||||
*
|
||||
* Corresponds to:
|
||||
* headers/os/storage/Node.h rev 42803
|
||||
* src/kits/storage/Node.cpp rev 42803
|
||||
* headers/os/storage/Node.h hrev47402
|
||||
* src/kits/storage/Node.cpp hrev47402
|
||||
*/
|
||||
|
||||
|
||||
@@ -17,7 +16,7 @@
|
||||
\file Node.h
|
||||
\ingroup storage
|
||||
\ingroup libbe
|
||||
\brief Provides the BNode class and node_ref structure.
|
||||
\brief Provides the BNode class and node_ref struct.
|
||||
*/
|
||||
|
||||
|
||||
@@ -26,50 +25,102 @@
|
||||
\ingroup storage
|
||||
\ingroup libbe
|
||||
\brief Reference structure to a particular vnode on a device.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn node_ref::node_ref()
|
||||
\brief Creates an uninitialized node_ref object.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn node_ref::node_ref(const node_ref &ref)
|
||||
\fn node_ref::node_ref(const node_ref& other)
|
||||
\brief Creates a copy of the given node_ref object.
|
||||
|
||||
\param ref the node_ref to be copied.
|
||||
\param other the node_ref to be copied.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn bool node_ref::operator==(const node_ref &ref) const
|
||||
\name Operators
|
||||
*/
|
||||
|
||||
|
||||
//! @{
|
||||
|
||||
|
||||
/*!
|
||||
\fn bool node_ref::operator==(const node_ref& other) const
|
||||
\brief Tests whether this node_ref and the supplied one are equal.
|
||||
|
||||
\param ref the node_ref to be compared with.
|
||||
\param other The node_ref to be compared against.
|
||||
|
||||
\return \c true, if the objects are equal, \c false otherwise.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn bool node_ref::operator!=(const node_ref &ref) const
|
||||
\brief Tests whether this node_ref and the supplied one are not equal.
|
||||
\fn bool node_ref::operator!=(const node_ref& other) const
|
||||
\brief Tests whether this node_ref and the supplied one are NOT equal.
|
||||
|
||||
\param ref the node_ref to be compared with.
|
||||
\param other The node_ref to be compared against.
|
||||
|
||||
\return \c true, if the objects are \b not equal, \c false otherwise.
|
||||
\return \c true, if the objects are \b NOT equal, \c false otherwise.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn node_ref& node_ref::operator=(const node_ref &ref)
|
||||
\fn bool node_ref::operator<(const node_ref& other) const
|
||||
\brief Tests whether this node_ref is less than the supplied one.
|
||||
|
||||
\param other The node_ref to be compared against.
|
||||
|
||||
\return \c true, if this node_ref is less than \a other,
|
||||
\c false otherwise.
|
||||
|
||||
\since Haiku R1
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn node_ref& node_ref::operator=(const node_ref& other)
|
||||
\brief Makes this node ref a copy of the supplied one.
|
||||
|
||||
\param ref the node_ref to be copied.
|
||||
\param other The node_ref to be copied.
|
||||
|
||||
\return a reference to this object.
|
||||
\return A reference to this object.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
//! @}
|
||||
|
||||
|
||||
/*!
|
||||
\var node_ref::device
|
||||
\brief The device number on which the node is located.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var node_ref::node
|
||||
\brief The node's inode number.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -83,107 +134,96 @@
|
||||
attributes belonging to filesystem entries. The BNode is unaware of the
|
||||
name that refers to it in the filesystem (i.e. its entry), instead, a
|
||||
BNode is concerned solely with the entry's data and attributes.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var BNode::fFd
|
||||
|
||||
File descriptor for the given node.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var BNode::fAttrFd
|
||||
|
||||
File descriptor for the attribute directory of the node.
|
||||
Initialized lazily.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var BNode::fCStatus
|
||||
|
||||
The object's initialization status.
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BNode::BNode()
|
||||
\brief Creates an uninitialized BNode object.
|
||||
|
||||
\see SetTo()
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BNode::BNode(const entry_ref *ref)
|
||||
\fn BNode::BNode(const entry_ref* ref)
|
||||
\brief Creates a BNode object and initializes it to the specified
|
||||
entry_ref.
|
||||
entry_ref.
|
||||
|
||||
\param ref the entry_ref referring to the entry.
|
||||
\param ref The entry_ref referring to the node.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BNode::BNode(const BEntry *entry)
|
||||
\fn BNode::BNode(const BEntry* entry)
|
||||
\brief Creates a BNode object and initializes it to the specified
|
||||
filesystem entry.
|
||||
filesystem entry.
|
||||
|
||||
\param entry the BEntry representing the entry.
|
||||
\param entry The BEntry referring to the node.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BNode::BNode(const char *path)
|
||||
\fn BNode::BNode(const char* path)
|
||||
\brief Creates a BNode object and initializes it to the entry referred
|
||||
to by the specified path.
|
||||
to by the specified path.
|
||||
|
||||
\param path the path referring to the entry.
|
||||
\param path The \a path referring to the node.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BNode::BNode(const BDirectory *dir, const char *path)
|
||||
\fn BNode::BNode(const BDirectory* dir, const char* path)
|
||||
\brief Creates a BNode object and initializes it to the entry referred
|
||||
to by the specified path rooted in the specified directory.
|
||||
to by the specified path rooted in the specified directory.
|
||||
|
||||
\param dir the BDirectory, relative to which the entry's path name is
|
||||
given.
|
||||
\param path the entry's path name relative to \a dir.
|
||||
\param dir The base BDirectory.
|
||||
\param path The \a path name relative to \a dir.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BNode::BNode(const BNode &node)
|
||||
\fn BNode::BNode(const BNode& other)
|
||||
\brief Creates a copy of the given BNode.
|
||||
|
||||
\param node the BNode to be copied.
|
||||
\param other The BNode to be copied.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BNode::~BNode()
|
||||
\brief Frees all resources associated with the BNode.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNode::InitCheck() const
|
||||
\brief Checks whether the object has been properly initialized or not.
|
||||
|
||||
\returns B_OK if the object has been properly initialized, or an error
|
||||
code otherwise.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNode::GetStat(struct stat *st) const
|
||||
\fn status_t BNode::GetStat(struct stat* stat) const
|
||||
\brief Fills in the given stat structure with the <tt>stat()</tt>
|
||||
information for this object.
|
||||
information for this object.
|
||||
|
||||
\param st a pointer to a stat structure to be filled in.
|
||||
\param stat A pointer to a stat structure to be filled in.
|
||||
|
||||
\return \c B_OK on success or an error code otherwise.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_BAD_VALUE: \c NULL \a st.
|
||||
\retval B_BAD_VALUE: \c NULL \a stat.
|
||||
|
||||
\since Haiku R1
|
||||
*/
|
||||
|
||||
|
||||
@@ -194,12 +234,14 @@
|
||||
Remember to call close() on the file descriptor when you're through
|
||||
with it.
|
||||
|
||||
\returns a valid file descriptor, or -1 if something went wrong.
|
||||
\returns A valid file descriptor, or -1 if something went wrong.
|
||||
|
||||
\since Haiku R1
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\name Assignment Methods
|
||||
\name Constructor Helpers
|
||||
*/
|
||||
|
||||
|
||||
@@ -207,59 +249,89 @@
|
||||
|
||||
|
||||
/*!
|
||||
\fn BNode& BNode::operator=(const BNode &node)
|
||||
\brief Initializes the object as a copy of the \a node.
|
||||
\fn status_t BNode::InitCheck() const
|
||||
\brief Checks whether the object has been properly initialized or not.
|
||||
|
||||
\param node the BNode to be copied.
|
||||
\returns \c B_OK if the object has been properly initialized, or
|
||||
\c B_NO_INIT otherwise.
|
||||
|
||||
\returns a reference to this BNode object.
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNode::SetTo(const entry_ref *ref)
|
||||
\fn status_t BNode::SetTo(const entry_ref* ref)
|
||||
\brief Initializes the object to the specified entry_ref.
|
||||
|
||||
\param ref the entry_ref referring to the entry.
|
||||
\param ref The entry_ref referring to the entry.
|
||||
|
||||
\return \c B_OK on success or an error code otherwise.
|
||||
\retval B_OK: Everything went fine.
|
||||
\retval B_BAD_VALUE: \c NULL \a ref.
|
||||
\retval B_BAD_VALUE: \a ref was \c NULL.
|
||||
\retval B_ENTRY_NOT_FOUND: The entry could not be found.
|
||||
\retval B_BUSY: The entry is locked.
|
||||
\retval B_BUSY: The entry was locked.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNode::SetTo(const BEntry *entry)
|
||||
\fn status_t BNode::SetTo(const BEntry* entry)
|
||||
\brief Initializes the object to the specified filesystem \a entry.
|
||||
|
||||
\param entry the BEntry representing the entry.
|
||||
\param entry The BEntry representing the entry.
|
||||
|
||||
\return \c B_OK on success or an error code otherwise.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_BAD_VALUE \c NULL \a entry.
|
||||
\retval B_ENTRY_NOT_FOUND The entry could not be found.
|
||||
\retval B_BUSY The entry is locked.
|
||||
\retval B_BAD_VALUE \a entry was \c NULL.
|
||||
\retval B_ENTRY_NOT_FOUND The \a entry could not be found.
|
||||
\retval B_BUSY The \a entry was locked.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNode::SetTo(const BDirectory *dir, const char *path)
|
||||
\brief Initializes the object to the entry referred by the
|
||||
specified \a path relative to the the specified directory.
|
||||
\fn status_t BNode::SetTo(const char* path)
|
||||
\brief Initializes the object to the specified \a path.
|
||||
|
||||
\param dir the base BDirectory.
|
||||
\param path the entry's path name relative to \a dir
|
||||
\param path The entry's path name; \a path can be relative or absolute,
|
||||
and can contain "." and ".." elements. If path is relative, it uses
|
||||
the current working directory as the base directory.
|
||||
|
||||
\return \c B_OK on success or an error code otherwise.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_BAD_VALUE \c NULL \a entry.
|
||||
\retval B_BAD_VALUE \a path was \c NULL.
|
||||
\retval B_ENTRY_NOT_FOUND The entry could not be found.
|
||||
\retval B_BUSY The entry is locked.
|
||||
\retval B_BUSY The entry of was locked.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNode::SetTo(const BDirectory* dir, const char* path)
|
||||
\brief Initializes the object to the entry referred by the
|
||||
specified \a path relative to the the specified directory.
|
||||
|
||||
\param dir The base BDirectory.
|
||||
\param path The path name relative to \a dir.
|
||||
|
||||
\return \c B_OK on success or an error code otherwise.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_BAD_VALUE \a dir was \c NULL.
|
||||
\retval B_ENTRY_NOT_FOUND The entry could not be found.
|
||||
\retval B_BUSY The entry was locked.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn void BNode::Unset()
|
||||
\brief Returns the object to an uninitialized state.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -277,11 +349,14 @@
|
||||
/*!
|
||||
\fn status_t BNode::Lock()
|
||||
\brief Attains an exclusive lock on the data referred to by this node
|
||||
so that it may not be modified by any other objects or methods.
|
||||
so that it may not be modified by any other objects or methods.
|
||||
|
||||
\return \c B_OK on success or an error code otherwise.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_FILE_ERROR The object is not initialized.
|
||||
\retval B_BUSY The node is already locked.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -289,9 +364,12 @@
|
||||
\fn status_t BNode::Unlock()
|
||||
\brief Unlocks the date referred to by this node.
|
||||
|
||||
\return \c B_OK on success or an error code otherwise.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_FILE_ERROR The object is not initialized.
|
||||
\retval B_BAD_VALUE The node is not locked.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -299,8 +377,11 @@
|
||||
\fn status_t BNode::Sync()
|
||||
\brief Immediately performs any pending disk actions on the node.
|
||||
|
||||
\return \c B_OK on success or an error code otherwise.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_FILE_ERROR Something went wrong.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -316,163 +397,192 @@
|
||||
|
||||
|
||||
/*!
|
||||
\fn ssize_t BNode::WriteAttr(const char *attr, type_code type,
|
||||
off_t offset, const void *buffer, size_t len)
|
||||
\fn ssize_t BNode::WriteAttr(const char* attr, type_code type,
|
||||
off_t offset, const void* buffer, size_t length)
|
||||
\brief Writes data from a buffer to an attribute.
|
||||
|
||||
Write \a len bytes of data from \a buffer to the attribute specified
|
||||
Write \a length bytes of data from \a buffer to the attribute specified
|
||||
by \a name after erasing any data that existed previously. The type
|
||||
specified by \a type \em is remembered, and may be queried with
|
||||
GetAttrInfo(). The value of \a offset is currently ignored.
|
||||
|
||||
\param attr the name of the attribute.
|
||||
\param type the type of the attribute.
|
||||
\param offset the index at which to write the data (currently ignored).
|
||||
\param buffer the buffer containing the data to be written.
|
||||
\param len the number of bytes to be written.
|
||||
\param attr The name of the attribute.
|
||||
\param type The type of the attribute.
|
||||
\param offset The index at which to write the data (currently ignored).
|
||||
\param buffer The buffer containing the data to be written.
|
||||
\param length The number of bytes to be written.
|
||||
|
||||
\returns the number of bytes actually written.
|
||||
\retval B_BAD_VALUE \a attr or \a buffer is \c NULL.
|
||||
\retval B_FILE_ERROR The object is not initialized or the node it refers to
|
||||
is read only.
|
||||
\return The number of bytes actually written.
|
||||
\retval B_BAD_VALUE \a attr or \a buffer was \c NULL.
|
||||
\retval B_FILE_ERROR The object was not initialized or the node it refers
|
||||
to was read only.
|
||||
\retval B_NOT_ALLOWED The node resides on a read only volume.
|
||||
\retval B_DEVICE_FULL Insufficient disk space.
|
||||
\retval B_NO_MEMORY Insufficient memory to complete the operation.
|
||||
\retval B_DEVICE_FULL There was insufficient disk space to complete the
|
||||
operation.
|
||||
\retval B_NO_MEMORY There was insufficient memory to complete the
|
||||
operation.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn ssize_t BNode::ReadAttr(const char *attr, type_code type,
|
||||
off_t offset, void *buffer, size_t len) const
|
||||
\fn ssize_t BNode::ReadAttr(const char* attr, type_code type,
|
||||
off_t offset, void* buffer, size_t length) const
|
||||
\brief Reads data from an attribute into \a buffer.
|
||||
|
||||
Reads \a len bytes of data from the attribute given by \a name into
|
||||
Reads \a length bytes of data from the attribute given by \a name into
|
||||
\a buffer. \a type and \a offset are currently ignored.
|
||||
|
||||
\param attr the name of the attribute.
|
||||
\param type the type of the attribute (currently ignored).
|
||||
\param offset the index from which to read the data (currently ignored).
|
||||
\param buffer the buffer for the data to be read.
|
||||
\param len the number of bytes to be read.
|
||||
\param attr The name of the attribute.
|
||||
\param type The type of the attribute (currently ignored).
|
||||
\param offset The index from which to read the data (currently ignored).
|
||||
\param buffer The buffer for the data to be read.
|
||||
\param length The number of bytes to be read.
|
||||
|
||||
\returns the number of bytes actually read
|
||||
\retval B_BAD_VALUE \a attr or \a buffer is \c NULL.
|
||||
\retval B_FILE_ERROR The object is not initialized.
|
||||
\retval B_ENTRY_NOT_FOUND The node has no attribute \a attr.
|
||||
\return The number of bytes actually read.
|
||||
\retval B_BAD_VALUE \a attr or \a buffer was \c NULL.
|
||||
\retval B_FILE_ERROR The object was not initialized.
|
||||
\retval B_ENTRY_NOT_FOUND The node had no attribute \a attr.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNode::RemoveAttr(const char *name)
|
||||
\fn status_t BNode::RemoveAttr(const char* name)
|
||||
\brief Deletes the attribute given by \a name.
|
||||
|
||||
\param name the name of the attribute to remove.
|
||||
\param name The name of the attribute to remove.
|
||||
|
||||
\return \c B_OK on success or an error code otherwise.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_BAD_VALUE \a name is \c NULL.
|
||||
\retval B_FILE_ERROR The object is not initialized or the node it
|
||||
refers to read only.
|
||||
\retval B_ENTRY_NOT_FOUND The node has no attribute \a name.
|
||||
\retval B_NOT_ALLOWED The node resides on a read only volume.
|
||||
\retval B_BAD_VALUE \a name was \c NULL.
|
||||
\retval B_FILE_ERROR The object was not initialized or the node it
|
||||
referred to was read-only.
|
||||
\retval B_ENTRY_NOT_FOUND The node had no attribute \a name.
|
||||
\retval B_NOT_ALLOWED The node resided on a read-only volume.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNode::RenameAttr(const char *oldname, const char *newname)
|
||||
\brief Moves the attribute given by \a oldname to \a newname.
|
||||
\fn status_t BNode::RenameAttr(const char* oldName, const char* newName)
|
||||
\brief Moves the attribute given by \a oldName to \a newName.
|
||||
|
||||
If \a newname already exists, the data is clobbered.
|
||||
If \a newName already exists, the data is clobbered.
|
||||
|
||||
\param oldname the name of the attribute to be renamed.
|
||||
\param newname the new name for the attribute.
|
||||
\param oldName The name of the attribute to be renamed.
|
||||
\param newName The new name for the attribute.
|
||||
|
||||
\return \c B_OK on success or an error code otherwise.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_BAD_VALUE \a oldname or \a newname is \c NULL.
|
||||
\retval B_FILE_ERROR The object is not initialized or the node it
|
||||
refers to is read only.
|
||||
\retval B_ENTRY_NOT_FOUND The node has no attribute \a oldname.
|
||||
\retval B_NOT_ALLOWED The node resides on a read only volume.
|
||||
\retval B_BAD_VALUE \a oldName or \a newName was \c NULL.
|
||||
\retval B_FILE_ERROR The object was not initialized or the node it
|
||||
referred to was read only.
|
||||
\retval B_ENTRY_NOT_FOUND The node had no attribute \a oldName.
|
||||
\retval B_NOT_ALLOWED The node resided on a read-only volume.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNode::GetAttrInfo(const char *name,
|
||||
struct attr_info *info) const
|
||||
\fn status_t BNode::GetAttrInfo(const char* name,
|
||||
struct attr_info* info) const
|
||||
\brief Fills in the pre-allocated attr_info struct pointed to by \a info
|
||||
with information about the attribute specified by \a name.
|
||||
with information about the attribute specified by \a name.
|
||||
|
||||
\param name the name of the attribute
|
||||
\param info the attr_info structure to be filled in
|
||||
\param name The name of the attribute.
|
||||
\param info The attr_info structure to be filled in.
|
||||
|
||||
\return \c B_OK on success or an error code otherwise.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_BAD_VALUE \a name is \c NULL.
|
||||
\retval B_FILE_ERROR The object is not initialized.
|
||||
\retval B_ENTRY_NOT_FOUND The node has no attribute \a name.
|
||||
\retval B_BAD_VALUE \a name was \c NULL.
|
||||
\retval B_FILE_ERROR The object was not initialized.
|
||||
\retval B_ENTRY_NOT_FOUND The node had no attribute \a name.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNode::GetNextAttrName(char *buffer)
|
||||
\fn status_t BNode::GetNextAttrName(char* buffer)
|
||||
\brief Copies the name of the attribute into \c buffer and then advances
|
||||
the pointer to the next attribute.
|
||||
the pointer to the next attribute.
|
||||
|
||||
The name of the node is first copied into \a buffer, which should be at
|
||||
least \c B_ATTR_NAME_LENGTH characters long. The copied node name is
|
||||
\c NUL terminated. Once the name is copied the attribute list pointer
|
||||
\0 terminated. Once the name is copied the attribute list pointer
|
||||
is advanced to the next attribute in the list. When GetNextAttrName()
|
||||
reaches the end of the list it returns \c B_ENTRY_NOT_FOUND.
|
||||
|
||||
\param buffer A buffer to copy the name of the attribute into.
|
||||
|
||||
\return \c B_OK on success or an error code otherwise.
|
||||
\retval B_OK The Attribute name was copied and there are more attribute
|
||||
names to copy.
|
||||
\retval B_BAD_VALUE passed in \a buffer is \c NULL.
|
||||
\retval B_FILE_ERROR The object is not initialized.
|
||||
\retval B_ENTRY_NOT_FOUND There are no more attributes, the last attribute
|
||||
name has already been copied.
|
||||
names to copy.
|
||||
\retval B_BAD_VALUE passed in \a buffer was \c NULL.
|
||||
\retval B_FILE_ERROR The object was not initialized.
|
||||
\retval B_ENTRY_NOT_FOUND There were no more attributes, the last attribute
|
||||
name had already been copied.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNode::RewindAttrs()
|
||||
\brief Resets the object's attribute pointer to the first attribute in the
|
||||
list.
|
||||
list.
|
||||
|
||||
\return \c B_OK on success or an error code otherwise.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_FILE_ERROR Some other error occurred.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNode::WriteAttrString(const char *name, const BString *data)
|
||||
\fn status_t BNode::WriteAttrString(const char* name, const BString* data)
|
||||
\brief Writes the specified string to the specified attribute, clobbering
|
||||
any previous data.
|
||||
any previous data.
|
||||
|
||||
\param name the name of the attribute.
|
||||
\param data the BString to be written to the attribute.
|
||||
|
||||
\return \c B_OK on success or an error code otherwise.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_BAD_VALUE \c NULL \a name or \a data
|
||||
\retval B_FILE_ERROR The object is not initialized or the node it refers to
|
||||
is read only.
|
||||
\retval B_NOT_ALLOWED The node resides on a read only volume.
|
||||
\retval B_DEVICE_FULL Insufficient disk space.
|
||||
\retval B_NO_MEMORY Insufficient memory to complete the operation.
|
||||
\retval B_BAD_VALUE \a name or \a data was \c NULL.
|
||||
\retval B_FILE_ERROR The object was not initialized or the node it
|
||||
referred to was read-only.
|
||||
\retval B_NOT_ALLOWED The node resided on a read-only volume.
|
||||
\retval B_DEVICE_FULL There was insufficient disk space to complete the
|
||||
operation.
|
||||
\retval B_NO_MEMORY There was insufficient memory to complete the
|
||||
operation.
|
||||
|
||||
\since Haiku R1
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNode::ReadAttrString(const char *name, BString *result) const
|
||||
\fn status_t BNode::ReadAttrString(const char* name, BString* result) const
|
||||
\brief Reads the data of the specified attribute into the pre-allocated
|
||||
\a result.
|
||||
\a result.
|
||||
|
||||
\param name the name of the attribute.
|
||||
\param result the BString to be set to the value of the attribute.
|
||||
|
||||
\return \c B_OK on success or an error code otherwise.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_BAD_VALUE \a name or \a result is \c NULL.
|
||||
\retval B_FILE_ERROR The object is not initialized.
|
||||
\retval B_ENTRY_NOT_FOUND The node has no attribute \a attr.
|
||||
\retval B_BAD_VALUE \a name or \a result was \c NULL.
|
||||
\retval B_FILE_ERROR The object was not initialized.
|
||||
\retval B_ENTRY_NOT_FOUND The node had no attribute \a attr.
|
||||
|
||||
\since Haiku R1
|
||||
*/
|
||||
|
||||
|
||||
@@ -480,23 +590,37 @@
|
||||
|
||||
|
||||
/*!
|
||||
\name Comparison Methods
|
||||
\name Operators
|
||||
*/
|
||||
|
||||
|
||||
//! @{
|
||||
|
||||
|
||||
/*!
|
||||
\fn BNode& BNode::operator=(const BNode& other)
|
||||
\brief Initializes the object as a copy of \a other.
|
||||
|
||||
\param other the BNode to be copied.
|
||||
|
||||
\returns A reference to this BNode object.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn bool BNode::operator==(const BNode &node) const
|
||||
\brief Tests whether this and the supplied BNode object are equal.
|
||||
|
||||
Two BNode objects are said to be equal if they're set to the same node,
|
||||
or if they're both \c B_NO_INIT.
|
||||
or if they're both unintialized
|
||||
|
||||
\param node the BNode to be compared with.
|
||||
\param node The BNode to be compared against.
|
||||
|
||||
\return \c true, if the BNode objects are equal, \c false otherwise.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
@@ -505,139 +629,13 @@
|
||||
\brief Tests whether this and the supplied BNode object are not equal.
|
||||
|
||||
Two BNode objects are said to be equal if they're set to the same node,
|
||||
or if they're both \c B_NO_INIT.
|
||||
or if they're both unintialized.
|
||||
|
||||
\param node the BNode to be compared with
|
||||
\param node The BNode to be compared with
|
||||
|
||||
\return \c false, if the BNode objects are equal, \c true otherwise.
|
||||
*/
|
||||
|
||||
|
||||
//! @}
|
||||
|
||||
|
||||
/*!
|
||||
\name Private Methods
|
||||
*/
|
||||
|
||||
|
||||
//! @{
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNode::set_fd(int fd)
|
||||
\brief Sets the node's file descriptor.
|
||||
|
||||
Used by each implementation (i.e. BNode, BFile, BDirectory, etc.) to set
|
||||
the node's file descriptor. This allows each subclass to use the various
|
||||
file-type specific system calls for opening file descriptors.
|
||||
|
||||
\note This method calls close_fd() to close previously opened FDs. Thus
|
||||
derived classes should take care to first call set_fd() and set
|
||||
class specific resources freed in their close_fd() version
|
||||
thereafter.
|
||||
|
||||
\param fd the file descriptor this BNode should be set to (may be -1).
|
||||
|
||||
\returns \c B_OK if everything went fine, or an error code if something
|
||||
went wrong.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn void BNode::close_fd()
|
||||
\brief Closes the node's file descriptor(s).
|
||||
|
||||
To be implemented by subclasses to close the file descriptor using the
|
||||
proper system call for the given file-type. This implementation calls
|
||||
_kern_close(fFd) and also _kern_close(fAttrDir) if necessary.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn void BNode::set_status(status_t newStatus)
|
||||
\brief Sets the BNode's status.
|
||||
|
||||
To be used by derived classes instead of accessing the BNode's private
|
||||
\c fCStatus member directly.
|
||||
|
||||
\param newStatus the new value for the status variable.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNode::_SetTo(int fd, const char *path, bool traverse)
|
||||
\brief Initializes the BNode's file descriptor to the node referred to
|
||||
by the given FD and path combo.
|
||||
|
||||
\a path must either be \c NULL, an absolute or a relative path.
|
||||
In the first case, \a fd must not be \c NULL; the node it refers to will
|
||||
be opened. If absolute, \a fd is ignored. If relative and \a fd is >= 0,
|
||||
it will be reckoned off the directory identified by \a fd, otherwise off
|
||||
the current working directory.
|
||||
|
||||
The method will first try to open the node with read and write permission.
|
||||
If that fails due to a read-only FS or because the user has no write
|
||||
permission for the node, it will re-try opening the node read-only.
|
||||
|
||||
The \a fCStatus member will be set to the return value of this method.
|
||||
|
||||
\param fd Either a directory FD or a value < 0. In the latter case \a path
|
||||
must be specified.
|
||||
\param path Either \a NULL in which case \a fd must be given, absolute, or
|
||||
relative to the directory specified by \a fd (if given) or to the
|
||||
current working directory.
|
||||
\param traverse If the node identified by \a fd and \a path is a symlink
|
||||
and \a traverse is \c true, the symlink will be resolved recursively.
|
||||
|
||||
\returns \c B_OK if everything went fine, or an error code if something
|
||||
went wrong.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNode::_SetTo(const entry_ref *ref, bool traverse)
|
||||
\brief Initializes the BNode's file descriptor to the node referred to
|
||||
by the given entry_ref.
|
||||
|
||||
The method will first try to open the node with read and write permission.
|
||||
If that fails due to a read-only FS or because the user has no write
|
||||
permission for the node, it will re-try opening the node read-only.
|
||||
|
||||
The \a fCStatus member will be set to the return value of this method.
|
||||
|
||||
\param ref An entry_ref identifying the node to be opened.
|
||||
\param traverse If the node identified by \a ref is a symlink and
|
||||
\a traverse is \c true, the symlink will be resolved recursively.
|
||||
|
||||
\returns \c B_OK if everything went fine, or an error code if something
|
||||
went wrong.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNode::set_stat(struct stat &st, uint32 what)
|
||||
\brief Modifies a certain setting for this node based on \a what and the
|
||||
corresponding value in \a st.
|
||||
|
||||
Inherited from and called by BStatable.
|
||||
|
||||
\param st a stat structure containing the value to be set.
|
||||
\param what specifies what setting to be modified.
|
||||
|
||||
\returns \c B_OK if everything went fine, or an error code if something
|
||||
went wrong.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNode::InitAttrDir()
|
||||
\brief Verifies that the BNode has been properly initialized, and then
|
||||
(if necessary) opens the attribute directory on the node's file
|
||||
descriptor, storing it in fAttrDir.
|
||||
|
||||
\returns \c B_OK if everything went fine, or an error code if something
|
||||
went wrong.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user