[haiku-commits] haiku: hrev45303 - src/kits/storage docs/user/storage headers/os/storage
- From: jscipione@xxxxxxxxx
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Tue, 19 Feb 2013 00:19:28 +0100 (CET)
hrev45303 adds 1 changeset to branch 'master'
old head: 55e7521e36ef7843eca83eb608694de9b2a8558c
new head: 6d5fae2a5ae5dc28b2c4b2aa3d98085d13af8a1e
overview: http://cgit.haiku-os.org/haiku/log/?qt=range&q=6d5fae2+%5E55e7521
----------------------------------------------------------------------------
6d5fae2: Move resources docs to Haiku Book
* Remove docs from Resources.cpp (leaving the brief description).
* Reformat Resources.h to style it like so many other header files.
* There is one not-entirely style based change. I renamed the outSize
parameter or the LoadResource method to _size as is our convention for out
parameters.
[ John Scipione <jscipione@xxxxxxxxx> ]
----------------------------------------------------------------------------
Revision: hrev45303
Commit: 6d5fae2a5ae5dc28b2c4b2aa3d98085d13af8a1e
URL: http://cgit.haiku-os.org/haiku/commit/?id=6d5fae2
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Sat Feb 16 00:12:11 2013 UTC
----------------------------------------------------------------------------
3 files changed, 900 insertions(+), 527 deletions(-)
docs/user/storage/Resources.dox | 689 ++++++++++++++++++++++++++++++++++++
headers/os/storage/Resources.h | 197 ++++++-----
src/kits/storage/Resources.cpp | 541 ++++++----------------------
----------------------------------------------------------------------------
diff --git a/docs/user/storage/Resources.dox b/docs/user/storage/Resources.dox
new file mode 100644
index 0000000..f1b9009
--- /dev/null
+++ b/docs/user/storage/Resources.dox
@@ -0,0 +1,689 @@
+/*
+ * Copyright 2001-2006 Ingo Weinhold, bonefish@xxxxxxxxxxxxxxx
+ * Copyright 2013 Haiku Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ * John Scipione, jscipione@xxxxxxxxx
+ * Ingo Weinhold, bonefish@xxxxxxxxxxxx
+ *
+ * Corresponds to:
+ * headers/os/storage/Resources.h hrev45283
+ * src/kits/storage/Resources.cpp hrev45283
+ */
+
+
+/*!
+ \file Resources.h
+ \ingroup storage
+ \ingroup libbe
+ Provides the BResources class.
+*/
+
+
+/*!
+ \class BResources
+ \ingroup storage
+ \ingroup libbe
+ \brief Provides an interface for accessing and manipulating file
+ resources.
+
+ BResources delegates most of the work to ResourcesContainer and
+ ResourceFile. The former manages a collections of ResourceItem objects's
+ (the actual resources) whereas the latter provides the file I/O
+ functionality.
+
+ An InitCheck() method is not needed, since a BResources object will
+ 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).
+*/
+
+
+/*!
+ \fn BResources::BResources()
+ \brief Creates an uninitialized BResources object.
+
+ \see SetTo()
+*/
+
+
+/*!
+ \fn BResources::BResources(const BFile* file, bool clobber)
+ \brief Creates a BResources object that represents the resources of the
+ supplied \a file.
+
+ If the \a clobber argument is \c true, the data of the file are erased
+ and it is turned into an empty resource file. Otherwise \a file
+ must refer either to a resource file or to an executable (ELF or PEF
+ binary). If the file has been opened \c B_READ_ONLY, only read access
+ to its resources is possible.
+
+ The BResources object makes a copy of \a file, that is the caller
remains
+ owner of the BFile object.
+
+ \param file The file to create a BResource object from.
+ \param clobber If \c true, the data of the file are erased.
+*/
+
+
+/*!
+ \fn BResources::BResources(const char* path, bool clobber)
+ \brief Creates a BResources object that represents the resources of the
+ file referenced by the supplied \a path.
+
+ If the \a clobber argument is \c true, the data of the file are erased
+ and it is turned into an empty resource file. Otherwise \a path
+ must refer either to a resource file or to an executable (ELF or PEF
+ binary).
+
+ \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.
+*/
+
+
+/*!
+ \fn BResources::BResources(const entry_ref* ref, bool clobber)
+ \brief Creates a BResources object that represents the resources of the
+ file referenced by the supplied \a ref.
+
+ If the \a clobber argument is \c true, the data of the file are erased
+ and it is turned into an empty resource file. Otherwise \a ref
+ must refer either to a resource file or to an executable (ELF or PEF
+ binary).
+
+ \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.
+*/
+
+
+/*!
+ \fn BResources::~BResources()
+ \brief Destroys the BResources object and frees any associated
resources.
+
+ Sync() is first called to make sure that the changes are written back to
+ the file.
+*/
+
+
+/*!
+ \name SetTo methods
+
+ 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
+ file or an executable (ELF or PEF), its resources are removed. Otherwise
+ the file's data are erased and it is turned into an empty resource file.
+ If \a clobber is \c false, \a file must refer to a file that is capable
+ of containing resources.
+
+ If the file has been opened \c B_READ_ONLY, only read access
+ to its resources is possible.
+
+ The BResources object makes a copy of \a file, that is the caller
remains
+ owner of the BFile object.
+*/
+
+
+//! @{
+
+
+/*!
+ \fn status_t BResources::SetTo(const BFile* file, bool clobber)
+ \brief Initializes the BResources object to represent the resources of
+ the supplied file.
+
+ \param file The file to initialize the BResources object from.
+ \param clobber If \c true, the data of the file are erased.
+
+ \returns A status code.
+ \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.
+*/
+
+
+/*!
+ \fn status_t BResources::SetTo(const char* path, bool clobber)
+ \brief Initialized the BResources object to represent the resources of
+ the file referred to by the supplied \a path.
+
+ \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.
+
+ \returns A status code.
+ \retval B_OK Everything went fine.
+ \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.
+*/
+
+
+/*!
+ \fn status_t BResources::SetTo(const entry_ref* ref, bool clobber)
+ \brief Initialized the BResources object to represent the resources of
the
+ file referenced by the supplied \a ref.
+
+ \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.
+
+ \returns A status code.
+ \retval B_OK Everything went fine.
+ \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.
+*/
+
+
+/*!
+ \fn status_t BResources::SetToImage(image_id image, bool clobber)
+ \brief Initialized the BResources object to represent the resources of
+ the file from which the specified \a image has been loaded.
+
+ If \a clobber is \c true, the file's resources are removed.
+
+ \param image ID of a loaded image.
+ \param clobber If \c true, the data of the file are erased.
+
+ \returns A status code.
+ \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.
+*/
+
+
+/*!
+ \fn status_t BResources::SetToImage(const void* codeOrDataPointer,
+ bool clobber)
+ \brief Initialized the BResources object to represent the resources of
+ the file from which the specified pointer has been loaded.
+
+ The image belongs to the current team and is identified by a pointer
into
+ it's code (aka text) or data segment, i.e. any pointer to a function or
a
+ static (or global) variable will do.
+
+ If \a clobber is \c true, the file's resources are removed.
+
+ \param codeOrDataPointer Pointer to the text or data segment of the
image.
+ \param clobber If \c true, the data of the file are erased.
+
+ \returns A status code.
+ \retval B_OK Everything went fine.
+ \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.
+*/
+
+
+//! @}
+
+
+/*!
+ \name Constructor helper methods
+*/
+
+
+//! @{
+
+
+/*!
+ \fn void BResources::Unset()
+ \brief Returns the BResources object to an uninitialized state.
+
+ If the object represented resources that had been modified, the data are
+ written back to the file.
+
+ \note This method is not found in BeOS R5.
+*/
+
+
+/*!
+ \fn status_t BResources::InitCheck() const
+ \brief Gets the initialization status of the object.
+
+ Unlike other Storage Kit classes a BResources object is always properly
+ initialized, unless it couldn't allocate memory for some important
+ internal structures. Thus even after a call to SetTo() that reported an
+ error, InitCheck() is likely to return \c B_OK.
+
+ \note This method is not found in BeOS R5.
+
+ \return \c B_OK if the objects is properly initialized,
+ \c B_NO_MEMORY otherwise.
+*/
+
+
+//! @}
+
+
+/*!
+ \name LoadResources methods
+
+ 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
+ owner of the allocated memory and the pointer to it will be valid until
+ the object is destroyed or the resource is removed or modified.
+*/
+
+
+//! @{
+
+
+/*!
+ \fn const void* BResources::LoadResource(type_code type, int32 id,
+ size_t* _size)
+ \brief Loads a resource identified by \a type and \a id into memory.
+
+ \param type The type of the resource to be loaded.
+ \param id The ID of the resource to be loaded.
+ \param _size A pointer to a variable into which the size of the resource
+ 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.
+*/
+
+
+/*!
+ \fn const void* BResources::LoadResource(type_code type, const char*
name,
+ size_t* _size)
+ \brief Loads a resource identified by \a type and \a name into memory.
+
+ \note Since a type and name pair may not identify a resource uniquely,
+ this method always returns the first resource that matches the
+ parameters, that is the one with the smallest index.
+
+ \param type The type of the resource to be loaded.
+ \param name The name of the resource to be loaded.
+ \param _size A pointer to a variable into which the size of the resource
+ 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.
+*/
+
+
+/*!
+ \fn status_t BResources::PreloadResourceType(type_code type)
+ \brief Loads all resources of the specified \a type into memory.
+
+ If \a type is 0, all resources are loaded. This might be useful for
+ performance reasons.
+
+ \param type The type of resources to be loaded.
+
+ \returns One of the following status codes or the negation of the number
+ of errors that occurred.
+ \retval B_OK Everything went fine.
+ \retval B_BAD_FILE The resource map is empty???
+*/
+
+
+//! @}
+
+
+/*!
+ \fn const BFile& BResources::File() const
+ \brief Gets a reference to the internal BFile object.
+
+ \return A reference to the internal BFile object.
+*/
+
+
+/*!
+ \fn status_t BResources::Sync()
+ \brief Writes all changes to the resources to the file.
+
+ Since AddResource() and RemoveResource() may change the resources only
in
+ memory, this method can be used to make sure, that all changes are
+ actually written to the file.
+
+ The BResources object's destructor calls Sync() before cleaning up.
+
+ \note When a resource is written to the file its data is converted
+ to the endianness of the file. When reading a resource the
+ data is converted to the endianness of the host. This of course
+ only works for known types, i.e. those that swap_data() is able to
+ understand.
+
+ \returns A status code.
+ \retval B_OK Everything went fine.
+ \retval B_BAD_FILE The resource map is empty???
+ \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.
+*/
+
+
+/*!
+ \fn status_t BResources::MergeFrom(BFile* fromFile)
+ \brief Adds the resources of \a fromFile to the internal file of the
+ BResources object.
+
+ \param fromFile The file whose resources are to be be copied from.
+
+ \returns A status code.
+ \retval B_OK Everything went fine.
+ \retval B_BAD_FILE The resource map is empty???
+ \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.
+*/
+
+
+/*!
+ \fn status_t BResources::WriteTo(BFile* file)
+ \brief Writes the resources to a new file.
+
+ The resources formerly contained in the target file (if any) are erased.
+ When the method returns, the BResources object refers to the new file.
+
+ \warning If the resources have been modified, but Sync() has not been
+ called, the old file remains unmodified.
+
+ \param file The file that the resources shall be written to.
+
+ \return \c B_OK if everything went fine or an error code otherwise.
+*/
+
+
+/*!
+ \fn status_t BResources::AddResource(type_code type, int32 id,
+ const void* data, size_t length, const char* name)
+ \brief Adds a new resource to the file.
+
+ If a resource already exists with the same \a type and \a id it is
+ replaced. The caller keeps the ownership of the supplied chunk of memory
+ containing the resource data.
+
+ Supplying an empty \a name (\c "") is equivalent to supplying a \c NULL
+ \a name.
+
+ \param type The type of the resource.
+ \param id The ID of the resource.
+ \param data The resource data.
+ \param length The size of the data in bytes.
+ \param name The name of the resource (may be empty or \c NULL).
+
+ \returns A status code.
+ \retval B_OK Everything went fine.
+ \retval B_BAD_VALUE \a data was \c NULL.
+ \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.
+*/
+
+
+/*!
+ \fn bool BResources::HasResource(type_code type, int32 id)
+ \brief Returns whether the file contains a resource with the specified
+ \a type and \a id.
+
+ \param type The resource type to check.
+ \param id The ID of the resource to check.
+
+ \return \c true if the file contains a matching resource,
+ \c false otherwise.
+*/
+
+
+/*!
+ \fn bool BResources::HasResource(type_code type, const char* name)
+ \brief Returns whether the file contains a resource with the specified
+ \a type and \a name.
+
+ \param type The resource type to check.
+ \param name The name of the resource to check.
+
+ \return \c true, if the file contains a matching resource,
+ \c false otherwise.
+*/
+
+
+/*!
+ \fn bool BResources::GetResourceInfo(int32 byIndex, type_code*
typeFound,
+ int32* idFound, const char** nameFound, size_t* lengthFound)
+ \brief Gets information about a resource identified by \a byindex.
+
+ \param byIndex The index of the resource in the file.
+ \param typeFound A pointer to a variable the type of the found resource
+ shall be written into.
+ \param idFound A pointer to a variable the ID of the found resource
+ shall be written into.
+ \param nameFound A pointer to a variable the name pointer of the found
+ resource shall be written into.
+ \param lengthFound A pointer to a variable the data size of the found
+ resource shall be written into.
+
+ \return \c true, if a matching resource could be found,
+ \c false otherwise.
+*/
+
+
+/*!
+ \fn bool BResources::GetResourceInfo(type_code byType, int32 andIndex,
+ int32* idFound, const char** nameFound, size_t* lengthFound)
+ \brief Gets information about a resource identified by \a byType and
+ \a andIndex.
+
+ \param byType The resource type.
+ \param andIndex The index into a array of resources of type \a byType.
+ \param idFound A pointer to a variable the ID of the found resource
+ shall be written into.
+ \param nameFound A pointer to a variable the name pointer of the found
+ resource shall be written into.
+ \param lengthFound A pointer to a variable the data size of the found
+ resource shall be written into.
+
+ \return \c true, if a matching resource could be found,
+ \c false otherwise.
+*/
+
+
+/*!
+ \fn bool BResources::GetResourceInfo(type_code byType, int32 andID,
+ const char** nameFound, size_t* lengthFound)
+ \brief Gets information about a resource identified by \a byType and
+ \a andID.
+
+ \param byType The resource type.
+ \param andID The resource ID.
+ \param nameFound A pointer to a variable the name pointer of the found
+ resource shall be written into.
+ \param lengthFound A pointer to a variable the data size of the found
+ resource shall be written into.
+
+ \return \c true, if a matching resource could be found,
+ \c false otherwise.
+*/
+
+
+/*!
+ \fn bool BResources::GetResourceInfo(type_code byType, const char*
andName,
+ int32* idFound, size_t* lengthFound)
+ \brief Gets information about a resource identified by \a byType and
+ \a andName.
+
+ \param byType The resource type.
+ \param andName The resource name.
+ \param idFound A pointer to a variable the ID of the found resource
+ shall be written into.
+ \param lengthFound A pointer to a variable the data size of the found
+ resource shall be written into.
+
+ \return \c true, if a matching resource could be found,
+ \c false otherwise.
+*/
+
+
+/*!
+ \fn bool BResources::GetResourceInfo(const void* byPointer,
+ type_code* typeFound, int32* idFound, size_t* lengthFound,
+ const char** nameFound)
+ \brief Gets information about a resource identified by \a byPointer.
+
+ \param byPointer The pointer to the resource data (formerly returned by
+ LoadResource()).
+ \param typeFound A pointer to a variable the type of the found resource
+ shall be written into.
+ \param idFound A pointer to a variable the ID of the found resource
+ shall be written into.
+ \param lengthFound A pointer to a variable the data size of the found
+ resource shall be written into.
+ \param nameFound A pointer to a variable the name pointer of the found
+ resource shall be written into.
+
+ \return \c true, if a matching resource could be found,
+ \c false otherwise.
+*/
+
+
+/*!
+ \fn status_t BResources::RemoveResource(const void* resource)
+ \brief Removes a resource identified by \a resource.
+
+ \param resource The pointer to the resource data (formerly returned by
+ LoadResource()).
+
+ \return A status code.
+ \retval B_OK Everything went fine.
+ \retval B_BAD_VALUE \a resource was \c NULL or invalid (didn't point to
+ any resource data of this file).
+ \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.
+*/
+
+
+/*!
+ \fn status_t BResources::RemoveResource(type_code type, int32 id)
+ \brief Removes a resource identified by \a type and \a id.
+
+ \param type The type of the resource to remove.
+ \param id The ID of the resource to remove.
+
+ \return A status code.
+ \retval B_OK Everything went fine.
+ \retval B_BAD_VALUE No such resource was found.
+ \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.
+*/
+
+
+/*!
+ \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.
+*/
+
+
+//! @{
+
+
+/*!
+ \fn status_t BResources::WriteResource(type_code type, int32 id,
+ const void* data, off_t offset, size_t length)
+ \brief Writes data into an existing resource.
+ (deprecated, use AddResource() instead)
+
+ \deprecated Use AddResource() instead.
+
+ If writing the data would exceed the bounds of the resource, it is
+ enlarged respectively. If \a offset is past the end of the resource,
+ padding with unspecified data is inserted.
+
+ \param type The type of the resource to write data to.
+ \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.
+ \param length The size of the data to be written.
+
+ \return A status code.
+ \retval B_OK Everything went fine.
+ \retval B_BAD_VALUE \a data was \c NULL or \a type and \a id did not
+ identify an existing resource.
+ \retval B_ERROR Error writing data.
+ \retval B_NO_MEMORY Not enough memory for this operation.
+*/
+
+
+/*!
+ \fn status_t BResources::ReadResource(type_code type, int32 id,
+ void* data, off_t offset, size_t length)
+ \brief Reads data from an existing resource.
+ (deprecated, use LoadResource() instead)
+
+ \deprecated Use LoadResource() instead.
+
+ If more data than existing are requested, this method does not fail. It
+ will then read only the existing data. As a consequence an offset past
+ the end of the resource will not cause the method to fail, but no data
+ will be read at all.
+
+ \param type The type of the resource to be read.
+ \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.
+ \param length The size of the data to be read.
+
+ \return A status code.
+ \retval B_OK Everything went fine.
+ \retval B_BAD_VALUE \a data was \c NULL or \a type and \a id did not
+ identify an existing resource.
+ \retval B_ERROR Error reading data.
+ \retval B_NO_MEMORY Not enough memory for this operation.
+*/
+
+
+/*!
+ \fn void* BResources::FindResource(type_code type, int32 id,
+ size_t* lengthFound)
+ \brief Finds a resource by \a type and \a id and returns a pointer to a
+ copy of its data. (deprecated, use LoadResource() instead)
+
+ \deprecated Use LoadResource() instead.
+
+ \warning The caller is responsible for calling free() to release the
+ memory used by the returned data.
+
+ \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.
+
+ \return A pointer to the resource data if everything went fine or \c
NULL
+ if an error occurred.
+*/
+
+
+/*!
+ \fn void* BResources::FindResource(type_code type, const char* name,
+ size_t* lengthFound)
+ \brief Finds a resource by \a type and \a name and returns a pointer to
a
+ copy of its data. (deprecated, use LoadResource() instead)
+
+ \deprecated Use LoadResource() instead.
+
+ \warning The caller is responsible for calling free() to release the
+ memory used by the returned data.
+
+ \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.
+
+ \return A pointer to the resource data if everything went fine or \c
NULL
+ if an error occurred.
+*/
+
+
+//! @}
diff --git a/headers/os/storage/Resources.h b/headers/os/storage/Resources.h
index e129f4e..86cf2f5 100644
--- a/headers/os/storage/Resources.h
+++ b/headers/os/storage/Resources.h
@@ -1,19 +1,16 @@
/*
- * Copyright 2001-2006, Haiku Inc. All Rights Reserved.
+ * Copyright 2001-2013, Haiku Inc. All Rights Reserved.
* Distributed under the terms of the MIT License.
*/
-/*!
- \file Resources.h
- BResources interface declaration.
-*/
-
#ifndef _RESOURCES_H
#define _RESOURCES_H
+
#include <Entry.h>
#include <File.h>
#include <image.h>
+
namespace BPrivate {
namespace Storage {
class ResourcesContainer;
@@ -21,99 +18,115 @@ namespace BPrivate {
};
};
-/*!
- \class BResources
- \brief Represent the resources in a file
-
- Provides an interface for accessing and manipulating resources.
- \author Ingo Weinhold
-
- \version 1.0.0
-*/
class BResources {
public:
- BResources();
- BResources(const BFile *file, bool clobber = false);
- BResources(const char *path, bool clobber = false);
// Haiku only
- BResources(const entry_ref *ref, bool clobber = false); //
Haiku only
-
- virtual ~BResources();
-
- status_t SetTo(const BFile *file, bool clobber = false);
- status_t SetTo(const char *path, bool clobber = false); //
Haiku only
- status_t SetTo(const entry_ref *ref, bool clobber = false); //
Haiku only
-
- // Haiku only
- status_t SetToImage(image_id image, bool clobber = false);
- status_t SetToImage(const void *codeOrDataPointer, bool clobber =
false);
-
- void Unset();
- status_t InitCheck() const;
-
- const BFile &File() const;
-
- const void *LoadResource(type_code type, int32 id, size_t *outSize);
- const void *LoadResource(type_code type, const char *name,
- size_t *outSize);
-
- status_t PreloadResourceType(type_code type = 0);
-
- status_t Sync();
- status_t MergeFrom(BFile *fromFile);
- status_t WriteTo(BFile *file);
-
- status_t AddResource(type_code type, int32 id, const void *data,
- size_t length, const char
*name = NULL);
-
- bool HasResource(type_code type, int32 id);
- bool HasResource(type_code type, const char *name);
-
- bool GetResourceInfo(int32 byIndex, type_code *typeFound, int32
*idFound,
- const char **nameFound, size_t
*lengthFound);
- bool GetResourceInfo(type_code byType, int32 andIndex, int32 *idFound,
- const char **nameFound, size_t
*lengthFound);
- bool GetResourceInfo(type_code byType, int32 andID,
- const char **nameFound, size_t
*lengthFound);
- bool GetResourceInfo(type_code byType, const char *andName, int32
*idFound,
- size_t *lengthFound);
- bool GetResourceInfo(const void *byPointer, type_code *typeFound,
- int32 *idFound, size_t
*lengthFound,
- const char **nameFound);
-
- status_t RemoveResource(const void *resource);
- status_t RemoveResource(type_code type, int32 id);
-
-
- // deprecated
-
- status_t WriteResource(type_code type, int32 id, const void *data,
- off_t offset, size_t length);
-
- status_t ReadResource(type_code type, int32 id, void *data, off_t
offset,
- size_t length);
-
- void *FindResource(type_code type, int32 id, size_t *lengthFound);
- void *FindResource(type_code type, const char *name, size_t
*lengthFound);
+ BResources();
+
BResources(const BFile* file,
+ bool
clobber = false);
+ // Haiku only
+
BResources(const char* path,
+ bool
clobber = false);
+ // Haiku only
+
BResources(const entry_ref* ref,
+ bool
clobber = false);
+
+ virtual ~BResources();
+
+ status_t SetTo(const BFile* file,
+ bool
clobber = false);
+ // Haiku only
+ status_t SetTo(const char* path,
+ bool
clobber = false);
+ // Haiku only
+ status_t SetTo(const entry_ref*
ref,
+ bool
clobber = false);
+
+ // Haiku only
+ status_t SetToImage(image_id
image,
+ bool
clobber = false);
+ status_t SetToImage(const void*
codeOrDataPointer,
+ bool
clobber = false);
+
+ void Unset();
+ status_t InitCheck() const;
+
+ const BFile &File() const;
+
+ const void* LoadResource(type_code type,
int32 id,
+ size_t*
_size);
+ const void* LoadResource(type_code type,
const char* name,
+ size_t*
_size);
+
+ status_t
PreloadResourceType(type_code type = 0);
+
+ status_t Sync();
+ status_t MergeFrom(BFile*
fromFile);
+ status_t WriteTo(BFile* file);
+
+ status_t AddResource(type_code
type, int32 id,
+ const
void* data, size_t length,
+ const
char* name = NULL);
+
+ bool HasResource(type_code
type, int32 id);
+ bool HasResource(type_code
type, const char* name);
+
+ bool GetResourceInfo(int32
byIndex,
+
type_code* typeFound, int32* idFound,
+ const
char** nameFound,
+ size_t*
lengthFound);
+ bool
GetResourceInfo(type_code byType,
+ int32
andIndex, int32* idFound,
+ const
char** nameFound,
+ size_t*
lengthFound);
+ bool
GetResourceInfo(type_code byType, int32 andID,
+ const
char **nameFound,
+ size_t*
lengthFound);
+ bool
GetResourceInfo(type_code byType,
+ const
char* andName, int32* idFound,
+ size_t*
lengthFound);
+ bool GetResourceInfo(const
void* byPointer,
+
type_code* typeFound,
+ int32*
idFound, size_t* lengthFound,
+ const
char** nameFound);
+
+ status_t RemoveResource(const
void *resource);
+ status_t
RemoveResource(type_code type, int32 id);
+
+ // deprecated
+ status_t WriteResource(type_code
type, int32 id,
+ const
void* data, off_t offset,
+ size_t
length);
+
+ status_t ReadResource(type_code
type, int32 id,
+ void*
data, off_t offset,
+ size_t
length);
+
+ void* FindResource(type_code
type, int32 id,
+ size_t*
lengthFound);
+ void* FindResource(type_code
type, const char* name,
+ size_t
*lengthFound);
private:
- // FBC
- virtual void _ReservedResources1();
- virtual void _ReservedResources2();
- virtual void _ReservedResources3();
- virtual void _ReservedResources4();
- virtual void _ReservedResources5();
- virtual void _ReservedResources6();
- virtual void _ReservedResources7();
- virtual void _ReservedResources8();
+ // FBC
+ virtual void _ReservedResources1();
+ virtual void _ReservedResources2();
+ virtual void _ReservedResources3();
+ virtual void _ReservedResources4();
+ virtual void _ReservedResources5();
+ virtual void _ReservedResources6();
+ virtual void _ReservedResources7();
+ virtual void _ReservedResources8();
private:
- BFile fFile;
- BPrivate::Storage::ResourcesContainer *fContainer;
- BPrivate::Storage::ResourceFile *fResourceFile;
- bool fReadOnly;
- bool _pad[3];
- uint32 _reserved[3];
// FBC
+ BFile fFile;
+ BPrivate::Storage::ResourcesContainer* fContainer;
+ BPrivate::Storage::ResourceFile*
fResourceFile;
+ bool fReadOnly;
+ bool _pad[3];
+ // FBC
+ uint32 _reserved[3];
};
+
#endif // _RESOURCES_H
diff --git a/src/kits/storage/Resources.cpp b/src/kits/storage/Resources.cpp
index 1fbf62b..3451abe 100644
--- a/src/kits/storage/Resources.cpp
+++ b/src/kits/storage/Resources.cpp
@@ -1,20 +1,14 @@
/*
* Copyright 2001-2006, Ingo Weinhold <bonefish@xxxxxxxxxxxxxxx>.
+ * Copyright 2013 Haiku, Inc.
* All Rights Reserved. Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ * John Scipione, jscipione@xxxxxxxxx
+ * Ingo Weinhold, bonefish@xxxxxxxxxxxxxxx
*/
-/*!
- \file Resources.cpp
- BResources implementation.
-
- BResources delegates most of the work to ResourcesContainer and
- ResourceFile. The first one manages a collections of ResourceItem's,
- the actual resources, whereas the latter provides the file I/O
- functionality.
- An InitCheck() method is not needed, since a BResources object will
- 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).
-*/
+
+
#include <Resources.h>
#include <new>
@@ -25,17 +19,18 @@
#include "ResourceItem.h"
#include "ResourcesContainer.h"
+
using namespace BPrivate::Storage;
using namespace std;
+
// debugging
//#define DBG(x) x
#define DBG(x)
#define OUT printf
-// constructor
-/*! \brief Creates an unitialized BResources object.
-*/
+
+// Creates an unitialized BResources object.
BResources::BResources()
:
fFile(),
@@ -46,19 +41,9 @@ BResources::BResources()
fContainer = new(nothrow) ResourcesContainer;
}
-// constructor
-/*! \brief Creates a BResources object that represents the resources of the
- supplied file.
- If the \a clobber argument is \c true, the data of the file are erased
- and it is turned into an empty resource file. Otherwise \a file
- must refer either to a resource file or to an executable (ELF or PEF
- binary). If the file has been opened \c B_READ_ONLY, only read access
- to its resources is possible.
- The BResources object makes a copy of \a file, that is the caller
remains
- owner of the BFile object.
- \param file the file
- \param clobber if \c true, the file's resources are truncated to size 0
-*/
+
+// Creates a BResources object that represents the resources of the
+// supplied file.
BResources::BResources(const BFile* file, bool clobber)
:
fFile(),
@@ -70,16 +55,9 @@ BResources::BResources(const BFile* file, bool clobber)
SetTo(file, clobber);
}
-// constructor
-/*! \brief Creates a BResources object that represents the resources of the
- supplied file.
- If the \a clobber argument is \c true, the data of the file are erased
- and it is turned into an empty resource file. Otherwise \a path
- must refer either to a resource file or to an executable (ELF or PEF
- binary).
- \param path a path referring to the file
- \param clobber if \c true, the file's resources are truncated to size 0
-*/
+
+// Creates a BResources object that represents the resources of the
+// file referenced by the supplied path.
BResources::BResources(const char* path, bool clobber)
:
fFile(),
@@ -91,16 +69,9 @@ BResources::BResources(const char* path, bool clobber)
SetTo(path, clobber);
}
-// constructor
-/*! \brief Creates a BResources object that represents the resources of the
- supplied file.
- If the \a clobber argument is \c true, the data of the file are erased
- and it is turned into an empty resource file. Otherwise \a ref
- must refer either to a resource file or to an executable (ELF or PEF
- binary).
- \param ref an entry_ref referring to the file
- \param clobber if \c true, the file's resources are truncated to size 0
-*/
+
+// Creates a BResources object that represents the resources of the
+// file referenced by the supplied ref.
BResources::BResources(const entry_ref* ref, bool clobber)
:
fFile(),
@@ -112,37 +83,17 @@ BResources::BResources(const entry_ref* ref, bool clobber)
SetTo(ref, clobber);
}
-// destructor
-/*! \brief Frees all resources associated with this object
- Calls Sync() before doing so to make sure that the changes are written
- back to the file.
-*/
+
+// Frees all resources associated with this object
BResources::~BResources()
{
Unset();
delete fContainer;
}
-// SetTo
-/*! \brief Re-initialized the BResources object to represent the resources
of
- the supplied file.
- 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
- file or an executable (ELF or PEF), its resources are removed. Otherwise
- the file's data are erased and it is turned into an empty resource file.
- If \a clobber is \c false, \a file must refer to a file that is capable
- of containing resources.
- If the file has been opened \c B_READ_ONLY, only read access
- to its resources is possible.
- The BResources object makes a copy of \a file, that is the caller
remains
- owner of the BFile object.
- \param file the file
- \param clobber if \c true, the file's resources are truncated to size 0
- \return
- - \c B_OK: Everything went fine.
- - \c B_BAD_VALUE: \c NULL or uninitialized \a file.
- - \c B_ERROR: Failed to initialize the object (for whatever reason).
-*/
+
+// Initialized the BResources object to represent the resources of
+// the supplied file.
status_t
BResources::SetTo(const BFile* file, bool clobber)
{
@@ -178,23 +129,9 @@ BResources::SetTo(const BFile* file, bool clobber)
return error;
}
-// SetTo
-/*! \brief Re-initialized the BResources object to represent the resources
of
- the supplied file.
- 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
- file or an executable (ELF or PEF), its resources are removed. Otherwise
- the file's data are erased and it is turned into an empty resource file.
- If \a clobber is \c false, \a path must refer to a file that is capable
- of containing resources.
- \param path a path referring to the file
- \param clobber if \c true, the file's resources are truncated to size 0
- \return
- - \c B_OK: Everything went fine.
- - \c B_BAD_VALUE: \c NULL \a path.
- - \c B_ENTRY_NOT_FOUND: The file couldn't be found.
- - \c B_ERROR: Failed to initialize the object (for whatever reason).
-*/
+
+// Initialized the BResources object to represent the resources of
+// the file referred to by the supplied path.
status_t
BResources::SetTo(const char* path, bool clobber)
{
@@ -213,23 +150,9 @@ BResources::SetTo(const char* path, bool clobber)
return SetTo(&file, clobber);
}
-// SetTo
-/*! \brief Re-initialized the BResources object to represent the resources
of
- the supplied file.
- 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
- file or an executable (ELF or PEF), its resources are removed. Otherwise
- the file's data are erased and it is turned into an empty resource file.
- If \a clobber is \c false, \a ref must refer to a file that is capable
- of containing resources.
- \param ref an entry_ref referring to the file
- \param clobber if \c true, the file's resources are truncated to size 0
- \return
- - \c B_OK: Everything went fine.
- - \c B_BAD_VALUE: \c NULL \a ref.
- - \c B_ENTRY_NOT_FOUND: The file couldn't be found.
- - \c B_ERROR: Failed to initialize the object (for whatever reason).
-*/
+
+// Initialized the BResources object to represent the resources of the
+// file referenced by the supplied ref.
status_t
BResources::SetTo(const entry_ref* ref, bool clobber)
{
@@ -248,17 +171,9 @@ BResources::SetTo(const entry_ref* ref, bool clobber)
return SetTo(&file, clobber);
}
-// SetToImage
-/*! \brief Re-initialized the BResources object to represent the resources
of
- the file from which the specified image has been loaded.
- If \a clobber is \c true, the file's resources are removed.
- \param image ID of a loaded image
- \param clobber if \c true, the file's resources are truncated to size 0
- \return
- - \c B_OK: Everything went fine.
- - \c B_ENTRY_NOT_FOUND: The file couldn't be found.
- - \c B_ERROR: Failed to initialize the object (for whatever reason).
-*/
+
+// Initialized the BResources object to represent the resources of
+// the file from which the specified image has been loaded.
status_t
BResources::SetToImage(image_id image, bool clobber)
{
@@ -278,20 +193,9 @@ BResources::SetToImage(image_id image, bool clobber)
#endif
}
-/*! \brief Re-initialized the BResources object to represent the resources
of
- the file from which the specified image has been loaded.
- The image belongs to the current team and is identified by a pointer
into
- it's code (aka text) or data segment, i.e. any pointer to a function or
a
- static (or global) variable will do.
- If \a clobber is \c true, the file's resources are removed.
- \param codeOrDataPointer pointer into the text or data segment of the
image
- \param clobber if \c true, the file's resources are truncated to size 0
- \return
- - \c B_OK: Everything went fine.
- - \c B_BAD_VALUE: \c NULL \a ref.
- - \c B_ENTRY_NOT_FOUND: The image or the file couldn't be found.
- - \c B_ERROR: Failed to initialize the object (for whatever reason).
-*/
+
+// Initialized the BResources object to represent the resources of
+// the file from which the specified pointer has been loaded.
status_t
BResources::SetToImage(const void* codeOrDataPointer, bool clobber)
{
@@ -319,12 +223,8 @@ BResources::SetToImage(const void* codeOrDataPointer, bool
clobber)
#endif
}
-// Unset
-/*! \brief Returns the BResources object to an uninitialized state.
- If the object represented resources that had been modified, the data are
- written back to the file.
- \note This method extends the BeOS R5 API.
-*/
+
+// Returns the BResources object to an uninitialized state.
void
BResources::Unset()
{
@@ -340,49 +240,26 @@ BResources::Unset()
fReadOnly = false;
}
-// InitCheck
-/*! Returns the current initialization status.
- Unlike other Storage Kit classes a BResources object is always properly
- initialized, unless it couldn't allocate memory for some important
- internal structures. Thus even after a call to SetTo() that reported an
- error, InitCheck() is likely to return \c B_OK.
- \return
- - \c B_OK, if the objects is properly initialized,
- - \c B_NO_MEMORY otherwise.
- \note This method extends the BeOS R5 API.
-*/
+
+// Gets the initialization status of the object.
status_t
BResources::InitCheck() const
{
return (fContainer ? B_OK : B_NO_MEMORY);
}
-// File
-/*! \brief Returns a reference to the BResources' BFile object.
- \return a reference to the object's BFile.
-*/
+
+// Gets a reference to the internal BFile object.
const BFile&
BResources::File() const
{
return fFile;
}
-// LoadResource
-/*! \brief Loads a resource identified by type and ID into memory.
- 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
- owner of the allocated memory and the pointer to it will be valid until
- the object is destroyed or the resource is removed or modified.
- \param type the type of the resource to be loaded
- \param id the ID of the resource to be loaded
- \param outSize a pointer to a variable into which the size of the
resource
- 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
matchs the
- parameters or an error occured.
-*/
+
+// Loads a resource identified by type and id into memory.
const void*
-BResources::LoadResource(type_code type, int32 id, size_t* outSize)
+BResources::LoadResource(type_code type, int32 id, size_t* _size)
{
// find the resource
status_t error = InitCheck();
@@ -399,31 +276,16 @@ BResources::LoadResource(type_code type, int32 id,
size_t* outSize)
const void *result = NULL;
if (error == B_OK) {
result = resource->Data();
- if (outSize)
- *outSize = resource->DataSize();
+ if (_size)
+ *_size = resource->DataSize();
}
return result;
}
-// LoadResource
-/*! \brief Loads a resource identified by type and name into memory.
- 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
- owner of the allocated memory and the pointer to it will be valid until
- the object is destroyed or the resource is removed or modified.
- \param type the type of the resource to be loaded
- \param name the name of the resource to be loaded
- \param outSize a pointer to a variable into which the size of the
resource
- 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 occured.
- \note Since a type and name pair may not identify a resource uniquely,
- this method always returns the first resource that matches the
- parameters, that is the one with the least index.
-*/
-const void *
-BResources::LoadResource(type_code type, const char* name, size_t* outSize)
+
+// Loads a resource identified by type and name into memory.
+const void*
+BResources::LoadResource(type_code type, const char* name, size_t* _size)
{
// find the resource
status_t error = InitCheck();
@@ -440,22 +302,14 @@ BResources::LoadResource(type_code type, const char*
name, size_t* outSize)
const void* result = NULL;
if (error == B_OK) {
result = resource->Data();
- if (outSize)
- *outSize = resource->DataSize();
+ if (_size)
+ *_size = resource->DataSize();
}
return result;
}
-// PreloadResourceType
-/*! \brief Loads all resources of a certain type into memory.
- For performance reasons it might be useful to do that. If \a type is
- 0, all resources are loaded.
- \param type of the resources to be loaded
- \return
- - \c B_OK: Everything went fine.
- - \c B_BAD_FILE: The resource map is empty???
- - The negative of the number of errors occured.
-*/
+
+// Loads all resources of the specified type into memory.
status_t
BResources::PreloadResourceType(type_code type)
{
@@ -479,24 +333,8 @@ BResources::PreloadResourceType(type_code type)
return error;
}
-// Sync
-/*! \brief Writes all changes to the resources to the file.
- Since AddResource() and RemoveResource() may change the resources only
in
- memory, this method can be used to make sure, that all changes are
- actually written to the file.
- The BResources object's destructor calls Sync() before cleaning up.
- \return
- - \c B_OK: Everything went fine.
- - \c B_BAD_FILE: The resource map is empty???
- - \c B_NOT_ALLOWED: The file is opened read only.
- - \c B_FILE_ERROR: A file error occured.
- - \c B_IO_ERROR: An error occured while writing the resources.
- \note When a resource is written to the file, its data are converted
- to the endianess of the file, and when reading a resource, the
- data are converted to the host's endianess. This does of
course
- only work for known types, i.e. those that swap_data() is
able to
- cope with.
-*/
+
+// Writes all changes to the resources to the file.
status_t
BResources::Sync()
{
@@ -516,16 +354,9 @@ BResources::Sync()
return error;
}
-// MergeFrom
-/*! \brief Adds the resources of the supplied file to this file's resources.
- \param fromFile the file whose resources shall be copied
- \return
- - \c B_OK: Everything went fine.
- - \c B_BAD_VALUE: \c NULL \a fromFile.
- - \c B_BAD_FILE: The resource map is empty???
- - \c B_FILE_ERROR: A file error occured.
- - \c B_IO_ERROR: An error occured while writing the resources.
-*/
+
+// Adds the resources of fromFile to the internal file of the
+// BResources object.
status_t
BResources::MergeFrom(BFile* fromFile)
{
@@ -546,17 +377,8 @@ BResources::MergeFrom(BFile* fromFile)
return error;
}
-// WriteTo
-/*! \brief Writes the resources to a new file.
- The resources formerly contained in the target file (if any) are erased.
- When the method returns, the BResources object refers to the new file.
- \param file the file the resources shall be written to.
- \return
- - \c B_OK: Everything went fine.
- - a specific error code.
- \note If the resources have been modified, but not Sync()ed, the old
file
- remains unmodified.
-*/
+
+// Writes the resources to a new file.
status_t
BResources::WriteTo(BFile* file)
{
@@ -585,24 +407,8 @@ BResources::WriteTo(BFile* file)
return error;
}
-// AddResource
-/*! \brief Adds a new resource to the file.
- If a resource with the same type and ID does already exist, it is
- replaced. The caller keeps the ownership of the supplied chunk of memory
- containing the resource data.
- Supplying an empty name (\c "") is equivalent to supplying a \c NULL
name.
- \param type the type of the resource
- \param id the ID of the resource
- \param data the resource data
- \param length the size of the data in bytes
- \param name the name of the resource (may be \c NULL)
- \return
- - \c B_OK: Everything went fine.
- - \c B_BAD_VALUE: \c NULL \a data
- - \c B_NOT_ALLOWED: The file is opened read only.
- - \c B_FILE_ERROR: A file error occured.
- - \c B_NO_MEMORY: Not enough memory for that operation.
-*/
+
+// Adds a new resource to the file.
status_t
BResources::AddResource(type_code type, int32 id, const void* data,
size_t length, const char* name)
@@ -634,49 +440,29 @@ BResources::AddResource(type_code type, int32 id, const
void* data,
return error;
}
-// HasResource
-/*! \brief Returns whether the file contains a resource with a certain
- type and ID.
- \param type the resource type
- \param id the ID of the resource
- \return \c true, if the file contains a matching resource, \false
otherwise
-*/
+
+// Returns whether the file contains a resource with the specified
+// type and id.
bool
BResources::HasResource(type_code type, int32 id)
{
return (InitCheck() == B_OK && fContainer->IndexOf(type, id) >= 0);
}
-// HasResource
-/*! \brief Returns whether the file contains a resource with a certain
- type and name.
- \param type the resource type
- \param name the name of the resource
- \return \c true, if the file contains a matching resource, \false
otherwise
-*/
+
+// Returns whether the file contains a resource with the specified
+// type and name.
bool
BResources::HasResource(type_code type, const char* name)
{
return (InitCheck() == B_OK && fContainer->IndexOf(type, name) >= 0);
}
-// GetResourceInfo
-/*! \brief Returns information about a resource identified by an index.
- \param byIndex the index of the resource in the file
- \param typeFound a pointer to a variable the type of the found resource
- shall be written into
- \param idFound a pointer to a variable the ID of the found resource
- shall be written into
- \param nameFound a pointer to a variable the name pointer of the found
- resource shall be written into
- \param lengthFound a pointer to a variable the data size of the found
- resource shall be written into
- \return \c true, if a matching resource could be found, false otherwise
-*/
+
+// Gets information about a resource identified by byindex.
bool
BResources::GetResourceInfo(int32 byIndex, type_code* typeFound,
- int32* idFound, const
char** nameFound,
- size_t* lengthFound)
+ int32* idFound, const char** nameFound, size_t* lengthFound)
{
ResourceItem* item = NULL;
if (InitCheck() == B_OK)
@@ -694,22 +480,11 @@ BResources::GetResourceInfo(int32 byIndex, type_code*
typeFound,
return item;
}
-// GetResourceInfo
-/*! \brief Returns information about a resource identified by a type and an
- index.
- \param byType the resource type
- \param andIndex the index into a array of resources of type \a byType
- \param idFound a pointer to a variable the ID of the found resource
- shall be written into
- \param nameFound a pointer to a variable the name pointer of the found
- resource shall be written into
- \param lengthFound a pointer to a variable the data size of the found
- resource shall be written into
- \return \c true, if a matching resource could be found, false otherwise
-*/
+
+// Gets information about a resource identified by byType and andIndex.
bool
BResources::GetResourceInfo(type_code byType, int32 andIndex, int32* idFound,
- const char** nameFound,
size_t* lengthFound)
+ const char** nameFound, size_t* lengthFound)
{
ResourceItem* item = NULL;
if (InitCheck() == B_OK) {
@@ -727,19 +502,11 @@ BResources::GetResourceInfo(type_code byType, int32
andIndex, int32* idFound,
return item;
}
-// GetResourceInfo
-/*! \brief Returns information about a resource identified by a type and an
ID.
- \param byType the resource type
- \param andID the resource ID
- \param nameFound a pointer to a variable the name pointer of the found
- resource shall be written into
- \param lengthFound a pointer to a variable the data size of the found
- resource shall be written into
- \return \c true, if a matching resource could be found, false otherwise
-*/
+
+// Gets information about a resource identified by byType and andID.
bool
BResources::GetResourceInfo(type_code byType, int32 andID,
- const char** nameFound,
size_t* lengthFound)
+ const char** nameFound, size_t* lengthFound)
{
ResourceItem* item = NULL;
if (InitCheck() == B_OK)
@@ -753,20 +520,11 @@ BResources::GetResourceInfo(type_code byType, int32 andID,
return item;
}
-// GetResourceInfo
-/*! \brief Returns information about a resource identified by a type and a
- name.
- \param byType the resource type
- \param andName the resource name
- \param idFound a pointer to a variable the ID of the found resource
- shall be written into
- \param lengthFound a pointer to a variable the data size of the found
- resource shall be written into
- \return \c true, if a matching resource could be found, false otherwise
-*/
+
+// Gets information about a resource identified by byType and andName.
bool
BResources::GetResourceInfo(type_code byType, const char* andName,
- int32* idFound, size_t*
lengthFound)
+ int32* idFound, size_t* lengthFound)
{
ResourceItem* item = NULL;
if (InitCheck() == B_OK)
@@ -780,24 +538,11 @@ BResources::GetResourceInfo(type_code byType, const char*
andName,
return item;
}
-// GetResourceInfo
-/*! \brief Returns information about a resource identified by a data
pointer.
- \param byPointer the pointer to the resource data (formely returned by
- LoadResource())
- \param typeFound a pointer to a variable the type of the found resource
- shall be written into
- \param idFound a pointer to a variable the ID of the found resource
- shall be written into
- \param lengthFound a pointer to a variable the data size of the found
- resource shall be written into
- \param nameFound a pointer to a variable the name pointer of the found
- resource shall be written into
- \return \c true, if a matching resource could be found, false otherwise
-*/
+
+// Gets information about a resource identified by byPointer.
bool
BResources::GetResourceInfo(const void* byPointer, type_code* typeFound,
- int32* idFound, size_t*
lengthFound,
- const char** nameFound)
+ int32* idFound, size_t* lengthFound, const char** nameFound)
{
ResourceItem* item = NULL;
if (InitCheck() == B_OK)
@@ -815,18 +560,8 @@ BResources::GetResourceInfo(const void* byPointer,
type_code* typeFound,
return item;
}
-// RemoveResource
-/*! \brief Removes a resource identified by its data pointer.
- \param resource the pointer to the resource data (formely returned by
- LoadResource())
- \return
- - \c B_OK: Everything went fine.
- - \c B_BAD_VALUE: \c NULL or invalid (not pointing to any resource data
of
- this file) \a resource.
- - \c B_NOT_ALLOWED: The file is opened read only.
- - \c B_FILE_ERROR: A file error occured.
- - \c B_ERROR: An error occured while removing the resource.
-*/
+
+// Removes a resource identified by its data pointer.
status_t
BResources::RemoveResource(const void* resource)
{
@@ -846,17 +581,8 @@ BResources::RemoveResource(const void* resource)
return error;
}
-// RemoveResource
-/*! \brief Removes a resource identified by type and ID.
- \param type the type of the resource
- \param id the ID of the resource
- \return
- - \c B_OK: Everything went fine.
- - \c B_BAD_VALUE: No such resource.
- - \c B_NOT_ALLOWED: The file is opened read only.
- - \c B_FILE_ERROR: A file error occured.
- - \c B_ERROR: An error occured while removing the resource.
-*/
+
+// Removes a resource identified by type and id.
status_t
BResources::RemoveResource(type_code type, int32 id)
{
@@ -875,30 +601,14 @@ BResources::RemoveResource(type_code type, int32 id)
}
-// deprecated
-
-// WriteResource
-/*! \brief Writes data into an existing resource.
- If writing the data would exceed the bounds of the resource, it is
- enlarged respectively. If \a offset is past the end of the resource,
- padding with unspecified data is inserted.
- \param type the type of the resource
- \param id the ID of the resource
- \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
- \param length the size of the data to be written
- \return
- - \c B_OK: Everything went fine.
- - \c B_BAD_VALUE: \a type and \a id do not identify an existing
resource or
- \c NULL \a data.
- - \c B_NO_MEMORY: Not enough memory for this operation.
- - other error codes.
- \deprecated Always use AddResource().
-*/
+// #pragma mark - deprecated methods
+
+
+// Writes data into an existing resource
+// (deprecated, use AddResource() instead).
status_t
BResources::WriteResource(type_code type, int32 id, const void* data,
- off_t offset, size_t length)
+ off_t offset, size_t length)
{
status_t error = (data && offset >= 0 ? B_OK : B_BAD_VALUE);
if (error == B_OK)
@@ -925,29 +635,12 @@ BResources::WriteResource(type_code type, int32 id, const
void* data,
return error;
}
-// ReadResource
-/*! \brief Reads data from an existing resource.
- If more data than existing are requested, this method does not fail. It
- will then read only the existing data. As a consequence an offset past
- the end of the resource will not cause the method to fail, but no data
- will be read at all.
- \param type the type of the resource
- \param id the ID of the resource
- \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
- \param length the size of the data to be read
- \return
- - \c B_OK: Everything went fine.
- - \c B_BAD_VALUE: \a type and \a id do not identify an existing
resource or
- \c NULL \a data.
- - \c B_NO_MEMORY: Not enough memory for this operation.
- - other error codes.
- \deprecated Use LoadResource() only.
-*/
+
+// Reads data from an existing resource
+// (deprecated, use LoadResource() instead).
status_t
BResources::ReadResource(type_code type, int32 id, void* data, off_t offset,
- size_t length)
+ size_t length)
{
status_t error = (data && offset >= 0 ? B_OK : B_BAD_VALUE);
if (error == B_OK)
@@ -971,18 +664,9 @@ BResources::ReadResource(type_code type, int32 id, void*
data, off_t offset,
return error;
}
-// FindResource
-/*! \brief Finds a resource by type and ID and returns a copy of its data.
- The caller is responsible for free()ing the returned memory.
- \param type the type of the resource
- \param id the ID of the resource
- \param lengthFound a pointer to a variable into which the size of the
- resource data shall be written
- \return
- - a pointer to the resource data, if everything went fine,
- - \c NULL, if an error occured.
- \deprecated Use LoadResource().
-*/
+
+// Finds a resource by type and id and returns a pointer to a copy of
+// its data (deprecated, use LoadResource() instead).
void*
BResources::FindResource(type_code type, int32 id, size_t* lengthFound)
{
@@ -998,18 +682,9 @@ BResources::FindResource(type_code type, int32 id, size_t*
lengthFound)
return result;
}
-// FindResource
-/*! \brief Finds a resource by type and name and returns a copy of its data.
- The caller is responsible for free()ing the returned memory.
- \param type the type of the resource
- \param name the name of the resource
- \param lengthFound a pointer to a variable into which the size of the
- resource data shall be written
- \return
- - a pointer to the resource data, if everything went fine,
- - \c NULL, if an error occured.
- \deprecated Use LoadResource().
-*/
+
+// Finds a resource by type and name and returns a pointer to a copy of
+// its data (deprecated, use LoadResource() instead).
void*
BResources::FindResource(type_code type, const char* name, size_t* lengthFound)
{
@@ -1035,7 +710,3 @@ void BResources::_ReservedResources5() {}
void BResources::_ReservedResources6() {}
void BResources::_ReservedResources7() {}
void BResources::_ReservedResources8() {}
-
-
-
-
Other related posts:
- » [haiku-commits] haiku: hrev45303 - src/kits/storage docs/user/storage headers/os/storage - jscipione
