Move documentation from NodeInfo into the API docs.
* Delete the docs from NodeInfo.cpp and NodeInfo.h * I snuck a couple of style fixes into NodeInfo.cpp * I had to make a small modification to MimeType.dox to prevent it from overriding the docs of one of the methods in NodeInfo.dox.
This commit is contained in:
John Scipione
@@ -280,9 +280,9 @@
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BMimeType::GetPreferredApp(char *signature, app_verb verb)
|
||||
const
|
||||
\brief Fetches the signature of the MIME type's preferred application from
|
||||
\fn status_t BMimeType::GetPreferredApp(char *signature,
|
||||
app_verb verb) const
|
||||
\brief Fetches the signature of the preferred application from
|
||||
the MIME database.
|
||||
|
||||
The preferred app is the application that's used to access a file when,
|
||||
|
||||
@@ -0,0 +1,428 @@
|
||||
/*
|
||||
* Copyright 2013 Haiku Inc. All rights reserved.
|
||||
* Distributed under the terms of the MIT License.
|
||||
*
|
||||
* Authors:
|
||||
* Axel Dörfler, [email protected]
|
||||
* John Scipione, [email protected]
|
||||
* Ingo Weinhold, [email protected]
|
||||
*
|
||||
* Corresponds to:
|
||||
* headers/os/app/NodeInfo.h hrev45253
|
||||
* src/kits/app/NodeInfo.cpp hrev45253
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\file Node.h
|
||||
\ingroup storage
|
||||
\ingroup libbe
|
||||
\brief Provides the BNodeInfo class.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\class BNodeInfo
|
||||
\ingroup storage
|
||||
\ingroup libbe
|
||||
\brief Provides meta data about a file type.
|
||||
|
||||
BNodeInfo provides a nice wrapper to all sorts of useful meta data
|
||||
like it's mime type, the files icon and the application which will load
|
||||
the file.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BNodeInfo::BNodeInfo()
|
||||
\brief Creates an uninitialized BNodeInfo object.
|
||||
|
||||
After created a BNodeInfo with this, you should call SetTo().
|
||||
|
||||
\see SetTo(BNode *node)
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BNodeInfo::BNodeInfo(BNode *node)
|
||||
\brief Creates a BNodeInfo object and initializes it to the supplied node.
|
||||
|
||||
\param node The node to gather information on.
|
||||
|
||||
\see SetTo(BNode *node)
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn BNodeInfo::~BNodeInfo()
|
||||
\brief Frees all resources associated with this object.
|
||||
|
||||
The internal BNode object is not deleted.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\name Constructor helper methods
|
||||
*/
|
||||
|
||||
|
||||
//! @{
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNodeInfo::SetTo(BNode *node)
|
||||
\brief Initializes the BNodeInfo to the supplied \a node.
|
||||
|
||||
The BNodeInfo object does not copy the supplied object, but uses it
|
||||
directly. You must not delete the object you supply while the BNodeInfo
|
||||
does exist. The BNodeInfo does not take over ownership of the \a and
|
||||
it doesn't delete it on destruction.
|
||||
|
||||
\param node The node to gather information on.
|
||||
|
||||
\returns A status code.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_BAD_VALUE The node was not properly initialized.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNodeInfo::InitCheck() const
|
||||
\brief Determines whether or not the object has been properly initialized.
|
||||
|
||||
\returns A status code.
|
||||
\retval B_OK The object was properly initialized.
|
||||
\retval B_BAD_VALUE The object was <b>not</b> properly initialized.
|
||||
*/
|
||||
|
||||
|
||||
//! @}
|
||||
|
||||
|
||||
/*!
|
||||
\name MIME-type methods
|
||||
*/
|
||||
|
||||
|
||||
//! @{
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNodeInfo::GetType(char *type) const
|
||||
\brief Writes the MIME-type of the node into \a type.
|
||||
|
||||
The source of the type information is the \c BEOS:TYPE attribute of the
|
||||
node. The \a type buffer should be pre-allocated before it is passed into
|
||||
GetType(), it should be at least \c B_MIME_TYPE_LENGTH in length.
|
||||
|
||||
\param type A pointer to a pre-allocated char buffer of at least
|
||||
\c B_MIME_TYPE_LENGTH length into which the MIME-type of the
|
||||
node is written.
|
||||
|
||||
\returns A status code.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_NO_INIT The object is not properly initialized.
|
||||
\retval B_BAD_VALUE \c NULL \a type or the type string stored in the
|
||||
attribute is longer than \c B_MIME_TYPE_LENGTH.
|
||||
\retval B_BAD_TYPE The attribute the type string is stored in has the
|
||||
wrong type.
|
||||
\retval B_ENTRY_NOT_FOUND No type is set on the node.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNodeInfo::SetType(const char *type)
|
||||
\brief Sets the MIME-type of the node. If \a type is \c NULL the
|
||||
\c BEOS:TYPE attribute is removed instead.
|
||||
|
||||
The \a type string is written into the \c BEOS:TYPE attribute of the node.
|
||||
If \a type is \c NULL, the \c BEOS:TYPE attribute is removed instead. The
|
||||
\a type parameter may not by longer than \c B_MIME_TYPE_LENGTH in length
|
||||
including the terminating \c NUL character.
|
||||
|
||||
\param type The MIME-type to be assigned to the node. Must not be longer
|
||||
than \c B_MIME_TYPE_LENGTH (including the terminating \c NUL).
|
||||
May be \c NULL to remove the attribute.
|
||||
|
||||
\returns A status code.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_NO_INIT The node object was not properly initialized.
|
||||
\retval B_BAD_VALUE \a type is longer than \c B_MIME_TYPE_LENGTH.
|
||||
*/
|
||||
|
||||
|
||||
//! @}
|
||||
|
||||
|
||||
/*!
|
||||
\name Icon methods
|
||||
*/
|
||||
|
||||
|
||||
//! @{
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNodeInfo::GetIcon(BBitmap *icon, icon_size k) const
|
||||
\brief Gets the icon of the node.
|
||||
|
||||
The icon stored in the \c BEOS:L:STD_ICON attribute (large) or
|
||||
\c BEOS:M:STD_ICON attribute (mini) is retrieved.
|
||||
|
||||
\param icon A pointer to a pre-allocated BBitmap object of the correct
|
||||
dimension to store the requested icon: 16x16 for the mini or
|
||||
32x32 for the large icon.
|
||||
\param k The size of the icon to be retrieved: \c B_MINI_ICON for a 16x16
|
||||
icon and \c B_LARGE_ICON for a 32x32 icon.
|
||||
|
||||
\returns A status code.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_NO_INIT The node 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.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNodeInfo::SetIcon(const BBitmap *icon, icon_size k)
|
||||
\brief Sets the icon of the node. If \a icon is \c NULL, the attribute is
|
||||
removed instead.
|
||||
|
||||
The icon is stored in the \c BEOS:L:STD_ICON attribute (large) or
|
||||
\c BEOS:M:STD_ICON attribute (mini). If \a icon is \c NULL the respective
|
||||
attribute is removed instead.
|
||||
|
||||
\param icon A pointer to a BBitmap object containing the icon to be set.
|
||||
May be \c NULL.
|
||||
\param k The size of the icon to be set: \c B_MINI_ICON for the mini or
|
||||
\c B_LARGE_ICON for the large icon.
|
||||
|
||||
\returns A status code.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_NO_INIT The object is not properly initialized.
|
||||
\retval B_BAD_VALUE Unknown icon size \a k or bitmap dimensions (\a icon)
|
||||
and icon size (\a k) do not match.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNodeInfo::GetIcon(uint8** data, size_t* size,
|
||||
type_code* type) const
|
||||
\brief Gets the icon of the node.
|
||||
|
||||
The icon stored in the \c BEOS:ICON attribute of the node is retrieved.
|
||||
The caller is responsible to <tt>delete[]</tt> the data if the icon was
|
||||
retrieved.
|
||||
|
||||
\param data A pointer in which a pointer to the icon data
|
||||
will be returned.
|
||||
\param size A pointer in which the size of the found icon data
|
||||
will be returned.
|
||||
\param type A pointer in which the type of the found icon data
|
||||
will be returned.
|
||||
|
||||
\returns A status code.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_NO_INIT The node object was not properly initialized.
|
||||
\retval B_BAD_VALUE \c NULL \a data, \c NULL size or \c NULL \a type.
|
||||
\retval B_NO_MEMORY No memory to allocate the data buffer.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNodeInfo::SetIcon(const uint8* data, size_t size)
|
||||
\brief Sets the node icon of the node. If \a data is \c NULL or \a size
|
||||
is 0, the \c BEOS:ICON attribute is removed instead.
|
||||
|
||||
The icon is stored in the \c BEOS:ICON attribute of the node.
|
||||
|
||||
\param data A pointer to valid icon data. May be \c NULL.
|
||||
\param size The size of the provided data buffer. May be 0.
|
||||
|
||||
\returns A status code.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_NO_INIT The node object was not properly initialized.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNodeInfo::GetTrackerIcon(BBitmap *icon,
|
||||
icon_size iconSize) const
|
||||
\brief Gets the icon displayed by Tracker for the icon.
|
||||
|
||||
This method tries really hard to find an icon for the node:
|
||||
- If the node has no type this method returns the icon for
|
||||
\c B_FILE_MIME_TYPE if it's a regular file or
|
||||
\c B_DIRECTORY_MIME_TYPE if it's a directory, even if the node has its
|
||||
own icon!
|
||||
- Next it will ask GetIcon() for an icon.
|
||||
- If this fails it will get the preferred application and ask the MIME
|
||||
database if the application has a special icon for the file type of the
|
||||
node.
|
||||
- Next it will ask the MIME database whether there is an icon for the file
|
||||
type of the node.
|
||||
- Then it will ask the MIME database for the preferred application for
|
||||
the file type of the node and whether this application has a special
|
||||
icon for the type.
|
||||
- Finally it will return the icon for whatever type of node
|
||||
(file/dir/etc.) from the MIME database.
|
||||
|
||||
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
|
||||
a predefined icon_size constant, pass in an integer casted
|
||||
to icon_size. For example to get a 64x64 icon pass in:
|
||||
\code
|
||||
(icon_size)64
|
||||
\endcode
|
||||
|
||||
\param icon A pointer to a pre-allocated BBitmap of the correct dimension
|
||||
to store the requested icon (16x16 for the mini and 32x32 for the
|
||||
large icon).
|
||||
\param iconSize The size of the icon to be retrieved: \c B_MINI_ICON
|
||||
for a 16x16 icon or \c B_LARGE_ICON for a 32x32 icon.
|
||||
|
||||
\returns A status code.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_NO_INIT The node 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
|
||||
not match.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNodeInfo::GetTrackerIcon(const entry_ref *ref,
|
||||
BBitmap *icon, icon_size iconSize)
|
||||
\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.
|
||||
|
||||
\param ref An entry_ref referring to the node for which the icon is
|
||||
retrieved.
|
||||
\param icon A pointer to a pre-allocated BBitmap of the correct dimension
|
||||
to store the requested icon (16x16 for the mini and 32x32 for the
|
||||
large icon).
|
||||
\param iconSize The size of the icon to be retrieved: \c B_MINI_ICON
|
||||
for a 16x16 icon or \c B_LARGE_ICON for a 32x32 icon.
|
||||
|
||||
\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.
|
||||
*/
|
||||
|
||||
|
||||
//! @}
|
||||
|
||||
|
||||
/*!
|
||||
\name Preferred application methods
|
||||
*/
|
||||
|
||||
|
||||
//! @{
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNodeInfo::GetPreferredApp(char *signature,
|
||||
app_verb verb) const
|
||||
\brief Gets the preferred application for the node.
|
||||
|
||||
Writes the contents of the \c BEOS:PREF_APP attribute into the
|
||||
\a signature buffer. The preferred application can be identified by its
|
||||
signature. \a signature should be at least \c B_MIME_TYPE_LENGTH or
|
||||
longer and pre-allocated before it is passed into this method.
|
||||
|
||||
\param signature A pointer to a pre-allocated character buffer of size
|
||||
\c B_MIME_TYPE_LENGTH or larger into which the MIME-type of the
|
||||
preferred application is written.
|
||||
\param verb The type of access the preferred application is requested.
|
||||
Currently \c B_OPEN is the only meaningful option.
|
||||
|
||||
\returns A status code.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_NO_INIT The node object was not properly initialized.
|
||||
\retval B_BAD_VALUE \c NULL \a signature or bad app_verb \a verb.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNodeInfo::SetPreferredApp(const char *signature,
|
||||
app_verb verb)
|
||||
\brief Sets the preferred application of the node. If \a signature is
|
||||
\c NULL, the \c BEOS:PREF_APP attribute is removed instead.
|
||||
|
||||
The supplied string is written into the \c BEOS:PREF_APP attribute of the
|
||||
node. If \a signature is \c NULL, the respective attribute is removed
|
||||
instead. \a signature must not be longer than \c B_MIME_TYPE_LENGTH
|
||||
(including the terminating \c NUL).
|
||||
|
||||
\param signature The signature of the preferred application to be set.
|
||||
May be \c NULL.
|
||||
\param verb The type of access set to the preferred application.
|
||||
Currently only \c B_OPEN is meaningful.
|
||||
|
||||
\returns A status code.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_NO_INIT The object is not properly initialized.
|
||||
\retval B_BAD_VALUE \c NULL \a signature, \a signature is longer than
|
||||
\c B_MIME_TYPE_LENGTH or bad app_verb \a verb.
|
||||
*/
|
||||
|
||||
|
||||
//! @}
|
||||
|
||||
|
||||
/*!
|
||||
\name Application hint methods
|
||||
*/
|
||||
|
||||
|
||||
//! @{
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNodeInfo::GetAppHint(entry_ref *ref) const
|
||||
\brief Fills out \a ref with a pointer to a hint about the application
|
||||
that will open this node.
|
||||
|
||||
The path contained in the \c BEOS:PPATH attribute of the node is converted
|
||||
into an entry_ref and returned. \a ref should be pre-allocated before being
|
||||
passed into this method.
|
||||
|
||||
\param ref A pointer to a pre-allocated entry_ref into which the requested
|
||||
app hint shall be written.
|
||||
|
||||
\returns A status code.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_NO_INIT The node object was not properly initialized.
|
||||
\retval B_BAD_VALUE The \a ref object passed in was \c NULL.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t BNodeInfo::SetAppHint(const entry_ref *ref)
|
||||
\brief Sets the app hint of the node. If \a ref is \c NULL, the
|
||||
\c BEOS:PPATH attribute is removed instead.
|
||||
|
||||
\a ref is converted into a path and stored in the \c BEOS:PPATH attribute
|
||||
of the node. If \a ref is NULL \c BEOS:PPATH is removed instead.
|
||||
|
||||
\param ref A pointer to an entry_ref referring to the application.
|
||||
May be \c NULL.
|
||||
|
||||
\returns A status code.
|
||||
\retval B_OK Everything went fine.
|
||||
\retval B_NO_INIT The node object was not properly initialized.
|
||||
\retval B_BAD_VALUE The \a ref object passed in was \c NULL.
|
||||
*/
|
||||
|
||||
|
||||
//! @}
|
||||
Reference in New Issue
Block a user