From 6d5fae2a5ae5dc28b2c4b2aa3d98085d13af8a1e Mon Sep 17 00:00:00 2001 From: John Scipione Date: Fri, 15 Feb 2013 19:12:11 -0500 Subject: [PATCH] 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. --- docs/user/storage/Resources.dox | 689 ++++++++++++++++++++++++++++++++ headers/os/storage/Resources.h | 167 ++++---- src/kits/storage/Resources.cpp | 537 +++++-------------------- 3 files changed, 883 insertions(+), 510 deletions(-) create mode 100644 docs/user/storage/Resources.dox diff --git a/docs/user/storage/Resources.dox b/docs/user/storage/Resources.dox new file mode 100644 index 0000000000..f1b90090e7 --- /dev/null +++ b/docs/user/storage/Resources.dox @@ -0,0 +1,689 @@ +/* + * Copyright 2001-2006 Ingo Weinhold, bonefish@cs.tu-berlin.de + * Copyright 2013 Haiku Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * John Scipione, jscipione@gmail.com + * Ingo Weinhold, bonefish@users.sf.net + * + * 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 e129f4e1d0..86cf2f5ad3 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 #include #include + 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 + 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(); + 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); + 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); - void Unset(); - status_t InitCheck() const; + // Haiku only + status_t SetToImage(image_id image, + bool clobber = false); + status_t SetToImage(const void* codeOrDataPointer, + bool clobber = false); - const BFile &File() const; + void Unset(); + status_t InitCheck() const; - const void *LoadResource(type_code type, int32 id, size_t *outSize); - const void *LoadResource(type_code type, const char *name, - size_t *outSize); + const BFile &File() const; - status_t PreloadResourceType(type_code type = 0); + 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 Sync(); - status_t MergeFrom(BFile *fromFile); - status_t WriteTo(BFile *file); + status_t PreloadResourceType(type_code type = 0); - status_t AddResource(type_code type, int32 id, const void *data, - size_t length, const char *name = NULL); + status_t Sync(); + status_t MergeFrom(BFile* fromFile); + status_t WriteTo(BFile* file); - bool HasResource(type_code type, int32 id); - bool HasResource(type_code type, const char *name); + status_t AddResource(type_code type, int32 id, + const void* data, size_t length, + const char* name = NULL); - 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); + bool HasResource(type_code type, int32 id); + bool HasResource(type_code type, const char* name); - status_t RemoveResource(const void *resource); - status_t RemoveResource(type_code type, int32 id); + 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 + // deprecated + status_t WriteResource(type_code type, int32 id, + const void* data, off_t offset, + size_t length); - 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); - 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); + 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 1fbf62b71f..3451abee35 100644 --- a/src/kits/storage/Resources.cpp +++ b/src/kits/storage/Resources.cpp @@ -1,20 +1,14 @@ /* * Copyright 2001-2006, Ingo Weinhold . + * Copyright 2013 Haiku, Inc. * All Rights Reserved. Distributed under the terms of the MIT License. + * + * Authors: + * John Scipione, jscipione@gmail.com + * Ingo Weinhold, bonefish@cs.tu-berlin.de */ -/*! - \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 #include @@ -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 +// #pragma mark - deprecated methods -// 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(). -*/ + +// 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() {} - - - -