docs/user/storage/NodeInfo.dox

   1 /*
   2  * Copyright 2013-2014 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Axel Dörfler, axeld@pinc-software.de
   7  *              John Scipione, jscipione@gmail.com
   8  *              Ingo Weinhold, bonefish@users.sf.net
   9  *
  10  * Corresponds to:
  11  *              headers/os/storage/NodeInfo.h   hrev47402
  12  *              src/kits/storage/NodeInfo.cpp   hrev47402
  13  */
  14
  15
  16 /*!
  17         \file NodeInfo.h
  18         \ingroup storage
  19         \ingroup libbe
  20         \brief Provides the BNodeInfo class.
  21 */
  22
  23
  24 /*!
  25         \class BNodeInfo
  26         \ingroup storage
  27         \ingroup libbe
  28         \brief Provides access to file type meta data on a node.
  29
  30         BNodeInfo provides a nice wrapper to all sorts of useful meta data such as
  31         the MIME-type, the file's icon and the application that will open
  32         the file.
  33
  34         \since BeOS R3
  35 */
  36
  37
  38 /*!
  39         \fn BNodeInfo::BNodeInfo()
  40         \brief Creates an uninitialized BNodeInfo object.
  41
  42         After created a BNodeInfo with this, you should call SetTo().
  43
  44         \see SetTo(BNode* node)
  45
  46         \since BeOS R3
  47 */
  48
  49
  50 /*!
  51         \fn BNodeInfo::BNodeInfo(BNode* node)
  52         \brief Creates a BNodeInfo object and initializes it to the supplied
  53                \a node.
  54
  55         \param node The \a node to initialize to and gather information.
  56
  57         \since BeOS R3
  58 */
  59
  60
  61 /*!
  62         \fn BNodeInfo::~BNodeInfo()
  63         \brief Frees the object and associated resources.
  64
  65         The internal BNode object is not deleted.
  66
  67         \since BeOS R3
  68 */
  69
  70
  71 /*!
  72         \name Constructor helper methods
  73 */
  74
  75
  76 //! @{
  77
  78
  79 /*!
  80         \fn status_t BNodeInfo::SetTo(BNode* node)
  81         \brief Initializes the BNodeInfo to the supplied \a node.
  82
  83         The BNodeInfo object does not copy the supplied \a node object, it uses it
  84         directly instead. You must not delete the supply \a node while the
  85         BNodeInfo object exists. The BNodeInfo does not take over ownership of the
  86         \a node and it doesn't delete it on destruction either.
  87
  88         \param node The \a node to gather information on.
  89
  90         \returns A status code.
  91         \retval B_OK Everything went fine.
  92         \retval B_BAD_VALUE The node was not properly initialized.
  93
  94         \since BeOS R3
  95 */
  96
  97
  98 /*!
  99         \fn status_t BNodeInfo::InitCheck() const
 100         \brief Checks whether or not the object has been properly initialized.
 101
 102         \returns A status code.
 103         \retval B_OK The object was properly initialized.
 104         \retval B_BAD_VALUE The object was \b not properly initialized.
 105
 106         \since BeOS R3
 107 */
 108
 109
 110 //! @}
 111
 112
 113 /*!
 114         \name MIME-type methods
 115 */
 116
 117
 118 //! @{
 119
 120
 121 /*!
 122         \fn status_t BNodeInfo::GetType(char* type) const
 123         \brief Writes the MIME-type of the node into \a type.
 124
 125         The source of the type information is the \c BEOS:TYPE attribute of the
 126         node. The \a type buffer should be pre-allocated before it is passed into
 127         GetType(), it should be at least \c B_MIME_TYPE_LENGTH in length.
 128
 129         \param type A pointer to a pre-allocated char buffer of at least
 130                \c B_MIME_TYPE_LENGTH length into which the MIME-type of the
 131                node is written.
 132
 133         \returns A status code.
 134         \retval B_OK Everything went fine.
 135         \retval B_NO_INIT The object is not properly initialized.
 136         \retval B_BAD_VALUE \c NULL \a type or the type string stored in the
 137                 attribute is longer than \c B_MIME_TYPE_LENGTH.
 138         \retval B_BAD_TYPE The stored type string attribute has the wrong type.
 139         \retval B_ENTRY_NOT_FOUND No type is set on the node.
 140
 141         \since BeOS R3
 142 */
 143
 144
 145 /*!
 146         \fn status_t BNodeInfo::SetType(const char* type)
 147         \brief Sets the MIME-type of the node. If \a type is \c NULL the
 148                \c BEOS:TYPE attribute is removed instead.
 149
 150         The \a type string is written into the \c BEOS:TYPE attribute of the node.
 151         If \a type is \c NULL, the \c BEOS:TYPE attribute is removed instead. The
 152         \a type parameter may not by longer than \c B_MIME_TYPE_LENGTH in length
 153         including the terminating \0 character.
 154
 155         \param type The MIME-type to be assigned to the \a node. Must not be
 156                longer than \c B_MIME_TYPE_LENGTH (including the terminating
 157                \c NUL). May be \c NULL to remove the attribute.
 158
 159         \returns A status code.
 160         \retval B_OK Everything went fine.
 161         \retval B_NO_INIT The object was not properly initialized.
 162         \retval B_BAD_VALUE \a type is longer than \c B_MIME_TYPE_LENGTH.
 163
 164         \since BeOS R3
 165 */
 166
 167
 168 //! @}
 169
 170
 171 /*!
 172         \name Icon
 173 */
 174
 175
 176 //! @{
 177
 178
 179 /*!
 180         \fn status_t BNodeInfo::GetIcon(BBitmap* icon, icon_size which) const
 181         \brief Gets the icon of the node.
 182
 183         The icon stored in the \c BEOS:L:STD_ICON attribute (large) or
 184         \c BEOS:M:STD_ICON attribute (mini) is retrieved.
 185
 186         \param icon A pointer to a pre-allocated BBitmap object of the correct
 187                dimension to store the requested icon: 16x16 for the mini or
 188                32x32 for the large icon.
 189         \param which The size of the icon to be retrieved: \c B_MINI_ICON for a 16x16
 190                icon and \c B_LARGE_ICON for a 32x32 icon.
 191
 192         \returns A status code.
 193         \retval B_OK Everything went fine.
 194         \retval B_NO_INIT The object was not properly initialized.
 195         \retval B_BAD_VALUE \c NULL \a icon, unsupported icon size \a k or bitmap
 196                 dimensions (\a icon) and icon size (\a k) do not match.
 197
 198         \since BeOS R3
 199 */
 200
 201
 202 /*!
 203         \fn status_t BNodeInfo::SetIcon(const BBitmap* icon, icon_size which)
 204         \brief Sets the icon of the node. If \a icon is \c NULL, the attribute is
 205                    removed instead.
 206
 207         The icon is stored in the \c BEOS:L:STD_ICON attribute (large) or
 208         \c BEOS:M:STD_ICON attribute (mini). If \a icon is \c NULL the respective
 209         attribute is removed instead.
 210
 211         \param icon A pointer to a BBitmap object containing the icon to be set.
 212                May be \c NULL.
 213         \param which The size of the icon to be set: \c B_MINI_ICON for the mini or
 214                \c B_LARGE_ICON for the large icon.
 215
 216         \returns A status code.
 217         \retval B_OK Everything went fine.
 218         \retval B_NO_INIT The object is not properly initialized.
 219         \retval B_BAD_VALUE Unknown icon size \a k or bitmap dimensions (\a icon)
 220                 and icon size (\a k) do not match.
 221
 222         \since BeOS R3
 223 */
 224
 225
 226 /*!
 227         \fn status_t BNodeInfo::GetIcon(uint8** data, size_t* size,
 228                 type_code* type) const
 229         \brief Gets the icon of the node.
 230
 231         The icon stored in the \c BEOS:ICON attribute of the node is retrieved.
 232         The caller is responsible to <tt>delete[]</tt> the data if the icon was
 233         retrieved.
 234
 235         \param data A pointer in which a pointer to the icon data
 236                will be filled in.
 237         \param size A pointer in which the size of the found icon data
 238                will be filled in.
 239         \param type A pointer in which the type of the found icon data
 240                will be filled in.
 241
 242         \returns A status code.
 243         \retval B_OK Everything went fine.
 244         \retval B_NO_INIT The object was not properly initialized.
 245         \retval B_BAD_VALUE \c NULL \a data, \c NULL \a size or \c NULL \a type.
 246         \retval B_NO_MEMORY No memory to allocate the \a data buffer.
 247
 248         \since Haiku R1
 249 */
 250
 251
 252 /*!
 253         \fn status_t BNodeInfo::SetIcon(const uint8* data, size_t size)
 254         \brief Sets the node icon of the node. If \a data is \c NULL or \a size
 255                is 0, the \c BEOS:ICON attribute is removed instead.
 256
 257         The icon is stored in the \c BEOS:ICON attribute of the node.
 258
 259         \param data A pointer to valid icon data. May be \c NULL.
 260         \param size The size of the provided data buffer. May be 0.
 261
 262         \returns A status code.
 263         \retval B_OK Everything went fine.
 264         \retval B_NO_INIT The object was not properly initialized.
 265
 266         \since Haiku R1
 267 */
 268
 269
 270 /*!
 271         \fn status_t BNodeInfo::GetTrackerIcon(BBitmap* icon,
 272                 icon_size which) const
 273         \brief Gets the icon displayed by Tracker for the icon.
 274
 275         This method tries really hard to find an icon for the node:
 276         - If the node has no type this method returns the icon for
 277           \c B_FILE_MIME_TYPE if it's a regular file or
 278           \c B_DIRECTORY_MIME_TYPE if it's a directory, even if the node has its
 279           own icon!
 280         - Next it will ask GetIcon() for an icon.
 281         - If this fails it will get the preferred application and ask the MIME
 282           database if the application has an icon for the file type of the
 283           node.
 284         - Next it will ask the MIME database whether there is an icon for the file
 285           type of the node.
 286         - Then it will ask the MIME database for the preferred application for
 287           the file type of the node and whether this application has a special
 288           icon for the type.
 289         - Finally it will return a generic icon for whatever type of file type
 290           (file/dir/etc.) the node is from the MIME database.
 291
 292         The first action that provides an icon is used. In the case that none of
 293         them yield an icon this method fails, this is very unlikely though.
 294
 295         \remarks You can set \a which to get a scaled icon instead of using
 296                  a predefined icon_size constant, pass in an integer casted
 297                  to icon_size. For example to get a 64x64 icon pass in:
 298 \code
 299 (icon_size)64
 300 \endcode
 301
 302         \param icon A pointer to a pre-allocated BBitmap of the correct dimension
 303                to store the requested icon (16x16 for the mini and 32x32 for the
 304                large icon).
 305         \param which The size of the icon to be retrieved: \c B_MINI_ICON
 306                for a 16x16 icon or \c B_LARGE_ICON for a 32x32 icon.
 307
 308         \returns A status code.
 309         \retval B_OK Everything went fine.
 310         \retval B_NO_INIT The object was not properly initialized.
 311         \retval B_BAD_VALUE \c NULL \a icon, unsupported icon size \a which
 312                 or bitmap dimensions (\a icon) and icon size (\a which) do
 313                 not match.
 314
 315         \since BeOS R3
 316 */
 317
 318
 319 /*!
 320         \fn status_t BNodeInfo::GetTrackerIcon(const entry_ref* ref,
 321                 BBitmap* icon, icon_size which)
 322         \brief Gets the icon displayed by Tracker for the node referred to by
 323                \a ref.
 324
 325         This methods works similarly to the non-static version but \a ref
 326         identifies the node. \a icon must be pre-allocated to the size requested
 327         using \a which before being passed to this method.
 328
 329         \param ref An entry_ref referring to the node for which the icon is
 330                retrieved.
 331         \param icon A pointer to a pre-allocated BBitmap object of the correct
 332                dimension to store the requested icon (16x16 for the mini and 32x32
 333                for the large icon).
 334         \param which The size of the icon to be retrieved: \c B_MINI_ICON
 335                for a 16x16 icon or \c B_LARGE_ICON for a 32x32 icon.
 336
 337         \returns A status code.
 338         \retval B_OK: Everything went fine.
 339         \retval B_NO_INIT: The object is not properly initialized.
 340         \retval B_BAD_VALUE: \c NULL ref or \a icon, unsupported icon size
 341                 \a which or bitmap dimensions (\a icon) and icon size
 342                 (\a which) do not match.
 343
 344         \since BeOS R3
 345 */
 346
 347
 348 //! @}
 349
 350
 351 /*!
 352         \name Preferred Application
 353 */
 354
 355
 356 //! @{
 357
 358
 359 /*!
 360         \fn status_t BNodeInfo::GetPreferredApp(char* signature,
 361                 app_verb verb) const
 362         \brief Gets the preferred application of the node.
 363
 364         Writes the contents of the \c BEOS:PREF_APP attribute into the
 365         \a signature buffer. The preferred application can be identified by its
 366         signature. \a signature should be at least \c B_MIME_TYPE_LENGTH or
 367         longer and pre-allocated before it is passed into this method.
 368
 369         \param signature A pointer to a pre-allocated character buffer of size
 370                \c B_MIME_TYPE_LENGTH or larger into which the MIME-type of the
 371                preferred application is written.
 372         \param verb The type of access the preferred application is requested.
 373                Currently \c B_OPEN is the only meaningful option.
 374
 375         \returns A status code.
 376         \retval B_OK Everything went fine.
 377         \retval B_NO_INIT The object was not properly initialized.
 378         \retval B_BAD_VALUE \c NULL \a signature or bad app_verb.
 379 */
 380
 381
 382 /*!
 383         \fn status_t BNodeInfo::SetPreferredApp(const char* signature,
 384                 app_verb verb)
 385         \brief Sets the preferred application of the node. If \a signature is
 386                \c NULL, the \c BEOS:PREF_APP attribute is removed instead.
 387
 388         The supplied string is written into the \c BEOS:PREF_APP attribute of the
 389         node. If \a signature is \c NULL, the respective attribute is removed
 390         instead. \a signature must not be longer than \c B_MIME_TYPE_LENGTH
 391                (including the terminating \c NUL).
 392
 393         \param signature The signature of the preferred application to be set.
 394                May be \c NULL.
 395         \param verb The type of access set to the preferred application.
 396                Currently only \c B_OPEN is meaningful.
 397
 398         \returns A status code.
 399         \retval B_OK Everything went fine.
 400         \retval B_NO_INIT The object is not properly initialized.
 401         \retval B_BAD_VALUE \c NULL \a signature, \a signature is longer than
 402                 \c B_MIME_TYPE_LENGTH or bad app_verb.
 403 */
 404
 405
 406 //! @}
 407
 408
 409 /*!
 410         \name Application Hint
 411 */
 412
 413
 414 //! @{
 415
 416
 417 /*!
 418         \fn status_t BNodeInfo::GetAppHint(entry_ref* ref) const
 419         \brief Fills out \a ref with a pointer to a hint about the application
 420                that will open this node.
 421
 422         The path contained in the \c BEOS:PPATH attribute of the node is converted
 423         into an entry_ref and returned. \a ref should be pre-allocated before being
 424         passed into this method.
 425
 426         \param ref A pointer to a pre-allocated entry_ref into which the app hint
 427                is written.
 428
 429         \returns A status code.
 430         \retval B_OK Everything went fine.
 431         \retval B_BAD_DATA Attribute size greater than \c B_PATH_NAME_LENGTH.
 432         \retval B_BAD_TYPE The stored type string attribute has the wrong type.
 433         \retval B_BAD_VALUE The \a ref object passed in was \c NULL.
 434         \retval B_ERROR Unable to read \c BEOS:PPATH attribute.
 435         \retval B_NO_INIT The object was not properly initialized.
 436 */
 437
 438
 439 /*!
 440         \fn status_t BNodeInfo::SetAppHint(const entry_ref* ref)
 441         \brief Sets the application that will open the file type of the node. If
 442                \a ref is \c NULL, the \c BEOS:PPATH attribute is removed instead.
 443
 444         \a ref is converted into a path and stored in the \c BEOS:PPATH attribute
 445         of the node. If \a ref is NULL \c BEOS:PPATH is removed instead.
 446
 447         \param ref A pointer to an entry_ref referring to the application.
 448                May be \c NULL.
 449
 450         \returns A status code.
 451         \retval B_OK Everything went fine.
 452         \retval B_BAD_VALUE The \a ref object passed in was \c NULL.
 453         \retval B_ENTRY_NOT_FOUND \c BEOS:PPATH attribute not found.
 454         \retval B_ERROR Unable to write \c BEOS:PPATH attribute.
 455         \retval B_NO_INIT The object was not properly initialized.
 456 */
 457
 458
 459 //! @}