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