From b885e90eb96c5c2b629c81d35b7f9970db239995 Mon Sep 17 00:00:00 2001 From: John Scipione Date: Wed, 18 Jun 2014 19:10:45 -0400 Subject: [PATCH] Documentation updates for Storage Kit classes * Added \since to each method and parameter. * Whitespace cleanup. * Some other minor cleanups and updates. --- docs/user/storage/AppFileInfo.dox | 341 ++++--- docs/user/storage/Directory.dox | 190 ++-- docs/user/storage/Entry.dox | 245 +++-- docs/user/storage/EntryList.dox | 54 +- docs/user/storage/File.dox | 148 +-- docs/user/storage/FilePanel.dox | 140 ++- docs/user/storage/FindDirectory.dox | 1323 +++++++++++++++++++++------ docs/user/storage/Mime.dox | 150 ++- docs/user/storage/MimeType.dox | 612 +++++++------ docs/user/storage/Node.dox | 588 ++++++------ docs/user/storage/NodeInfo.dox | 116 ++- docs/user/storage/NodeMonitor.dox | 186 ++-- docs/user/storage/Path.dox | 105 ++- docs/user/storage/PathFinder.dox | 264 +++--- docs/user/storage/Query.dox | 152 ++- docs/user/storage/Resources.dox | 96 +- docs/user/storage/Statable.dox | 82 +- docs/user/storage/SymLink.dox | 59 +- docs/user/storage/Volume.dox | 87 +- docs/user/storage/VolumeRoster.dox | 28 +- 20 files changed, 3210 insertions(+), 1756 deletions(-) diff --git a/docs/user/storage/AppFileInfo.dox b/docs/user/storage/AppFileInfo.dox index 39e30659e5..d0cc58779d 100644 --- a/docs/user/storage/AppFileInfo.dox +++ b/docs/user/storage/AppFileInfo.dox @@ -1,5 +1,5 @@ /* - * Copyright 2011 Haiku, Inc. All rights reserved. + * Copyright 2011-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: @@ -7,8 +7,8 @@ * Ingo Weinhold, bonefish@users.sf.net * * Corresponds to: - * headers/os/storage/AppFileInfo.h rev 42274 - * src/kits/storage/AppFileInfo.cpp rev 42274 + * headers/os/storage/AppFileInfo.h hrev47402 + * src/kits/storage/AppFileInfo.cpp hrev47402 */ @@ -46,19 +46,23 @@ object will next look at the resource of the BFile. You can tell the BFileInfo object to look only in the attributes or resources with the SetInfoLocation() method. + + \since BeOS R3 */ /*! \fn BAppFileInfo::BAppFileInfo() \brief Creates an uninitialized BAppFileInfo object. + + \since BeOS R3 */ /*! \fn BAppFileInfo::BAppFileInfo(BFile* file) \brief Creates an BAppFileInfo object and initializes it to the supplied - file. + file. The caller retains ownership of the supplied BFile object. It must not be deleted during the life time of the BAppFileInfo. It is not deleted @@ -66,6 +70,8 @@ \param file The BFile object that the BAppFileInfo object shall be initialized to. + + \since BeOS R3 */ @@ -74,6 +80,8 @@ \brief Frees all resources associated with this object. The supplied BFile object is not deleted if one is specified. + + \since BeOS R3 */ @@ -91,6 +99,8 @@ \returns an status code. \retval B_OK Everything went fine. \retval B_BAD_VALUE \c NULL \a file or \a file is not properly initialized. + + \since BeOS R3 */ @@ -107,17 +117,19 @@ \brief Gets the MIME type of the associated file. \param type A pointer to a pre-allocated character buffer of size - \c B_MIME_TYPE_LENGTH or larger into which the MIME type of the - file will be written. + \c B_MIME_TYPE_LENGTH or larger into which the MIME type of the + file will be 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/resources is longer than \c B_MIME_TYPE_LENGTH. + attribute/resources is longer than \c B_MIME_TYPE_LENGTH. \retval B_BAD_TYPE The attribute/resources the type string is stored in - has the wrong type. + has the wrong type. \retval B_ENTRY_NOT_FOUND No type is set on the file. + + \since BeOS R3 */ @@ -128,13 +140,15 @@ If \a type is \c NULL if the file's MIME type is unset. \param type The MIME type to be assigned to the file. It must not be - longer than \c B_MIME_TYPE_LENGTH (including the terminating null). - The MIME type may be \c NULL. + longer than \c B_MIME_TYPE_LENGTH (including the terminating \0). + The MIME type may be \c NULL. \returns a status code. \retval B_OK Everything went fine. \retval B_NO_INIT The object is not properly initialized. \retval B_BAD_VALUE \a type is longer than \c B_MIME_TYPE_LENGTH. + + \since BeOS R3 */ @@ -154,17 +168,19 @@ \brief Gets the application signature of the associated file. \param signature A pointer to a pre-allocated character buffer of size - \c B_MIME_TYPE_LENGTH or larger into which the application - signature of the file will be written. + \c B_MIME_TYPE_LENGTH or larger into which the application + signature of the file will be 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 signature or the signature stored in the - attribute/resources is longer than \c B_MIME_TYPE_LENGTH. + attribute/resources is longer than \c B_MIME_TYPE_LENGTH. \retval B_BAD_TYPE The attribute/resources the signature is stored in have - the wrong type. + the wrong type. \retval B_ENTRY_NOT_FOUND No signature is set on the file. + + \since BeOS R3 */ @@ -175,13 +191,15 @@ If \a signature is \c NULL the file's application signature is unset. \param signature The application signature to be assigned to the file. - Must not be longer than \c B_MIME_TYPE_LENGTH (including the - terminating \c NUL). The \a signature may be \c NULL. + Must not be longer than \c B_MIME_TYPE_LENGTH (including the + terminating \0). The \a signature may be \c NULL. \returns a status code. \retval B_OK Everything went fine. \retval B_NO_INIT The object is not properly initialized. \retval B_BAD_VALUE \a signature is longer than \c B_MIME_TYPE_LENGTH. + + \since BeOS R3 */ @@ -201,17 +219,19 @@ \brief Gets the catalog entry of the associated file used for localization. \param catalogEntry A pointer to a pre-allocated character buffer of size - \c B_MIME_TYPE_LENGTH * 3 or larger into which the catalog entry - of the file will be written. + \c B_MIME_TYPE_LENGTH * 3 or larger into which the catalog entry + of the file will be 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 catalogEntry or the entry stored in the - attribute/resources is longer than \c B_MIME_TYPE_LENGTH * 3. + attribute/resources is longer than \c B_MIME_TYPE_LENGTH * 3. \retval B_BAD_TYPE The attribute/resources the entry is stored in have - the wrong type. + the wrong type. \retval B_ENTRY_NOT_FOUND No catalog entry is set on the file. + + \since Haiku R1 */ @@ -222,15 +242,17 @@ If \a catalogEntry is \c NULL the file's catalog entry is unset. \param catalogEntry The catalog entry to be assigned to the file. - Of the form "x-vnd.Haiku-app:context:name". Must not be longer than - \c B_MIME_TYPE_LENGTH * 3 (including the terminating \c NUL). - The \a catalogEntry may be \c NULL. + Of the form "x-vnd.Haiku-app:context:name". Must not be longer than + \c B_MIME_TYPE_LENGTH * 3 (including the terminating \0). + The \a catalogEntry may be \c NULL. \returns a status code. \retval B_OK Everything went fine. \retval B_NO_INIT The object is not properly initialized. \retval B_BAD_VALUE \a catalogEntry is longer than - \c B_MIME_TYPE_LENGTH * 3. + \c B_MIME_TYPE_LENGTH * 3. + + \since Haiku R1 */ @@ -250,15 +272,17 @@ \brief Gets the application \a flags of the associated file. \param flags A pointer to a pre-allocated \c uint32 into which the - application flags of the file are written. + application flags of the file are 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 flags. \retval B_BAD_TYPE The attribute/resources the flags are stored in have - the wrong type. + the wrong type. \retval B_ENTRY_NOT_FOUND No application flags are set on the file. + + \since BeOS R3 */ @@ -271,6 +295,8 @@ \returns A status code. \retval B_OK Everything went fine. \retval B_NO_INIT The object was not properly initialized. + + \since BeOS R3 */ @@ -281,6 +307,8 @@ \returns A status code. \retval B_OK Everything went fine. \retval B_NO_INIT The object was not properly initialized. + + \since Haiku R1 */ @@ -303,24 +331,26 @@ \c B_STRING_TYPE in \a types. \param types A pointer to a pre-allocated BMessage into which the - MIME types supported by the application will be written. + MIME types supported by the application will be 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 types. \retval B_BAD_TYPE The attribute/resources that the supported types - are stored in have the wrong type. + are stored in have the wrong type. \retval B_ENTRY_NOT_FOUND No supported types are set on the file. + + \since BeOS R3 */ /*! \fn status_t BAppFileInfo::SetSupportedTypes(const BMessage* types, bool updateMimeDB, bool syncAll) - \brief Sets the MIME types that are supported by the application and allows - you to specify whether or not the supported types in the MIME DB shall - be updated as well. + \brief Sets the MIME types that are supported by the application + and allows you to specify whether or not the supported types + in the MIME DB shall be updated as well. If \a types is \c NULL then the application's supported types are unset. @@ -338,15 +368,17 @@ is \c true. \param types The supported types to be assigned to the file. - May be \c NULL. + May be \c NULL. \param updateMimeDB \c true to update the supported types in the MIME DB, - \c false otherwise. + \c false otherwise. \param syncAll \c true to also synchronize the no-longer supported - types, \c false otherwise. + types, \c false otherwise. \returns A status code. \retval B_OK Everything went fine. \retval B_NO_INIT The object is not properly initialized. + + \since BeOS R3 */ @@ -354,8 +386,8 @@ \fn status_t BAppFileInfo::SetSupportedTypes(const BMessage* types, bool syncAll) \brief Sets the MIME types that are supported by the application and allows - you to specify whether or not the no longer supported types shall be - updated as well. + you to specify whether or not the no longer supported types shall be + updated as well. If \a types is \c NULL then the application's supported types are unset. @@ -372,13 +404,15 @@ from the list of supporting applications. \param types The supported types to be assigned to the file. - May be \c NULL. + May be \c NULL. \param syncAll \c true to also synchronize the no-longer supported - types, \c false otherwise. + types, \c false otherwise. \returns A status code. \retval B_OK Everything went fine. \retval B_NO_INIT The object is not properly initialized. + + \since BeOS R3 */ @@ -390,10 +424,12 @@ \see SetSupportedType(const BMessage*, bool) for detailed information. \param types The supported types to be assigned to the file. - May be \c NULL. + May be \c NULL. \returns A status code. \retval B_OK Everything went fine. \retval B_NO_INIT The object is not properly initialized. + + \since BeOS R3 */ @@ -408,6 +444,8 @@ \returns \c true if \a type is a valid MIME type and it is supported by the application, \c false otherwise. + + \since BeOS R3 */ @@ -424,6 +462,8 @@ \returns \c true if \a type is a valid MIME type and it is explicitly supported by the application, \c false otherwise. + + \since BeOS R3 */ @@ -440,21 +480,23 @@ /*! \fn status_t BAppFileInfo::GetIcon(BBitmap* icon, icon_size which) const - \brief Gets the icon of the associated file and puts it into a pre-allocated - BBitmap. + \brief Gets the icon of the associated file and puts it into a + pre-allocated BBitmap. \param icon A pointer to a pre-allocated BBitmap of the correct dimension - to store the requested icon (16x16 for the \c B_MINI_ICON and 32x32 - for the \c B_LARGE_ICON). + to store the requested icon (16x16 for the \c B_MINI_ICON and 32x32 + for the \c B_LARGE_ICON). \param which Specifies the size of the icon to be retrieved: - \c B_MINI_ICON for the mini and \c B_LARGE_ICON for the large icon. - For HVIF icons this parameter has no effect. + \c B_MINI_ICON for the mini and \c B_LARGE_ICON for the large icon. + For HVIF icons this parameter has no effect. \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 icon, unsupported icon size \a which or - bitmap dimensions (\a icon) and icon size (\a which) do not match. + bitmap dimensions (\a icon) and icon size (\a which) do not match. + + \since BeOS R3 */ @@ -464,12 +506,14 @@ \param data The pointer in which the flat icon data will be returned. \param size The pointer in which the size of the data found will be - returned. + returned. \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 data or \c NULL size. + + \since BeOS R3 */ @@ -481,20 +525,23 @@ If \a icon is \c NULL then the icon of the file is unset. \param icon A pointer to the BBitmap containing the icon to be set. - May be \c NULL to specify no icon. + May be \c NULL to specify no icon. \param which Specifies the size of the icon to be set: \c B_MINI_ICON for - 16x16 mini icon and \c B_LARGE_ICON for the 32x32 large icon. - For HVIF icons this parameter has no effect. + 16x16 mini icon and \c B_LARGE_ICON for the 32x32 large icon. + For HVIF icons this parameter has no effect. \param updateMimeDB \c true to also set the icon for the application in the - MIME DB. \c false otherwise. + MIME DB. \c false otherwise. \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 which or bitmap dimensions - (\a icon) and icon size (\a which) do not match. + (\a icon) and icon size (\a which) do not match. + + \since Haiku R1 */ + /*! \fn status_t BAppFileInfo::SetIcon(const BBitmap* icon, icon_size which) \brief Sets the icon of the associated file from a BBitmap. @@ -505,16 +552,18 @@ application signature. \param icon A pointer to the BBitmap containing the icon to be set. - May be \c NULL to specify no icon. + May be \c NULL to specify no icon. \param which Specifies the size of the icon to be set: \c B_MINI_ICON for - 16x16 mini icon and \c B_LARGE_ICON for the 32x32 large icon. - For HVIF icons this parameter has no effect. + 16x16 mini icon and \c B_LARGE_ICON for the 32x32 large icon. + For HVIF icons this parameter has no effect. \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 which or bitmap dimensions - (\a icon) and icon size (\a which) do not match. + (\a icon) and icon size (\a which) do not match. + + \since BeOS R3 */ @@ -526,15 +575,17 @@ If \a data is \c NULL then the icon of the file is unset. \param data A pointer to the data buffer containing the vector icon - to be set. May be \c NULL. + to be set. May be \c NULL. \param size Specifies the size of buffer pointed to by \a data. \param updateMimeDB \c true to also set the icon for the application in the - MIME DB. \c false otherwise. + MIME DB. \c false otherwise. \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 data. + + \since Haiku R1 */ @@ -548,13 +599,15 @@ application signature. \param data A pointer to the data buffer containing the vector icon - to be set. May be \c NULL. + to be set. May be \c NULL. \param size Specifies the size of buffer pointed to by \a data. \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 data. + + \since Haiku R1 */ @@ -562,23 +615,25 @@ \fn status_t BAppFileInfo::GetIconForType(const char* type, BBitmap* icon, icon_size size) const \brief Gets the icon the application provides for a given MIME type and - puts it into a BBitmap. + puts it into a BBitmap. \note If \a type is \c NULL, the application's icon is retrieved. \param type The MIME type in question. May be \c NULL. \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). + to store the requested icon (16x16 for the mini and 32x32 for the + large icon). \param size Specifies the size of the icon to be retrieved: - \c B_MINI_ICON for the mini and \c B_LARGE_ICON for the large icon. + \c B_MINI_ICON for the mini and \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 \c NULL \a icon, unsupported icon size - \a which or bitmap dimensions (\a icon) and icon size (\a which) do - not match. + \a which or bitmap dimensions (\a icon) and icon size (\a which) + do not match. + + \since BeOS R3 */ @@ -586,7 +641,7 @@ \fn status_t BAppFileInfo::GetIconForType(const char* type, uint8** data, size_t* size) const \brief Gets the icon the application provides for a given MIME type and - puts it into a buffer. + puts it into a buffer. \note If \a type is set to \c NULL the the application's icon is retrieved. @@ -599,7 +654,9 @@ \retval B_OK Everything went fine. \retval B_NO_INIT The object is not properly initialized. \retval B_BAD_VALUE \c NULL \a data and/or \a size. Or the supplied - \a type is not a valid MIME type. + \a type is not a valid MIME type. + + \since Haiku R1 */ @@ -607,7 +664,7 @@ \fn status_t BAppFileInfo::SetIconForType(const char* type, const BBitmap* icon, icon_size which, bool updateMimeDB) \brief Sets the icon the application provides for a given MIME type from a - BBitmap. + BBitmap. \note If \a type is \c NULL then the icon is set. \note If \a icon is \c NULL then the icon is unset. @@ -618,18 +675,20 @@ \param type The MIME type in question. May be \c NULL. \param icon A pointer to the BBitmap containing the icon to be set. - May be \c NULL. + May be \c NULL. \param which Specifies the size of the icon to be set: \c B_MINI_ICON - for the mini and \c B_LARGE_ICON for the large icon. + for the mini and \c B_LARGE_ICON for the large icon. \param updateMimeDB \c true to also set the icon for the type in the MIME - DB. \c false otherwise. + DB. \c false otherwise. \returns A status code. \retval B_OK Everything went fine. \retval B_NO_INIT The object is not properly initialized. \retval B_BAD_VALUE Either the icon size \a which is unknown, - the bitmap dimensions (\a icon) and icon size (\a which) do not - match, or the provided \a type is not a valid MIME type. + the bitmap dimensions (\a icon) and icon size (\a which) do not + match, or the provided \a type is not a valid MIME type. + + \since Haiku R1 */ @@ -637,7 +696,7 @@ \fn status_t BAppFileInfo::SetIconForType(const char* type, const BBitmap* icon, icon_size which) \brief Sets the icon the application provides for a given MIME type from a - BBitmap. + BBitmap. \note If \a type is \c NULL then the icon is set. \note If \a icon is \c NULL then the icon is unset. @@ -656,8 +715,10 @@ \retval B_OK Everything went fine. \retval B_NO_INIT The object is not properly initialized. \retval B_BAD_VALUE Either the icon size \a which is unknown, - the bitmap dimensions (\a icon) and icon size (\a which) do not - match, or the provided \a type is not a valid MIME type. + the bitmap dimensions (\a icon) and icon size (\a which) do not + match, or the provided \a type is not a valid MIME type. + + \since BeOS R3 */ @@ -665,7 +726,7 @@ \fn status_t BAppFileInfo::SetIconForType(const char* type, const uint8* data, size_t size, bool updateMimeDB) \brief Sets the icon the application provides for a given MIME type from a - buffer. + buffer. \note If \a type is \c NULL then the icon is set. \note If \a data is \c NULL then the icon is unset. @@ -676,15 +737,17 @@ \param type The MIME type in question. May be \c NULL. \param data A pointer to the data containing the icon to be set. - May be \c NULL. + May be \c NULL. \param size Specifies the size of buffer provided in \a data. \param updateMimeDB \c true to also set the icon for the type in the MIME - DB. \c false otherwise. + DB. \c false otherwise. \returns A status code. \retval B_OK Everything went fine. \retval B_NO_INIT The object is not properly initialized. \retval B_BAD_VALUE The provided \a type is not a valid MIME type. + + \since Haiku R1 */ @@ -692,7 +755,7 @@ \fn status_t BAppFileInfo::SetIconForType(const char* type, const uint8* data, size_t size) \brief Sets the icon the application provides for a given MIME type from a - buffer. + buffer. \note If \a type is \c NULL then the icon is set. \note If \a data is \c NULL then the icon is unset. @@ -703,13 +766,15 @@ \param type The MIME type in question. May be \c NULL. \param data A pointer to the data containing the icon to be set. - May be \c NULL. + May be \c NULL. \param size Specifies the size of buffer provided in \a data. \returns A status code. \retval B_OK Everything went fine. \retval B_NO_INIT The object is not properly initialized. \retval B_BAD_VALUE The provided \a type is not a valid MIME type. + + \since Haiku R1 */ @@ -740,6 +805,8 @@ \retval B_OK Everything went fine. \retval B_NO_INIT The object is not properly initialized. \retval B_BAD_VALUE \c NULL \a info. + + \since BeOS R3 */ @@ -759,6 +826,8 @@ \returns A status code. \retval B_OK Everything went fine. \retval B_NO_INIT The object is not properly initialized. + + \since BeOS R3 */ @@ -783,6 +852,8 @@ - \c B_USE_BOTH_LOCATIONS: Store the data in attributes and resources. \param location The location where the metadata shall be stored. + + \since BeOS R3 */ @@ -793,6 +864,8 @@ \returns \c true if the metadata are (also) stored in the file's attributes, \c false otherwise. + + \since BeOS R3 */ @@ -803,111 +876,9 @@ \returns \c true if the metadata are (also) stored in the file's resources, \c false otherwise. + + \since BeOS R3 */ //! @} - - -/*! - \fn BAppFileInfo & BAppFileInfo::operator=(const BAppFileInfo &) - \brief Privatized assignment operator to prevent usage. -*/ - - -/*! - \fn BAppFileInfo::BAppFileInfo(const BAppFileInfo &) - \brief Privatized copy constructor to prevent usage. -*/ - - -/*! - \fn status_t BAppFileInfo::GetMetaMime(BMimeType* meta) const - \brief Initializes a BMimeType to the signature of the associated file. - - \warning The parameter \a meta is not checked. - - \param meta A pointer to a pre-allocated BMimeType that shall be - initialized to the signature of the associated file. - - \returns A status code. - \retval B_OK Everything went fine. - \retval B_BAD_VALUE \c NULL \a meta - \retval B_ENTRY_NOT_FOUND The file has not signature or the signature is - (not installed in the MIME database.) no valid MIME string. -*/ - - -/*! - \fn status_t BAppFileInfo::_ReadData(const char* name, int32 id, - type_code type, void* buffer, size_t bufferSize, - size_t &bytesRead, void** allocatedBuffer) const - \brief Reads data from an attribute or resource. - - \note The data is read from the location specified by \a fWhere. - - \warning The object must be properly initialized. The parameters are - \b NOT checked. - - \param name The name of the attribute/resource to be read. - \param id The resource ID of the resource to be read. It is ignored - when < 0. - \param type The type of the attribute/resource to be read. - \param buffer A pre-allocated buffer for the data to be read. - \param bufferSize The size of the supplied buffer. - \param bytesRead A reference parameter, set to the number of bytes - actually read. - \param allocatedBuffer If not \c NULL, the method allocates a buffer - large enough too store the whole data and writes a pointer to it - into this variable. If \c NULL, the supplied buffer is used. - - \returns A status code. - \retval B_OK Everything went fine. - \retval B_ENTRY_NOT_FOUND The entry was not found. - \retval B_NO_MEMORY Ran out of memory allocating the buffer. - \retval B_BAD_VALUE \a type did not match. -*/ - - -/*! - \fn status_t BAppFileInfo::_WriteData(const char* name, int32 id, - type_code type, const void* buffer, size_t bufferSize, bool findID) - \brief Writes data to an attribute or resource. - - \note The data is written to the location(s) specified by \a fWhere. - - \warning The object must be properly initialized. The parameters are - \b NOT checked. - - \param name The name of the attribute/resource to be written. - \param id The resource ID of the resource to be written. - \param type The type of the attribute/resource to be written. - \param buffer A buffer containing the data to be written. - \param bufferSize The size of the supplied buffer. - \param findID If set to \c true use the ID that is already assigned to the - \a name / \a type pair or take the first unused ID >= \a id. - If \c false, \a id is used. - - \returns A status code. - \retval B_OK Everything went fine. - \retval B_ERROR An error occurred while trying to write the data. -*/ - - -/*! - \fn status_t BAppFileInfo::_RemoveData(const char* name, type_code type) - \brief Removes an attribute or resource. - - \note The removal location is specified by \a fWhere. - - \warning The object must be properly initialized. The parameters are - \b NOT checked. - - \param name The name of the attribute/resource to be remove. - \param type The type of the attribute/resource to be removed. - - \returns A status code. - \retval B_OK Everything went fine. - \retval B_NO_INIT Not using attributes and not using resources. - \retval B_ENTRY_NOT_FOUND The attribute or resource was not found. -*/ diff --git a/docs/user/storage/Directory.dox b/docs/user/storage/Directory.dox index 98b1f19d90..6f75b88316 100644 --- a/docs/user/storage/Directory.dox +++ b/docs/user/storage/Directory.dox @@ -1,5 +1,5 @@ /* - * Copyright 2011 Haiku, Inc. All rights reserved. + * Copyright 2011-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: @@ -9,8 +9,8 @@ * John Scipione, jscipione@gmail.com * * Corresponds to: - * headers/os/storage/Directory.h hrev43528 - * src/kits/storage/Directory.cpp hrev43528 + * headers/os/storage/Directory.h hrev47402 + * src/kits/storage/Directory.cpp hrev47402 */ @@ -27,12 +27,16 @@ \ingroup storage \ingroup libbe \brief A directory in the file system. + + \since BeOS R3 */ /*! \fn BDirectory::BDirectory() \brief Creates an uninitialized BDirectory object. + + \since BeOS R3 */ @@ -41,52 +45,64 @@ \brief Creates a copy of the supplied BDirectory object. \param dir The BDirectory object to be copied. + + \since BeOS R3 */ /*! \fn BDirectory::BDirectory(const entry_ref* ref) \brief Creates a BDirectory and initializes it to the directory referred - to by the supplied entry_ref. + to by the supplied entry_ref. \param ref The entry_ref that refers to the directory. + + \since BeOS R3 */ /*! \fn BDirectory::BDirectory(const node_ref* nref) \brief Creates a BDirectory and initializes it to the directory referred - to by the supplied node_ref. + to by the supplied node_ref. \param nref The node_ref that refers to the directory. + + \since BeOS R3 */ /*! \fn BDirectory::BDirectory(const BEntry* entry) \brief Creates a BDirectory and initializes it to the directory referred - to by the supplied BEntry. + to by the supplied BEntry. \param entry The BEntry that refers to the directory. + + \since BeOS R3 */ /*! \fn BDirectory::BDirectory(const char* path) \brief Creates a BDirectory and initializes it to the directory referred - to by the supplied \a path name. + to by the supplied \a path name. \param path The \a path name of the directory. + + \since BeOS R3 */ /*! \fn BDirectory::BDirectory(const BDirectory* dir, const char* path) \brief Creates a BDirectory and initializes it to the directory referred - to by the supplied path name relative to the specified BDirectory. + to by the supplied path name relative to the specified BDirectory. \param dir The base BDirectory object. \param path The \a path of the directory relative to \a dir + + \since BeOS R3 */ @@ -96,13 +112,15 @@ If the BDirectory is properly initialized, the directory's file descriptor is closed. + + \since BeOS R3 */ /*! \fn status_t BDirectory::SetTo(const entry_ref* ref) \brief Re-initializes the BDirectory to the directory referred to by the - supplied entry_ref. + supplied entry_ref. \param ref The entry_ref referring to the directory. @@ -116,13 +134,15 @@ \retval B_BUSY A node was busy. \retval B_FILE_ERROR A general file error. \retval B_NO_MORE_FDS The application has run out of file descriptors. + + \since BeOS R3 */ /*! \fn status_t BDirectory::SetTo(const node_ref* nref) \brief Re-initializes the BDirectory to the directory referred to by the - supplied node_ref. + supplied node_ref. \param nref The node_ref referring to the directory. @@ -136,13 +156,15 @@ \retval B_BUSY A node was busy. \retval B_FILE_ERROR A general file error. \retval B_NO_MORE_FDS The application has run out of file descriptors. + + \since BeOS R3 */ /*! \fn status_t BDirectory::SetTo(const BEntry* entry) \brief Re-initializes the BDirectory to the directory referred to by the - supplied BEntry. + supplied BEntry. \param entry The BEntry referring to the directory. @@ -156,13 +178,15 @@ \retval B_BUSY A node was busy. \retval B_FILE_ERROR A general file error. \retval B_NO_MORE_FDS The application has run out of file descriptors. + + \since BeOS R3 */ /*! \fn status_t BDirectory::SetTo(const char* path) \brief Re-initializes the BDirectory to the directory referred to by the - supplied path name. + supplied path name. \param path The directory's \a path name. @@ -178,13 +202,15 @@ \retval B_FILE_ERROR A general file error. \retval B_NO_MORE_FDS The application has run out of file descriptors. \retval B_NOT_A_DIRECTORY \a path includes a non-directory. + + \since BeOS R3 */ /*! \fn status_t BDirectory::SetTo(const BDirectory* dir, const char* path) \brief Re-initializes the BDirectory to the directory referred to by the - supplied path name relative to the specified BDirectory. + supplied path name relative to the specified BDirectory. \param dir The base directory. \param path The directory path name relative to \a dir. @@ -201,13 +227,15 @@ \retval B_FILE_ERROR A general file error. \retval B_NO_MORE_FDS The application has run out of file descriptors. \retval B_NOT_A_DIRECTORY \a path includes a non-directory. + + \since BeOS R3 */ /*! \fn status_t BDirectory::GetEntry(BEntry* entry) const \brief Gets a BEntry object referring to the directory. If the - initialization of \a entry fails, it is Unset(). + initialization of \a entry fails, it is Unset(). \param entry A pointer to the \a entry that will refer to the directory. @@ -221,6 +249,8 @@ \retval B_BUSY A node was busy. \retval B_FILE_ERROR A general file error. \retval B_NO_MORE_FDS The application has run out of file descriptors. + + \since BeOS R3 */ @@ -229,7 +259,9 @@ \brief Returns whether the directory is the root directory of a volume. \returns \c true if the BDirectory is properly initialized and represents - a root directory of a volume, \c false otherwise. + a root directory of a volume, \c false otherwise. + + \since BeOS R3 */ @@ -237,18 +269,18 @@ \fn status_t BDirectory::FindEntry(const char* path, BEntry* entry, bool traverse) const \brief Finds an entry referred to by a path relative to the directory - represented by this BDirectory. + represented by this BDirectory. \a path may represent an absolute path. If the BDirectory is not properly initialized then the entry is relative to the current directory. If the entry couldn't be found, \a entry is Unset(). \note The functionality of this method differs from - BEntry::SetTo(BDirectory *, const char *, bool) in that it doesn't - require the entry to exist, whereas this method does. + BEntry::SetTo(BDirectory *, const char *, bool) in that it doesn't + require the entry to exist, whereas this method does. \param path The entry's \a path name. May be relative to this directory - or an absolute path. + or an absolute path. \param entry A pointer to a BEntry to be initialized with the found entry. \param traverse Whether or not to follow a symbolic link. @@ -266,69 +298,77 @@ \retval B_NOT_A_DIRECTORY \a path includes a non-directory. \sa BEntry::SetTo(BDirectory *, const char *, bool) + + \since BeOS R3 */ /*! \fn bool BDirectory::Contains(const char* path, int32 nodeFlags) const \brief Returns whether or not this directory or any of its subdirectories - at any level contain the entry referred to by the supplied path name. + at any level contain the entry referred to by the supplied path + name. Only entries that match the node flavor specified by \a nodeFlags are considered. - If the BDirectory is not properly initialized, the method returns \c false. - A non-absolute path is considered relative to the current directory. + If the BDirectory is not properly initialized, the method returns + \c false. A non-absolute path is considered relative to the current + directory. - \note R5's implementation always returns \c true given an absolute path - or an unitialized directory. This implementation is not compatible - with that behavior. Instead it converts the path into a BEntry and - passes it to the other version of Contains(). + \note BeOS R5's implementation always returns \c true given an absolute + path or an initialized directory. This implementation is not + compatible with that behavior. Instead it converts the path into + a BEntry and passes it to the other version of Contains(). \param path The entry's \a path name. May be relative to this directory - or may be an absolute \a path. + or may be an absolute \a path. \param nodeFlags Any of the following: - - \c B_FILE_NODE: The entry must be a file. - - \c B_DIRECTORY_NODE: The entry must be a directory. - - \c B_SYMLINK_NODE: The entry must be a symbolic link. - - \c B_ANY_NODE: The entry may be of any kind. + - \c B_FILE_NODE: The entry must be a file. + - \c B_DIRECTORY_NODE: The entry must be a directory. + - \c B_SYMLINK_NODE: The entry must be a symbolic link. + - \c B_ANY_NODE: The entry may be of any kind. \returns \c true if the entry exists and its kind does match \a nodeFlags - and the BDirectory is properly initialized and does contain the entry - at any level, \c false otherwise. + and the BDirectory is properly initialized and does contain the + entry at any level, \c false otherwise. + + \since BeOS R3 */ /*! \fn bool BDirectory::Contains(const BEntry* entry, int32 nodeFlags) const \brief Returns whether or not this directory or any of its subdirectories - at any level contain the entry referred to by the supplied BEntry. - + at any level contain the entry referred to by the supplied BEntry. + Only entries that match the node flavor specified by \a nodeFlags are considered. \note If the paths are identical, this method returns \c true to stay - consistent with BeOS 5. + consistent with BeOS 5. \param entry a BEntry referring to the entry \param nodeFlags Any of the following: - - \c B_FILE_NODE: The entry must be a file. - - \c B_DIRECTORY_NODE: The entry must be a directory. - - \c B_SYMLINK_NODE: The entry must be a symbolic link. - - \c B_ANY_NODE: The entry may be of any kind. + - \c B_FILE_NODE: The entry must be a file. + - \c B_DIRECTORY_NODE: The entry must be a directory. + - \c B_SYMLINK_NODE: The entry must be a symbolic link. + - \c B_ANY_NODE: The entry may be of any kind. \returns \c true if the BDirectory is properly initialized and the - entry of the matching kind was found, \c false otherwise. + entry of the matching kind was found, \c false otherwise. + + \since BeOS R3 */ /*! \fn status_t BDirectory::GetStatFor(const char* path, struct stat* st) const \brief Returns the stat structure of the entry referred to by the supplied - path name. + path name. \param path The entry's path name. May be relative to this directory or - absolute, or \c NULL to get the directories stat info. + absolute, or \c NULL to get the directories stat info. \param st A pointer to the stat structure to be filled in by this method. \returns A status code. @@ -343,6 +383,8 @@ \retval B_FILE_ERROR A general file error. \retval B_NO_MORE_FDS The application has run out of file descriptors. \retval B_NOT_A_DIRECTORY \a path includes a non-directory. + + \since BeOS R3 */ @@ -353,7 +395,7 @@ Unlike GetNextDirents() this method ignores "." and "..". \note The iterator used by this method is the same one used by - GetNextRef(), GetNextDirents(), Rewind() and CountEntries(). + GetNextRef(), GetNextDirents(), Rewind() and CountEntries(). \param entry A pointer to a BEntry to be initialized to the found entry \param traverse Specifies whether or not to follow a symbolic link. @@ -368,6 +410,8 @@ \retval B_BUSY A node was busy. \retval B_FILE_ERROR A general file error. \retval B_NO_MORE_FDS The application has run out of file descriptors. + + \since BeOS R3 */ @@ -378,10 +422,10 @@ Unlike GetNextDirents() this method ignores "." and "..". \note The iterator used be this method is the same one used by - GetNextEntry(), GetNextDirents(), Rewind() and CountEntries(). + GetNextEntry(), GetNextDirents(), Rewind() and CountEntries(). \param ref A pointer to an entry_ref to be filled in with the data - from the found entry. + from the found entry. \returns A status code. \retval B_OK Everything went fine. @@ -393,27 +437,31 @@ \retval B_BUSY A node was busy. \retval B_FILE_ERROR A general file error. \retval B_NO_MORE_FDS The application has run out of file descriptors. + + \since BeOS R3 */ /*! - \fn int32 BDirectory::GetNextDirents(dirent* buf, size_t bufSize, int32 count) + \fn int32 BDirectory::GetNextDirents(dirent* buf, size_t bufSize, + int32 count) \brief Returns the next entries of the BDirectory object as a pointer - to dirent structures. + to dirent structures. Unlike GetNextEntry() and GetNextRef(), this method returns also the entries "." and "..". \note The iterator used by this method is the same one used by - GetNextEntry(), GetNextRef(), Rewind() and CountEntries(). + GetNextEntry(), GetNextRef(), Rewind() and CountEntries(). \param buf A pointer to a buffer filled with dirent structures containing - the found entries. + the found entries. \param bufSize The size of \a buf. \param count The maximum number of entries to be returned. \returns The number of dirent structures stored in the buffer, 0 when - there are no more entries to be returned or a status code on error. + there are no more entries to be returned or a status code on + error. \retval B_BAD_VALUE \c NULL \a buf. \retval B_PERMISSION_DENIED Directory permissions didn't allow operation. \retval B_NO_MEMORY Insufficient memory for operation. @@ -422,6 +470,8 @@ \retval B_BUSY A node was busy. \retval B_FILE_ERROR A general file error. \retval B_NO_MORE_FDS The application has run out of file descriptors. + + \since BeOS R3 */ @@ -442,6 +492,8 @@ \sa BDirectory::GetNextRef() \sa BDirectory::GetNextDirents() \sa BDirectory::CountEntries() + + \since BeOS R3 */ @@ -454,7 +506,7 @@ the entries and Rewind()s again. The entries "." and ".." are not counted. \returns The number of entries in the directory (not counting "." and - "..") or a status code on error. + "..") or a status code on error. \retval B_PERMISSION_DENIED Directory permissions didn't allow operation. \retval B_NO_MEMORY Insufficient memory for operation. \retval B_LINK_LIMIT Indicates a cyclic loop within the file system. @@ -466,6 +518,8 @@ \sa BDirectory::GetNextRef() \sa BDirectory::GetNextDirents() \sa BDirectory::Rewind() + + \since BeOS R3 */ @@ -477,9 +531,9 @@ an error status code. \param path The new path name of the directory. May be a relative - path to this directory or an absolute path. + path to this directory or an absolute path. \param dir A pointer to a BDirectory to be initialized to the newly - created directory. May be \c NULL. + created directory. May be \c NULL. \returns A status code. \retval B_OK Everything went fine. @@ -492,6 +546,8 @@ \retval B_FILE_ERROR A general file error. \retval B_FILE_EXISTS An entry with that name does already exist. \retval B_NO_MORE_FDS The application has run out of file descriptors. + + \since BeOS R3 */ @@ -506,9 +562,9 @@ mode. \param path The new file's path name. May be relative to this - directory or an absolute path. + directory or an absolute path. \param file A pointer to a BFile to be initialized to the newly - created file. May be \c NULL. + created file. May be \c NULL. \param failIfExists Whether or not to fail if the file already exists. \returns A status code. @@ -521,10 +577,12 @@ \retval B_BUSY A node was busy. \retval B_FILE_ERROR A general file error. \retval B_FILE_EXISTS A file with that name does already exist and - \c true has been passed for \a failIfExists. + \c true has been passed for \a failIfExists. \retval B_IS_A_DIRECTORY A directory with the supplied name already - exists. + exists. \retval B_NO_MORE_FDS The application has run out of file descriptors. + + \since BeOS R3 */ @@ -536,10 +594,10 @@ This method fails if an entry with the supplied name already exists. \param path the new symbolic link's path name. May be relative to this - directory or absolute. + directory or absolute. \param linkToPath the path the symbolic link shall point to. \param link a pointer to a BSymLink to be initialized to the newly - created symbolic link. May be \c NULL. + created symbolic link. May be \c NULL. \returns A status code. \retval B_OK Everything went fine. @@ -552,6 +610,8 @@ \retval B_FILE_ERROR A general file error. \retval B_FILE_EXISTS An entry with that name does already exist. \retval B_NO_MORE_FDS The application has run out of file descriptors. + + \since BeOS R3 */ @@ -566,6 +626,8 @@ \param dir The original BDirectory object. \returns A reference to this BDirectory object. + + \since BeOS R3 */ @@ -577,6 +639,8 @@ member directly. \returns the file descriptor, or -1 if not properly initialized. + + \since Haiku R1 */ @@ -586,7 +650,7 @@ \param path The directory path name. \param mode A permission specification, which shall be used for the - newly created directories. + newly created directories. \returns A status code. \retval B_OK Everything went fine. @@ -598,6 +662,8 @@ \retval B_BUSY A node was busy. \retval B_FILE_ERROR A general file error. \retval B_NOT_A_DIRECTORY An entry other than a directory with that name - already exists. + already exists. \retval B_NO_MORE_FDS The application has run out of file descriptors. + + \since BeOS R3 */ diff --git a/docs/user/storage/Entry.dox b/docs/user/storage/Entry.dox index d4b25ef9f6..f6c6db3ea2 100644 --- a/docs/user/storage/Entry.dox +++ b/docs/user/storage/Entry.dox @@ -1,5 +1,5 @@ /* - * Copyright 2011 Haiku, Inc. All rights reserved. + * Copyright 2011-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: @@ -8,8 +8,8 @@ * John Scipione, jscipione@gmail.com * * Corresponds to: - * headers/os/storage/Entry.h hrev43528 - * src/kits/storage/Entry.cpp hrev43528 + * headers/os/storage/Entry.h hrev47402 + * src/kits/storage/Entry.cpp hrev47402 */ @@ -45,28 +45,34 @@ the old name (the upside in this case is that abstract entries may be represented by entry_refs without preallocating an internal filesystem node for them). + + \since BeOS R3 */ /*! \fn entry_ref::entry_ref() \brief Creates an uninitialized entry_ref object. + + \since BeOS R3 */ /*! \fn entry_ref::entry_ref(dev_t dev, ino_t dir, const char* name) \brief Creates an entry_ref object initialized to the given file name in - the given directory on the given device. + the given directory on the given device. \a name may refer to either a pre-existing file in the given directory, or a non-existent file. No explicit checking is done to verify validity of the given arguments, but later use of the entry_ref will fail if \p dev is not a valid device or \a dir is a not a directory on \p dev. - \param dev the device on which the entry's parent directory resides - \param dir the directory in which the entry resides - \param name the leaf name of the entry, which is not required to exist + \param dev The \a device on which the entry's parent directory resides. + \param dir The directory in which the entry resides. + \param name The leaf name of the entry, which is not required to exist. + + \since BeOS R3 */ @@ -75,41 +81,51 @@ \brief Returns a copy of the passed in entry_ref object. \param ref A reference to an entry_ref to copy. + + \since BeOS R3 */ /*! \fn entry_ref::~entry_ref() \brief Destroys the object and frees the storage allocated for the leaf - name, if necessary. + name, if necessary. + + \since BeOS R3 */ /*! \fn status_t entry_ref::set_name(const char* name) \brief Set the entry_ref's leaf name, freeing the storage allocated for any - previous name and then making a copy of the new name. + previous name and then making a copy of the new name. \param name Pointer to a null-terminated string containing the new name for - the entry. May be \c NULL. + the entry. May be \c NULL. + + \since BeOS R3 */ /*! \fn bool entry_ref::operator==(const entry_ref& ref) const \brief Compares the entry_ref object with the passed in entry_ref, - returning \c true if they are equal. + returning \c true if they are equal. \returns \c true if he entry_refs are equal, \c false otherwise. + + \since BeOS R3 */ /*! \fn bool entry_ref::operator!=(const entry_ref& ref) const \brief Compares the entry_ref object with the passed in entry_ref, - returning \c true if they are NOT equal. + returning \c true if they are NOT equal. \returns \c true if the entry_refs are NOT equal, \c false otherwise. + + \since BeOS R3 */ @@ -120,6 +136,8 @@ \param ref The entry_ref to copy. \returns A pointer to the resulting entry_ref copy. + + \since BeOS R5 */ @@ -128,6 +146,7 @@ The device id of the storage device on which the entry resides. + \since BeOS R3 */ @@ -135,6 +154,8 @@ \var ino_t entry_ref::directory The inode number of the directory in which the entry resides. + + \since BeOS R3 */ @@ -142,6 +163,8 @@ \var char *entry_ref::name The leaf name of the entry + + \since BeOS R3 */ @@ -170,10 +193,13 @@ BEntry entry("/boot/home/fido"); Should be followed by a call to one of the SetTo() methods, or an assignment. - - SetTo(const BDirectory*, const char*, bool) - - SetTo(const entry_ref*, bool) - - SetTo(const char*, bool) - - operator=(const BEntry&) + + \sa SetTo(const BDirectory*, const char*, bool) + \sa SetTo(const entry_ref*, bool) + \sa SetTo(const char*, bool) + \sa operator=(const BEntry&) + + \since BeOS R3 */ @@ -191,6 +217,8 @@ BEntry entry("/boot/home/fido"); \param traverse Whether or not to traverse symbolic links. \see BEntry::SetTo(const BDirectory*, const char *, bool) + + \since BeOS R3 */ @@ -207,6 +235,8 @@ BEntry entry("/boot/home/fido"); \param traverse Whether or not symlinks are to be traversed. \sa BEntry::SetTo(const entry_ref*, bool) + + \since BeOS R3 */ @@ -223,6 +253,8 @@ BEntry entry("/boot/home/fido"); \param traverse Whether or not symlinks are to be traversed. \sa BEntry::SetTo(const char*, bool) + + \since BeOS R3 */ @@ -233,6 +265,8 @@ BEntry entry("/boot/home/fido"); \param entry the entry to be copied \sa operator=(const BEntry&) + + \since BeOS R3 */ @@ -241,6 +275,8 @@ BEntry entry("/boot/home/fido"); \brief Frees all of the allocated resources of the BEntry. \sa Unset() + + \since BeOS R3 */ @@ -251,7 +287,9 @@ BEntry entry("/boot/home/fido"); \returns A status code. \retval B_OK Success \retval B_NO_INIT The object has been Unset() or is uninitialized. -*/ + + \since BeOS R3 + /*! @@ -259,6 +297,8 @@ BEntry entry("/boot/home/fido"); \brief Returns whether or not the entry exists in the filesystem. \returns \c true if the entry exists, \c false if not. + + \since BeOS R3 */ @@ -276,6 +316,8 @@ BEntry entry("/boot/home/fido"); information is copied. \returns \c B_OK on success, or an error code on failure. + + \since BeOS R3 */ @@ -283,20 +325,22 @@ BEntry entry("/boot/home/fido"); \fn status_t BEntry::SetTo(const BDirectory* dir, const char* path, bool traverse) \brief Reinitializes the BEntry to the path or directory path combination, - resolving symlinks if traverse is \c true. + resolving symlinks if traverse is \c true. \param dir The base directory in which the \a path resides. \param path Relative path based off of \a dir. \param traverse Whether or not to traverse symbolic links. \returns \c B_OK on success, or an error code on failure. + + \since BeOS R3 */ /*! \fn status_t BEntry::SetTo(const entry_ref* ref, bool traverse) \brief Reinitializes the BEntry to the passed in entry_ref object - resolving symlinks if traverse is \c true. + resolving symlinks if traverse is \c true. \param ref The entry_ref referring to the given file. \param traverse Whether or not symlinks are to be traversed. @@ -304,13 +348,15 @@ BEntry entry("/boot/home/fido"); \returns \c B_OK on success, or an error code on failure. \sa BEntry::BEntry(const entry_ref* ref, bool traverse) + + \since BeOS R3 */ /*! \fn status_t BEntry::SetTo(const char* path, bool traverse) \brief Reinitializes the BEntry object to the path, resolving symlinks if - traverse is \c true. + traverse is \c true. \param path The path of the file. \param traverse Whether or not symlinks are to be traversed. @@ -318,12 +364,16 @@ BEntry entry("/boot/home/fido"); \returns \c B_OK on success, or an error code on failure. \sa BEntry::BEntry(const char* path, bool traverse) + + \since BeOS R3 */ /*! void BEntry::Unset() \brief Reinitializes the BEntry to an uninitialized BEntry object + + \since BeOS R3 */ @@ -335,6 +385,8 @@ BEntry entry("/boot/home/fido"); result is copied. \returns \c B_OK on success, or an error code on failure. + + \since BeOS R3 */ @@ -346,6 +398,8 @@ BEntry entry("/boot/home/fido"); result is copied. \returns \c B_OK on success, or an error code on failure. + + \since BeOS R3 */ @@ -382,12 +436,14 @@ if (err != B_ENTRY_NOT_FOUND) \endcode \param entry A pointer to a pre-allocated BEntry object into which the - result is stored. + result is stored. \returns A status code. \retval B_OK Success \retval B_ENTRY_NOT_FOUND Attempted to get the parent of the root - directory. + directory. + + \since BeOS R3 */ @@ -398,12 +454,14 @@ if (err != B_ENTRY_NOT_FOUND) If the function fails, the argument is Unset(). \param dir A pointer to a pre-allocated BDirectory object into which the - result is copied. + result is copied. \returns A status code. \retval B_OK Success \retval B_ENTRY_NOT_FOUND Attempted to get the parent of the root - directory. + directory. + + \since BeOS R3 */ @@ -415,32 +473,36 @@ if (err != B_ENTRY_NOT_FOUND) entire string. A length of \c B_FILE_NAME_LENGTH is recommended. \param buffer A pointer to a pre-allocated string into which the result - is copied. + is copied. \returns \c B_OK on success, or an error code on failure. + + \since BeOS R3 */ /*! \fn status_t BEntry::Rename(const char* path, bool clobber) \brief Renames the BEntry to \a path replacing an existing entry - if \a clobber is \c true. + if \a clobber is \c true. \note The BEntry object must refer to an existing file, if it is abstract, - this method will fail. + this method will fail. \param path A pointer to a string containing the new name for the entry. - It may be an absolute or relative path. If it is a relative path the - entry is renamed within its current directory. + It may be an absolute or relative path. If it is a relative path + the entry is renamed within its current directory. \param clobber If \c false and a file with the name given by \c path - already exists, the method will fail. If \c true and such a file - exists, it will be overwritten. + already exists, the method will fail. If \c true and such a file + exists, it will be overwritten. \returns A status code. \retval B_OK Success \retval B_ENTRY_EXISTS The new location already exists and \c clobber - is \c false. + is \c false. \retval B_ENTRY_NOT_FOUND Attempted to rename an abstract entry. + + \since BeOS R3 */ @@ -454,19 +516,21 @@ if (err != B_ENTRY_NOT_FOUND) this method will fail. \param dir A pointer to a pre-allocated BDirectory into which the entry - should be moved. + should be moved. \param path (optional) new leaf name for the entry. May be a simple leaf - or a relative path; either way, \c path is reckoned off of \c dir. If - \c NULL, the entry retains its previous leaf name. + or a relative path; either way, \c path is reckoned off of \c dir. + If \c NULL, the entry retains its previous leaf name. \param clobber If \c false and an entry already exists at the specified - destination, the method will fail. If \c true and such an entry exists, - it will be overwritten. + Spdestination, the method will fail. If \c true and such an entry + exists, it will be overwritten. \returns A status code. \retval B_OK Success \retval B_ENTRY_EXISTS The new location already exists and \c clobber - is \c false. + is \c false. \retval B_ENTRY_NOT_FOUND Attempted to rename an abstract entry. + + \since BeOS R3 */ @@ -480,28 +544,36 @@ if (err != B_ENTRY_NOT_FOUND) no longer refers to any actual data in the filesystem. \returns \c B_OK on success, or an error code on failure. + + \since BeOS R3 */ /*! \fn bool BEntry::operator==(const BEntry& item) const \brief Returns \c true if the BEntry and \a item refer to the same entry - or if they are both uninitialized. + or if they are both uninitialized. + \returns Whether or not the items refer to the same entry. \retval true Both BEntry objects refer to the same entry or they are - both uninitialized. + both uninitialized. \retval false The BEntry objects refer to different entries. + + \since BeOS R3 */ /*! \fn bool BEntry::operator!=(const BEntry& item) const \brief Returns false if the BEntry and \c item refer to the same entry or - if they are both uninitialized. + if they are both uninitialized. + \returns Whether or not the items do NOT refer to the same entry. \retval true The BEntry objects refer to different entries. \retval false Both BEntry objects refer to the same entry or they are - both uninitialized. + both uninitialized. + + \since BeOS R3 */ @@ -510,91 +582,8 @@ if (err != B_ENTRY_NOT_FOUND) \brief Reinitializes the BEntry to be a copy of \a item. \returns A pointer to the copy. -*/ - -/*! - \fn status_t BEntry::set_stat(struct stat& st, uint32 what) - \brief Updates the BEntry with the data from the stat structure according - to the \a what mask. - - \param st The stat structure to set. - \param what A mask - - \returns A status code. - \retval B_OK Everything went fine. - \retval B_FILE_ERROR There was an error writing to the BEntry object. -*/ - - -/*! - \fn status_t BEntry::_SetTo(int dirFD, const char* path, bool traverse) - \brief Sets the entry to point to the entry specified by the path \a path - relative to the given directory. - - If \a traverse is \c true and the given entry is a symbolic link, the - object is recursively set to point to the entry pointed to by the symlink. - - If \a path is an absolute path, \a dirFD is ignored. - - If \a dirFD is -1, \a path is considered relative to the current directory - (unless it is an absolute path). - - The ownership of the file descriptor \a dirFD is transferred to the - method, regardless of whether it succeeds or fails. The caller must not - close the FD afterwards. - - \param dirFD File descriptor of a directory relative to which path is to - be considered. May be -1 if the current directory shall be considered. - \param path Pointer to a path relative to the given directory. - \param traverse If \c true and the given entry is a symbolic link, the - object is recursively set to point to the entry linked to by the - symbolic link. - - \returns \c B_OK on success, or an error code on failure. -*/ - - -/*! - \fn status_t BEntry::_SetName(const char* name) - \brief Handles string allocation, deallocation, and copying for the - leaf name of the entry. - - \param name The leaf \a name of the entry. - - \returns A status code. - \retval B_OK Everything went fine. - \retval B_BAD_VALUE \a name is \c NULL. - \retval B_NO_MEMORY Ran out of memory trying to allocate \a name. -*/ - - -/*! - \fn status_t BEntry::_Rename(BEntry& target, bool clobber) - \brief Renames the entry referred to by this object to the location - specified by \a target. - - If an entry exists at the target location, the method fails, unless - \a clobber is \c true, in which case that entry is overwritten (doesn't - work for non-empty directories, though). - - If the operation was successful, this entry is made a clone of the - supplied one and the supplied one is uninitialized. - - \param target The entry specifying the target location. - \param clobber If \c true, the an entry existing at the target location - will be overwritten. - - \return \c B_OK, if everything went fine, another error code otherwise. -*/ - - -/*! - \fn void BEntry::_Dump(const char* name) - \brief Debugging function, dumps the given entry to stdout. - - \param name A pointer to a string to be printed along with the dump for - identification purposes. + \since BeOS R3 */ @@ -610,6 +599,8 @@ if (err != B_ENTRY_NOT_FOUND) \retval B_BAD_VALUE \c NULL \a path or \a ref. \retval B_ENTRY_NOT_FOUND A (non-leaf) path component does not exist. \retval B_NO_MEMORY Insufficient memory for successful completion. + + \since BeOS R4 */ @@ -622,4 +613,6 @@ if (err != B_ENTRY_NOT_FOUND) \retval true a < b \retval false a >= b + + \since Haiku R1 */ diff --git a/docs/user/storage/EntryList.dox b/docs/user/storage/EntryList.dox index b36eb59e93..dfcc60586c 100644 --- a/docs/user/storage/EntryList.dox +++ b/docs/user/storage/EntryList.dox @@ -1,5 +1,5 @@ /* - * Copyright 2011 Haiku, Inc. All rights reserved. + * Copyright 2011-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: @@ -7,8 +7,8 @@ * John Scipione, jscipione@gmail.com * * Corresponds to: - * headers/os/storage/EntryList.h rev 42794 - * src/kits/storage/EntryList.cpp rev 42794 + * headers/os/storage/EntryList.h hrev47402 + * src/kits/storage/EntryList.cpp hrev47402 */ @@ -28,6 +28,8 @@ Defines a general interface for iterating through a list of entries i.e. files in a folder. + + \since BeOS R3 */ @@ -36,6 +38,8 @@ \brief Creates a BEntryList object. Does nothing at this time. + + \since Haiku R1 */ @@ -44,6 +48,8 @@ \brief Frees all resources associated with the BEntryList object. Does nothing at this time. + + \since Haiku R1 */ @@ -56,15 +62,17 @@ \param entry a pointer to a BEntry to be initialized with the found entry. \param traverse specifies whether to follow it, if the found entry - is a symbolic link. + is a symbolic link. \note The iterator used by this method is the same one used by - GetNextRef(), GetNextDirents(), Rewind() and CountEntries(). + GetNextRef(), GetNextDirents(), Rewind() and CountEntries(). \retval B_OK if successful \retval B_ENTRY_NOT_FOUND when at the end of the list \retval B_ERROR or another error code (depending on the implementation - of the derived class). + of the derived class). + + \since BeOS R3 */ @@ -75,21 +83,23 @@ Places an entry_ref to the next entry in the list into \a ref. \param ref a pointer to an entry_ref to be filled in with the data of the - found entry. + found entry. \note The iterator used by this method is the same one used by - GetNextEntry(), GetNextDirents(), Rewind() and CountEntries(). + GetNextEntry(), GetNextDirents(), Rewind() and CountEntries(). \retval B_OK if successful \retval B_ENTRY_NOT_FOUND when at the end of the list \retval B_ERROR or another error code (depending on the implementation - of the derived class). + of the derived class). + + \since BeOS R3 */ /*! \fn int32 BEntryList::GetNextDirents(struct dirent *buf, size_t length, - int32 count) + int32 count) \brief Returns the BEntryList's next entries as dirent structures. Reads a number of entries into the array of dirent structures pointed @@ -98,18 +108,20 @@ \a buf with given length \a length (in bytes), whichever is smallest. \param buf A pointer to a buffer to be filled with dirent structures of - the found entries. + the found entries. \param length The length of the \a buf array. \param count the maximum number of entries to be read. \note The iterator used by this method is the same one used by - GetNextEntry(), GetNextRef(), Rewind() and CountEntries(). + GetNextEntry(), GetNextRef(), Rewind() and CountEntries(). \returns - - The number of dirent structures stored in the buffer or 0 when - there are no more entries to be read. - - an error code (depending on the implementation of the derived class) - if an error occurred. + - The number of dirent structures stored in the buffer or 0 when + there are no more entries to be read. + - an error code (depending on the implementation of the derived class) + if an error occurred. + + \since BeOS R3 */ @@ -119,7 +131,9 @@ \retval B_OK if successful \retval B_ERROR or another error code (depending on the implementation - of the derived class). + of the derived class). + + \since BeOS R3 */ @@ -130,5 +144,7 @@ \retval B_OK if successful \retval B_ENTRY_NOT_FOUND when at the end of the list \retval B_ERROR or another error code (depending on the implementation - of the derived class). -*/ \ No newline at end of file + of the derived class). + + \since BeOS R3 +*/ diff --git a/docs/user/storage/File.dox b/docs/user/storage/File.dox index 786d8425fd..e4cfd49419 100644 --- a/docs/user/storage/File.dox +++ b/docs/user/storage/File.dox @@ -1,5 +1,5 @@ /* - * Copyright 2009-2012 Haiku, Inc. All rights reserved. + * Copyright 2009-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: @@ -8,8 +8,8 @@ * Ingo Weinhold, bonefish@users.sf.net * * Corresponds to: - * headers/os/storage/File.h hrev45060 - * src/kits/storage/File.cpp hrev45060 + * headers/os/storage/File.h hrev47402 + * src/kits/storage/File.cpp hrev47402 */ @@ -33,6 +33,8 @@ Symbolic links are automatically transversed by opening a BFile. The node that the BFile ends up opening will be the file or directory that the link points to, not the symbolic link file itself. + + \since BeOS R3 */ @@ -47,6 +49,8 @@ - SetTo(const char* path, uint32 openMode) - SetTo(const BDirectory* dir, const char* path, uint32 openMode) - operator=(const BFile &file) + + \since BeOS R3 */ @@ -57,57 +61,67 @@ If \a file is uninitialized, the newly constructed BFile will be too. \param file The BFile object to be copied. + + \since BeOS R3 */ /*! \fn BFile::BFile(const entry_ref* ref, uint32 openMode) \brief Creates a BFile and initializes it to the file referred to by - the supplied entry_ref and according to the specified open mode. + the supplied entry_ref and according to the specified open mode. \param ref The entry_ref referring to the file. \param openMode The mode in which the file should be opened. \see SetTo(const entry_ref* ref, uint32 openMode) + + \since BeOS R3 */ /*! \fn BFile::BFile(const BEntry* entry, uint32 openMode) \brief Creates a BFile and initializes it to the file referred to by - the supplied BEntry and according to the specified open mode. + the supplied BEntry and according to the specified open mode. \param entry The BEntry referring to the file. \param openMode The mode in which the file should be opened. \see SetTo(const BEntry* entry, uint32 openMode) + + \since BeOS R3 */ /*! \fn BFile::BFile(const char* path, uint32 openMode) \brief Creates a BFile and initializes it to the file referred to by - the supplied path name and according to the specified open mode. + the supplied path name and according to the specified open mode. \param path The file's path name. \param openMode The mode in which the file should be opened. \see SetTo(const char* path, uint32 openMode) + + \since BeOS R3 */ /*! \fn BFile::BFile(const BDirectory *dir, const char* path, uint32 openMode) \brief Creates a BFile and initializes it to the file referred to by - the supplied path name relative to the specified BDirectory and - according to the specified open mode. + the supplied path name relative to the specified BDirectory and + according to the specified open mode. \param dir The BDirectory, relative to which the file's path name is - given. + given. \param path The file's path name relative to \a dir. \param openMode The mode in which the file should be opened. \see SetTo(const BDirectory* dir, const char* path, uint32 openMode) + + \since BeOS R3 */ @@ -116,27 +130,30 @@ \brief Destroys the BFile object and frees all allocated resources. If the file is properly initialized, the file descriptor is closed. + + \since BeOS R3 */ /*! \fn status_t BFile::SetTo(const entry_ref* ref, uint32 openMode) \brief Re-initializes the BFile to the file referred to by the - supplied entry_ref and according to the specified open mode. + supplied entry_ref and according to the specified open mode. \param ref The entry_ref referring to the file. \param openMode The mode in which the file should be opened - \a openMode must be a bitwise or of exactly one of the flags. - - \c B_READ_ONLY: The file is opened read only. - - \c B_WRITE_ONLY: The file is opened write only. - - \c B_READ_WRITE: The file is opened for random read/write access. - and any number of the flags - - \c B_CREATE_FILE: A new file will be created, if it does not already - exist. - - \c B_FAIL_IF_EXISTS: If the file does already exist and - \c B_CREATE_FILE is set, SetTo() fails. - - \c B_ERASE_FILE: An already existing file is truncated to zero size. - - \c B_OPEN_AT_END: Seek() to the end of the file after opening. + \a openMode must be a bitwise or of exactly one of the flags. + - \c B_READ_ONLY: The file is opened read only. + - \c B_WRITE_ONLY: The file is opened write only. + - \c B_READ_WRITE: The file is opened for random read/write access. + and any number of the flags + - \c B_CREATE_FILE: A new file will be created, if it does not + already exist. + - \c B_FAIL_IF_EXISTS: If the file does already exist and + \c B_CREATE_FILE is set, SetTo() fails. + - \c B_ERASE_FILE: An already existing file is truncated to zero + size. + - \c B_OPEN_AT_END: Seek() to the end of the file after opening. \returns A status code. \retval B_OK Everything went fine. @@ -149,13 +166,15 @@ \retval B_BUSY A node was busy. \retval B_FILE_ERROR A general file error. \retval B_NO_MORE_FDS The application has run out of file descriptors. + + \since BeOS R3 */ /*! \fn status_t BFile::SetTo(const BEntry* entry, uint32 openMode) \brief Re-initializes the BFile to the file referred to by the - supplied BEntry and according to the specified open mode. + supplied BEntry and according to the specified open mode. \param entry the BEntry referring to the file \param openMode the mode in which the file should be opened @@ -173,14 +192,16 @@ \retval B_NO_MORE_FDS The application has run out of file descriptors. \todo Implemented using SetTo(entry_ref*, uint32). Check, if necessary - to re-implement! + to re-implement! + + \since BeOS R3 */ /*! \fn status_t BFile::SetTo(const char* path, uint32 openMode) \brief Re-initializes the BFile to the file referred to by the - supplied path name and according to the specified open mode. + supplied path name and according to the specified open mode. \param path The file's path name. \param openMode The mode in which the file should be opened. @@ -196,19 +217,20 @@ \retval B_BUSY A node was busy. \retval B_FILE_ERROR A general file error. \retval B_NO_MORE_FDS The application has run out of file descriptors. -*/ + + \since BeOS R3 */ /*! \fn status_t BFile::SetTo(const BDirectory* dir, const char* path, - uint32 openMode) + uint32 openMode) \brief Re-initializes the BFile to the file referred to by the - supplied path name relative to the specified BDirectory and - according to the specified open mode. + supplied path name relative to the specified BDirectory and + according to the specified open mode. \param dir The BDirectory, relative to which the file's path name is - given. + given. \param path The file's path name relative to \a dir. \param openMode The mode in which the file should be opened. @@ -225,7 +247,9 @@ \retval B_NO_MORE_FDS The application has run out of file descriptors. \todo Implemented using SetTo(BEntry*, uint32). Check, if necessary - to re-implement! + to re-implement! + + \since BeOS R3 */ @@ -237,6 +261,8 @@ - \c true, if the BFile has been initialized properly and the file has been been opened for reading, - \c false, otherwise. + + \since BeOS R3 */ @@ -248,6 +274,8 @@ - \c true, if the BFile has been initialized properly and the file has been opened for writing, - \c false, otherwise. + + \since BeOS R3 */ @@ -259,20 +287,24 @@ \param size The number of bytes that shall be read. \returns The number of bytes read or an error code. + + \since BeOS R3 */ /*! \fn ssize_t BFile::ReadAt(off_t location, void* buffer, size_t size) \brief Reads a number of bytes from a certain position within the file - into a buffer. + into a buffer. \param location The position (in bytes) within the file from which the - data shall be read. + data shall be read. \param buffer The buffer the data from the file shall be written to. \param size The number of bytes that shall be read. \returns The number of bytes read or an error code. + + \since BeOS R3 */ @@ -284,20 +316,24 @@ \param size The number of bytes that shall be written. \returns The number of bytes actually written or an error code. + + \since BeOS R3 */ /*! \fn ssize_t BFile::WriteAt(off_t location, const void* buffer, size_t size) - \brief \brief Writes a number of bytes from a buffer at a certain position - into the file. + \brief Writes a number of bytes from a buffer at a certain position + into the file. \param location The position (in bytes) within the file at which the data - shall be written. + shall be written. \param buffer The buffer containing the data to be written to the file. \param size The number of bytes that shall be written. \returns The number of bytes actually written or an error code. + + \since BeOS R3 */ @@ -311,16 +347,18 @@ or Write() invocations will be undefined. \param offset New read/write position, depending on \a seekMode relative - to the beginning or the end of the file or the current position. + to the beginning or the end of the file or the current position. \param seekMode - - \c SEEK_SET: move relative to the beginning of the file - - \c SEEK_CUR: move relative to the current position - - \c SEEK_END: move relative to the end of the file + - \c SEEK_SET: move relative to the beginning of the file. + - \c SEEK_CUR: move relative to the current position. + - \c SEEK_END: move relative to the end of the file. \returns The new read/write position relative to the beginning of the - file or an error code. + file or an error code. \retval B_ERROR Trying to seek before the beginning of the file. \retval B_FILE_ERROR The file is not properly initialized. + + \since BeOS R3 */ @@ -329,9 +367,11 @@ \brief Gets the current read/write position within the file. \returns The current read/write position relative to the beginning of the - file or an error code. + file or an error code. \retval B_ERROR After a Seek() before the beginning of the file. \retval B_FILE_ERROR The file has not been initialized. + + \since BeOS R3 */ @@ -344,15 +384,17 @@ truncated. \note There's no problem with setting the size of a BFile opened in - \c B_READ_ONLY mode, unless the file resides on a read only volume. + \c B_READ_ONLY mode, unless the file resides on a read only volume. \param size The new file size. \returns A status code. \retval B_OK Everything went fine. \retval B_NOT_ALLOWED Trying to set the size of a file on a read only - volume. + volume. \retval B_DEVICE_FULL There's not enough space left on the volume. + + \since BeOS R3 */ @@ -365,6 +407,8 @@ \returns A status code. \see BStatable::GetSize() + + \since BeOS R3 */ @@ -378,20 +422,6 @@ \param file The original BFile to assign from. \returns A reference to the assigned BFile. -*/ - - -/*! - \fn int BFile::get_fd() const - \brief Gets the file descriptor of the BFile. - - To be used instead of accessing the BNode's private \c fFd member directly. - - \returns The file descriptor, or -1 if not properly initialized. -*/ - - -/*! - \fn void BFile::close_fd() - \brief Overrides BNode::close_fd() for binary compatibility with BeOS R5. + + \since BeOS R3 */ diff --git a/docs/user/storage/FilePanel.dox b/docs/user/storage/FilePanel.dox index 9dc6ebb34f..d04fa228f7 100644 --- a/docs/user/storage/FilePanel.dox +++ b/docs/user/storage/FilePanel.dox @@ -1,13 +1,13 @@ /* - * Copyright 2009-2012 Haiku, Inc. All rights reserved. + * Copyright 2009-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: * John Scipione, jscipione@gmail.com * * Corresponds to: - * headers/os/storage/FilePanel.h hrev45162 - * src/kits/tracker/FilePanel.cpp hrev45162 + * headers/os/storage/FilePanel.h hrev47402 + * src/kits/tracker/FilePanel.cpp hrev47402 */ @@ -23,6 +23,8 @@ \enum file_panel_mode \ingroup storage \brief Whether the file panel is a save or open panel. + + \since BeOS R3 */ @@ -30,12 +32,16 @@ \var file_panel_mode B_OPEN_PANEL Open panel + + \since BeOS R3 */ /*! \var file_panel_mode B_SAVE_PANEL + + \since BeOS R3 Save panel */ @@ -43,7 +49,9 @@ /*! \enum file_panel_button \ingroup storage - \brief List of buttons used by the file panel + \brief List of buttons used by the file panel. + + \since BeOS R3 */ @@ -51,6 +59,8 @@ \var file_panel_button B_CANCEL_BUTTON Cancel button + + \since BeOS R3 */ @@ -58,6 +68,8 @@ \var file_panel_button B_DEFAULT_BUTTON Default button + + \since BeOS R3 */ @@ -66,6 +78,8 @@ \ingroup storage \ingroup libbe \brief Allows you to filter the items displayed in a file panel. + + \since BeOS R3 */ @@ -73,7 +87,7 @@ \fn virtual bool BRefFilter::Filter(const entry_ref* ref, BNode* node, struct stat_beos* stat, const char* mimeType) \brief Hook method that's called on each file in the target directory - displayed by a file panel. + displayed by a file panel. \param ref The file currently under consideration. \param node The node currently under consideration. @@ -81,9 +95,11 @@ \param mimeType The MIME type of the file. \returns Whether or not the entry is a valid candidate for an open/save - dialog. + dialog. \see BFilePanel::SetRefFilter() + + \since BeOS R3 */ @@ -172,6 +188,8 @@ destroyed, it is hidden instead. You can then delete the BFilePanel object or leave it be and simply call Show() to use the panel next time you need it. + + \since BeOS R3 */ @@ -189,22 +207,28 @@ SetRefFilter(), and SetHideWhenDone() methods. \param mode Set to \c B_OPEN_PANEL for an open panal or \c B_SAVE_PANEL - for a save panel. Default is \c B_OPEN_PANEL. + for a save panel. Default is \c B_OPEN_PANEL. \param target The BMessenger object that sends messages to the BLooper - or BHandler controlled by the file panel. + or BHandler controlled by the file panel. \param ref The directory to display, by default the current working - directory. - \param nodeFlavors One or more option flags, this applies to open panels only. - - \c B_FILE_NODE Can select files and symlinks to files. - - \c B_DIRECTORY_NODE Can select directories and symlinks to directories. - - \c B_SYMLINK_NODE Can select symlinks only. + directory. + \param nodeFlavors One or more option flags, this applies to open panels + only. + - \c B_FILE_NODE Can select files and symlinks to files. + - \c B_DIRECTORY_NODE Can select directories and symlinks to + directories. + - \c B_SYMLINK_NODE Can select symlinks only. \param multipleSelection Whether or not the user is allowed to select more - than one item to open. Save panels should always set this to \c false. + than one item to open. Save panels should always set this to + \c false. \param message Message sent by the file panel on confirms or cancels. \param filter Hook method to call. \param modal Whether or not the panel is modal, defaults to \c false. \param hideWhenDone Set to \c false to keep the panel even after the user - confirms or cancels. The close button will hide the panel regardless. + confirms or cancels. The close button will hide the panel + regardless. + + \since BeOS R3 */ @@ -214,18 +238,24 @@ If file panel is currently being displayed it is closed. The BRefFilter object references by this panel is not destroyed by this method. + + \since BeOS R3 */ /*! \fn void BFilePanel::Show() \brief Displays the file panel on screen. + + \since BeOS R3 */ /*! \fn void BFilePanel::Hide() \brief Hides the file panel. + + \since BeOS R3 */ @@ -234,6 +264,10 @@ \brief Determines whether or not the file panel is shown. \returns \c true if visible, \c false if hidden. + + \see Show() + + \since BeOS R3 */ @@ -246,6 +280,8 @@ \param message The message to send. \see BMessenger::SendMessage() + + \since BeOS R3 */ @@ -253,8 +289,10 @@ \fn file_panel_mode BFilePanel::PanelMode() const \brief Gets the panel mode, either \c B_OPEN_PANEL or \c B_SAVE_PANEL. - \returns \c B_OPEN_PANEL if the panel is an open panel or \c B_SAVE_PANEL - if the panel is a save panel. + \returns \c B_OPEN_PANEL if the panel is an open panel, or \c B_SAVE_PANEL + if the panel is a save panel. + + \since BeOS R3 */ @@ -263,6 +301,8 @@ \brief Gets the panel's target messenger object. \returns The BMessenger object that sends messages for this panel. + + \since BeOS R3 */ @@ -271,6 +311,8 @@ \brief Sets the target messenger. \param target the target BMessenger object to set. + + \since BeOS R3 */ @@ -279,13 +321,17 @@ \brief Sets the target messenge. \param message The BMessage object to send on confirm. + + \since BeOS R3 */ /*! \fn void BFilePanel::Refresh() \brief Refresh the directory or the panel causing the entries to be re-run - through the BRefFilter::Filter() method. + through the BRefFilter::Filter() method. + + \since BeOS R3 */ @@ -296,6 +342,8 @@ \returns The BRefFilter set to the panel. \see BRefFilter::Filter() + + \since BeOS R3 */ @@ -306,6 +354,8 @@ \param filter The BRefFilter object to set. \see BRefFilter::Filter() + + \since BeOS R3 */ @@ -316,6 +366,8 @@ \param button The button to set the label of. \param text The text to set the button label to. + + \since BeOS R3 */ @@ -324,6 +376,8 @@ \brief Gets the entry ref of the panel and sets \a ref to point to it. \param ref The \c entry_ref pointer you want set. + + \since BeOS R3 */ @@ -332,42 +386,52 @@ \brief Set some save text to display in the save dialog. \param text The text to display. + + \since BeOS R3 */ /*! \fn void BFilePanel::SetPanelDirectory(const entry_ref* ref) \brief Sets the entry ref of the panel to the directory contained - by \a ref. + by \a ref. \param ref The entry contained by the desired panel directory. + + \since BeOS R3 */ /*! \fn void BFilePanel::SetPanelDirectory(const char* path) \brief Sets the entry ref of the panel to the directory referenced - by \a path. + by \a path. \param path The path of the desired directory. + + \since BeOS R3 */ /*! \fn void BFilePanel::SetPanelDirectory(const BEntry* entry) \brief Sets the entry ref of the panel to the directory referenced - by \a entry. + by \a entry. \param entry The BEntry object pointing to the desired directory. + + \since BeOS R3 */ /*! \fn void BFilePanel::SetPanelDirectory(const BDirectory* dir) \brief Sets the entry ref of the panel to the directory referenced - by \a dir. + by \a dir. \param dir The BDirectory object pointing to the desired directory. + + \since BeOS R3 */ @@ -376,6 +440,8 @@ \brief Gets a pointer to the BWindow object used by the file panel. \returns A pointer to the BWindow object used by the file panel. + + \since BeOS R3 */ @@ -384,6 +450,8 @@ \brief Sets the entry ref back to the top of the list. \see SelectionChanged() + + \since BeOS R3 */ @@ -396,7 +464,10 @@ \retval B_ERROR Couldn't attain a lock on the window. \retval B_ENTRY_NOT_FOUND End of the entry list. + \see Rewind() \see SelectionChanged() + + \since BeOS R3 */ @@ -405,6 +476,8 @@ \brief Sets whether or not the panel should hide on confirm or cancel. \param on \c true to hide, \c false to not hide when done. + + \since BeOS R3 */ @@ -415,23 +488,42 @@ Panel always hides if the user clicks the window's close button. \returns \c true if panel will hide, \c false if panel will not hide. + + \see SetHideWhenDone() + + \since BeOS R3 */ +/*! + \name Hook Methods +*/ + + +//! @{ + + /*! \fn void BFilePanel::WasHidden() \brief Hook method that gets called when the file panel is hidden due to - a user action. + a user action. WasHidden() is not called if you call Hide() manually. + + \since BeOS R3 */ /*! \fn void BFilePanel::SelectionChanged() \brief Hook method that gets called when the entry ref references by the - file panel changes. + file panel changes. \see GetNextSelectedRef() \see Rewind() + + \since BeOS R3 */ + + +//! @} diff --git a/docs/user/storage/FindDirectory.dox b/docs/user/storage/FindDirectory.dox index afa310ad40..061210acd1 100644 --- a/docs/user/storage/FindDirectory.dox +++ b/docs/user/storage/FindDirectory.dox @@ -1,5 +1,5 @@ /* - * Copyright 2011-2013, Haiku, Inc. All rights reserved. + * Copyright 2011-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Documentation by: @@ -8,8 +8,8 @@ * Ingo Weinhold, ingo_weinhold@gmx.de * * Corresponds to: - * headers/os/storage/FindDirectory.h hrev46390 - * src/kits/storage/FindDirectory.cpp hrev46390 + * headers/os/storage/FindDirectory.h hrev47402 + * src/kits/storage/FindDirectory.cpp hrev47402 */ @@ -17,8 +17,8 @@ \file FindDirectory.h \ingroup storage \ingroup libbe - \brief Provides the find_directory(), find_path(), find_paths(), etc. - functions. + \brief Provides the find_directory(), find_path(), find_paths(), functions + as well as the directory_which constants. Haiku provides a set of directories for applications to use. These can be accessed using the functions find_directory(), find_path(), find_path_etc(), @@ -56,317 +56,929 @@ there are also a C++ version of find_directory() and the BPathFinder class (both implemented in libbe), which may be more convenient to use in C++ code. + + \since BeOS R3 */ /*! \enum directory_which - \brief Directory constants to use with find_directory. + \brief Directory constants to use with find_directory(). There are four kind of directories. Volume-local directories exist on each - volume. They may be at a different place in each of them, for example the - trash location depends on the filesystem. System and common directories are - system-wide. They live on only one volume. The difference is system is - only meant for internal system management and shouldn't be used by - applications. The common directories have a similar hierarchy, and they are - ignored when the user disable user add-ons in the boot menu. User + volume, they may be at a different location in each of them. For example + the location of the trash directory depends on the filesystem. System + directories are system-wide, they live on only one volume. System is meant + for internal system management and system-wide applications. User directories have a different value depending on the UID of the application - calling the function. They are usually located in the user home directory. + calling the function. They are usually located in the user's home + directory. - Use common directories for system-wide files such as drivers. Use user - directories for application settings, since each user may want different - settings. + Use system directories for system-wide files such as drivers and use user + directories are for application settings, since each user may want + different settings. + + \remark The \c B_COMMON_* constants have been intentionally removed in + Haiku R1, use the \c B_SYSTEM_* constants instead. + + \since BeOS R3 */ /*! \var directory_which B_DESKTOP_DIRECTORY - The desktop for a given volume. + \brief The desktop directory for a given volume. + \since BeOS R3 +*/ + + +/*! \var directory_which B_TRASH_DIRECTORY - The trash for a given volume. + \brief The trash directory for a given volume. + \since BeOS R3 +*/ + + +/*! \var directory_which B_SYSTEM_DIRECTORY - The system directory. + \brief The system directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_ADDONS_DIRECTORY - The system add-ons directory + \brief The system add-ons directory + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_BOOT_DIRECTORY - The system boot directory. Contains the minimal set of files required for - booting Haiku. + \brief The system boot directory. + Contains the minimal set of files required for booting Haiku. + + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_FONTS_DIRECTORY - The system fonts directory + \brief The system fonts directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_LIB_DIRECTORY - The system lib directory. + \brief The system lib directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_SERVERS_DIRECTORY - The system servers directory. + \brief The system servers directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_APPS_DIRECTORY - The system applications directory. Contains applications with graphical - user interface. + \brief The system applications directory. + Contains applications with graphical user interface. + + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_BIN_DIRECTORY - The system bin directory. Contains command-line applications runnable from - Terminal. + \brief The system bin directory. + Contains command-line applications runnable from Terminal. + + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_DOCUMENTATION_DIRECTORY - The system documentation directory. Contains e.g. man pages. + \brief The system documentation directory, contains e.g. man pages. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_PREFERENCES_DIRECTORY - The system preferences directory. + \brief The system preferences directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_TRANSLATORS_DIRECTORY - The system translator directory. + \brief The system translator directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_MEDIA_NODES_DIRECTORY - The system media nodes directory. + \brief The system media nodes directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_SOUNDS_DIRECTORY - The system sounds directory. + \brief The system sounds directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_DATA_DIRECTORY - The system data directory. + \brief The system data directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_DEVELOP_DIRECTORY - The system directory containing development related files. + \brief The system directory containing development related files. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_PACKAGES_DIRECTORY - The system directory where activated packages live. + \brief The system directory where activated packages live. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_HEADERS_DIRECTORY - The system directory for development header files. + \brief The system directory for development header files. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_ETC_DIRECTORY - The system directory used for Unix-like installation location wide settings - (Unix "etc" directory). + \brief The system directory used for Unix-like installation location-wide + settings (Unix "etc" directory). + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_SETTINGS_DIRECTORY - The system directory used for installation location wide settings. + \brief The system directory used for installation location-wide settings. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_LOG_DIRECTORY - The system directory where log files are put. + \brief The system directory where log files are put. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_SPOOL_DIRECTORY - The system directory for spool data (e.g. pending printer jobs). + \brief The system directory for spool data (e.g. pending printer jobs). + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_TEMP_DIRECTORY - The global directory for temporary files. + \brief The global directory for temporary files (Unix "tmp" directory). + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_VAR_DIRECTORY - The system directory for variable data (Unix "var" directory). + \brief The system directory for variable data (Unix "var" directory). + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_CACHE_DIRECTORY - The system directory used for cache files. + \brief The system directory used for cache files. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_NONPACKAGED_DIRECTORY - The system non-packaged installation location directory. + \brief The system non-packaged installation location directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_NONPACKAGED_ADDONS_DIRECTORY - The system non-packaged add-ons directory + \brief The system non-packaged add-ons directory + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_NONPACKAGED_TRANSLATORS_DIRECTORY - The system non-packaged translator directory. + \brief The system non-packaged translator directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_NONPACKAGED_MEDIA_NODES_DIRECTORY - The system non-packaged media nodes directory. + \brief The system non-packaged media nodes directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_NONPACKAGED_BIN_DIRECTORY The system non-packaged bin directory. Contains command-line applications - runnable from Terminal. + \brief runnable from Terminal. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_NONPACKAGED_DATA_DIRECTORY - The system non-packaged data directory. + \brief The system non-packaged data directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_NONPACKAGED_FONTS_DIRECTORY - The system non-packaged fonts directory + \brief The system non-packaged fonts directory + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_NONPACKAGED_SOUNDS_DIRECTORY - The system non-packaged sounds directory. + \brief The system non-packaged sounds directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_NONPACKAGED_DOCUMENTATION_DIRECTORY - The system non-packaged documentation directory. Contains e.g. man pages. + \brief The system non-packaged documentation directory. Contains e.g. man pages. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_NONPACKAGED_LIB_DIRECTORY - The system non-packaged lib directory. + \brief The system non-packaged lib directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_NONPACKAGED_HEADERS_DIRECTORY - The system non-packaged directory for development header files. + \brief The system non-packaged directory for development header files. + \since Haiku R1 +*/ + + +/*! \var directory_which B_SYSTEM_NONPACKAGED_DEVELOP_DIRECTORY - The system non-packaged directory containing development related files. + \brief The system non-packaged directory containing development related + files. + + \since Haiku R1 */ /*! \var directory_which B_USER_DIRECTORY - The user home directory. Do NOT store application settings here as on unix, - instead use B_USER_SETTINGS_DIRECTORY. + \brief The user home directory. + Do NOT store application settings here as on unix, instead use + \c B_USER_SETTINGS_DIRECTORY. + + \since BeOS R3 +*/ + + +/*! \var directory_which B_USER_CONFIG_DIRECTORY - The user's packaged installation location directory. + \brief The user packaged installation location directory. + \since BeOS R3 +*/ + + +/*! \var directory_which B_USER_ADDONS_DIRECTORY - The user add-ons directory + \brief The user add-ons directory + \since BeOS R3 +*/ + + +/*! \var directory_which B_USER_BOOT_DIRECTORY - The user directory containing booting related files. + \brief The user directory containing booting related files. + \since BeOS R3 +*/ + + +/*! \var directory_which B_USER_FONTS_DIRECTORY - The user fonts directory + \brief The user fonts directory. + \since BeOS R3 +*/ + + +/*! \var directory_which B_USER_LIB_DIRECTORY - The user lib directory. + \brief The user lib directory. + \since BeOS R3 +*/ + + +/*! \var directory_which B_USER_SETTINGS_DIRECTORY - The user settings directory. You may store your application settings here. - Create a subdirectory for your application if you have multiple files to - store, else, put a single file. The file or directory should have the same - name as your application, so the user knows what it's used for. + \brief The user settings directory. + You may store your application settings here. Create a subdirectory for + your application if you have multiple files to store, else, put a single + file. The file or directory should have the same name as your + application, so the user knows what it's used for. + + \since BeOS R3 +*/ + + +/*! \var directory_which B_USER_DESKBAR_DIRECTORY - The user deskbar directory. You may add a link to your application here, so - it shows up in the user deskbar's leaf menu. + \brief The user Deskbar directory. + You may add a link to your application here, so it shows up in the user's + Deskbar leaf menu. + + \since BeOS R3 +*/ + + +/*! \var directory_which B_USER_PRINTERS_DIRECTORY - The user directory for printer settings. + \brief The user directory for printer settings. + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_TRANSLATORS_DIRECTORY - The user translator directory. + \brief The user translator directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_MEDIA_NODES_DIRECTORY - The user media nodes directory. + \brief The user media nodes directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_SOUNDS_DIRECTORY - The user sounds directory. + \brief The user sounds directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_DATA_DIRECTORY - The user data directory. + \brief The user data directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_CACHE_DIRECTORY - The system directory used for cache files. + \brief The user directory used for cache files. + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_PACKAGES_DIRECTORY - The user directory where activated packages live. + \brief The user directory where activated packages live. + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_HEADERS_DIRECTORY - The user directory for development header files. + \brief The user directory for development header files. + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_DEVELOP_DIRECTORY - The user directory containing development related files. + \brief The user directory containing development related files. + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_DOCUMENTATION_DIRECTORY - The user documentation directory. Contains e.g. man pages. + \brief The user documentation directory, contains e.g. man pages. - \var directory_which B_USER_SERVERS_DIRECTORY - The user servers directory. + \since Haiku R1 +*/ + +/*! + \var directory_which B_USER_SERVERS_DIRECTORY + \brief The user servers directory. + + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_APPS_DIRECTORY - The user applications directory. Contains applications with graphical - user interface. + \brief The user applications directory. + Contains applications with graphical user interface. + + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_BIN_DIRECTORY - The user bin directory. Contains command-line applications runnable from - Terminal. + \brief The user bin directory. + Contains command-line applications runnable from Terminal. + + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_PREFERENCES_DIRECTORY - The user preference applications directory. + \brief The user preference applications directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_ETC_DIRECTORY - The user directory used for Unix-like installation location wide settings - (Unix "etc" directory). + \brief The user directory used for Unix-like installation location-wide + settings (Unix "etc" directory). + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_LOG_DIRECTORY - The user directory where log files are put. + \brief The user directory where log files are put. + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_SPOOL_DIRECTORY - The user directory for spool data (e.g. pending printer jobs). + \brief The user directory for spool data, e.g. pending printer jobs. + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_VAR_DIRECTORY - The user directory for variable data (Unix "var" directory). + \brief The user directory for variable data (Unix "var" directory). + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_NONPACKAGED_DIRECTORY - The user non-packaged installation location directory. + \brief The user non-packaged installation location directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_NONPACKAGED_ADDONS_DIRECTORY - The user non-packaged add-ons directory + \brief The user non-packaged add-ons directory + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_NONPACKAGED_TRANSLATORS_DIRECTORY - The user non-packaged translator directory. + \brief The user non-packaged translator directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_NONPACKAGED_MEDIA_NODES_DIRECTORY - The user non-packaged media nodes directory. + \brief The user non-packaged media nodes directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_NONPACKAGED_BIN_DIRECTORY - The user non-packaged bin directory. Contains command-line applications - runnable from Terminal. + \brief The user non-packaged bin directory. + Contains command-line applications runnable from Terminal. + + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_NONPACKAGED_DATA_DIRECTORY - The user non-packaged data directory. + \brief The user non-packaged data directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_NONPACKAGED_FONTS_DIRECTORY - The user non-packaged fonts directory + \brief The user non-packaged fonts directory + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_NONPACKAGED_SOUNDS_DIRECTORY - The user non-packaged sounds directory. + \brief The user non-packaged sounds directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_NONPACKAGED_DOCUMENTATION_DIRECTORY - The user non-packaged documentation directory. Contains e.g. man pages. + \brief The user non-packaged documentation directory, contains e.g. man + pages. + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_NONPACKAGED_LIB_DIRECTORY - The user non-packaged lib directory. + \brief The user non-packaged lib directory. + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_NONPACKAGED_HEADERS_DIRECTORY - The user non-packaged directory for development header files. + \brief The user non-packaged directory for development header files. + \since Haiku R1 +*/ + + +/*! \var directory_which B_USER_NONPACKAGED_DEVELOP_DIRECTORY - The user non-packaged directory containing development related files. + \brief The user non-packaged directory containing development related + files. + + \since Haiku R1 */ /*! \var directory_which B_APPS_DIRECTORY - The global applications directory. Contains applications with graphical - user interface. + \brief The global applications directory. - \var directory_which B_PREFERENCES_DIRECTORY - The global preference applications directory. + Contains applications with graphical user interface. - \var directory_which B_UTILITIES_DIRECTORY - The global utility applications directory. - - \var directory_which B_PACKAGE_LINKS_DIRECTORY - The global package links directory. This is where symlink directories for - all activated packages are exposed. + \since BeOS R3 */ -/* find_path[s]() flags */ +/*! + \var directory_which B_PREFERENCES_DIRECTORY + \brief The global preference applications directory. + + \since BeOS R3 +*/ + + +/*! + \var directory_which B_UTILITIES_DIRECTORY + \brief The global utility applications directory. + + \since Haiku R1 +*/ + + +/*! + \var directory_which B_PACKAGE_LINKS_DIRECTORY + \brief The global package links directory. + + This is where symlink directories for all activated packages are exposed. + + \since Haiku R1 +*/ + + +/*! + \var directory_which B_BEOS_DIRECTORY + \brief The BeOS directory. + + \deprecated Legacy BeOS definition to be phased out, use + \c B_SYSTEM_DIRECTORY instead. + + \since BeOS R3 +*/ + + +/*! + \var directory_which B_BEOS_SYSTEM_DIRECTORY + \brief The BeOS system directory. + + \deprecated Legacy BeOS definition to be phased out, use + \c B_SYSTEM_DIRECTORY instead. + + \since BeOS R3 +*/ + + +/*! + \var directory_which B_BEOS_ADDONS_DIRECTORY + \brief The BeOS Add-ons directory. + + \deprecated Legacy BeOS definition to be phased out, use + \c B_SYSTEM_ADDONS_DIRECTORY instead. + + \since BeOS R3 +*/ + + +/*! + \var directory_which B_BEOS_BOOT_DIRECTORY + \brief The BeOS boot directory. + + \deprecated Legacy BeOS definition to be phased out, use + \c B_SYSTEM_BOOT_DIRECTORY instead. + + \since BeOS R3 +*/ + + +/*! + \var directory_which B_BEOS_FONTS_DIRECTORY + \brief The BeOS fonts directory. + + \deprecated Legacy BeOS definition to be phased out, use + \c B_SYSTEM_FONTS_DIRECTORY instead. + + \since BeOS R3 +*/ + + +/*! + \var directory_which B_BEOS_LIB_DIRECTORY + \brief The BeOS lib directory. + + \deprecated Legacy BeOS definition to be phased out, use + \c B_SYSTEM_LIB_DIRECTORY instead. + + \since BeOS R3 +*/ + + +/*! + \var directory_which B_BEOS_SERVERS_DIRECTORY + \brief The BeOS servers directory. + + \deprecated Legacy BeOS definition to be phased out, use + \c B_SYSTEM_SERVERS_DIRECTORY instead. + + \since BeOS R3 +*/ + + +/*! + \var directory_which B_BEOS_APPS_DIRECTORY + \brief The BeOS apps directory. + + \deprecated Legacy BeOS definition to be phased out, use + \c B_SYSTEM_APPS_DIRECTORY instead. + + \since BeOS R3 +*/ + + +/*! + \var directory_which B_BEOS_BIN_DIRECTORY + \brief The BeOS bin directory. + + \deprecated Legacy BeOS definition to be phased out, use + \c B_SYSTEM_BIN_DIRECTORY instead. + + \since BeOS R3 +*/ + + +/*! + \var directory_which B_BEOS_ETC_DIRECTORY + \brief The BeOS etc directory used for Unix-like installation location-wide + settings (Unix "etc" directory). + + \deprecated Legacy BeOS definition to be phased out, use + \c B_SYSTEM_ETC_DIRECTORY instead. + + \since BeOS R3 +*/ + + +/*! + \var directory_which B_BEOS_DOCUMENTATION_DIRECTORY + \brief The BeOS documentation directory. + + \deprecated Legacy BeOS definition to be phased out, use + \c B_SYSTEM_DOCUMENTATION_DIRECTORY instead. + + \since BeOS R3 +*/ + + +/*! + \var directory_which B_BEOS_PREFERENCES_DIRECTORY + \brief The BeOS preferences directory. + + \deprecated Legacy BeOS definition to be phased out, use + \c B_SYSTEM_PREFERENCES_DIRECTORY instead. + + \since BeOS R3 +*/ + + +/*! + \var directory_which B_BEOS_TRANSLATORS_DIRECTORY + \brief The BeOS translators directory. + + \deprecated Legacy BeOS definition to be phased out, use + \c B_SYSTEM_TRANSLATORS_DIRECTORY instead. + + \since BeOS R3 +*/ + + +/*! + \var directory_which B_BEOS_MEDIA_NODES_DIRECTORY + \brief The BeOS media nodes directory. + + \deprecated Legacy BeOS definition to be phased out, use + \c B_SYSTEM_MEDIA_NODES_DIRECTORY instead. + + \since BeOS R3 +*/ + + +/*! + \var directory_which B_BEOS_SOUNDS_DIRECTORY + \brief The BeOS sounds directory. + + \deprecated Legacy BeOS definition to be phased out, use + \c B_SYSTEM_SOUNDS_DIRECTORY instead. + + \since BeOS R3 +*/ + + +/*! + \var directory_which B_BEOS_DATA_DIRECTORY + \brief The BeOS data directory. + + \deprecated Legacy BeOS definition to be phased out, use + \c B_SYSTEM_DATA_DIRECTORY instead. + + \since BeOS R3 +*/ + + +//// find_path[s]() flags /*! \var B_FIND_PATH_CREATE_DIRECTORY - Flag for the find_path_etc(), find_path_for_path_etc(), find_paths_etc(), - and BPathFinder API. Specifies that, if the resulting path doesn't exist, - it shall be created as a directory, including all missing ancestors. Failure - to create the path will cause the respective function to fail. + \brief Specifies that if the resulting path doesn't exist, it shall be + created a directory, including all missing ancestors. + Failure to create the path will cause the respective function to fail. + + Flag for the find_path_etc(), find_path_for_path_etc(), find_paths_etc(), + and BPathFinder API. + + \since Haiku R1 +*/ + + +/*! \var B_FIND_PATH_CREATE_PARENT_DIRECTORY - Flag for the find_path_etc(), find_path_for_path_etc(), find_paths_etc(), - and BPathFinder API. Specifies that, if the resulting path's parent doesn't - exist, the parent shall be created as a directory, including all missing - ancestors. Failure to create the directory will cause the respective - function to fail. + \brief Specifies that if the resulting path's parent doesn't exist, the + parent shall be created as a directory, including all missing + ancestors. + + Failure to create the directory will cause the respective function to fail. - \var B_FIND_PATH_EXISTING_ONLY Flag for the find_path_etc(), find_path_for_path_etc(), find_paths_etc(), - and BPathFinder API. Specifies that, if the resulting path doesn't exist, - the respective function shall skip it. In case multiple paths shall be - retrieved and none of the paths exists, the function shall fail with - \c B_ENTRY_NOT_FOUND. + and BPathFinder API. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_EXISTING_ONLY + \brief Specifies that if the resulting path doesn't exist, the respective + function shall skip it. + + In case multiple paths shall be retrieved and none of the paths exists, + the function shall fail with \c B_ENTRY_NOT_FOUND. + + Flag for the find_path_etc(), find_path_for_path_etc(), find_paths_etc(), + and BPathFinder API. + + \since Haiku R1 */ @@ -378,94 +990,232 @@ location and those that based off an image or given path. The latter are not valid argument for all functions. - \var B_FIND_PATH_INSTALLATION_LOCATION_DIRECTORY - The installation location base directory. - - \var B_FIND_PATH_ADD_ONS_DIRECTORY - The add-ons directory. - - \var B_FIND_PATH_APPS_DIRECTORY - The application directory. - - \var B_FIND_PATH_BIN_DIRECTORY - The command line application directory (Unix "bin" directory). - - \var B_FIND_PATH_BOOT_DIRECTORY - The directory containing booting related files. - - \var B_FIND_PATH_CACHE_DIRECTORY - The directory used for cache files. - - \var B_FIND_PATH_DATA_DIRECTORY - The base directory used for read-only data. - - \var B_FIND_PATH_DEVELOP_DIRECTORY - The directory containing development related files. - - \var B_FIND_PATH_DEVELOP_LIB_DIRECTORY - The the development library directory. This is the directory where the - linker finds libraries. - - \var B_FIND_PATH_DOCUMENTATION_DIRECTORY - The base directory used for documentation. - - \var B_FIND_PATH_ETC_DIRECTORY - The directory used for Unix-like installation location wide settings (Unix - "etc" directory). - - \var B_FIND_PATH_FONTS_DIRECTORY - The fonts directory. - - \var B_FIND_PATH_HEADERS_DIRECTORY - The development header files directory. - - \var B_FIND_PATH_LIB_DIRECTORY - The runtime library directory. This is where the runtime loader finds - libraries. - - \var B_FIND_PATH_LOG_DIRECTORY - The directory where log files are put. - - \var B_FIND_PATH_MEDIA_NODES_DIRECTORY - The media node add-ons directory. - - \var B_FIND_PATH_PACKAGES_DIRECTORY - The directory where activated packages live. - - \var B_FIND_PATH_PREFERENCES_DIRECTORY - The preference application directory. - - \var B_FIND_PATH_SERVERS_DIRECTORY - The server and daemon program directory. - - \var B_FIND_PATH_SETTINGS_DIRECTORY - The directory used for installation location wide settings. Note that for - the user's home config installation location, this is not the same as the - user's settings directory. Software installed in that installation location - puts their global settings files here. - - \var B_FIND_PATH_SOUNDS_DIRECTORY - The directory for sound files. - - \var B_FIND_PATH_SPOOL_DIRECTORY - The directory for spool data (e.g. pending printer jobs). - - \var B_FIND_PATH_TRANSLATORS_DIRECTORY - The translator add-ons directory. - - \var B_FIND_PATH_VAR_DIRECTORY - The directory for variable data (Unix "var" directory). - - \var B_FIND_PATH_IMAGE_PATH - The path of the image file that was identified by a pointer argument passed - to the respective function. - - \var B_FIND_PATH_PACKAGE_PATH - The path of the package the file referred to by the specified path belongs - to. + \since Haiku R1 */ +/*! + \var B_FIND_PATH_INSTALLATION_LOCATION_DIRECTORY + \brief The installation location base directory. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_ADD_ONS_DIRECTORY + \brief The add-ons directory. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_APPS_DIRECTORY + \brief The application directory. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_BIN_DIRECTORY + \brief The command line application directory (Unix "bin" directory). + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_BOOT_DIRECTORY + \brief The directory containing booting related files. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_CACHE_DIRECTORY + \brief The directory used for cache files. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_DATA_DIRECTORY + \brief The base directory used for read-only data. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_DEVELOP_DIRECTORY + \brief The directory containing development related files. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_DEVELOP_LIB_DIRECTORY + \brief The the development library directory. + + This is the directory where the linker finds libraries. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_DOCUMENTATION_DIRECTORY + \brief The base directory used for documentation. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_ETC_DIRECTORY + \brief The directory used for Unix-like installation location wide + settings (Unix "etc" directory). + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_FONTS_DIRECTORY + \brief The fonts directory. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_HEADERS_DIRECTORY + \brief The development header files directory. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_LIB_DIRECTORY + \brief The runtime library directory. + + This is where the runtime loader finds libraries. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_LOG_DIRECTORY + \brief The directory where log files are put. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_MEDIA_NODES_DIRECTORY + \brief The media node add-ons directory. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_PACKAGES_DIRECTORY + \brief The directory where activated packages live. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_PREFERENCES_DIRECTORY + \brief The preference application directory. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_SERVERS_DIRECTORY + \brief The server and daemon program directory. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_SETTINGS_DIRECTORY + \brief The directory used for installation location wide settings. + + Note that for the user's home config installation location, this is not + the same as the user's settings directory. Software installed in that + installation location puts their global settings files here. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_SOUNDS_DIRECTORY + \brief The directory for sound files. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_SPOOL_DIRECTORY + \brief The directory for spool data, e.g. pending printer jobs. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_TRANSLATORS_DIRECTORY + \brief The translator add-ons directory. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_VAR_DIRECTORY + \brief The directory for variable data (Unix "var" directory). + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_IMAGE_PATH + \brief The path of the image file that was identified by a pointer + argument passed to the respective function. + + \since Haiku R1 +*/ + + +/*! + \var B_FIND_PATH_PACKAGE_PATH + \brief The path of the package the file referred to by the specified path + belongs to. + + \since Haiku R1 +*/ + + +/*! + + /*! \fn status_t find_directory(directory_which which, dev_t volume, bool createIt, char* pathString, int32 length) @@ -474,6 +1224,8 @@ Fills up to \a length characters of \a pathString with the path to \a which on \a volume. Creates the directory if it doesn't exists if \a createIt is set. + + \since BeOS R3 */ @@ -483,6 +1235,8 @@ \brief C++ interface to find_directory Set \a path to \a which on \a volume. + + \since BeOS R3 */ @@ -491,7 +1245,7 @@ path_base_directory baseDirectory, const char* subPath, char* pathBuffer, size_t bufferSize) \brief Retrieves a path in the file system layout based on a loaded image - file. + file. The function determines the path of the image (i.e. executable, library, or add-on) file associated with \a codePointer, a pointer to a location in the @@ -511,20 +1265,22 @@ image file, if any. \param codePointer A pointer to code or static data belonging to the image - based on which the path shall be computed. The special value - \c B_APP_IMAGE_SYMBOL can be used to refer to the program image, and - \c B_CURRENT_IMAGE_SYMBOL for the caller's image. + based on which the path shall be computed. The special value + \c B_APP_IMAGE_SYMBOL can be used to refer to the program image, and + \c B_CURRENT_IMAGE_SYMBOL for the caller's image. \param baseDirectory Constant indicating which path to retrieve. \param subPath Relative subpath that shall be appended. Can be \c NULL. \param pathBuffer Pointer to a pre-allocated buffer the retrieved path - shall be stored in. + shall be stored in. \param bufferSize Size of the \a pathBuffer buffer. \return A status code. \retval B_OK Everything went fine. \retval B_BUFFER_OVERFLOW The provided \a pathBuffer wasn't large enough. \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the - path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified - and the image file doesn't belong to a package. + path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified + and the image file doesn't belong to a package. + + \since Haiku R1 */ @@ -533,7 +1289,7 @@ const char* architecture, path_base_directory baseDirectory, const char* subPath, uint32 flags, char* pathBuffer, size_t bufferSize) \brief Retrieves a path in the file system layout based on a loaded image - file. + file. The function determines the path of the image (i.e. executable, library, or add-on) file associated with \a codePointer, a pointer to a location in the @@ -558,36 +1314,38 @@ package containing the image file, if any. \param codePointer A pointer to code or static data belonging to the image - based on which the path shall be computed. The special value - \c B_APP_IMAGE_SYMBOL can be used to refer to the program image, and - \c B_CURRENT_IMAGE_SYMBOL for the caller's image. + based on which the path shall be computed. The special value + \c B_APP_IMAGE_SYMBOL can be used to refer to the program image, and + \c B_CURRENT_IMAGE_SYMBOL for the caller's image. \param dependency The name of the package's "requires" entry to be used for - resolving the installation location. Can be \c NULL. + resolving the installation location. Can be \c NULL. \param architecture The name of the architecture to be used for resolving - architecture dependent paths. Can be \c NULL, in which case the caller's - architecture is used. + architecture dependent paths. Can be \c NULL, in which case the + caller's architecture is used. \param baseDirectory Constant indicating which path to retrieve. \param subPath Relative subpath that shall be appended. Can be \c NULL. \param flags Bitwise OR of any of the following flags: - - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't exist, - create it as a directory (including all missing ancestors). - - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's parent - doesn't exist, create the parent directory (including all missing - ancestors). - - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist, - fail with \c B_ENTRY_NOT_FOUND. + - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't + exist, create it as a directory (including all missing ancestors). + - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's + parent doesn't exist, create the parent directory (including all + missing ancestors). + - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist, + fail with \c B_ENTRY_NOT_FOUND. \param pathBuffer Pointer to a pre-allocated buffer the retrieved path - shall be stored in. + shall be stored in. \param bufferSize Size of the \a pathBuffer buffer. \return A status code. \retval B_OK Everything went fine. \retval B_BUFFER_OVERFLOW The provided \a pathBuffer wasn't large enough. \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the - path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified - and the image file doesn't belong to a package, or \c dependency was - specified, but isn't a "requires" entry of the package, or - \c B_FIND_PATH_EXISTING_ONLY was specified and the resulting path - doesn't exist. + path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified + and the image file doesn't belong to a package, or \c dependency + was specified, but isn't a "requires" entry of the package, or + \c B_FIND_PATH_EXISTING_ONLY was specified and the resulting path + doesn't exist. + + \since Haiku R1 */ @@ -616,14 +1374,16 @@ \param baseDirectory Constant indicating which path to retrieve. \param subPath Relative subpath that shall be appended. Can be \c NULL. \param pathBuffer Pointer to a pre-allocated buffer the retrieved path - shall be stored in. + shall be stored in. \param bufferSize Size of the \a pathBuffer buffer. \return A status code. \retval B_OK Everything went fine. \retval B_BUFFER_OVERFLOW The provided \a pathBuffer wasn't large enough. \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the - path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified - and \a path does refer to a file that belongs to a package. + path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified + and \a path does refer to a file that belongs to a package. + + \since Haiku R1 */ @@ -657,32 +1417,34 @@ \param path A path based on which the path shall be computed. \param dependency The name of the package's "requires" entry to be used for - resolving the installation location. Can be \c NULL. + resolving the installation location. Can be \c NULL. \param architecture The name of the architecture to be used for resolving - architecture dependent paths. Can be \c NULL, in which case the - architecture associated with \a path is used. + architecture dependent paths. Can be \c NULL, in which case the + architecture associated with \a path is used. \param baseDirectory Constant indicating which path to retrieve. \param subPath Relative subpath that shall be appended. Can be \c NULL. \param flags Bitwise OR of any of the following flags: - - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't exist, - create it as a directory (including all missing ancestors). - - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's parent - doesn't exist, create the parent directory (including all missing - ancestors). - - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist, - fail with \c B_ENTRY_NOT_FOUND. + - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't + exist, create it as a directory (including all missing ancestors). + - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's + parent doesn't exist, create the parent directory (including all + missing ancestors). + - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist, + fail with \c B_ENTRY_NOT_FOUND. \param pathBuffer Pointer to a pre-allocated buffer the retrieved path - shall be stored in. + shall be stored in. \param bufferSize Size of the \a pathBuffer buffer. \return A status code. \retval B_OK Everything went fine. \retval B_BUFFER_OVERFLOW The provided \a pathBuffer wasn't large enough. \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the - path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified - and \a path does refer to a file that belongs to a package, or - \c dependency was specified, but isn't a "requires" entry of the - package, or \c B_FIND_PATH_EXISTING_ONLY was specified and the resulting - path doesn't exist. + path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified + and \a path does refer to a file that belongs to a package, or + \c dependency was specified, but isn't a "requires" entry of the + package, or \c B_FIND_PATH_EXISTING_ONLY was specified and the + resulting path doesn't exist. + + \since Haiku R1 */ @@ -709,13 +1471,16 @@ \param baseDirectory Constant indicating which paths to retrieve. \param subPath Relative subpath that shall be appended. Can be \c NULL. \param _paths Pointer to a pre-allocated variable where the pointer to the - allocated path array shall be stored on success. + allocated path array shall be stored on success. \param _pathCount Pointer to a pre-allocated variable where the number of - paths in the path array shall be stored on success. + paths in the path array shall be stored on success. + \return A status code. \retval B_OK Everything went fine. \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the - paths doesn't exist. + paths doesn't exist. + + \since Haiku R1 */ @@ -742,25 +1507,27 @@ pointer. \param architecture The name of the architecture to be used for resolving - architecture dependent paths. Can be \c NULL, in which case the caller's - architecture is used. + architecture dependent paths. Can be \c NULL, in which case the + caller's architecture is used. \param baseDirectory Constant indicating which paths to retrieve. \param subPath Relative subpath that shall be appended. Can be \c NULL. \param flags Bitwise OR of any of the following flags: - - \c B_FIND_PATH_CREATE_DIRECTORY: If a resulting path doesn't exist, - create it as a directory (including all missing ancestors). - - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If a resulting path's parent - doesn't exist, create the parent directory (including all missing - ancestors). - - \c B_FIND_PATH_EXISTING_ONLY: If a resulting path doesn't exist, skip - it. If none of the paths exist, fail with \c B_ENTRY_NOT_FOUND. + - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't + exist, create it as a directory (including all missing ancestors). + - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's + parent doesn't exist, create the parent directory (including all + missing ancestors). + - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist, + fail with \c B_ENTRY_NOT_FOUND. \param _paths Pointer to a pre-allocated variable where the pointer to the - allocated path array shall be stored on success. + allocated path array shall be stored on success. \param _pathCount Pointer to a pre-allocated variable where the number of - paths in the path array shall be stored on success. + paths in the path array shall be stored on success. \return A status code. \retval B_OK Everything went fine. \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the - paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was specified and - none of the resulting paths do exist. + paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was + specified and none of the resulting paths do exist. + + \since Haiku R1 */ diff --git a/docs/user/storage/Mime.dox b/docs/user/storage/Mime.dox index 321077f76e..bf2727093f 100644 --- a/docs/user/storage/Mime.dox +++ b/docs/user/storage/Mime.dox @@ -1,5 +1,5 @@ /* - * Copyright 2013 Haiku Inc. All rights reserved. + * Copyright 2013-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: @@ -7,8 +7,8 @@ * John Scipione, jscipione@gmail.com * * Corresponds to: - * headers/os/storage/Mime.h hrev45224 - * src/kits/storage/Mime.cpp hrev45224 + * headers/os/storage/Mime.h hrev47402 + * src/kits/storage/Mime.cpp hrev47402 */ @@ -24,6 +24,8 @@ \enum icon_size \ingroup storage \brief Legacy BeOS icon size constants. + + \since BeOS R3 */ @@ -31,6 +33,8 @@ \var icon_size B_LARGE_ICON 32x32 "Large" icon. + + \since BeOS R3 */ @@ -38,34 +42,39 @@ \var icon_size B_MINI_ICON 16x16 "Mini" icon. + + \since BeOS R3 */ /*! \var B_UPDATE_MIME_INFO_NO_FORCE + \brief Files that already have a \c BEOS:TYPE attribute won't be updated. - Files that already have a \c BEOS:TYPE attribute won't be updated. + \since Haiku R1 */ /*! \var B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE + \brief Files that already have a \c BEOS:TYPE attribute will be updated + too, but \c BEOS:TYPE itself will remain untouched. - Files that already have a \c BEOS:TYPE attribute will be updated too, but - \c BEOS:TYPE itself will remain untouched. + \since Haiku R1 */ /*! \var B_UPDATE_MIME_INFO_FORCE_UPDATE_ALL + \brief Similar to \c B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE, but the + \c BEOS:TYPE attribute will be updated too. - Similar to \c B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE, but the \c BEOS:TYPE - attribute will be updated too. + \since Haiku R1 */ /*! - \fn int update_mime_info(const char *path, int recursive, int synchronous, + \fn int update_mime_info(const char* path, int recursive, int synchronous, int force) \brief Updates the MIME information (i.e MIME type) for one or more files. @@ -78,21 +87,23 @@ \param path The path to a file or directory, or \c NULL. \param recursive Triggers recursive behavior if not \c NULL. \param synchronous If not \c NULL update_mime_info() waits until the - operation is finished, otherwise it returns immediately and the - update is done asynchronously. + operation is finished, otherwise it returns immediately and the + update is done asynchronously. \param force Specifies how to handle files that already have MIME - information. See enum definitions for more information. - - \c B_UPDATE_MIME_INFO_NO_FORCE - - \c B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE - - \c B_UPDATE_MIME_INFO_FORCE_UPDATE_ALL + information. See enum definitions for more information: + - \c B_UPDATE_MIME_INFO_NO_FORCE + - \c B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE + - \c B_UPDATE_MIME_INFO_FORCE_UPDATE_ALL - \returns A status code. \c B_OK if everything went fine, an error code - otherwise. + \return A status code, \c B_OK if everything went fine, an error code + otherwise. + + \since BeOS R3 */ /*! - \fn status_t create_app_meta_mime(const char *path, int recursive, + \fn status_t create_app_meta_mime(const char* path, int recursive, int synchronous, int force) \brief Creates a MIME database entry for one or more applications. @@ -105,65 +116,128 @@ \param path The path to an application file, a directory, or \c NULL. \param recursive Trigger recursive behavior if not \c NULL. \param synchronous Waits until the operation is finished if not \c NULL, - otherwise it returns immediately and the operation is done - asynchronously. + otherwise it returns immediately and the operation is done + asynchronously. \param force Entries are created even if they do already exist if not - \c NULL. + \c NULL. - \returns A status code. \c B_OK if everything went fine, an error code - otherwise. + \return A status code, \c B_OK if everything went fine, an error code + otherwise. + + \since BeOS R3 */ /*! - \fn status_t get_device_icon(const char *device, void *icon, int32 size) + \fn status_t get_device_icon(const char* device, void* icon, int32 size) \brief Retrieves an icon associated with a given device. \param device The path to the device. \param icon A pointer to a buffer the icon data shall be written to. \param size The size of the icon to retrieve. Currently 16 - (\c B_MINI_ICON) and 32 (\c B_LARGE_ICON) are supported. + (\c B_MINI_ICON) and 32 (\c B_LARGE_ICON) are supported. - \returns A status code. - \retval B_OK Everything went fine. + \return A status code, \c B_OK if everything went fine, an error code + otherwise. + \retval B_OK Retrieved the icon successfully. \retval B_BAD_VALUE \a device or \a icon was \c NULL. \retval B_NO_MEMORY Ran out of memory allocating bitmap. + + \since BeOS R3 */ /*! - \fn status_t get_device_icon(const char *device, BBitmap *icon, + \fn status_t get_device_icon(const char* device, BBitmap* icon, icon_size which) - \brief Retrieves an icon associated with a given device into a BBitmap. + \brief Retrieves an icon associated with a given device into a BBitmap, + C++ only. \param device The path to the device. \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). + to store the requested icon (16x16 for the mini and 32x32 for the + large icon). \param which The size of the icon to retrieve. Currently 16 - (\c B_MINI_ICON) and 32 (\c B_LARGE_ICON) are supported. + (\c B_MINI_ICON) and 32 (\c B_LARGE_ICON) are supported. - \returns A status code. \c B_OK if everything went fine, an error code - otherwise. + \return A status code, \c B_OK if everything went fine, an error code + otherwise. + \retval B_OK Retrieved the icon successfully. + \retval B_BAD_VALUE \a device or \a icon was \c NULL. + + \since Haiku R1 */ /*! \fn status_t get_device_icon(const char* device, uint8** _data, size_t* _size, type_code* _type); - \brief Undocumented. + \brief Try to get the icon by name first, if that fails try to get the + vector icon, C++ only. + + \param device The path to the device. + \param _data A pointer to a pointer to an array of uint8 pixel data to + fill out. + \param _size The size of the icon to fill out. If vector, it is filled in + with the width in pixels, if bitmap, one of the following constants: + - \c B_MINI_ICON + - \c B_LARGE_ICON + \param _type The icon type code to fill out, one of the following: + - \c B_MINI_ICON_TYPE + - \c B_LARGE_ICON_TYPE + - \c B_VECTOR_ICON_TYPE + + \return A status code, \c B_OK if everything went fine, an error code + otherwise. + \retval B_OK Retrieved the icon successfully. + \retval B_BAD_VALUE \a device, \a _data, \a _size, or _type was \c NULL. + + \since Haiku R1 */ /*! \fn status_t get_named_icon(const char* name, BBitmap* icon, icon_size which); - \brief Undocumented. + \brief Get the icon by name, C++ only. + + \param name The name of the icon to get. + \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 which The size of the icon to retrieve. Currently 16 + (\c B_MINI_ICON) and 32 (\c B_LARGE_ICON) are supported. + + \return A status code, \c B_OK if everything went fine, an error code + otherwise. + \retval B_OK Retrieved the icon successfully. + \retval B_BAD_VALUE \a name or \a icon was \c NULL. + + \since Haiku R1 */ /*! - \fn status_t get_named_icon(const char* name, uint8** _data, + \fn status_t get_named_icon(const char* name, uint8** _data, size_t* _size, type_code* _type); - \brief Undocumented. + \brief Get the icon by name, C++ only. + + \param name The name of the icon to get. + \param _data A pointer to a pointer to an array of uint8 pixel data to + fill out. + \param _size The size of the icon to fill out. If vector, it is filled in + with the width in pixels, if bitmap, one of the following constants: + - \c B_MINI_ICON + - \c B_LARGE_ICON + \param _type The icon type code to fill out, one of the following: + - \c B_MINI_ICON_TYPE + - \c B_LARGE_ICON_TYPE + - \c B_VECTOR_ICON_TYPE + + \return A status code, \c B_OK if everything went fine, an error code + otherwise. + \retval B_OK Retrieved the icon successfully. + \retval B_BAD_VALUE \a name, \a _data, \a _size, or \c _type was \c NULL. + + \since Haiku R1 */ diff --git a/docs/user/storage/MimeType.dox b/docs/user/storage/MimeType.dox index 912c83ab47..87a1e9a0ae 100644 --- a/docs/user/storage/MimeType.dox +++ b/docs/user/storage/MimeType.dox @@ -1,16 +1,15 @@ /* - * Copyright 2011 Haiku, Inc. All rights reserved. + * Copyright 2011-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: - * Tyler Dauwalder * Ingo Weinhold, bonefish@users.sf.net * Axel Dörfler, axeld@pinc-software.de * John Scipione, jscipione@gmail.com * * Corresponds to: - * headers/os/storage/MimeType.h hrev43528 - * src/kits/storage/MimeType.cpp hrev43528 + * headers/os/storage/MimeType.h hrev47402 + * src/kits/storage/MimeType.cpp hrev47402 */ @@ -26,43 +25,51 @@ \class BMimeType \ingroup storage \ingroup libbe - \brief A class that represents a MIME (Multipurpose Internet Mail - Extensions) type string. + \brief A class that represents a MIME (Multi-purpose Internet Mail + Extensions) type string. MIME types use, has grown beyond describing the content of email to describe the content types of applications and file formats. - MIME types consist of a super type and a + MIME types consist of a supertype and a subtype. + + \since BeOS R3 */ /*! \fn BMimeType::BMimeType() \brief Creates an uninitialized BMimeType object. + + \since BeOS R3 */ /*! - \fn BMimeType::BMimeType(const char *mimeType) + \fn BMimeType::BMimeType(const char* mimeType) \brief Creates a BMimeType object and initializes it to the supplied - MIME type. + MIME type. The supplied string must specify a valid MIME type or supertype. \param mimeType The MIME string. \sa SetTo() for further information. + + \since BeOS R3 */ /*! \fn BMimeType::~BMimeType() \brief Frees all resources associated with this object. + + \since BeOS R3 */ /*! - \fn status_t BMimeType::SetTo(const char *mimeType) + \fn status_t BMimeType::SetTo(const char* mimeType) \brief Initializes this object to the supplied MIME type. The supplied string must specify a valid MIME type or supertype. @@ -85,15 +92,19 @@ \returns A status code. \retval B_OK Everything went fine. - \retval B_NO_INIT \c NULL \a mimeType string. \retval B_BAD_VALUE Invalid \a mimeType string. + \retval B_NO_INIT BMimeType was uninitialized. \retval B_NO_MEMORY Insufficient memory to copy the MIME string. + + \since BeOS R3 */ /*! \fn void BMimeType::Unset() \brief Returns the object to an uninitialized state. + + \since BeOS R3 */ @@ -102,7 +113,9 @@ \brief Returns the result of the most recent constructor or SetTo() call. \returns \c B_OK If the object is properly initialized, a specific - error code otherwise. + error code otherwise. + + \since BeOS R3 */ @@ -111,7 +124,9 @@ \brief Returns the MIME string represented by this object. \return The MIME string, if the object is properly initialized, \c NULL - otherwise. + otherwise. + + \since BeOS R3 */ @@ -120,9 +135,11 @@ \brief Returns whether the object represents a valid MIME type. \return \c true, if the object is properly initialized, \c false - otherwise. + otherwise. \sa SetTo() for further information. + + \since BeOS R3 */ @@ -131,39 +148,46 @@ \brief Returns whether this objects represents a supertype. \return \c true, if the object is properly initialized and represents a - supertype, \c false otherwise. + supertype, \c false otherwise. + + \since BeOS R3 */ /*! \fn bool BMimeType::IsInstalled() const \brief Returns whether or not this type is currently installed in the - MIME database. + MIME database. To add the MIME type to the database, call \c Install(). To remove the MIME type from the database, call \c Delete(). - \returns A \c bool indicating whether or not this type is currently - installed in the MIME database. + \return A \c bool indicating whether or not this type is currently + installed in the MIME database. \retval true The MIME type is currently installed in the database. \retval false The MIME type is not currently installed in the database. + + \since BeOS R3 */ /*! - \fn status_t BMimeType::GetSupertype(BMimeType *superType) const - \brief Gets the supertype of the MIME type represented by this object. + \fn status_t BMimeType::GetSupertype(BMimeType* supertype) const + \brief Gets the \a supertype of the MIME type represented by this object. - The supplied object is initialized to this object's supertype. If this + The supplied object is initialized to this object's \a supertype. If this BMimeType is not properly initialized, the supplied object will be Unset(). - \param superType A pointer to the BMimeType object that shall be - initialized to this object's supertype. + \param supertype A pointer to the BMimeType object that shall be + initialized to this object's \a supertype. \returns A status code. \retval B_OK Everything went fine. \retval B_BAD_VALUE \c NULL \a superType, this object is not initialized, - or this object is a supertype only. + or this object is a supertype only. + \retval B_NO_INIT BMimeType was uninitialized. + + \since BeOS R3 */ @@ -175,16 +199,18 @@ MIME string, ignoring case, or if both are not initialized. \warning In BeOS R5 two uninitialized BMimeType objects were not - considered to be equal, in Haiku they are. + considered to be equal, in Haiku they are. \param type The BMimeType to be compared with. \return \c true, if the objects are equal, \c false otherwise. + + \since BeOS R3 */ /*! - \fn bool BMimeType::operator==(const char *type) const + \fn bool BMimeType::operator==(const char* type) const \brief Returns whether this and the supplied MIME type are equal. A BMimeType objects equals a MIME string, if its MIME string equals the @@ -192,23 +218,27 @@ is \c NULL. \warning In BeOS R5 an uninitialized BMimeType object was not - considered to be equal to \c NULL, in Haiku it is. + considered to be equal to \c NULL, in Haiku it is. \param type The MIME string to be compared with. \return \c true, if the MIME types are equal, \c false otherwise. + + \since BeOS R4 */ /*! - \fn bool BMimeType::Contains(const BMimeType *type) const + \fn bool BMimeType::Contains(const BMimeType* type) const \brief Returns whether this MIME type is a supertype of or equals the supplied one. \param type The MIME type. \returns \c true, if this MIME type is a supertype of or equals the - supplied one, \c false otherwise. + supplied one, \c false otherwise. + + \since BeOS R3 */ @@ -218,11 +248,15 @@ To check if the MIME type is already installed, call \c IsInstalled(). To remove the MIME type from the database, call \c Delete(). - + \note The R5 implementation returns random values if the type is already installed, so be sure to check \c IsInstalled() first. - + \returns \c B_OK on success or another error code on failure. + + \see Delete() + + \since BeOS R3 */ @@ -232,17 +266,19 @@ To check if the MIME type is already installed, call \c IsInstalled(). To add the MIME type to the database, call \c Install(). - + \note Calling \c BMimeType::Delete() does not uninitialize or otherwise - deallocate the \c BMimeType object; it simply removes the type from the - database. - + deallocate the \c BMimeType object; it simply removes the type from + the database. + \returns \c B_OK on success or another error code on failure. + + \since BeOS R3 */ /*! - \fn status_t BMimeType::GetIcon(BBitmap *icon, icon_size size) const + \fn status_t BMimeType::GetIcon(BBitmap* icon, icon_size size) const \brief Fetches the large or mini icon associated with the MIME type. The icon is copied into the \c BBitmap pointed to by \c icon. The bitmap @@ -251,14 +287,17 @@ (8-bit color). \param icon Pointer to a pre-allocated \c BBitmap of proper size and - colorspace into which the icon is copied. + colorspace into which the icon is copied. \param size Value that specifies which icon to return. - Currently \c B_LARGE_ICON and \c B_MINI_ICON are supported. + Currently \c B_LARGE_ICON and \c B_MINI_ICON are supported. \returns A status code. \retval B_OK Everything went fine. - \retval B_ENTRY_NOT_FOUND: No icon of the given size exists for the - given type. + \retval B_ENTRY_NOT_FOUND No icon of the given size exists for the + given type. + \retval B_NO_INIT BMimeType was uninitialized. + + \since BeOS R3 */ @@ -268,22 +307,25 @@ The icon data is returned in \c data. \param data Pointer in which the allocated icon data is returned. You - need to delete the buffer when you are done with it. + need to delete the buffer when you are done with it. \param size Pointer in which the size of the allocated icon data is - returned. + returned. \returns A status code. \retval B_OK Everything went fine. - \retval B_ENTRY_NOT_FOUND No icon of the given size exists for the given - type + \retval B_ENTRY_NOT_FOUND No icon of the given size found for the given + type. + \retval B_NO_INIT BMimeType was uninitialized. + + \since BeOS R3 */ /*! - \fn status_t BMimeType::GetPreferredApp(char *signature, + \fn status_t BMimeType::GetPreferredApp(char* signature, app_verb verb) const \brief Fetches the signature of the preferred application from - the MIME database. + the MIME database. The preferred app is the application that's used to access a file when, for example, the user double-clicks the file in a Tracker window. Unless @@ -294,24 +336,30 @@ The string pointed to by \c signature must be long enough to hold the preferred applications signature; a length of \c B_MIME_TYPE_LENGTH is recommended. - + \param signature Pointer to a pre-allocated string into which the - signature of the preferred app is copied. If the function fails, - the contents of the string are undefined. + signature of the preferred app is copied. If the function fails, + the contents of the string are undefined. \param verb \c app_verb value that specifies the type of access for which you are requesting the preferred app. Currently, the only supported app verb is \c B_OPEN. + \returns A status code. \retval B_OK Success \retval B_ENTRY_NOT_FOUND No preferred app exists for the given type - and app_verb. + and app_verb. + \retval B_NO_INIT BMimeType was uninitialized. + + \see SetPreferredApp() + + \since BeOS R3 */ /*! - \fn status_t BMimeType::GetAttrInfo(BMessage *info) const + \fn status_t BMimeType::GetAttrInfo(BMessage* info) const \brief Fetches from the MIME database a BMessage describing the attributes - typically associated with files of the given MIME type. + typically associated with files of the given MIME type. The attribute information is returned in a pre-allocated BMessage pointed to by the \c info parameter (note that the any prior contents of the @@ -352,19 +400,23 @@ editable, \c false if not - + The \c BMessage::what value is set to decimal \c 233, but is otherwise meaningless. \param info Pointer to a pre-allocated BMessage into which information about - the MIME type's associated file attributes is stored. + the MIME type's associated file attributes is stored. \returns \c B_OK on success or another error code on failure. + + \see SetAttrInfo() + + \since BeOS R3 */ /*! - \fn status_t BMimeType::GetFileExtensions(BMessage *extensions) const + \fn status_t BMimeType::GetFileExtensions(BMessage* extensions) const \brief Fetches the MIME type's associated filename extensions from the MIME database. @@ -378,44 +430,53 @@ the message will be destroyed). If the method succeeds, the format of the BMessage pointed to by \c extensions will be the following: - - The message's \c "extensions" field will contain an indexed array - of strings, one for each extension. The extensions are given - without the preceding \c "." character by convention. - - The message's \c "type" field will be a string containing the - MIME type whose associated file extensions you are fetching. - - The \c what member of the BMessage will be set to \c 234, but - is otherwise irrelevant. + - The message's \c "extensions" field will contain an indexed array + of strings, one for each extension. The extensions are given + without the preceding \c "." character by convention. + - The message's \c "type" field will be a string containing the + MIME type whose associated file extensions you are fetching. + - The \c what member of the BMessage will be set to \c 234, but + is otherwise irrelevant. Note that any other fields present in the BMessage passed to the most recent \c SetFileExtensions() call will also be returned. - + \param extensions Pointer to a pre-allocated BMessage into which the - MIME type's associated file extensions will be stored. + MIME type's associated file extensions will be stored. \returns \c B_OK on success or another error code on failure. + + \see SetFileExtensions() + + \since BeOS R3 */ /*! - \fn status_t BMimeType::GetShortDescription(char *description) const + \fn status_t BMimeType::GetShortDescription(char* description) const \brief Fetches the MIME type's short description from the MIME database. The string pointed to by \c description must be long enough to hold the short description; a length of \c B_MIME_TYPE_LENGTH is recommended. - + \param description Pointer to a pre-allocated string into which the long - description is copied. If the function fails, the contents of the - string are undefined. + description is copied. If the function fails, the contents of the + string are undefined. \returns A status code. \retval B_OK Success - \retval B_ENTRY_NOT_FOUND No short description exists for the given type + \retval B_ENTRY_NOT_FOUND No short description exists for the given type. + \retval B_NO_INIT BMimeType was uninitialized. + + \see SetShortDescription() + + \since BeOS R3 */ /*! - \fn status_t BMimeType::GetLongDescription(char *description) const + \fn status_t BMimeType::GetLongDescription(char* description) const \brief Fetches the MIME type's long description from the MIME database. The string pointed to by \c description must be long enough to @@ -423,19 +484,24 @@ recommended. \param description Pointer to a pre-allocated string into which the - long description is copied. If the function fails, the contents - of the string are undefined. + long description is copied. If the function fails, the contents + of the string are undefined. \returns A status code. \retval B_OK Success \retval B_ENTRY_NOT_FOUND No long description exists for the given type. + \retval B_NO_INIT BMimeType was uninitialized. + + \see SetLongDescription() + + \since BeOS R3 */ /*! - \fn status_t BMimeType::GetSupportingApps(BMessage *signatures) const + \fn status_t BMimeType::GetSupportingApps(BMessage* signatures) const \brief Fetches a \c BMessage containing a list of MIME signatures of - applications that are able to handle files of this MIME type. + applications that are able to handle files of this MIME type. If successful, the BMessage containing the MIME signatures will be of the following format: @@ -484,14 +550,18 @@ The \c BMessage::what value is meaningless and should be ignored. \param signatures Pointer to a pre-allocated BMessage into which the - signatures of the supporting applications will be copied. - - \returns \c B_OK on success or another error code on failure. + signatures of the supporting applications will be copied. + + \returns \c B_OK on success or an error code on failure. + + \see SetSupportingApps() + + \since BeOS R3 */ /*! - \fn status_t BMimeType::SetIcon(const BBitmap *icon, icon_size which) + \fn status_t BMimeType::SetIcon(const BBitmap* icon, icon_size which) \brief Sets the large or mini icon for the MIME type. The icon is copied from the \c BBitmap pointed to by \c icon. The bitmap @@ -502,12 +572,14 @@ If you want to erase the current icon, pass \c NULL as the \c icon argument. \param icon Pointer to a pre-allocated \c BBitmap of proper size and - colorspace containing the new icon, or \c NULL to clear the current - icon. + colorspace containing the new icon, or \c NULL to clear the current + icon. \param which Value that specifies which icon to update. Currently - \c B_LARGE_ICON and \c B_MINI_ICON are supported. + \c B_LARGE_ICON and \c B_MINI_ICON are supported. \returns \c B_OK on success or another error code on failure. + + \since BeOS R3 */ @@ -521,15 +593,17 @@ If you want to erase the current icon, pass \c NULL as the \a data argument. \param data Pointer to a buffer containing the new icon, or \c NULL to clear - the current icon. + the current icon. \param size Size of the provided buffer. \returns \c B_OK on success or another error code on failure. + + \since Haiku R1 */ /*! - \fn status_t BMimeType::SetPreferredApp(const char *signature, + \fn status_t BMimeType::SetPreferredApp(const char* signature, app_verb verb) \brief Sets the preferred application for the MIME type. @@ -546,17 +620,19 @@ and then the preferred app will be set. \param signature Pointer to a pre-allocated string containing the - signature of the new preferred app. + signature of the new preferred app. \param verb \c app_verb value that specifies the type of access for - which you are setting the preferred app. Currently, the only - supported app verb is \c B_OPEN. + which you are setting the preferred app. Currently, the only + supported app verb is \c B_OPEN. \returns \c B_OK on success or another error code on failure.*/ + + \since BeOS R3 */ /*! - \fn status_t BMimeType::SetAttrInfo(const BMessage *info) + \fn status_t BMimeType::SetAttrInfo(const BMessage* info) \brief Sets the description of the attributes typically associated with files of the given MIME type @@ -597,56 +673,60 @@ user editable, \c false if not - + The \c BMessage::what value is ignored. - + \param info Pointer to a pre-allocated and properly formatted BMessage - containing information about the file attributes typically associated - with the MIME type. + containing information about the file attributes typically + associated with the MIME type. \returns \c B_OK on success or another error code on failure. + + \since BeOS R3 */ /*! - \fn status_t BMimeType::SetFileExtensions(const BMessage *extensions) + \fn status_t BMimeType::SetFileExtensions(const BMessage* extensions) \brief Sets the list of filename extensions associated with the MIME type. The MIME database associates a list of filename extensions (a character string following the rightmost dot, \c ".", character in the filename) with each type. These extensions can then be used to help determine the - type of any untyped files that may be encountered. + type of any untyped files that may be encountered. The list of extensions is given in a pre-allocated BMessage pointed to by the \c extensions parameter. The format of the message should be as follows: - - The message's \c "extensions" field should contain an indexed array of - strings, one for each extension. The extensions are to be given - without the preceding \c "." character (i.e. \c "html" or \c "mp3", - not \c ".html" or \c ".mp3" ). - - The \c what member of the BMessage is ignored. - - \note any other fields present in the \c BMessage will currently be retained - and returned by calls to \c GetFileExtensions(); however, this may change in - the future, so it is recommended that you not rely on this behaviour, and - that no other fields be present. Also, note that no checking is performed to - verify the \c BMessage is properly formatted; it's up to you to do things - right. + - The message's \c "extensions" field should contain an indexed array of + strings, one for each extension. The extensions are to be given + without the preceding \c "." character (i.e. \c "html" or \c "mp3", + not \c ".html" or \c ".mp3" ). + - The \c what member of the BMessage is ignored. + + \note Any other fields present in the \c BMessage will currently be + retained and returned by calls to \c GetFileExtensions(); however, + this may change in the future, so it is recommended that you not rely + on this behavior, and that no other fields be present. Also, note that + no checking is performed to verify the \c BMessage is properly + formatted; it's up to you to do things right. Finally, bear in mind that \c SetFileExtensions() clobbers the existing set of extensions. If you want to augment a type's extensions, you should retrieve the existing set, add the new ones, and then call - \c SetFileExtensions(). - + \c SetFileExtensions(). + \param extensions Pointer to a pre-allocated, properly formatted BMessage - containing the new list of file extensions to associate with this MIME - type. + containing the new list of file extensions to associate with this + MIME type. \returns \c B_OK on success or another error code on failure. + + \since BeOS R3 */ /*! - \fn status_t BMimeType::SetShortDescription(const char *description) + \fn status_t BMimeType::SetShortDescription(const char* description) \brief Sets the short description field for the MIME type. The string pointed to by \c description must be of length less than @@ -656,14 +736,16 @@ and then the short description will be set. \param description Pointer to a pre-allocated string containing the - new short description. + new short description. \returns \c B_OK on success or another error code on failure. + + \since BeOS R3 */ /*! - \fn status_t BMimeType::SetLongDescription(const char *description) + \fn status_t BMimeType::SetLongDescription(const char* description) \brief Sets the long description field for the MIME type. The string pointed to by \c description must be of length less than @@ -673,82 +755,92 @@ and then the long description will be set. \param description Pointer to a pre-allocated string containing the new - long description + long description \returns \c B_OK on success or another error code on failure. + + \since BeOS R3 */ /*! - \fn status_t BMimeType::GetInstalledSupertypes(BMessage *supertypes) - \brief Fetches a BMessage listing all the MIME supertypes currently - installed in the MIME database. + \fn status_t BMimeType::GetInstalledSupertypes(BMessage* supertypes) + \brief Fetches a BMessage listing all the MIME \a supertypes currently + installed in the MIME database. The types are copied into the \c "super_types" field of the passed-in \c BMessage. The \c BMessage must be pre-allocated. - - \param supertypes Pointer to a pre-allocated \c BMessage into which the - MIME supertypes will be copied. + + \param supertypes Pointer to a pre-allocated \c BMessage into which the + MIME \a supertypes will be copied. \returns \c B_OK on success or another error code on failure. + + \since BeOS R3 */ /*! - \fn status_t BMimeType::GetInstalledTypes(BMessage *types) + \fn status_t BMimeType::GetInstalledTypes(BMessage* types) \brief Fetches a BMessage listing all the MIME types currently installed in the MIME database. The types are copied into the \c "types" field of the passed-in \c BMessage. The \c BMessage must be pre-allocated. - \param types Pointer to a pre-allocated \c BMessage into which the - MIME types will be copied. - - \returns \c B_OK on success or another error code on failure. -*/ - - -/*! - \fn status_t BMimeType::GetInstalledTypes(const char *supertype, - BMessage *types) - \brief Fetches a BMessage listing all the MIME subtypes of the given - supertype currently installed in the MIME database. - - The types are copied into the \c "types" field of the passed-in \c BMessage. - The \c BMessage must be pre-allocated. - - \param supertype Pointer to a string containing the MIME supertype whose - subtypes you wish to retrieve. \param types Pointer to a pre-allocated \c BMessage into which the - appropriate MIME subtypes will be copied. + MIME types will be copied. \returns \c B_OK on success or another error code on failure. + + \since BeOS R3 */ /*! - \fn status_t BMimeType::GetWildcardApps(BMessage *wild_ones) + \fn status_t BMimeType::GetInstalledTypes(const char* supertype, + BMessage* types) + \brief Fetches a BMessage listing all the MIME subtypes of the given + \a supertype currently installed in the MIME database. + + The types are copied into the \c "types" field of the passed-in + \c BMessage. The \c BMessage must be pre-allocated. + + \param supertype Pointer to a string containing the MIME \a supertype whose + subtypes you wish to retrieve. + \param types Pointer to a pre-allocated \c BMessage into which the + appropriate MIME subtypes will be copied. + + \returns \c B_OK on success or another error code on failure. + + \since BeOS R3 +*/ + + +/*! + \fn status_t BMimeType::GetWildcardApps(BMessage* wild_ones) \brief Fetches a \c BMessage containing a list of MIME signatures of - applications that are able to handle files of any type. + applications that are able to handle files of any type. This function is the same as calling \c GetSupportingApps() on a \c BMimeType object initialized to a MIME type of] \c "application/octet-stream". \param wild_ones Pointer to a pre-allocated BMessage into which - signatures of applications supporting files of any type - are copied. + signatures of applications supporting files of any type + are copied. \returns \c B_OK on success or another error code on failure. \sa GetSupportingApps() for details on the format of the data returned in - the \c BMessage pointed to by \c wild_ones. + the \c BMessage pointed to by \c wild_ones. + + \since BeOS R3 */ /*! - \fn bool BMimeType::IsValid(const char *string) + \fn bool BMimeType::IsValid(const char* string) \brief Returns whether the given string represents a valid MIME type. \param string The MIME type string. @@ -756,14 +848,15 @@ \return \c true, if the given string represents a valid MIME type. \sa SetTo() for further information. + + \since BeOS R3 */ - /*! - \fn status_t BMimeType::GetAppHint(entry_ref *ref) const + \fn status_t BMimeType::GetAppHint(entry_ref* ref) const \brief Fetches an \c entry_ref that serves as a hint as to where the MIME - type's preferred application might live + type's preferred application might live The app hint is a path that identifies the executable that should be used when launching an application that has this signature. For example, when @@ -776,18 +869,20 @@ The \c entry_ref pointed to by \c ref must be pre-allocated. \param ref Pointer to a pre-allocated \c entry_ref into which the location - of the app hint is copied. If the function fails, the contents of - the \c entry_ref are undefined. + of the app hint is copied. If the function fails, the contents of + the \c entry_ref are undefined. - \return - - \c B_OK: Success - - \c B_ENTRY_NOT_FOUND: No app hint exists for the given type - - other error code: Failure + \return A status code, B_OK on success or an error code otherwise. + \retval B_OK The ref was retrieved successfully. + \retval B_ENTRY_NOT_FOUND No app hint existed for the given \a ref. + \retval B_NO_INIT BMimeType was uninitialized. + + \since BeOS R3 */ /*! - \fn status_t BMimeType::SetAppHint(const entry_ref *ref) + \fn status_t BMimeType::SetAppHint(const entry_ref* ref) \brief Sets the app hint field for the MIME type The app hint is a path that identifies the executable that should be used @@ -805,24 +900,30 @@ such an \c entry_ref would render the app hint useless. \param ref Pointer to a pre-allocated \c entry_ref containting the location - of the new app hint + of the new app hint \returns \c B_OK on success or another error code on failure. + \retval B_OK The ref was retrieved successfully. + \retval B_NO_INIT BMimeType was uninitialized. + \retval B_BAD_VALUE \a ref was \c NULL. + \retval B_NO_INIT BMimeType was uninitialized. + + \since BeOS R3 */ /*! - \fn status_t BMimeType::GetIconForType(const char *type, BBitmap *icon, + \fn status_t BMimeType::GetIconForType(const char* type, BBitmap* icon, icon_size which) const \brief Fetches the large or mini icon used by an application of this type - for files of the given type. - + for files of the given type. + This can be confusing, so here's how this function is intended to be used: - - The actual \c BMimeType object should be set to the MIME signature - of an application for whom you want to look up custom icons for - custom MIME types. - - The \c type parameter specifies the file type whose custom icon you - are fetching. + - The actual \c BMimeType object should be set to the MIME signature + of an application for whom you want to look up custom icons for + custom MIME types. + - The \c type parameter specifies the file type whose custom icon you + are fetching. The type of the \c BMimeType object is not required to actually be a subtype of \c "application/"; that is the intended use however, and calling @@ -835,47 +936,53 @@ (8-bit color). \param type Pointer to a pre-allocated string containing the MIME type - whose custom icon you wish to fetch. + whose custom icon you wish to fetch. \param icon Pointer to a pre-allocated \c BBitmap of proper size and - colorspace into which the icon is copied. + colorspace into which the icon is copied. \param which Value that specifies which icon to return. Currently - \c B_LARGE_ICON and \c B_MINI_ICON are supported. + \c B_LARGE_ICON and \c B_MINI_ICON are supported. - \returns A status code. + \returns A status code, \c B_OK on success or an error code otherwise. \retval B_OK Success \retval B_ENTRY_NOT_FOUND No icon of the given size exists for the - given type + given type. + \retval B_NO_INIT BMimeType was uninitialized. + + \since BeOS R3 */ /*! - \fn status_t BMimeType::GetIconForType(const char *type, + \fn status_t BMimeType::GetIconForType(const char* type, uint8** _data, size_t* _size) const \brief Fetches the vector icon used by an application of this type for - files of the given type. + files of the given type. The icon data is returned in \c data. See the other GetIconForType() for more information. \param type Pointer to a pre-allocated string containing the MIME type whose - custom icon you wish to fetch. + custom icon you wish to fetch. \param _data Pointer in which the allocated icon data is returned. You need - to delete the buffer when you are done with it. + to delete the buffer when you are done with it. \param _size Pointer in which the size of the allocated icon data is - returned. + filled out. - \returns A status code. - \retval B_OK Success + \returns A status code, \c B_OK on success or an error code otherwise. + \retval B_OK Success. \retval B_ENTRY_NOT_FOUND No icon of the given size exists for the - given type. + given type. + \retval B_NO_INIT BMimeType was uninitialized. + + \since Haiku R1 */ /*! - \fn status_t BMimeType::SetIconForType(const char *type, - const BBitmap *icon, icon_size which) + \fn status_t BMimeType::SetIconForType(const char* type, + const BBitmap* icon, icon_size which) \brief Sets the large or mini icon used by an application of this type - for files of the given type. + for files of the given type. This can be confusing, so here's how this function is intended to be used: - The actual \c BMimeType object should be set to the MIME signature of an @@ -887,7 +994,7 @@ of \c "application/"; that is the intended use however, and application-specific icons are not expected to be present for non-application types. - + The icon is copied from the \c BBitmap pointed to by \c icon. The bitmap must be the proper size: \c 32x32 for the large icon, \c 16x16 for the mini icon. @@ -895,14 +1002,16 @@ If you want to erase the current icon, pass \c NULL as the \c icon argument. \param type Pointer to a pre-allocated string containing the MIME type whose - custom icon you wish to set. + custom icon you wish to set. \param icon Pointer to a pre-allocated \c BBitmap of proper size and - colorspace containing the new icon, or \c NULL to clear the - current icon. + colorspace containing the new icon, or \c NULL to clear the current + icon. \param which Value that specifies which icon to update. Currently - \c B_LARGE_ICON and \c B_MINI_ICON are supported. + \c B_LARGE_ICON and \c B_MINI_ICON are supported. \returns \c B_OK on success or another error code on failure. + + \since BeOS R3 */ @@ -918,12 +1027,12 @@ application to whom you want to assign custom icons for custom MIME types. - The \c type parameter specifies the file type whose custom icon you are setting. - + The type of the \c BMimeType object is not required to actually be a subtype of \c "application/"; that is the intended use however, and application-specific icons are not expected to be present for non-application types. - + The icon is copied from the \c BBitmap pointed to by \c icon. The bitmap must be the proper size: \c 32x32 for the large icon, \c 16x16 for the mini icon. @@ -931,33 +1040,40 @@ If you want to erase the current icon, pass \c NULL as the \c icon argument. \param type Pointer to a pre-allocated string containing the MIME type whose - custom icon you wish to set. + custom icon you wish to set. \param icon Pointer to a pre-allocated \c BBitmap of proper size and - colorspace containing the new icon, or \c NULL to clear the - current icon. + colorspace containing the new icon, or \c NULL to clear the + current icon. \param icon_size Value that specifies which icon to update. Currently - \c B_LARGE_ICON and \c B_MINI_ICON are supported. + \c B_LARGE_ICON and \c B_MINI_ICON are supported. \returns \c B_OK on success or another error code on failure. + + \since Haiku R1 */ /*! - \fn status_t BMimeType::GetSnifferRule(BString *result) const + \fn status_t BMimeType::GetSnifferRule(BString* result) const \brief Retrieves the MIME type's sniffer rule. \param result Pointer to a pre-allocated BString into which the value is - copied. + copied. \returns A status code. \retval B_OK Everything went fine. \retval B_BAD_VALUE \c NULL \a result or uninitialized BMimeType. \retval B_ENTRY_NOT_FOUND The MIME type is not installed. + \retval B_NO_INIT BMimeType was uninitialized. + + \see SetSnifferRule() + + \since Haiku R1 */ /*! - \fn status_t BMimeType::SetSnifferRule(const char *rule) + \fn status_t BMimeType::SetSnifferRule(const char* rule) \brief Sets the MIME type's sniffer rule. If the supplied \a rule is \c NULL, the MIME type's sniffer rule is @@ -972,14 +1088,17 @@ \retval B_OK Everything went fine. \retval B_BAD_VALUE Uninitialized BMimeType. \retval B_BAD_MIME_SNIFFER_RULE The supplied sniffer rule is invalid. + \retval B_NO_INIT BMimeType was uninitialized. - \sa CheckSnifferRule(). + \sa CheckSnifferRule() + + \since Haiku R1 */ /*! - \fn status_t BMimeType::CheckSnifferRule(const char *rule, - BString *parseError) + \fn status_t BMimeType::CheckSnifferRule(const char* rule, + BString* parseError) \brief Checks whether a MIME sniffer rule is valid or not. A MIME sniffer rule is valid, if it is well-formed with respect to the @@ -1056,21 +1175,24 @@ \param rule The rule string. \param parseError A pointer to a pre-allocated BString into which a - description of the parse error is written (if any), may be \c NULL. + description of the parse error is written (if any), may be \c NULL. \returns A status code. \retval B_OK The supplied sniffer rule is valid. \retval B_BAD_VALUE \c NULL \a rule. \retval B_BAD_MIME_SNIFFER_RULE The supplied sniffer rule is not valid. A - description of the error is written to \a parseError, if supplied. + description of the error is written to \a parseError, if supplied. + \retval B_NO_INIT BMimeType was uninitialized. + + \since Haiku R1 */ /*! - \fn status_t BMimeType::GuessMimeType(const entry_ref *file, - BMimeType *type) + \fn status_t BMimeType::GuessMimeType(const entry_ref* file, + BMimeType* type) \brief Guesses a MIME type for the entry referred to by the given - entry_ref. + entry_ref. This version of GuessMimeType() combines the features of the other versions: First the data of the given file are checked (sniffed). Only @@ -1079,33 +1201,39 @@ \param file Pointer to the entry_ref referring to the entry. \param type Pointer to a pre-allocated BMimeType which is set to the - resulting MIME type. + resulting MIME type. \returns A status code. \retval B_OK Everything went fine. \retval B_BAD_VALUE \c NULL \a ref or \a result. \retval B_NAME_NOT_FOUND \a ref refers to an abstract entry. + \retval B_NO_INIT BMimeType was uninitialized. + + \since Haiku R1 */ /*! - \fn status_t BMimeType::GuessMimeType(const void *buffer, int32 length, - BMimeType *type) + \fn status_t BMimeType::GuessMimeType(const void* buffer, int32 length, + BMimeType* type) \brief Guesses a MIME type for the supplied chunk of data. \param buffer Pointer to the data buffer. \param length Size of the buffer in bytes. \param type Pointer to a pre-allocated BMimeType which is set to the - resulting MIME type. + resulting MIME type. \returns A status code. \retval B_OK Everything went fine. \retval B_BAD_VALUE \c NULL \a buffer or \a result. + \retval B_NO_INIT BMimeType was uninitialized. + + \since Haiku R1 */ /*! - \fn status_t BMimeType::GuessMimeType(const char *filename, BMimeType *type) + \fn status_t BMimeType::GuessMimeType(const char* filename, BMimeType* type) \brief Guesses a MIME type for the given filename. Only the filename itself is taken into consideration (in particular its @@ -1114,11 +1242,14 @@ \param filename The filename. \param type Pointer to a pre-allocated BMimeType which is set to the - resulting MIME type. + resulting MIME type. \returns A status code. \retval B_OK Everything went fine. \retval B_BAD_VALUE \c NULL \a ref or \a result. + \retval B_NO_INIT BMimeType was uninitialized. + + \since Haiku R1 */ @@ -1132,77 +1263,30 @@ \param target A BMessenger identifying the target for the update messages. \returns \c B_OK on success or another error code on failure. + + \since BeOS R4 */ /*! \fn status_t BMimeType::StopWatching(BMessenger target) \brief Stops monitoring the MIME database for a given target (previously - started via StartWatching()). + started via StartWatching()). \param target A BMessenger identifying the target for the update messages. \returns \c B_OK on success or another error code on failure. + + \since BeOS R4 */ /*! - \fn status_t BMimeType::SetType(const char *mimeType) + \fn status_t BMimeType::SetType(const char* mimeType) \brief Initializes this object to the supplied MIME type. \deprecated This method has the same semantics as SetTo(). - Use SetTo() instead. + Use SetTo() instead. + + \since BeOS R3 */ - - -/*! - \fn status_t BMimeType::SetSupportedTypes(const BMessage *types, - bool fullSync) - \brief Sets the list of MIME types supported by the MIME type (which is - assumed to be an application signature). - - If \a types is \c NULL the application's supported types are unset. - - The supported MIME types must be stored in a field "types" of type - \c B_STRING_TYPE in \a types. - - For each supported type the result of BMimeType::GetSupportingApps() will - afterwards include the signature of this application. - - \a fullSync specifies whether or not any types that are no longer - listed as supported types as of this call to SetSupportedTypes() shall be - updated as well, i.e. whether this application shall be removed from their - lists of supporting applications. - - If \a fullSync is \c false, this application will not be removed from the - previously supported types' supporting apps lists until the next call - to BMimeType::SetSupportedTypes() or BMimeType::DeleteSupportedTypes() - with a \c true \a fullSync parameter, the next call to BMimeType::Delete(), - or the next reboot. - - \param types The supported types to be assigned to the file. - May be \c NULL. - \param fullSync \c true to also synchronize the previously supported - types, \c false otherwise. - - \returns \c B_OK on success or another error code on failure. -*/ - - -/*! - \fn status_t BMimeType::GetAssociatedTypes(const char *extension, - BMessage *types) - \brief Returns a list of mime types associated with the given file extension - - The list of types is returned in the pre-allocated \c BMessage pointed to - by \a types. The types are stored in the message's "types" field, which - is an array of \c B_STRING_TYPE values. - - \param extension The file extension of interest - \param types Pointer to a pre-allocated BMessage into which the result will - be stored - - \returns \c B_OK on success or another error code on failure. -*/ - - diff --git a/docs/user/storage/Node.dox b/docs/user/storage/Node.dox index ce98bd242e..5241bc0567 100644 --- a/docs/user/storage/Node.dox +++ b/docs/user/storage/Node.dox @@ -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, tylerdauwalder@users.sf.net * John Scipione, jscipione@gmail.com * Ingo Weinhold, bonefish@users.sf.net * * 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 stat() - 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 */ diff --git a/docs/user/storage/NodeInfo.dox b/docs/user/storage/NodeInfo.dox index 121ceff310..49f5eec4e1 100644 --- a/docs/user/storage/NodeInfo.dox +++ b/docs/user/storage/NodeInfo.dox @@ -1,5 +1,5 @@ /* - * Copyright 2013 Haiku Inc. All rights reserved. + * Copyright 2013-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: @@ -8,8 +8,8 @@ * Ingo Weinhold, bonefish@users.sf.net * * Corresponds to: - * headers/os/storage/NodeInfo.h hrev45253 - * src/kits/storage/NodeInfo.cpp hrev45253 + * headers/os/storage/NodeInfo.h hrev47402 + * src/kits/storage/NodeInfo.cpp hrev47402 */ @@ -30,6 +30,8 @@ BNodeInfo provides a nice wrapper to all sorts of useful meta data such as the MIME-type, the file's icon and the application that will open the file. + + \since BeOS R3 */ @@ -39,16 +41,20 @@ After created a BNodeInfo with this, you should call SetTo(). - \see SetTo(BNode *node) + \see SetTo(BNode* node) + + \since BeOS R3 */ /*! - \fn BNodeInfo::BNodeInfo(BNode *node) + \fn BNodeInfo::BNodeInfo(BNode* node) \brief Creates a BNodeInfo object and initializes it to the supplied \a node. - \param node The \a node to gather information on. + \param node The \a node to initialize to and gather information. + + \since BeOS R3 */ @@ -57,6 +63,8 @@ \brief Frees the object and associated resources. The internal BNode object is not deleted. + + \since BeOS R3 */ @@ -69,7 +77,7 @@ /*! - \fn status_t BNodeInfo::SetTo(BNode *node) + \fn status_t BNodeInfo::SetTo(BNode* node) \brief Initializes the BNodeInfo to the supplied \a node. The BNodeInfo object does not copy the supplied \a node object, it uses it @@ -82,6 +90,8 @@ \returns A status code. \retval B_OK Everything went fine. \retval B_BAD_VALUE The node was not properly initialized. + + \since BeOS R3 */ @@ -92,6 +102,8 @@ \returns A status code. \retval B_OK The object was properly initialized. \retval B_BAD_VALUE The object was \b not properly initialized. + + \since BeOS R3 */ @@ -107,7 +119,7 @@ /*! - \fn status_t BNodeInfo::GetType(char *type) const + \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 @@ -125,18 +137,20 @@ attribute is longer than \c B_MIME_TYPE_LENGTH. \retval B_BAD_TYPE The stored type string attribute has the wrong type. \retval B_ENTRY_NOT_FOUND No type is set on the node. + + \since BeOS R3 */ /*! - \fn status_t BNodeInfo::SetType(const char *type) + \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. + including the terminating \0 character. \param type The MIME-type to be assigned to the \a node. Must not be longer than \c B_MIME_TYPE_LENGTH (including the terminating @@ -146,6 +160,8 @@ \retval B_OK Everything went fine. \retval B_NO_INIT The object was not properly initialized. \retval B_BAD_VALUE \a type is longer than \c B_MIME_TYPE_LENGTH. + + \since BeOS R3 */ @@ -153,7 +169,7 @@ /*! - \name Icon methods + \name Icon */ @@ -161,28 +177,30 @@ /*! - \fn status_t BNodeInfo::GetIcon(BBitmap *icon, icon_size k) const + \fn status_t BNodeInfo::GetIcon(BBitmap* icon, icon_size which) 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 + dimension to store the requested icon: 16x16 for the mini or + 32x32 for the large icon. + \param which 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 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. + dimensions (\a icon) and icon size (\a k) do not match. + + \since BeOS R3 */ /*! - \fn status_t BNodeInfo::SetIcon(const BBitmap *icon, icon_size k) + \fn status_t BNodeInfo::SetIcon(const BBitmap* icon, icon_size which) \brief Sets the icon of the node. If \a icon is \c NULL, the attribute is removed instead. @@ -191,15 +209,17 @@ 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 + May be \c NULL. + \param which 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. + and icon size (\a k) do not match. + + \since BeOS R3 */ @@ -213,17 +233,19 @@ retrieved. \param data A pointer in which a pointer to the icon data - will be returned. + will be filled in. \param size A pointer in which the size of the found icon data - will be returned. + will be filled in. \param type A pointer in which the type of the found icon data - will be returned. + will be filled in. \returns A status code. \retval B_OK Everything went fine. \retval B_NO_INIT The object was not properly initialized. \retval B_BAD_VALUE \c NULL \a data, \c NULL \a size or \c NULL \a type. \retval B_NO_MEMORY No memory to allocate the \a data buffer. + + \since Haiku R1 */ @@ -240,12 +262,14 @@ \returns A status code. \retval B_OK Everything went fine. \retval B_NO_INIT The object was not properly initialized. + + \since Haiku R1 */ /*! - \fn status_t BNodeInfo::GetTrackerIcon(BBitmap *icon, - icon_size iconSize) const + \fn status_t BNodeInfo::GetTrackerIcon(BBitmap* icon, + icon_size which) const \brief Gets the icon displayed by Tracker for the icon. This method tries really hard to find an icon for the node: @@ -268,7 +292,7 @@ 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 + \remarks You can set \a which 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 @@ -276,44 +300,48 @@ \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. + to store the requested icon (16x16 for the mini and 32x32 for the + large icon). + \param which 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 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 + \retval B_BAD_VALUE \c NULL \a icon, unsupported icon size \a which + or bitmap dimensions (\a icon) and icon size (\a which) do not match. + + \since BeOS R3 */ /*! - \fn status_t BNodeInfo::GetTrackerIcon(const entry_ref *ref, - BBitmap *icon, icon_size iconSize) + \fn status_t BNodeInfo::GetTrackerIcon(const entry_ref* ref, + BBitmap* icon, icon_size which) \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. + using \a which 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 object 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 + \param which 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. + \a which or bitmap dimensions (\a icon) and icon size + (\a which) do not match. + + \since BeOS R3 */ @@ -321,7 +349,7 @@ /*! - \name Preferred application methods + \name Preferred Application */ @@ -329,7 +357,7 @@ /*! - \fn status_t BNodeInfo::GetPreferredApp(char *signature, + \fn status_t BNodeInfo::GetPreferredApp(char* signature, app_verb verb) const \brief Gets the preferred application of the node. @@ -352,7 +380,7 @@ /*! - \fn status_t BNodeInfo::SetPreferredApp(const char *signature, + \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. @@ -379,7 +407,7 @@ /*! - \name Application hint methods + \name Application Hint */ @@ -387,7 +415,7 @@ /*! - \fn status_t BNodeInfo::GetAppHint(entry_ref *ref) const + \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. @@ -409,7 +437,7 @@ /*! - \fn status_t BNodeInfo::SetAppHint(const entry_ref *ref) + \fn status_t BNodeInfo::SetAppHint(const entry_ref* ref) \brief Sets the application that will open the file type of the node. If \a ref is \c NULL, the \c BEOS:PPATH attribute is removed instead. diff --git a/docs/user/storage/NodeMonitor.dox b/docs/user/storage/NodeMonitor.dox index 3df7e78ea5..86e239a6af 100644 --- a/docs/user/storage/NodeMonitor.dox +++ b/docs/user/storage/NodeMonitor.dox @@ -1,5 +1,5 @@ /* - * Copyright 2003-2013 Haiku Inc. All rights reserved. + * Copyright 2003-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: @@ -9,8 +9,8 @@ * Clemens Zeidler, haiku@clemens-zeidler.de * * Corresponds to: - * headers/os/storage/NodeMonitor.h hrev45253 - * src/kits/storage/NodeMonitor.cpp hrev45253 + * headers/os/storage/NodeMonitor.h hrev47402 + * src/kits/storage/NodeMonitor.cpp hrev47402 */ @@ -21,7 +21,7 @@ \brief Provides functions and constants for monitoring changes to a node. The are three main node monitoring functions are watch_volume(), - watch_node() and stop_watching(). + watch_node(), and stop_watching(). - watch_volume() starts watching a volume and sends a message when a requested event occurs. - watch_node() starts or stops watching a node, or watches for volumes @@ -31,219 +31,279 @@ */ +//// Flags for the watch_node() call. + + /*! \var B_STOP_WATCHING + \brief Unsubscribe from watching a node. - Flag for watch_node(). Unsubscribe from watching a node. + Flag for watch_node(). \attention \c B_STOP_WATCHING does not apply to volume watching, you must call stop_watching() instead. + + \since BeOS R3 */ /*! \var B_WATCH_NAME + \brief Subscribe to watching for change to the name of a node. - Flag for watch_volume() and watch_node(). Subscribe to watching for - change to the name of a node. + Flag for watch_volume() and watch_node(). + + \since BeOS R3 */ /*! \var B_WATCH_STAT + \brief Subscribe to watching for changes to the stat information of a node. - Flag for watch_volume() and watch_node(). Subscribe to watching for - changes to the stat information of a node. + Flag for watch_volume() and watch_node(). + + \since BeOS R3 */ /*! \var B_WATCH_ATTR + \brief Subscribe to watching for changes to the attributes of a node. - Flag for watch_volume() and watch_node(). Subscribe to watching for - changes to the attributes of a node. + Flag for watch_volume() and watch_node(). + + \since BeOS R3 */ /*! \var B_WATCH_DIRECTORY + \brief Subscribe to watching for changes to the contents of a directory. - Flag for watch_node(). Subscribe to watching for changes to the contents - of a directory. + Flag for watch_node(). + + \since BeOS R3 */ /*! \var B_WATCH_ALL + \brief Flag for watch_node(). - Flag for watch_node(). Subscribe to watching for changes to all - information of a node except \c B_WATCH_MOUNT. + Subscribe to watching for changes to all information of a node except + \c B_WATCH_MOUNT. + + \since BeOS R3 */ /*! \var B_WATCH_MOUNT + \brief Subscribe to watching for when a volume is mounted or unmounted. - Flag for watch_node(). Subscribe to watching for when a volume is mounted - or unmounted. You may prefer to use BVolumeRoster for volume watching - instead. + You may prefer to use BVolumeRoster for volume watching instead. + + Flag for watch_node(). + + \since BeOS R3 */ /*! \var B_WATCH_INTERIM_STAT + \brief To avoid a flood of messages for small and frequent write operations + on an open file the file system can limit the number of + notifications and mark them with the \c B_WATCH_INTERIM_STAT flag. - \internal Implementation detail. Not in Be Book. + \internal Implementation detail, not in Be Book. - To avoid a flood of messages for small and frequent write operations on an - open file the file system can limit the number of notifications and mark - them with the \c B_WATCH_INTERIM_STAT flag. + \since Haiku R1 */ +//// The "opcode" field of the B_NODE_MONITOR notification message you get. + + /*! - \def B_ENTRY_CREATED + \var B_ENTRY_CREATED \c B_NODE_MONITOR notification message "opcode" is set when entry is created. + + \since BeOS R3 */ /*! - \def B_ENTRY_REMOVED + \var B_ENTRY_REMOVED \c B_NODE_MONITOR notification message "opcode" is set when entry is removed. + + \since BeOS R3 */ /*! - \def B_ENTRY_MOVED + \var B_ENTRY_MOVED \c B_NODE_MONITOR notification message "opcode" is set when entry is moved. + + \since BeOS R3 */ /*! - \def B_STAT_CHANGED + \var B_STAT_CHANGED \c B_NODE_MONITOR notification message "opcode" set when stat info changes. More information can be found in the "fields" field. + + \since BeOS R3 */ /*! - \def B_ATTR_CHANGED + \var B_ATTR_CHANGED \c B_NODE_MONITOR notification message "opcode" set when attribute changes. More information can be found in the "cause" field. + + \since BeOS R3 */ /*! - \def B_DEVICE_MOUNTED + \var B_DEVICE_MOUNTED \c B_NODE_MONITOR notification message "opcode" set when device is mounted. + + \since BeOS R3 */ /*! - \def B_DEVICE_UNMOUNTED + \var B_DEVICE_UNMOUNTED \c B_NODE_MONITOR notification message "opcode" set when device is unmounted. + + \since BeOS R3 */ /*! - \def B_ATTR_CREATED + \var B_ATTR_CREATED \c B_ATTR_CHANGED notification message "cause" set when attribute is - created. (Haiku only) + created. + + \since Haiku R1 */ /*! - \def B_ATTR_REMOVED + \var B_ATTR_REMOVED \c B_ATTR_CHANGED notification message "cause" set when attribute is - removed. (Haiku only) + removed. + + \since Haiku R1 */ /*! \var B_STAT_MODE + \brief Set when stat mode changes. - \c B_STAT_CHANGED notification messages "fields" flag set when stat mode - changes. + \c B_STAT_CHANGED notification messages "fields" flag. + + \since Haiku R1 */ /*! \var B_STAT_UID + \brief Set when UID changes. - \c B_STAT_CHANGED notification messages "fields" flag set when UID - changes. + \c B_STAT_CHANGED notification messages "fields" flag. + + \since Haiku R1 */ /*! \var B_STAT_GID + \brief Set when GID changes. - \c B_STAT_CHANGED notification messages "fields" flag set when GID - changes. + \c B_STAT_CHANGED notification messages "fields" flag. + + \since Haiku R1 */ /*! \var B_STAT_SIZE + \brief Set when stat size changes. - \c B_STAT_CHANGED notification messages "fields" flag set when stat size - changes. + \c B_STAT_CHANGED notification messages "fields" flag. + + \since Haiku R1 */ /*! \var B_STAT_ACCESS_TIME + \brief Set when access time changes. - \c B_STAT_CHANGED notification messages "fields" flag set when access time - changes. + \c B_STAT_CHANGED notification messages "fields" flag. + + \since Haiku R1 */ /*! \var B_STAT_MODIFICATION_TIME + \brief Set when modification time changes. - \c B_STAT_CHANGED notification messages "fields" flag set when - modification time changes. + \c B_STAT_CHANGED notification messages "fields" flag. + + \since Haiku R1 */ /*! \var B_STAT_CREATION_TIME + \brief Set when creation time changes. - \c B_STAT_CHANGED notification messages "fields" flag set when creation - time changes. + \c B_STAT_CHANGED notification messages "fields" flag. + + \since Haiku R1 */ /*! \var B_STAT_CHANGE_TIME + \brief Set when access, modification or creation time changes. - \c B_STAT_CHANGED notification messages "fields" flag set when access, - modification or creation time changes. + \c B_STAT_CHANGED notification messages "fields" flag. + + \since Haiku R1 */ /*! \var B_STAT_INTERIM_UPDATE + \brief Set when file is written to. - \internal Implementation detail. Not in Be Book. + \internal Implementation detail, not in Be Book. - \c B_STAT_CHANGED notification messages "fields" flag set when file is - written to. + \c B_STAT_CHANGED notification messages "fields" flag. + + \since Haiku R1 */ @@ -271,12 +331,14 @@ \retval B_OK Everything went fine. \retval B_BAD_VALUE \a flags did not include one of \c B_WATCH_NAME, \c B_WATCH_STAT, or \c B_WATCH_ATTR. + + \since Haiku R1 */ /*! \fn status_t watch_volume(dev_t volume, uint32 flags, - const BHandler *handler, const BLooper *looper) + const BHandler* handler, const BLooper* looper) \brief Subscribes \a handler or \a looper to watch node changes on \a volume. @@ -303,11 +365,13 @@ \retval B_OK Everything went fine. \retval B_BAD_VALUE \a flags did not include one of \c B_WATCH_NAME, \c B_WATCH_STAT, or \c B_WATCH_ATTR. + + \since Haiku R1 */ /*! - \fn status_t watch_node(const node_ref *node, uint32 flags, + \fn status_t watch_node(const node_ref* node, uint32 flags, BMessenger target) \brief Subscribes or unsubscribes \a target to node and/or mount watching. @@ -341,12 +405,14 @@ \param target BMessenger object referring to the \a target. \return \c B_OK if everything went fine, an error code otherwise. + + \since BeOS R3 */ /*! - \fn status_t watch_node(const node_ref *node, uint32 flags, - const BHandler *handler, const BLooper *looper) + \fn status_t watch_node(const node_ref* node, uint32 flags, + const BHandler* handler, const BLooper* looper) \brief Subscribes or unsubscribes \a handler or \a looper to node and/or mount watching. @@ -383,6 +449,8 @@ \c NULL. Then the handler's looper is the target looper. \return \c B_OK if everything went fine, an error code otherwise. + + \since BeOS R3 */ @@ -403,11 +471,13 @@ \retval B_OK Stopped sending notification messages to the \a target. \retval B_BAD_VALUE \a target was invalid. \retval B_ENTRY_NOT_FOUND Node not found. + + \since BeOS R3 */ /*! - \fn status_t stop_watching(const BHandler *handler, const BLooper *looper) + \fn status_t stop_watching(const BHandler* handler, const BLooper* looper) \brief Unsubscribes \a handler or \a looper target from node and mount monitoring. @@ -427,4 +497,6 @@ \retval B_OK Stopped sending notification messages to the target. \retval B_BAD_VALUE Target from \a handler or \a looper was invalid. \retval B_ENTRY_NOT_FOUND Node not found. + + \since BeOS R3 */ diff --git a/docs/user/storage/Path.dox b/docs/user/storage/Path.dox index 52f0a38368..901e92a5bb 100644 --- a/docs/user/storage/Path.dox +++ b/docs/user/storage/Path.dox @@ -9,8 +9,8 @@ * Ingo Weinhold, bonefish@users.sf.net * * Corresponds to: - * headers/os/storage/Path.h hrev45260 - * src/kits/storage/Path.cpp hrev45260 + * headers/os/storage/Path.h hrev47402 + * src/kits/storage/Path.cpp hrev47402 */ @@ -27,6 +27,8 @@ \ingroup storage \ingroup libbe \brief A class representing a file system path. + + \since BeOS R3 */ @@ -43,6 +45,8 @@ \brief Creates a copy of the given BPath object. \param path the object to be copied. + + \since BeOS R3 */ @@ -52,6 +56,8 @@ specified by the passed in entry_ref struct. \param ref the entry_ref to initialize from. + + \since BeOS R5 */ @@ -61,6 +67,8 @@ specified by the passed in BEntry object. \param entry the BEntry object to initialize from. + + \since BeOS R4 */ @@ -81,6 +89,8 @@ - The presence of "." or ".." ("/boot/ltj/../ltj/./gwar") - Redundant slashes ("/boot//ltj") - A trailing slash ("/boot/ltj/") + + \since BeOS R3 */ @@ -100,17 +110,21 @@ - The presence of "." or ".." ("/boot/ltj/../ltj/./gwar") - Redundant slashes ("/boot//ltj") - A trailing slash ("/boot/ltj/") + + \since BeOS R3 */ /*! \fn BPath::~BPath() \brief Destroys the BPath object and frees any associated resources. + + \since BeOS R3 */ /*! - \name Constructor helper methods + \name Constructor Helpers */ @@ -123,6 +137,8 @@ \return \c B_OK, if the BPath object was properly initialized, an error code otherwise. + + \since BeOS R3 */ @@ -136,6 +152,8 @@ \retval B_OK Initialization was successful. \retval B_BAD_VALUE \a ref was \c NULL. \retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH. + + \since BeOS R5 */ @@ -149,6 +167,8 @@ \retval B_OK Initialization was successful. \retval B_BAD_VALUE \a ref was \c NULL. \retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH. + + \since BeOS R4 */ @@ -174,6 +194,8 @@ \retval B_OK Initialization was successful. \retval B_BAD_VALUE \a ref was \c NULL. \retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH. + + \since BeOS R3 */ @@ -197,6 +219,8 @@ \retval B_OK Initialization was successful. \retval B_BAD_VALUE \a ref was \c NULL. \retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH. + + \since BeOS R3 */ @@ -205,6 +229,8 @@ \brief Returns the object to an uninitialized state. Frees any resources it allocated and marks the object as uninitialized. + + \since BeOS R3 */ @@ -212,7 +238,7 @@ /*! - \name Path manipulation methods + \name Path Manipulation */ @@ -239,6 +265,8 @@ \retval B_OK Initialization was successful. \retval B_BAD_VALUE \a ref was \c NULL. \retval B_NAME_TOO_LONG The pathname was longer than \c B_PATH_NAME_LENGTH. + + \since BeOS R3 */ @@ -246,7 +274,7 @@ /*! - \name Path information methods + \name Path Information */ @@ -259,6 +287,8 @@ \returns The path name of the object, or \c NULL if it is not properly initialized. + + \since BeOS R3 */ @@ -271,6 +301,8 @@ \returns The leaf portion of the path or \c NULL if it is not properly initialized. + + \since BeOS R3 */ @@ -305,7 +337,7 @@ /*! - \name Operator overload methods + \name Operators */ @@ -322,6 +354,8 @@ \param item the BPath object to compare. \return \c true, if the paths are equal, \c false otherwise. + + \since BeOS R3 */ @@ -334,6 +368,8 @@ \param path The path to compare. \return \c true, if the path names are equal, \c false otherwise. + + \since BeOS R3 */ @@ -347,6 +383,8 @@ \param item the BPath object to compare. \return \c true, if the path names are \b not equal, \c false otherwise. + + \since BeOS R3 */ @@ -359,6 +397,8 @@ \param path The path to compare. \return \c true, if the path names are \b not equal, \c false otherwise. + + \since BeOS R3 */ @@ -369,6 +409,8 @@ \param item The BPath object to copy \return A pointer to the newly initialized BPath object. + + \since BeOS R3 */ @@ -381,6 +423,8 @@ \param path the path to be assign to this object. \return A pointer to the newly initialized BPath object. + + \since BeOS R3 */ @@ -388,7 +432,7 @@ /*! - \name BFlattenable method implementations + \name BFlattenable Method Implementations */ @@ -400,6 +444,8 @@ \brief Implements BFlattenable::IsFixedSize(). Always returns \c false. \return \c false + + \since BeOS R3 */ @@ -408,6 +454,8 @@ \brief Implements BFlattenable::TypeCode(). Always returns \c B_REF_TYPE. \return \c B_REF_TYPE + + \since BeOS R3 */ @@ -418,6 +466,8 @@ \return The size of the flattened entry_ref struct that represents the path in bytes. + + \since BeOS R3 */ @@ -432,6 +482,8 @@ \returns A status code. \retval B_OK Everything went fine. \retval B_BAD_VALUE \a buffer was \c NULL or of insufficient size. + + \since BeOS R3 */ @@ -443,6 +495,8 @@ \param code The type code to test. \return \c true if code is \c B_REF_TYPE, \c false otherwise. + + \since BeOS R3 */ @@ -461,42 +515,9 @@ \returns A status code. \retval B_OK Everything went fine. \retval B_BAD_VALUE \a buffer was \c NULL or didn't contain an entry_ref. + + \since BeOS R3 */ //! @} - - -/// private methods, won't show up in docs - - -/*! - status_t BPath::_SetPath(const char* path) - \brief Sets the supplied path. - - The path is copied, if \a path is \c NULL the path of the object is set to - \c NULL as well. The old path is deleted. - - \param path the path to be set - - \returns A status code. - \retval B_OK Everything went fine. - \retval B_NO_MEMORY Insufficient memory. -*/ - - -/*! - bool BPath::_MustNormalize(const char* path, status_t* _error) - \brief Checks a path to see if normalization is required. - - The following items require normalization: - - Relative pathnames (after concatenation; e.g. "boot/ltj") - - The presence of "." or ".." ("/boot/ltj/../ltj/./gwar") - - Redundant slashes ("/boot//ltj") - - A trailing slash ("/boot/ltj/") - - \param _error A pointer to an error variable that will be set if the input - is not a valid path. - - \return \c true if \a path requires normalization, \c false otherwise. -*/ diff --git a/docs/user/storage/PathFinder.dox b/docs/user/storage/PathFinder.dox index 1dbb77f59f..7049154d90 100644 --- a/docs/user/storage/PathFinder.dox +++ b/docs/user/storage/PathFinder.dox @@ -1,13 +1,14 @@ /* - * Copyright 2013, Haiku, Inc. All rights reserved. + * Copyright 2013-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Documentation by: + * John Scipione, jscipione@gmail.com * Ingo Weinhold, ingo_weinhold@gmx.de * * Corresponds to: - * headers/os/storage/PathFinder.h hrev46390 - * src/kits/storage/PathFinder.cpp hrev46390 + * headers/os/storage/PathFinder.h hrev47402 + * src/kits/storage/PathFinder.cpp hrev47402 */ @@ -29,6 +30,8 @@ FindPath() for getting a single path in an installation location specified via a constructor or a SetTo() invocation, and the static FindPaths() for getting a list of paths for all installation locations. + + \since Haiku R1 */ @@ -36,7 +39,7 @@ \fn BPathFinder::BPathFinder(const void* codePointer, const char* dependency) \brief Creates an object referring to an installation location based on a - loaded image file. + loaded image file. When initialized with this constructor a FindPath() method called afterward determines the path of the image (i.e. executable, library, or add-on) file @@ -53,23 +56,25 @@ arguments, subsequent calls to FindPath() will return an error. \param codePointer A pointer to code or static data belonging to the image - based on which FindPath() shall compute the path. The special value - \c B_APP_IMAGE_SYMBOL (the default) can be used to refer to the program - image, and \c B_CURRENT_IMAGE_SYMBOL for the caller's image. + based on which FindPath() shall compute the path. The special value + \c B_APP_IMAGE_SYMBOL (the default) can be used to refer to the + program image, and \c B_CURRENT_IMAGE_SYMBOL for the caller's image. \param dependency The name of the package's "requires" entry to be used for - resolving the installation location. Can be \c NULL (the default). + resolving the installation location. Can be \c NULL (the default). + + \since Haiku R1 */ /*! \fn BPathFinder::BPathFinder(const char* path, const char* dependency) \brief Creates an object referring to an installation location based on a - given path. + given \a path. When initialized with this constructor a FindPath() method called afterward evaluates the path constant passed to it based on \a path. In most cases that means first determining the path of the installation location from the - given path. + given \a path. If \a dependency is specified, instead of determining the installation location path from the given path, the installation location path of the @@ -80,48 +85,55 @@ arguments, subsequent calls to FindPath() will return an error. \param path A path based on which FindPath() shall compute the path. - \param dependency The name of the package's "requires" entry to be used for - resolving the installation location. Can be \c NULL. + \param dependency The name of the package's "requires" entry to be used + for resolving the installation location. Can be \c NULL. + + \since Haiku R1 */ /*! \fn BPathFinder::BPathFinder(const entry_ref& ref, const char* dependency) \brief Creates an object referring to an installation location based on a - given entry_ref. + given entry_ref. The constructor converts the given entry_ref \a ref to a path and then initializes the object like BPathFinder::BPathFinder(const char*, const char*). \param ref A reference to be resolved to a path based on which FindPath() - shall compute the path. - \param dependency The name of the package's "requires" entry to be used for - resolving the installation location. Can be \c NULL. + shall compute the path. + \param dependency The name of the package's "requires" entry to be used + for resolving the installation location. Can be \c NULL. \see BPathFinder::BPathFinder(const char*, const char*) + + \since Haiku R1 */ /*! \fn BPathFinder::BPathFinder(const BResolvableExpression& expression, const char* dependency) - \brief Creates an object referring to an installation location based on the - path of a package satisfying the given resolvable expression. + \brief Creates an object referring to an installation location based on + the path of a package satisfying the given resolvable expression. The constructor finds the latest package that satisfies the resolvable expression \a expression and then uses its path to initialize the object like BPathFinder::BPathFinder(const char*, const char*). - \note When using this constructor linking against libpackage.so is required. + \note When using this constructor linking against libpackage.so is + required. - \param expression A resolvable expression to be resolved to the path of the - latest package satisfying it, based on which FindPath() shall compute - the path. - \param dependency The name of the package's "requires" entry to be used for - resolving the installation location. Can be \c NULL. + \param expression A resolvable expression to be resolved to the path of + the latest package satisfying it, based on which FindPath() shall + compute the path. + \param dependency The name of the package's "requires" entry to be used + for resolving the installation location. Can be \c NULL. \see BPathFinder::BPathFinder(const char*, const char*) + + \since Haiku R1 */ @@ -129,14 +141,15 @@ \fn status_t BPathFinder::SetTo(const void* codePointer, const char* dependency) \brief Reinitializes the object to refer to an installation location based - on a loaded image file. + on a loaded image file. When reinitialized with this method a FindPath() method called afterward - determines the path of the image (i.e. executable, library, or add-on) file - associated with \a codePointer, a pointer to a location in the code or - static data of an image loaded in the caller's team. Based on that path the - path constant passed to FindPath() will be evaluated. In most cases that - means first determining the path of the installation location from the path. + determines the path of the image (i.e. executable, library, or add-on) + file associated with \a codePointer, a pointer to a location in the code + or static data of an image loaded in the caller's team. Based on that path + the path constant passed to FindPath() will be evaluated. In most cases + that means first determining the path of the installation location from + the path. If \a dependency is specified, instead of determining the installation location path from the image path, the installation location path of the @@ -147,25 +160,28 @@ error. \param codePointer A pointer to code or static data belonging to the image - based on which FindPath() shall compute the path. The special value - \c B_APP_IMAGE_SYMBOL (the default) can be used to refer to the program - image, and \c B_CURRENT_IMAGE_SYMBOL for the caller's image. + based on which FindPath() shall compute the path. The special value + \c B_APP_IMAGE_SYMBOL (the default) can be used to refer to the + program image, and \c B_CURRENT_IMAGE_SYMBOL for the caller's image. \param dependency The name of the package's "requires" entry to be used for - resolving the installation location. Can be \c NULL (the default). + resolving the installation location. Can be \c NULL (the default). + \return A status code. \retval B_OK Everything went fine. + + \since Haiku R1 */ /*! \fn status_t BPathFinder::SetTo(const char* path, const char* dependency) \brief Reinitializes the object to refer to an installation location based - on a given path. + on a given \a path. When reinitialized with this method a FindPath() method called afterward evaluates the path constant passed to it based on \a path. In most cases - that means first determining the path of the installation location from the - given path. + that means first determining the path of the installation location from + the given \a path. If \a dependency is specified, instead of determining the installation location path from the given path, the installation location path of the @@ -178,9 +194,11 @@ \param path A path based on which FindPath() shall compute the path. \param dependency The name of the package's "requires" entry to be used for - resolving the installation location. Can be \c NULL. - \return A status code. - \retval B_OK Everything went fine. + resolving the installation location. Can be \c NULL. + + \return \c B_OK Everything if went fine or an error code otherwise. + + \since Haiku R1 */ @@ -188,17 +206,21 @@ \fn status_t BPathFinder::SetTo(const entry_ref& ref, const char* dependency) \brief Reinitializes the object to refer to an installation location based - on a given entry_ref. + on a given entry_ref. This method converts the given entry_ref \a ref to a path and then calls calls BPathFinder::SetTo(const char*, const char*). \param ref A reference to be resolved to a path based on which FindPath() - shall compute the path. - \param dependency The name of the package's "requires" entry to be used for - resolving the installation location. Can be \c NULL. + shall compute the path. + \param dependency The name of the package's "requires" entry to be used + for resolving the installation location. Can be \c NULL. \see status_t BPathFinder::SetTo(const char*, const char*) + + \return \c B_OK Everything if went fine or an error code otherwise. + + \since Haiku R1 */ @@ -221,6 +243,10 @@ resolving the installation location. Can be \c NULL. \see status_t BPathFinder::SetTo(const char*, const char*) + + \return \c B_OK Everything if went fine or an error code otherwise. + + \since Haiku R1 */ @@ -258,27 +284,30 @@ resolved to is returned. \param architecture The name of the architecture to be used for resolving - architecture dependent paths. Can be \c NULL, in which case the - architecture associated with the initial path is used. + \a architecture dependent paths. Can be \c NULL, in which case the + \a architecture associated with the initial path is used. \param baseDirectory Constant indicating which path to retrieve. \param subPath Relative subpath that shall be appended. Can be \c NULL. \param flags Bitwise OR of any of the following flags: - - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't exist, - create it as a directory (including all missing ancestors). - - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's parent - doesn't exist, create the parent directory (including all missing - ancestors). - - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist, - fail with \c B_ENTRY_NOT_FOUND. + - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't + exist, create it as a directory (including all missing ancestors). + - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's + parent doesn't exist, create the parent directory (including all + missing ancestors). + - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist, + fail with \c B_ENTRY_NOT_FOUND. \param _path The variable to be set to the resulting path on success. + \return A status code. \retval B_OK Everything went fine. \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the - path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified - and the image file doesn't belong to a package, or \c dependency was - specified, but isn't a "requires" entry of the package, or - \c B_FIND_PATH_EXISTING_ONLY was specified and the resulting path - doesn't exist. + path didn't exist, e.g. \c B_FIND_PATH_PACKAGE_PATH was specified + and the image file didn't belong to a package, or \c dependency + was specified, but wasn't a "requires" entry of the package, or + \c B_FIND_PATH_EXISTING_ONLY was specified and the resulting path + didn't exist. + + \since Haiku R1 */ @@ -294,22 +323,25 @@ \param baseDirectory Constant indicating which path to retrieve. \param subPath Relative subpath that shall be appended. Can be \c NULL. \param flags Bitwise OR of any of the following flags: - - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't exist, - create it as a directory (including all missing ancestors). - - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's parent - doesn't exist, create the parent directory (including all missing - ancestors). - - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist, - fail with \c B_ENTRY_NOT_FOUND. + - \c B_FIND_PATH_CREATE_DIRECTORY: If the resulting path doesn't + exist, create it as a directory (including all missing ancestors). + - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If the resulting path's + parent doesn't exist, create the parent directory (including all + missing ancestors). + - \c B_FIND_PATH_EXISTING_ONLY: If the resulting path doesn't exist, + fail with \c B_ENTRY_NOT_FOUND. \param _path The variable to be set to the resulting path on success. + \return A status code. \retval B_OK Everything went fine. \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the - path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified - and the image file doesn't belong to a package, or \c dependency was - specified, but isn't a "requires" entry of the package, or - \c B_FIND_PATH_EXISTING_ONLY was specified and the resulting path - doesn't exist. + path didn't exist, e.g. \c B_FIND_PATH_PACKAGE_PATH was specified + and the image file didn't belong to a package, or \c dependency + was specified, but wasn't a "requires" entry of the package, or + \c B_FIND_PATH_EXISTING_ONLY was specified and the resulting path + didn't exist. + + \since Haiku R1 */ @@ -325,12 +357,13 @@ \param baseDirectory Constant indicating which path to retrieve. \param subPath Relative subpath that shall be appended. Can be \c NULL. \param _path The variable to be set to the resulting path on success. + \return A status code. \retval B_OK Everything went fine. \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the - path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified - and the image file doesn't belong to a package, or \c dependency was - specified, but isn't a "requires" entry of the package. + path didn't exist, e.g. \c B_FIND_PATH_PACKAGE_PATH was specified + and the image file didn't belong to a package, or \c dependency was + specified, but wasn't a "requires" entry of the package. */ @@ -348,9 +381,11 @@ \return A status code. \retval B_OK Everything went fine. \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the - path doesn't exist. E.g. \c B_FIND_PATH_PACKAGE_PATH was specified - and the image file doesn't belong to a package, or \c dependency was - specified, but isn't a "requires" entry of the package. + path didn't exist, e.g. \c B_FIND_PATH_PACKAGE_PATH was specified + and the image file didn't belong to a package, or \c dependency + was specified, but wasn't a "requires" entry of the package. + + \since Haiku R1 */ @@ -373,26 +408,29 @@ valid arguments for this function. \param architecture The name of the architecture to be used for resolving - architecture dependent paths. Can be \c NULL, in which case the caller's - architecture is used. + \a architecture dependent paths. Can be \c NULL, in which case the + caller's \a architecture is used. \param baseDirectory Constant indicating which paths to retrieve. \param subPath Relative subpath that shall be appended. Can be \c NULL. \param flags Bitwise OR of any of the following flags: - - \c B_FIND_PATH_CREATE_DIRECTORY: If a resulting path doesn't exist, - create it as a directory (including all missing ancestors). - - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If a resulting path's parent - doesn't exist, create the parent directory (including all missing - ancestors). - - \c B_FIND_PATH_EXISTING_ONLY: If a resulting path doesn't exist, skip - it. If none of the paths exist, fail with \c B_ENTRY_NOT_FOUND. + - \c B_FIND_PATH_CREATE_DIRECTORY: If a resulting path doesn't + exist, create it as a directory (including all missing ancestors). + - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If a resulting path's + parent doesn't exist, create the parent directory (including all + missing ancestors). + - \c B_FIND_PATH_EXISTING_ONLY: If a resulting path doesn't exist, + skip it. If none of the paths exist, fail with \c B_ENTRY_NOT_FOUND. \param _paths The BStringList variable where the retrieved paths shall be - stored. The list is emptied before adding the paths. It is also emptied - on error. + stored. The list is emptied before adding the paths. It is also + emptied on error. + \return A status code. \retval B_OK Everything went fine. \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the - paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was specified and - none of the resulting paths do exist. + paths didn't exist, e.g. \c B_FIND_PATH_EXISTING_ONLY was + specified and none of the resulting paths existed. + + \since Haiku R1 */ @@ -408,21 +446,25 @@ \param baseDirectory Constant indicating which paths to retrieve. \param subPath Relative subpath that shall be appended. Can be \c NULL. \param flags Bitwise OR of any of the following flags: - - \c B_FIND_PATH_CREATE_DIRECTORY: If a resulting path doesn't exist, - create it as a directory (including all missing ancestors). - - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If a resulting path's parent - doesn't exist, create the parent directory (including all missing - ancestors). - - \c B_FIND_PATH_EXISTING_ONLY: If a resulting path doesn't exist, skip - it. If none of the paths exist, fail with \c B_ENTRY_NOT_FOUND. + - \c B_FIND_PATH_CREATE_DIRECTORY: If a resulting path doesn't + exist, create it as a directory (including all missing ancestors). + - \c B_FIND_PATH_CREATE_PARENT_DIRECTORY: If a resulting path's + parent doesn't exist, create the parent directory (including all + missing ancestors). + - \c B_FIND_PATH_EXISTING_ONLY: If a resulting path doesn't exist, + skip it. If none of the paths exist, fail with + \c B_ENTRY_NOT_FOUND. \param _paths The BStringList variable where the retrieved paths shall be - stored. The list is emptied before adding the paths. It is also emptied - on error. + stored. The list is emptied before adding the paths. It is also + emptied on error. + \return A status code. \retval B_OK Everything went fine. \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the - paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was specified and - none of the resulting paths do exist. + paths didn't exist, e.g. \c B_FIND_PATH_EXISTING_ONLY was specified + and none of the resulting paths existed. + + \since Haiku R1 */ @@ -438,13 +480,16 @@ \param baseDirectory Constant indicating which paths to retrieve. \param subPath Relative subpath that shall be appended. Can be \c NULL. \param _paths The BStringList variable where the retrieved paths shall be - stored. The list is emptied before adding the paths. It is also emptied - on error. + stored. The list is emptied before adding the paths. It is also + emptied on error. + \return A status code. \retval B_OK Everything went fine. \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the - paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was specified and - none of the resulting paths do exist. + paths didn't exist, e.g. \c B_FIND_PATH_EXISTING_ONLY was specified + and none of the resulting paths existed. + + \since Haiku R1 */ @@ -459,11 +504,14 @@ \param baseDirectory Constant indicating which paths to retrieve. \param _paths The BStringList variable where the retrieved paths shall be - stored. The list is emptied before adding the paths. It is also emptied - on error. + stored. The list is emptied before adding the paths. It is also + emptied on error. + \return A status code. \retval B_OK Everything went fine. \retval B_ENTRY_NOT_FOUND A file system entry required for retrieving the - paths doesn't exist. E.g. \c B_FIND_PATH_EXISTING_ONLY was specified and - none of the resulting paths do exist. + paths didn't exist, e.g. \c B_FIND_PATH_EXISTING_ONLY was specified + and none of the resulting paths existed. + + \since Haiku R1 */ diff --git a/docs/user/storage/Query.dox b/docs/user/storage/Query.dox index 5437bfa117..36d905a7f8 100644 --- a/docs/user/storage/Query.dox +++ b/docs/user/storage/Query.dox @@ -1,5 +1,5 @@ /* - * Copyright 2002-2013 Haiku Inc. All rights reserved. + * Copyright 2002-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: @@ -9,8 +9,8 @@ * Ingo Weinhold, bonefish@users.sf.net * * Corresponds to: - * headers/os/storage/Query.h hrev45283 - * src/kits/storage/Query.cpp hrev45283 + * headers/os/storage/Query.h hrev47402 + * src/kits/storage/Query.cpp hrev47402 */ @@ -28,6 +28,8 @@ \ingroup libbe \brief Provides an interface for creating file system queries and implements BEntryList methods for iterating through the results. + + \since BeOS R3 */ @@ -36,12 +38,16 @@ \brief Creates an uninitialized BQuery object. \see SetPredicate() + + \since BeOS R3 */ /*! \fn BQuery::~BQuery() \brief Destroys the BQuery object and frees any associated resources. + + \since BeOS R3 */ @@ -50,6 +56,8 @@ \brief Resets the object to a uninitialized state. \return \c B_OK + + \since BeOS R3 */ @@ -69,11 +77,13 @@ \retval B_NO_INIT The object predicate or the volume wasn't set. \retval B_BAD_VALUE The object predicate was invalid. \retval B_NOT_ALLOWED Fetch() already called. + + \since BeOS R3 */ /*! - \name Predicate push methods + \name Predicate Push Methods to push data onto the predicate stack. @@ -101,6 +111,8 @@ \retval B_OK Everything went fine. \retval B_NO_MEMORY Not enough memory. \retval B_NOT_ALLOWED PushAttribute() was called after Fetch(). + + \since BeOS R3 */ @@ -114,6 +126,8 @@ \retval B_OK Everything went fine. \retval B_NO_MEMORY Not enough memory. \retval B_NOT_ALLOWED PushOp() was called after Fetch(). + + \since BeOS R3 */ @@ -127,6 +141,8 @@ \retval B_OK Everything went fine. \retval B_NO_MEMORY Not enough memory. \retval B_NOT_ALLOWED PushUInt32() was called after Fetch(). + + \since BeOS R3 */ @@ -140,6 +156,8 @@ \retval B_OK Everything went fine. \retval B_NO_MEMORY Not enough memory. \retval B_NOT_ALLOWED PushInt32() was called after Fetch(). + + \since BeOS R3 */ @@ -153,6 +171,8 @@ \retval B_OK Everything went fine. \retval B_NO_MEMORY Not enough memory. \retval B_NOT_ALLOWED PushUInt64() was called after Fetch(). + + \since BeOS R3 */ @@ -166,6 +186,8 @@ \retval B_OK Everything went fine. \retval B_NO_MEMORY Not enough memory. \retval B_NOT_ALLOWED PushInt64() was called after Fetch(). + + \since BeOS R3 */ @@ -179,6 +201,8 @@ \retval B_OK Everything went fine. \retval B_NO_MEMORY Not enough memory. \retval B_NOT_ALLOWED PushFloat() was called after Fetch(). + + \since BeOS R3 */ @@ -192,6 +216,8 @@ \retval B_OK Everything went fine. \retval B_NO_MEMORY Not enough memory. \retval B_NOT_ALLOWED PushDouble() was called after Fetch(). + + \since BeOS R3 */ @@ -207,6 +233,8 @@ \retval B_OK Everything went fine. \retval B_NO_MEMORY Not enough memory. \retval B_NOT_ALLOWED PushString() was called after Fetch(). + + \since BeOS R3 */ @@ -224,6 +252,8 @@ \retval B_NOT_ALLOWED PushDate() was called after Fetch(). \see parsedate() + + \since Haiku R1 */ @@ -231,7 +261,7 @@ /*! - \name Assignment methods + \name Assignment */ @@ -252,6 +282,8 @@ \return A status code. \retval B_OK Everything went fine. \retval B_NOT_ALLOWED SetVolume() was called after Fetch(). + + \since BeOS R3 */ @@ -272,6 +304,8 @@ \retval B_OK Everything went fine. \retval B_NO_MEMORY Not enough memory. \retval B_NOT_ALLOWED SetPredicate() was called after Fetch(). + + \since BeOS R3 */ @@ -291,6 +325,8 @@ \retval B_OK Everything went fine. \retval B_NO_MEMORY Not enough memory. \retval B_NOT_ALLOWED SetTarget() was called after Fetch(). + + \since BeOS R3 */ @@ -298,7 +334,7 @@ /*! - \name Query information methods + \name Query Information */ @@ -308,7 +344,12 @@ /*! \fn bool BQuery::IsLive() const \brief Gets whether the query associated with this object is live. + \return \c true, if the query is live, \c false otherwise. + + \sa SetTarget() + + \since BeOS R3 */ @@ -318,6 +359,10 @@ \return The device ID of the volume or \c B_NO_INIT if the volume wasn't set. + + \since BeOS R3 + + \since Haiku R1 */ @@ -331,6 +376,10 @@ SetPredicate(). \return The length of the predicate string or 0 if an error occurred. + + \see SetPredicate() + + \since BeOS R3 */ @@ -338,7 +387,7 @@ /*! - \name Get predicate methods + \name Get Predicate These methods fetch a string representation regardless of whether the predicate has been constructed using the predicate stack or via @@ -364,6 +413,8 @@ \retval B_OK Everything went fine. \retval B_NO_INIT The predicate of the BQuery object wasn't set. \retval B_BAD_VALUE \a buffer was \c NULL or too short. + + \since BeOS R3 */ @@ -379,6 +430,8 @@ \retval B_OK Everything went fine. \retval B_NO_INIT The predicate of the BQuery object wasn't set. \retval B_BAD_VALUE \a predicate was \c NULL. + + \since Haiku R1 */ @@ -386,7 +439,7 @@ /*! - \name BEntryList interface methods + \name BEntryList Interface These methods are used to traverse the results of a query as a BEntryList. @@ -411,6 +464,8 @@ \retval B_ENTRY_NOT_FOUND At end of list. \retval B_BAD_VALUE The predicate included unindexed attributes. \retval B_NOT_ALLOWED Fetch() was not previously called on the object. + + \since BeOS R3 */ @@ -426,6 +481,8 @@ \retval B_ENTRY_NOT_FOUND At end of list. \retval B_BAD_VALUE The predicate included unindexed attributes. \retval B_NOT_ALLOWED Fetch() was not previously called on the object. + + \since BeOS R3 */ @@ -448,6 +505,8 @@ are no more entries to be read, or an error code. \retval B_BAD_VALUE The predicate included unindexed attributes. \retval B_FILE_ERROR Fetch() was not previously called on the object. + + \since BeOS R3 */ @@ -460,6 +519,8 @@ \return A status code. \retval B_OK Everything went fine. \retval B_FILE_ERROR Fetch() was not previously called on the object. + + \since BeOS R3 */ @@ -468,80 +529,9 @@ \brief Unimplemented. \return \c B_ERROR. + + \since BeOS R3 */ //! @} - - -/// private methods, won't show up in docs - - -/*! - \fn bool BQuery::_HasFetched() const - \brief Gets whether Fetch() has already been called on this object. - - \return \c true, if Fetch() was already called, \c false otherwise. -*/ - - -/*! - \fn status_t BQuery::_PushNode(QueryNode* node, bool deleteOnError) - \brief Pushes a node onto the predicate stack. - - If the stack has not been allocate until this time, this method does - allocate it. - - If the supplied node is \c NULL, it is assumed that there was not enough - memory to allocate the node and thus \c B_NO_MEMORY is returned. - - In case the method fails, the caller retains the ownership of the supplied - node and thus is responsible for deleting it, if \a deleteOnError is - \c false. If it is \c true, the node is deleted, if an error occurs. - - \param node The node to push. - \param deleteOnError Whether or not to delete the node if an error occurs. - - \return A status code. - \retval B_OK Everything went fine. - \retval B_NO_MEMORY \a node was \c NULL or there was insufficient memory to - allocate the predicate stack or push the node. - \retval B_NOT_ALLOWED _PushNode() was called after Fetch(). -*/ - - -/*! - \fn status_t BQuery::_SetPredicate(const char* expression) - \brief Helper method to set the predicate. - - Does not check whether Fetch() has already been invoked. - - \param expression The predicate string to set. - - \return A status code. - \retval B_OK Everything went fine. - \retval B_NO_MEMORY There was insufficient memory to store the predicate. -*/ - - -/*! - \fn status_t BQuery::_EvaluateStack() - Evaluates the predicate stack. - - The method does nothing (and returns \c B_OK), if the stack is \c NULL. - If the stack is not \c null and Fetch() has already been called, this - method fails. - - \return A status code. - \retval B_OK Everything went fine. - \retval B_NO_MEMORY There was insufficient memory. - \retval B_NOT_ALLOWED _EvaluateStack() was called after Fetch(). -*/ - - -/*! - \fn void BQuery::_ParseDates(BString& parsedPredicate) - \brief Fills out \a parsedPredicate with a parsed predicate string. - - \param parsedPredicate The predicate string to fill out. -*/ diff --git a/docs/user/storage/Resources.dox b/docs/user/storage/Resources.dox index 412006b11d..fbdc954104 100644 --- a/docs/user/storage/Resources.dox +++ b/docs/user/storage/Resources.dox @@ -8,8 +8,8 @@ * Ingo Weinhold, bonefish@users.sf.net * * Corresponds to: - * headers/os/storage/Resources.h hrev45283 - * src/kits/storage/Resources.cpp hrev45283 + * headers/os/storage/Resources.h hrev47402 + * src/kits/storage/Resources.cpp hrev47402 */ @@ -37,6 +37,8 @@ never be invalid. It always serves as a resources container, even if it is not associated with a file. It is always possible to WriteTo() the resources BResources contains to a file (a valid one of course). + + \since BeOS R3 */ @@ -45,6 +47,8 @@ \brief Creates an uninitialized BResources object. \see SetTo() + + \since BeOS R3 */ @@ -64,6 +68,8 @@ \param file The file to create a BResource object from. \param clobber If \c true, the data of the file are erased. + + \since BeOS R3 */ @@ -80,6 +86,8 @@ \param path A path referring to the file to create a BResource object from. \param clobber If \c true, the data of the file are erased. + + \since Haiku R1 */ @@ -96,6 +104,8 @@ \param ref An entry_ref referring to the file to create a BResource object from. \param clobber If \c true, the data of the file are erased. + + \since Haiku R1 */ @@ -105,11 +115,13 @@ Sync() is first called to make sure that the changes are written back to the file. + + \since BeOS R3 */ /*! - \name SetTo methods + \name SetTo What happens, if \a clobber is \c true, depends on the type of the file. If the file is capable of containing resources, that is, is a resource @@ -141,6 +153,8 @@ \retval B_OK Everything went fine. \retval B_BAD_VALUE \a file was \c NULL or uninitialized. \retval B_ERROR Failed to initialize the object. + + \since BeOS R3 */ @@ -158,6 +172,8 @@ \retval B_BAD_VALUE \a path was \c NULL. \retval B_ENTRY_NOT_FOUND The file referenced by \a path couldn't be found. \retval B_ERROR Failed to initialize the object. + + \since Haiku R1 */ @@ -175,6 +191,8 @@ \retval B_BAD_VALUE \a ref was \c NULL. \retval B_ENTRY_NOT_FOUND The file referenced by \a ref couldn't be found. \retval B_ERROR Failed to initialize the object. + + \since Haiku R1 */ @@ -192,6 +210,8 @@ \retval B_OK Everything went fine. \retval B_ENTRY_NOT_FOUND The file referenced by \a ref couldn't be found. \retval B_ERROR Failed to initialize the object. + + \since Haiku R1 */ @@ -215,6 +235,8 @@ \retval B_BAD_VALUE \a codeOrDataPointer was \c NULL. \retval B_ENTRY_NOT_FOUND The image or the file couldn't be found. \retval B_ERROR Failed to initialize the object. + + \since Haiku R1 */ @@ -222,7 +244,7 @@ /*! - \name Constructor helper methods + \name Constructor Helpers */ @@ -237,6 +259,8 @@ written back to the file. \note This method is not found in BeOS R5. + + \since Haiku R1 */ @@ -253,6 +277,8 @@ \return \c B_OK if the objects is properly initialized, \c B_NO_MEMORY otherwise. + + \since Haiku R1 */ @@ -260,7 +286,7 @@ /*! - \name LoadResources methods + \name LoadResources A resource is loaded into memory only once. A second call with the same parameters will result in the same pointer. The BResources object is the @@ -283,8 +309,10 @@ shall be written. \return A pointer to the resource data if everything went fine, or - \c NULL if the file does not have a resource that matches the - parameters or an error occurred. + \c NULL if the file does not have a resource that matches the + parameters or an error occurred. + + \since BeOS R4 */ @@ -303,8 +331,10 @@ shall be written. \return A pointer to the resource data if everything went fine, or - \c NULL if the file does not have a resource that matches the - parameters or an error occurred. + \c NULL if the file does not have a resource that matches the + parameters or an error occurred. + + \since BeOS R4 */ @@ -321,6 +351,8 @@ of errors that occurred. \retval B_OK Everything went fine. \retval B_BAD_FILE The resource map is empty??? + + \since BeOS R4 */ @@ -332,6 +364,8 @@ \brief Gets a reference to the internal BFile object. \return A reference to the internal BFile object. + + \since BeOS R4 */ @@ -357,6 +391,8 @@ \retval B_FILE_ERROR A file error occurred. \retval B_IO_ERROR An error occurred while writing the resources. \retval B_NOT_ALLOWED The file was opened read only. + + \since BeOS R4 */ @@ -373,6 +409,8 @@ \retval B_BAD_VALUE \a fromFile was \c NULL. \retval B_FILE_ERROR A file error occurred. \retval B_IO_ERROR An error occurred while writing the resources. + + \since BeOS R4 */ @@ -389,6 +427,8 @@ \param file The file that the resources shall be written to. \return \c B_OK if everything went fine or an error code otherwise. + + \since BeOS R4 */ @@ -416,6 +456,8 @@ \retval B_FILE_ERROR A file error occurred. \retval B_NO_MEMORY Not enough memory for the operation. \retval B_NOT_ALLOWED The file was opened read only. + + \since BeOS R3 */ @@ -429,6 +471,8 @@ \return \c true if the file contains a matching resource, \c false otherwise. + + \since BeOS R3 */ @@ -442,6 +486,8 @@ \return \c true, if the file contains a matching resource, \c false otherwise. + + \since BeOS R3 */ @@ -462,6 +508,8 @@ \return \c true, if a matching resource could be found, \c false otherwise. + + \since BeOS R3 */ @@ -482,6 +530,8 @@ \return \c true, if a matching resource could be found, \c false otherwise. + + \since BeOS R3 */ @@ -500,6 +550,8 @@ \return \c true, if a matching resource could be found, \c false otherwise. + + \since BeOS R3 */ @@ -518,6 +570,8 @@ \return \c true, if a matching resource could be found, \c false otherwise. + + \since BeOS R3 */ @@ -540,6 +594,8 @@ \return \c true, if a matching resource could be found, \c false otherwise. + + \since BeOS R4 */ @@ -557,6 +613,8 @@ \retval B_ERROR An error occurred while removing the resource. \retval B_FILE_ERROR A file error occurred. \retval B_NOT_ALLOWED The file was opened read only. + + \since BeOS R4 */ @@ -573,11 +631,13 @@ \retval B_ERROR An error occurred while removing the resource. \retval B_FILE_ERROR A file error occurred. \retval B_NOT_ALLOWED The file was opened read only. + + \since BeOS R3 */ /*! - \name Deprecated methods + \name Deprecated Methods These methods are deprecated and should not be used as there is a better method. See the method description for the replacement method to use. @@ -603,7 +663,7 @@ \param id The ID of the resource to write data to. \param data The data to be written. \param offset The byte offset relative to the beginning of the resource at - which the data shall be written. + which the data shall be written. \param length The size of the data to be written. \return A status code. @@ -612,6 +672,8 @@ identify an existing resource. \retval B_ERROR Error writing data. \retval B_NO_MEMORY Not enough memory for this operation. + + \since BeOS R3 */ @@ -632,7 +694,7 @@ \param id The ID of the resource to be read. \param data A pointer to a buffer into which the data shall be read \param offset The byte offset relative to the beginning of the resource - from which the data shall be read. + from which the data shall be read. \param length The size of the data to be read. \return A status code. @@ -641,6 +703,8 @@ identify an existing resource. \retval B_ERROR Error reading data. \retval B_NO_MEMORY Not enough memory for this operation. + + \since BeOS R3 */ @@ -658,10 +722,12 @@ \param type The type of the resource to find. \param id The ID of the resource to find. \param lengthFound A pointer to a variable into which the size of the - resource data shall be written. + resource data shall be written. \return A pointer to the resource data if everything went fine or \c NULL if an error occurred. + + \since BeOS R3 */ @@ -679,10 +745,12 @@ \param type The type of the resource to find. \param name The name of the resource to find. \param lengthFound A pointer to a variable into which the size of the - resource data shall be written. + resource data shall be written. \return A pointer to the resource data if everything went fine or \c NULL if an error occurred. + + \since BeOS R3 */ diff --git a/docs/user/storage/Statable.dox b/docs/user/storage/Statable.dox index a70112f83b..790f6647c6 100644 --- a/docs/user/storage/Statable.dox +++ b/docs/user/storage/Statable.dox @@ -1,5 +1,5 @@ /* - * Copyright 2002-2013 Haiku Inc. All rights reserved. + * Copyright 2002-2013 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: @@ -8,8 +8,8 @@ * Ingo Weinhold, bonefish@users.sf.net * * Corresponds to: - * headers/os/storage/Statable.h hrev45306 - * src/kits/storage/Statable.cpp hrev45306 + * headers/os/storage/Statable.h hrev47402 + * src/kits/storage/Statable.cpp hrev47402 */ @@ -46,22 +46,26 @@ GetVolume() method. - Get a node_ref of a node to pass into watch_node() via the GetNodeRef() method. + + \since BeOS R3 */ /*! - \fn status_t BStatable::GetStat(struct stat *st) const + \fn status_t BStatable::GetStat(struct stat* stat) const \brief Fills out the stat structure for the node. This method may be used to access the stat structure of a node directly. - \param st The stat structure to be filled in. + \param stat The stat structure to be filled in. \returns A status code. \retval B_OK Everything went fine. \retval B_NO_MEMORY Could not allocate enough memory. \retval B_BAD_VALUE The node does not exist. \retval B_NOT_ALLOWED Node or volume was read only. + + \since BeOS R3 */ @@ -71,6 +75,8 @@ \return \c true, if the node is properly initialized and is a file, \c false otherwise. + + \since BeOS R5 */ @@ -80,6 +86,8 @@ \return \c true, if the node is properly initialized and is a directory, \c false otherwise. + + \since BeOS R5 */ @@ -89,26 +97,33 @@ \return \c true, if the node is properly initialized and is a symlink, \c false otherwise. + + \since BeOS R5 */ /*! - \fn status_t BStatable::GetNodeRef(node_ref *ref) const + \fn status_t BStatable::GetNodeRef(node_ref* ref) const \brief Fills out \a ref with the \c node_ref of the node. \param ref the node_ref to be set. \see GetStat() for return codes. + + \since BeOS R3 */ /*! - \fn status_t BStatable::GetOwner(uid_t *owner) const + \fn status_t BStatable::GetOwner(uid_t* owner) const \brief Fills out the node's UID into \a owner. \param owner A pointer to a \c uid_t to be set. + \see SetOwner() \see GetStat() for return codes. + + \since BeOS R3 */ @@ -119,16 +134,21 @@ \param owner The UID to set the node to. \see GetStat() for return codes. + + \since BeOS R3 */ /*! - \fn status_t BStatable::GetGroup(gid_t *group) const + \fn status_t BStatable::GetGroup(gid_t* group) const \brief Fills out the node's GID into \a group. \param group a pointer to a \c gid_t variable to be set. + \see SetGroup() \see GetStat() for return codes. + + \since BeOS R3 */ @@ -139,47 +159,59 @@ \param group The GID to set the node to. \see GetStat() for return codes. + + \since BeOS R3 */ /*! - \fn status_t BStatable::GetPermissions(mode_t *perms) const + \fn status_t BStatable::GetPermissions(mode_t* permissions) const \brief Fills out \a perms with the permissions of the node. - \param perms A pointer to a \c mode_t variable to be set. + \param permissions The permissions to get from the node. + \see SetPermissions() \see GetStat() for return codes. + + \since BeOS R3 */ /*! - \fn status_t BStatable::SetPermissions(mode_t perms) + \fn status_t BStatable::SetPermissions(mode_t permissions) \brief Sets the node's permissions to \a perms. - \param perms The permissions to set the node to. + \param permissions The permissions to set the node to. \see GetStat() for return codes. + + \since BeOS R3 */ /*! - \fn status_t BStatable::GetSize(off_t *size) const + \fn status_t BStatable::GetSize(off_t* size) const \brief Fills out the size of the node's data (not counting attributes) into \a size. \param size A pointer to a \c off_t variable to be set. \see GetStat() for return codes. + + \since BeOS R3 */ /*! - \fn status_t BStatable::GetModificationTime(time_t *mtime) const + \fn status_t BStatable::GetModificationTime(time_t* mtime) const \brief Fills out \a mtime with the last modification time of the node. \param mtime A pointer to a \c time_t variable to be set. + \see SetModificationTime() \see GetStat() for return codes. + + \since BeOS R3 */ @@ -190,16 +222,21 @@ \param mtime The modification time to set the node to. \see GetStat() for return codes. + + \since BeOS R3 */ /*! - \fn status_t BStatable::GetCreationTime(time_t *ctime) const + \fn status_t BStatable::GetCreationTime(time_t* ctime) const \brief Fills out \a ctime with the creation time of the node. \param ctime A pointer to a \c time_t variable to be set. + \see SetCreationTime() \see GetStat() for return codes. + + \since BeOS R3 */ @@ -210,15 +247,20 @@ \param ctime The creation time to set the node to. \see GetStat() for return codes. + + \since BeOS R3 */ /*! - \fn status_t BStatable::GetAccessTime(time_t *atime) const + \fn status_t BStatable::GetAccessTime(time_t* atime) const \brief Fills out \a atime with the access time of the node. \see GetModificationTime() + \see SetAccessTime() \see GetStat() for return codes. + + \since BeOS R3 */ @@ -228,15 +270,19 @@ \see GetModificationTime() \see GetStat() for return codes. + + \since BeOS R3 */ /*! - \fn status_t BStatable::GetVolume(BVolume *vol) const + \fn status_t BStatable::GetVolume(BVolume* volume) const \brief Fills out \a vol with the the volume that the node lives on. - \param vol A pointer to a BVolume object to be set. + \param volume A pointer to a BVolume object to be set. \see BVolume \see GetStat() for return codes. + + \since Haiku R1 */ diff --git a/docs/user/storage/SymLink.dox b/docs/user/storage/SymLink.dox index 847ea478bd..936bbabefc 100644 --- a/docs/user/storage/SymLink.dox +++ b/docs/user/storage/SymLink.dox @@ -1,5 +1,5 @@ /* - * Copyright 2002-2013 Haiku Inc. All rights reserved. + * Copyright 2002-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: @@ -8,8 +8,8 @@ * Ingo Weinhold, bonefish@users.sf.net * * Corresponds to: - * headers/os/storage/SymLink.h hrev45306 - * src/kits/storage/SymLink.cpp hrev45306 + * headers/os/storage/SymLink.h hrev47402 + * src/kits/storage/SymLink.cpp hrev47402 */ @@ -27,58 +27,72 @@ \ingroup libbe \brief Provides an interface for creating, manipulating, and accessing the contents of symbolic links. + + \since BeOS R3 */ /*! \fn BSymLink::BSymLink() \brief Creates an uninitialized BSymLink object. + + \since BeOS R3 */ /*! - \fn BSymLink::BSymLink(const BSymLink &link) + \fn BSymLink::BSymLink(const BSymLink& other) \brief Creates a copy of the supplied BSymLink object. - \param link The BSymLink object to be copied. + \param other The BSymLink object to be copied. + + \since BeOS R3 */ /*! - \fn BSymLink::BSymLink(const entry_ref *ref) + \fn BSymLink::BSymLink(const entry_ref* ref) \brief Creates a BSymLink object and initializes it to the symbolic link referred to by the supplied entry_ref. \param ref the entry_ref referring to the symbolic link. + + \since BeOS R3 */ /*! - \fn BSymLink::BSymLink(const BEntry *entry) + \fn BSymLink::BSymLink(const BEntry* entry) \brief Creates a BSymLink object and initializes it to the symbolic link referred to by the supplied BEntry. \param entry The BEntry referring to the symbolic link. + + \since BeOS R3 */ /*! - \fn BSymLink::BSymLink(const char *path) + \fn BSymLink::BSymLink(const char* path) \brief Creates a BSymLink object and initializes it to the symbolic link referred to by the supplied path name. \param path The path of the symbolic link. + + \since BeOS R3 */ /*! - \fn BSymLink::BSymLink(const BDirectory *dir, const char *path) + \fn BSymLink::BSymLink(const BDirectory* dir, const char* path) \brief Creates a BSymLink object and initializes it to the symbolic link referred to by the supplied path name relative to the specified BDirectory. \param dir The base BDirectory. \param path The path of the symbolic link relative to \a dir. + + \since BeOS R3 */ @@ -88,11 +102,13 @@ If the BSymLink was properly initialized, the file descriptor of the symbolic link is also closed. + + \since BeOS R3 */ /*! - \fn ssize_t BSymLink::ReadLink(char *buffer, size_t size) + \fn ssize_t BSymLink::ReadLink(char* buffer, size_t size) \brief Reads the contents of the symbolic link into \a buffer. The string written to the buffer is guaranteed to be \c NULL terminated. @@ -104,11 +120,13 @@ \retval B_BAD_VALUE \a buf was \c NULL or the object didn't refer to a symbolic link. \retval B_FILE_ERROR The object was not initialized. + + \since BeOS R3 */ /*! - \fn ssize_t BSymLink::MakeLinkedPath(const char *dirPath, BPath *path) + \fn ssize_t BSymLink::MakeLinkedPath(const char* dirPath, BPath* path) \brief Combines a directory path and the contents of this symbolic link to form an absolute path. @@ -120,11 +138,13 @@ refer to a symbolic link. \retval B_FILE_ERROR The object was not initialized. \retval B_NAME_TOO_LONG The resulting path name was too long to fit. + + \since BeOS R3 */ /*! - \fn ssize_t BSymLink::MakeLinkedPath(const BDirectory *dir, BPath *path) + \fn ssize_t BSymLink::MakeLinkedPath(const BDirectory* dir, BPath* path) \brief Combines a directory path and the contents of this symbolic link to form an absolute path. @@ -136,6 +156,8 @@ refer to a symbolic link. \retval B_FILE_ERROR The object was not initialized. \retval B_NAME_TOO_LONG The resulting path name was too long to fit. + + \since BeOS R3 */ @@ -145,15 +167,6 @@ /return \c true if the object is properly initialized and the symbolic link refers to an absolute path, \c false otherwise. -*/ - - -/*! - \fn int BSymLink::get_fd() const - \brief Returns the file descriptor of the BSymLink. - - This method should be used instead of accessing the private \c fFd member - of the BNode directly. - - \return The object's file descriptor, or -1 if not properly initialized. + + \since BeOS R3 */ diff --git a/docs/user/storage/Volume.dox b/docs/user/storage/Volume.dox index f2a483ce08..1b9b6c50c6 100644 --- a/docs/user/storage/Volume.dox +++ b/docs/user/storage/Volume.dox @@ -1,5 +1,5 @@ /* - * Copyright 2002-2013 Haiku Inc. All rights reserved. + * Copyright 2002-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: @@ -9,8 +9,8 @@ * Ingo Weinhold, bonefish@users.sf.net * * Corresponds to: - * headers/os/storage/Volume.h hrev45306 - * src/kits/storage/Volume.cpp hrev45306 + * headers/os/storage/Volume.h hrev47402 + * src/kits/storage/Volume.cpp hrev47402 */ @@ -31,6 +31,8 @@ The class is a simple wrapper for a \c dev_t and the function fs_stat_dev(). The sole exception is the SetName() method which sets the name of the volume. + + \since BeOS R3 */ @@ -41,6 +43,8 @@ InitCheck() will return \c B_NO_INIT. \see SetTo() + + \since BeOS R3 */ @@ -53,11 +57,13 @@ successful. \param device The device ID of the volume. + + \since BeOS R3 */ /*! - \fn BVolume::BVolume(const BVolume &volume) + \fn BVolume::BVolume(const BVolume& volume) \brief Creates a copy of the supplied BVolume object. Afterwards the object refers to the same device the supplied object @@ -65,17 +71,21 @@ either. \param volume The volume object to be copied. + + \since BeOS R3 */ /*! \fn BVolume::~BVolume() \brief Destroys the object and frees all associated resources. + + \since BeOS R3 */ /*! - \name Constructor helper methods + \name Constructor Helpers */ @@ -88,6 +98,8 @@ \return \c B_OK if the object was properly initialized, or an error code otherwise. + + \since BeOS R3 */ @@ -97,8 +109,11 @@ the supplied device ID. \param device The device ID of the volume to set. + \return \c B_OK if the object was properly initialized, or an error code otherwise. + + \since BeOS R3 */ @@ -107,6 +122,8 @@ \brief Brings the BVolume object to an uninitialized state. InitCheck() will return \c B_NO_INIT. + + \since BeOS R3 */ @@ -114,7 +131,7 @@ /*! - \name Volume information methods + \name Volume Information */ @@ -126,7 +143,9 @@ \brief Returns the device ID of the volume the object refers to. \return Returns the device ID of the volume the object refers to - or -1 if the object was not properly initialized. + or -1 if the object was not properly initialized. + + \since BeOS R3 */ @@ -136,12 +155,14 @@ object into \a directory. \param directory A pointer to a pre-allocated BDirectory to be initialized - to the volume's root directory. + to the volume's root directory. \return A status code. \retval B_OK Everything went fine. \retval B_BAD_VALUE \a directory was \c NULL or the object was not properly initialized. + + \since BeOS R3 */ @@ -151,6 +172,10 @@ \return The volume's total storage capacity (in bytes), or \c B_BAD_VALUE if the object is not properly initialized. + + \see FreeBytes() + + \since BeOS R3 */ @@ -160,6 +185,8 @@ \return The amount of unused space on the volume (in bytes), or \c B_BAD_VALUE if the object is not properly initialized. + + \since BeOS R3 */ @@ -170,6 +197,8 @@ \return The block size in bytes, \c B_NO_INIT if the volume is not initialized or other errors forwarded from the file system. + + \since Haiku R1 */ @@ -177,7 +206,7 @@ /*! - \name Volume name methods + \name Volume Name */ @@ -196,6 +225,10 @@ \retval B_OK Everything went fine. \retval B_BAD_VALUE \a name was \c NULL or the object was not properly initialized. + + \see SetName() + + \since BeOS R3 */ @@ -220,6 +253,8 @@ \retval B_OK Everything went fine. \retval B_BAD_VALUE \a name was \c NULL or the object was not properly initialized. + + \since Haiku R1 */ @@ -227,7 +262,7 @@ /*! - \name Volume icon methods + \name Volume Icon */ @@ -239,11 +274,13 @@ \brief Writes the volume's icon into the supplied BBitmap. \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). + to store the requested icon (16x16 for the mini and 32x32 for the + large icon). \param which The icon size to be retrieved: \c B_MINI_ICON for the mini or \c B_LARGE_ICON for the large icon. + + \since BeOS R4 */ @@ -263,6 +300,8 @@ \see fs_stat_dev() for more return codes. \see get_device_icon() for more return codes. + + \since Haiku R1 */ @@ -270,7 +309,7 @@ /*! - \name Volume capability methods + \name Volume Capabilities */ @@ -283,6 +322,8 @@ \return \c true, if the volume was properly initialized and is removable, \c false otherwise. + + \since BeOS R3 */ @@ -292,6 +333,8 @@ \return \c true, if the volume was properly initialized and is read-only, \c false otherwise. + + \since BeOS R3 */ @@ -301,6 +344,8 @@ \return \c true, if the volume was properly initialized and is persistent, \c false otherwise. + + \since BeOS R3 */ @@ -310,6 +355,8 @@ return \c true, if the volume was properly initialized and is shared, \c false otherwise. + + \since BeOS R3 */ @@ -319,6 +366,8 @@ \return \c true, if the volume was properly initialized and supports MIME-types, \c false otherwise. + + \since BeOS R3 */ @@ -328,6 +377,8 @@ \return \c true, if the volume was properly initialized and supports attributes, \c false otherwise. + + \since BeOS R3 */ @@ -337,6 +388,8 @@ \return \c true, if the volume was properly initialized and supports queries, \c false otherwise. + + \since BeOS R3 */ @@ -344,7 +397,7 @@ /*! - \name Operator overload methods + \name Operators */ @@ -362,6 +415,8 @@ \param volume The volume to be tested for equality. \return \c true, if the objects are equal, \c false otherwise. + + \since BeOS R3 */ @@ -377,6 +432,8 @@ \param volume The volume to be tested for inequality. \return \c true, if the objects and unequal, \c false otherwise. + + \since BeOS R3 */ @@ -388,6 +445,8 @@ \param volume The volume to be assigned. \return A reference to this object. + + \since BeOS R3 */ diff --git a/docs/user/storage/VolumeRoster.dox b/docs/user/storage/VolumeRoster.dox index e29bfba5c4..049ca5d9e4 100644 --- a/docs/user/storage/VolumeRoster.dox +++ b/docs/user/storage/VolumeRoster.dox @@ -1,5 +1,5 @@ /* - * Copyright 2002-2013 Haiku Inc. All rights reserved. + * Copyright 2002-2014 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: @@ -8,8 +8,8 @@ * Ingo Weinhold, bonefish@users.sf.net * * Corresponds to: - * headers/os/storage/VolumeRoster.h hrev45306 - * src/kits/storage/VolumeRoster.cpp hrev45306 + * headers/os/storage/VolumeRoster.h hrev47402 + * src/kits/storage/VolumeRoster.cpp hrev47402 */ @@ -31,12 +31,16 @@ This class wraps the next_dev() function for iterating through the list of available volumes and watch_node()/stop_watching() for watching volumes. + + \since BeOS R3 */ /*! \fn BVolumeRoster::BVolumeRoster() \brief Creates a BVolumeRoster object. The object is ready to be used. + + \since BeOS R3 */ @@ -45,6 +49,8 @@ \brief Deletes the volume roster and frees all associated resources. If a watch was activated (by StartWatching()), it is deactivated. + + \since BeOS R3 */ @@ -60,6 +66,8 @@ \return A status code. \retval B_OK Everything went fine. \retval B_BAD_VALUE The last volume in the list was already returned. + + \since BeOS R3 */ @@ -68,6 +76,8 @@ \brief Rewinds the list of available volumes back to the first item. The next call to GetNextVolume() will return the first available volume. + + \since BeOS R3 */ @@ -80,10 +90,12 @@ volume is to rename "/boot" -- but, please refrain from doing this. \param volume A pointer to a pre-allocated BVolume to be initialized to - refer to the boot volume. + refer to the boot volume. \return A status code, \c B_OK if everything went fine or an error code otherwise. + + \since BeOS R3 */ @@ -111,6 +123,8 @@ operation. \see watch_node() + + \since BeOS R3 */ @@ -119,6 +133,8 @@ \brief Stops watching volumes initiated by StartWatching(). \see stop_watching() + + \since BeOS R3 */ @@ -127,5 +143,7 @@ \brief Returns the messenger currently watching the volume list. \return A messenger to the target currently watching the volume list, or - an invalid messenger if not watching. + an invalid messenger if not watching. + + \since BeOS R3 */