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//! @} 460