Public Member Functions | List of all members
BResources Class Reference

Provides an interface for accessing and manipulating file resources. More...

Public Member Functions

 BResources ()
 Creates an uninitialized BResources object. More...
 
 BResources (const BFile *file, bool clobber=false)
 Creates a BResources object that represents the resources of the supplied file. More...
 
 BResources (const char *path, bool clobber=false)
 Creates a BResources object that represents the resources of the file referenced by the supplied path. More...
 
 BResources (const entry_ref *ref, bool clobber=false)
 Creates a BResources object that represents the resources of the file referenced by the supplied ref. More...
 
virtual ~BResources ()
 Destroys the BResources object and frees any associated resources. More...
 
status_t AddResource (type_code type, int32 id, const void *data, size_t length, const char *name=NULL)
 Adds a new resource to the file. More...
 
const BFileFile () const
 Gets a reference to the internal BFile object. More...
 
bool GetResourceInfo (int32 byIndex, type_code *typeFound, int32 *idFound, const char **nameFound, size_t *lengthFound)
 Gets information about a resource identified by byindex. More...
 
bool GetResourceInfo (type_code byType, int32 andIndex, int32 *idFound, const char **nameFound, size_t *lengthFound)
 Gets information about a resource identified by byType and andIndex. More...
 
bool GetResourceInfo (type_code byType, int32 andID, const char **nameFound, size_t *lengthFound)
 Gets information about a resource identified by byType and andID. More...
 
bool GetResourceInfo (type_code byType, const char *andName, int32 *idFound, size_t *lengthFound)
 Gets information about a resource identified by byType and andName. More...
 
bool GetResourceInfo (const void *byPointer, type_code *typeFound, int32 *idFound, size_t *lengthFound, const char **nameFound)
 Gets information about a resource identified by byPointer. More...
 
bool HasResource (type_code type, int32 id)
 Returns whether the file contains a resource with the specified type and id. More...
 
bool HasResource (type_code type, const char *name)
 Returns whether the file contains a resource with the specified type and name. More...
 
status_t MergeFrom (BFile *fromFile)
 Adds the resources of fromFile to the internal file of the BResources object. More...
 
status_t RemoveResource (const void *resource)
 Removes a resource identified by resource. More...
 
status_t RemoveResource (type_code type, int32 id)
 Removes a resource identified by type and id. More...
 
status_t Sync ()
 Writes all changes to the resources to the file. More...
 
status_t WriteTo (BFile *file)
 Writes the resources to a new file. More...
 
SetTo

What happens, if clobber is 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 clobber is false, file must refer to a file that is capable of containing resources.

If the file has been opened B_READ_ONLY, only read access to its resources is possible.

The BResources object makes a copy of file, that is the caller remains owner of the BFile object.

status_t SetTo (const BFile *file, bool clobber=false)
 Initializes the BResources object to represent the resources of the supplied file. More...
 
status_t SetTo (const char *path, bool clobber=false)
 Initialized the BResources object to represent the resources of the file referred to by the supplied path. More...
 
status_t SetTo (const entry_ref *ref, bool clobber=false)
 Initialized the BResources object to represent the resources of the file referenced by the supplied ref. More...
 
status_t SetToImage (image_id image, bool clobber=false)
 Initialized the BResources object to represent the resources of the file from which the specified image has been loaded. More...
 
status_t SetToImage (const void *codeOrDataPointer, bool clobber=false)
 Initialized the BResources object to represent the resources of the file from which the specified pointer has been loaded. More...
 
Constructor Helpers
void Unset ()
 Returns the BResources object to an uninitialized state. More...
 
status_t InitCheck () const
 Gets the initialization status of the object. More...
 
LoadResources

A resource is loaded into memory only once. A second call with the same parameters will result in the same pointer. The BResources object is the 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.

const void * LoadResource (type_code type, int32 id, size_t *_size)
 Loads a resource identified by type and id into memory. More...
 
const void * LoadResource (type_code type, const char *name, size_t *_size)
 Loads a resource identified by type and name into memory. More...
 
status_t PreloadResourceType (type_code type=0)
 Loads all resources of the specified type into memory. More...
 
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.

status_t WriteResource (type_code type, int32 id, const void *data, off_t offset, size_t length)
 Writes data into an existing resource. (deprecated, use AddResource() instead) More...
 
status_t ReadResource (type_code type, int32 id, void *data, off_t offset, size_t length)
 Reads data from an existing resource. (deprecated, use LoadResource() instead) More...
 
void * FindResource (type_code type, int32 id, size_t *lengthFound)
 Finds a resource by type and id and returns a pointer to a copy of its data. (deprecated, use LoadResource() instead) More...
 
void * FindResource (type_code type, const char *name, size_t *lengthFound)
 Finds a resource by type and name and returns a pointer to a copy of its data. (deprecated, use LoadResource() instead) More...
 

Detailed Description

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).

Since
BeOS R3

Constructor & Destructor Documentation

◆ BResources() [1/4]

BResources::BResources ( )

Creates an uninitialized BResources object.

See also
SetTo()
Since
BeOS R3

◆ BResources() [2/4]

BResources::BResources ( const BFile file,
bool  clobber = false 
)

Creates a BResources object that represents the resources of the supplied file.

If the clobber argument is true, the data of the file are erased and it is turned into an empty resource file. Otherwise file must refer either to a resource file or to an executable (ELF or PEF binary). If the file has been opened B_READ_ONLY, only read access to its resources is possible.

The BResources object makes a copy of file, that is the caller remains owner of the BFile object.

Parameters
fileThe file to create a BResource object from.
clobberIf true, the data of the file are erased.
Since
BeOS R3

◆ BResources() [3/4]

BResources::BResources ( const char *  path,
bool  clobber = false 
)

Creates a BResources object that represents the resources of the file referenced by the supplied path.

If the clobber argument is true, the data of the file are erased and it is turned into an empty resource file. Otherwise path must refer either to a resource file or to an executable (ELF or PEF binary).

Parameters
pathA path referring to the file to create a BResource object from.
clobberIf true, the data of the file are erased.
Since
Haiku R1

◆ BResources() [4/4]

BResources::BResources ( const entry_ref ref,
bool  clobber = false 
)

Creates a BResources object that represents the resources of the file referenced by the supplied ref.

If the clobber argument is true, the data of the file are erased and it is turned into an empty resource file. Otherwise ref must refer either to a resource file or to an executable (ELF or PEF binary).

Parameters
refAn entry_ref referring to the file to create a BResource object from.
clobberIf true, the data of the file are erased.
Since
Haiku R1

◆ ~BResources()

BResources::~BResources ( )
virtual

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.

Since
BeOS R3

Member Function Documentation

◆ AddResource()

status_t BResources::AddResource ( type_code  type,
int32  id,
const void *  data,
size_t  length,
const char *  name = NULL 
)

Adds a new resource to the file.

If a resource already exists with the same type and id it is replaced. The caller keeps the ownership of the supplied chunk of memory containing the resource data.

Supplying an empty name ("") is equivalent to supplying a NULL name.

Parameters
typeThe type of the resource.
idThe ID of the resource.
dataThe resource data.
lengthThe size of the data in bytes.
nameThe name of the resource (may be empty or NULL).
Returns
A status code.
Return values
B_OKEverything went fine.
B_BAD_VALUEdata was NULL.
B_FILE_ERRORA file error occurred.
B_NO_MEMORYNot enough memory for the operation.
B_NOT_ALLOWEDThe file was opened read only.
Since
BeOS R3

◆ File()

const BFile & BResources::File ( ) const

Gets a reference to the internal BFile object.

Returns
A reference to the internal BFile object.
Since
BeOS R4

◆ FindResource() [1/2]

void * BResources::FindResource ( type_code  type,
int32  id,
size_t *  lengthFound 
)

Finds a resource by type and id and returns a pointer to a copy of its data. (deprecated, use LoadResource() instead)

Warning
The caller is responsible for calling free() to release the memory used by the returned data.
Parameters
typeThe type of the resource to find.
idThe ID of the resource to find.
lengthFoundA pointer to a variable into which the size of the resource data shall be written.
Returns
A pointer to the resource data if everything went fine or NULL if an error occurred.
Since
BeOS R3

◆ FindResource() [2/2]

void * BResources::FindResource ( type_code  type,
const char *  name,
size_t *  lengthFound 
)

Finds a resource by type and name and returns a pointer to a copy of its data. (deprecated, use LoadResource() instead)

Warning
The caller is responsible for calling free() to release the memory used by the returned data.
Parameters
typeThe type of the resource to find.
nameThe name of the resource to find.
lengthFoundA pointer to a variable into which the size of the resource data shall be written.
Returns
A pointer to the resource data if everything went fine or NULL if an error occurred.
Since
BeOS R3

◆ GetResourceInfo() [1/5]

bool BResources::GetResourceInfo ( int32  byIndex,
type_code typeFound,
int32 *  idFound,
const char **  nameFound,
size_t *  lengthFound 
)

Gets information about a resource identified by byindex.

Parameters
byIndexThe index of the resource in the file.
typeFoundA pointer to a variable the type of the found resource shall be written into.
idFoundA pointer to a variable the ID of the found resource shall be written into.
nameFoundA pointer to a variable the name pointer of the found resource shall be written into.
lengthFoundA pointer to a variable the data size of the found resource shall be written into.
Returns
true, if a matching resource could be found, false otherwise.
Since
BeOS R3

◆ GetResourceInfo() [2/5]

bool BResources::GetResourceInfo ( type_code  byType,
int32  andIndex,
int32 *  idFound,
const char **  nameFound,
size_t *  lengthFound 
)

Gets information about a resource identified by byType and andIndex.

Parameters
byTypeThe resource type.
andIndexThe index into a array of resources of type byType.
idFoundA pointer to a variable the ID of the found resource shall be written into.
nameFoundA pointer to a variable the name pointer of the found resource shall be written into.
lengthFoundA pointer to a variable the data size of the found resource shall be written into.
Returns
true, if a matching resource could be found, false otherwise.
Since
BeOS R3

◆ GetResourceInfo() [3/5]

bool BResources::GetResourceInfo ( type_code  byType,
int32  andID,
const char **  nameFound,
size_t *  lengthFound 
)

Gets information about a resource identified by byType and andID.

Parameters
byTypeThe resource type.
andIDThe resource ID.
nameFoundA pointer to a variable the name pointer of the found resource shall be written into.
lengthFoundA pointer to a variable the data size of the found resource shall be written into.
Returns
true, if a matching resource could be found, false otherwise.
Since
BeOS R3

◆ GetResourceInfo() [4/5]

bool BResources::GetResourceInfo ( type_code  byType,
const char *  andName,
int32 *  idFound,
size_t *  lengthFound 
)

Gets information about a resource identified by byType and andName.

Parameters
byTypeThe resource type.
andNameThe resource name.
idFoundA pointer to a variable the ID of the found resource shall be written into.
lengthFoundA pointer to a variable the data size of the found resource shall be written into.
Returns
true, if a matching resource could be found, false otherwise.
Since
BeOS R3

◆ GetResourceInfo() [5/5]

bool BResources::GetResourceInfo ( const void *  byPointer,
type_code typeFound,
int32 *  idFound,
size_t *  lengthFound,
const char **  nameFound 
)

Gets information about a resource identified by byPointer.

Parameters
byPointerThe pointer to the resource data (formerly returned by LoadResource()).
typeFoundA pointer to a variable the type of the found resource shall be written into.
idFoundA pointer to a variable the ID of the found resource shall be written into.
lengthFoundA pointer to a variable the data size of the found resource shall be written into.
nameFoundA pointer to a variable the name pointer of the found resource shall be written into.
Returns
true, if a matching resource could be found, false otherwise.
Since
BeOS R4

◆ HasResource() [1/2]

bool BResources::HasResource ( type_code  type,
int32  id 
)

Returns whether the file contains a resource with the specified type and id.

Parameters
typeThe resource type to check.
idThe ID of the resource to check.
Returns
true if the file contains a matching resource, false otherwise.
Since
BeOS R3

◆ HasResource() [2/2]

bool BResources::HasResource ( type_code  type,
const char *  name 
)

Returns whether the file contains a resource with the specified type and name.

Parameters
typeThe resource type to check.
nameThe name of the resource to check.
Returns
true, if the file contains a matching resource, false otherwise.
Since
BeOS R3

◆ InitCheck()

status_t BResources::InitCheck ( ) const

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 B_OK.

Note
This method is not found in BeOS R5.
Returns
B_OK if the objects is properly initialized, B_NO_MEMORY otherwise.
Since
Haiku R1

◆ LoadResource() [1/2]

const void * BResources::LoadResource ( type_code  type,
int32  id,
size_t *  _size 
)

Loads a resource identified by type and id into memory.

Parameters
typeThe type of the resource to be loaded.
idThe ID of the resource to be loaded.
_sizeA pointer to a variable into which the size of the resource shall be written.
Returns
A pointer to the resource data if everything went fine, or NULL if the file does not have a resource that matches the parameters or an error occurred.
Since
BeOS R4

◆ LoadResource() [2/2]

const void * BResources::LoadResource ( type_code  type,
const char *  name,
size_t *  _size 
)

Loads a resource identified by type and 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.
Parameters
typeThe type of the resource to be loaded.
nameThe name of the resource to be loaded.
_sizeA pointer to a variable into which the size of the resource shall be written.
Returns
A pointer to the resource data if everything went fine, or NULL if the file does not have a resource that matches the parameters or an error occurred.
Since
BeOS R4

◆ MergeFrom()

status_t BResources::MergeFrom ( BFile fromFile)

Adds the resources of fromFile to the internal file of the BResources object.

Parameters
fromFileThe file whose resources are to be be copied from.
Returns
A status code.
Return values
B_OKEverything went fine.
B_BAD_FILEThe resource map is empty???
B_BAD_VALUEfromFile was NULL.
B_FILE_ERRORA file error occurred.
B_IO_ERRORAn error occurred while writing the resources.
Since
BeOS R4

◆ PreloadResourceType()

status_t BResources::PreloadResourceType ( type_code  type = 0)

Loads all resources of the specified type into memory.

If type is 0, all resources are loaded. This might be useful for performance reasons.

Parameters
typeThe type of resources to be loaded.
Returns
One of the following status codes or the negation of the number of errors that occurred.
Return values
B_OKEverything went fine.
B_BAD_FILEThe resource map is empty???
Since
BeOS R4

◆ ReadResource()

status_t BResources::ReadResource ( type_code  type,
int32  id,
void *  data,
off_t  offset,
size_t  length 
)

Reads data from an existing resource. (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.

Parameters
typeThe type of the resource to be read.
idThe ID of the resource to be read.
dataA pointer to a buffer into which the data shall be read
offsetThe byte offset relative to the beginning of the resource from which the data shall be read.
lengthThe size of the data to be read.
Returns
A status code.
Return values
B_OKEverything went fine.
B_BAD_VALUEdata was NULL or type and id did not identify an existing resource.
B_ERRORError reading data.
B_NO_MEMORYNot enough memory for this operation.
Since
BeOS R3

◆ RemoveResource() [1/2]

status_t BResources::RemoveResource ( const void *  resource)

Removes a resource identified by resource.

Parameters
resourceThe pointer to the resource data (formerly returned by LoadResource()).
Returns
A status code.
Return values
B_OKEverything went fine.
B_BAD_VALUEresource was NULL or invalid (didn't point to any resource data of this file).
B_ERRORAn error occurred while removing the resource.
B_FILE_ERRORA file error occurred.
B_NOT_ALLOWEDThe file was opened read only.
Since
BeOS R4

◆ RemoveResource() [2/2]

status_t BResources::RemoveResource ( type_code  type,
int32  id 
)

Removes a resource identified by type and id.

Parameters
typeThe type of the resource to remove.
idThe ID of the resource to remove.
Returns
A status code.
Return values
B_OKEverything went fine.
B_BAD_VALUENo such resource was found.
B_ERRORAn error occurred while removing the resource.
B_FILE_ERRORA file error occurred.
B_NOT_ALLOWEDThe file was opened read only.
Since
BeOS R3

◆ SetTo() [1/3]

status_t BResources::SetTo ( const BFile file,
bool  clobber = false 
)

Initializes the BResources object to represent the resources of the supplied file.

Parameters
fileThe file to initialize the BResources object from.
clobberIf true, the data of the file are erased.
Returns
A status code.
Return values
B_OKEverything went fine.
B_BAD_VALUEfile was NULL or uninitialized.
B_ERRORFailed to initialize the object.
Since
BeOS R3

◆ SetTo() [2/3]

status_t BResources::SetTo ( const char *  path,
bool  clobber = false 
)

Initialized the BResources object to represent the resources of the file referred to by the supplied path.

Parameters
pathA path referring to the file to create a BResource object from.
clobberIf true, the data of the file are erased.
Returns
A status code.
Return values
B_OKEverything went fine.
B_BAD_VALUEpath was NULL.
B_ENTRY_NOT_FOUNDThe file referenced by path couldn't be found.
B_ERRORFailed to initialize the object.
Since
Haiku R1

◆ SetTo() [3/3]

status_t BResources::SetTo ( const entry_ref ref,
bool  clobber = false 
)

Initialized the BResources object to represent the resources of the file referenced by the supplied ref.

Parameters
refAn entry_ref referring to the file to create a BResource object from.
clobberIf true, the data of the file are erased.
Returns
A status code.
Return values
B_OKEverything went fine.
B_BAD_VALUEref was NULL.
B_ENTRY_NOT_FOUNDThe file referenced by ref couldn't be found.
B_ERRORFailed to initialize the object.
Since
Haiku R1

◆ SetToImage() [1/2]

status_t BResources::SetToImage ( image_id  image,
bool  clobber = false 
)

Initialized the BResources object to represent the resources of the file from which the specified image has been loaded.

If clobber is true, the file's resources are removed.

Parameters
imageID of a loaded image.
clobberIf true, the data of the file are erased.
Returns
A status code.
Return values
B_OKEverything went fine.
B_ENTRY_NOT_FOUNDThe file referenced by image couldn't be found.
B_ERRORFailed to initialize the object.
Since
Haiku R1

◆ SetToImage() [2/2]

status_t BResources::SetToImage ( const void *  codeOrDataPointer,
bool  clobber = false 
)

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 clobber is true, the file's resources are removed.

Parameters
codeOrDataPointerPointer to the text or data segment of the image.
clobberIf true, the data of the file are erased.
Returns
A status code.
Return values
B_OKEverything went fine.
B_BAD_VALUEcodeOrDataPointer was NULL.
B_ENTRY_NOT_FOUNDThe image or the file couldn't be found.
B_ERRORFailed to initialize the object.
Since
Haiku R1

◆ Sync()

status_t BResources::Sync ( )

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.
Return values
B_OKEverything went fine.
B_BAD_FILEThe resource map is empty???
B_FILE_ERRORA file error occurred.
B_IO_ERRORAn error occurred while writing the resources.
B_NOT_ALLOWEDThe file was opened read only.
Since
BeOS R4

◆ Unset()

void BResources::Unset ( )

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.
Since
Haiku R1

◆ WriteResource()

status_t BResources::WriteResource ( type_code  type,
int32  id,
const void *  data,
off_t  offset,
size_t  length 
)

Writes data into an existing resource. (deprecated, use AddResource() instead)

If writing the data would exceed the bounds of the resource, it is enlarged respectively. If offset is past the end of the resource, padding with unspecified data is inserted.

Parameters
typeThe type of the resource to write data to.
idThe ID of the resource to write data to.
dataThe data to be written.
offsetThe byte offset relative to the beginning of the resource at which the data shall be written.
lengthThe size of the data to be written.
Returns
A status code.
Return values
B_OKEverything went fine.
B_BAD_VALUEdata was NULL or type and id did not identify an existing resource.
B_ERRORError writing data.
B_NO_MEMORYNot enough memory for this operation.
Since
BeOS R3

◆ WriteTo()

status_t BResources::WriteTo ( BFile file)

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.
Parameters
fileThe file that the resources shall be written to.
Returns
B_OK if everything went fine or an error code otherwise.
Since
BeOS R4