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

Public Member Functions
	BResources ()
	Creates an uninitialized BResources object.

	BResources (const BFile *file, bool clobber=false)
	Creates a BResources object that represents the resources of the supplied file.

	BResources (const char *path, bool clobber=false)
	Creates a BResources object that represents the resources of the file referenced by the supplied path.

	BResources (const entry_ref *ref, bool clobber=false)
	Creates a BResources object that represents the resources of the file referenced by the supplied ref.

virtual	~BResources ()
	Destroys the BResources object and frees any associated resources.

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.

const BFile &	File () const
	Gets a reference to the internal BFile object.

bool	GetResourceInfo (const void byPointer, type_code typeFound, int32 idFound, size_t lengthFound, const char **nameFound)
	Gets information about a resource identified by byPointer.

bool	GetResourceInfo (int32 byIndex, type_code typeFound, int32 idFound, const char *nameFound, size_t lengthFound)
	Gets information about a resource identified by byindex.

bool	GetResourceInfo (type_code byType, const char andName, int32 idFound, size_t *lengthFound)
	Gets information about a resource identified by byType and andName.

bool	GetResourceInfo (type_code byType, int32 andID, const char *nameFound, size_t lengthFound)
	Gets information about a resource identified by byType and andID.

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.

bool	HasResource (type_code type, const char *name)
	Returns whether the file contains a resource with the specified type and name.

bool	HasResource (type_code type, int32 id)
	Returns whether the file contains a resource with the specified type and id.

status_t	MergeFrom (BFile *fromFile)
	Adds the resources of fromFile to the internal file of the BResources object.

status_t	RemoveResource (const void *resource)
	Removes a resource identified by resource.

status_t	RemoveResource (type_code type, int32 id)
	Removes a resource identified by type and id.

status_t	Sync ()
	Writes all changes to the resources to the file.

status_t	WriteTo (BFile *file)
	Writes the resources to a new file.

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.

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.

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.

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.

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.

Constructor Helpers
void	Unset ()
	Returns the BResources object to an uninitialized state.

status_t	InitCheck () const
	Gets the initialization status of the object.

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.

const void *	LoadResource (type_code type, const char name, size_t _size)
	Loads a resource identified by type and name into memory.

status_t	PreloadResourceType (type_code type=0)
	Loads all resources of the specified type into memory.

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)

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)

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)

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)

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

file	The file to create a BResource object from.
clobber	If `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

path	A path referring to the file to create a BResource object from.
clobber	If `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

ref	An entry_ref referring to the file to create a BResource object from.
clobber	If `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

type	The type of the resource.
id	The ID of the resource.
data	The resource data.
length	The size of the data in bytes.
name	The name of the resource (may be empty or `NULL`).

Returns: A status code.

Return values

B_OK	Everything went fine.
B_BAD_VALUE	data was `NULL`.
B_FILE_ERROR	A file error occurred.
B_NO_MEMORY	Not enough memory for the operation.
B_NOT_ALLOWED	The 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,
		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

type	The type of the resource to find.
name	The name of the resource to find.
lengthFound	A 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,
		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

type	The type of the resource to find.
id	The ID of the resource to find.
lengthFound	A 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	(	const void *	byPointer,
		type_code *	typeFound,
		int32 *	idFound,
		size_t *	lengthFound,
		const char **	nameFound
	)

Gets information about a resource identified by byPointer.

Parameters

byPointer	The pointer to the resource data (formerly returned by LoadResource()).
typeFound	A pointer to a variable the type of the found resource shall be written into.
idFound	A pointer to a variable the ID of the found resource shall be written into.
lengthFound	A pointer to a variable the data size of the found resource shall be written into.
nameFound	A 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

◆ GetResourceInfo() [2/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

byIndex	The index of the resource in the file.
typeFound	A pointer to a variable the type of the found resource shall be written into.
idFound	A pointer to a variable the ID of the found resource shall be written into.
nameFound	A pointer to a variable the name pointer of the found resource shall be written into.
lengthFound	A 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,
		const char *	andName,
		int32 *	idFound,
		size_t *	lengthFound
	)

Gets information about a resource identified by byType and andName.

Parameters

byType	The resource type.
andName	The resource name.
idFound	A pointer to a variable the ID of the found resource shall be written into.
lengthFound	A 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,
		int32	andID,
		const char **	nameFound,
		size_t *	lengthFound
	)

Gets information about a resource identified by byType and andID.

Parameters

byType	The resource type.
andID	The resource ID.
nameFound	A pointer to a variable the name pointer of the found resource shall be written into.
lengthFound	A 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	(	type_code	byType,
		int32	andIndex,
		int32 *	idFound,
		const char **	nameFound,
		size_t *	lengthFound
	)

Gets information about a resource identified by byType and andIndex.

Parameters

byType	The resource type.
andIndex	The index into a array of resources of type byType.
idFound	A pointer to a variable the ID of the found resource shall be written into.
nameFound	A pointer to a variable the name pointer of the found resource shall be written into.
lengthFound	A 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

◆ HasResource() [1/2]

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

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

Parameters

type	The resource type to check.
name	The name 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,
		int32	id
	)

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

Parameters

type	The resource type to check.
id	The ID 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,
		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

type	The type of the resource to be loaded.
name	The name of the resource to be loaded.
_size	A 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,
		int32	id,
		size_t *	_size
	)

Loads a resource identified by type and id into memory.

Parameters

type	The type of the resource to be loaded.
id	The ID of the resource to be loaded.
_size	A 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

fromFile The file whose resources are to be be copied from.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_BAD_FILE	The resource map is empty???
B_BAD_VALUE	fromFile was `NULL`.
B_FILE_ERROR	A file error occurred.
B_IO_ERROR	An 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

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.

Return values

B_OK	Everything went fine.
B_BAD_FILE	The 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

type	The type of the resource to be read.
id	The ID of the resource to be read.
data	A pointer to a buffer into which the data shall be read
offset	The byte offset relative to the beginning of the resource from which the data shall be read.
length	The size of the data to be read.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_BAD_VALUE	data was `NULL` or type and id did not identify an existing resource.
B_ERROR	Error reading data.
B_NO_MEMORY	Not 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

resource The pointer to the resource data (formerly returned by LoadResource()).

Returns: A status code.

Return values

B_OK	Everything went fine.
B_BAD_VALUE	resource was `NULL` or invalid (didn't point to any resource data of this file).
B_ERROR	An error occurred while removing the resource.
B_FILE_ERROR	A file error occurred.
B_NOT_ALLOWED	The 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

type	The type of the resource to remove.
id	The ID of the resource to remove.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_BAD_VALUE	No such resource was found.
B_ERROR	An error occurred while removing the resource.
B_FILE_ERROR	A file error occurred.
B_NOT_ALLOWED	The 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

file	The file to initialize the BResources object from.
clobber	If `true`, the data of the file are erased.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_BAD_VALUE	file was `NULL` or uninitialized.
B_ERROR	Failed 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

path	A path referring to the file to create a BResource object from.
clobber	If `true`, the data of the file are erased.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_BAD_VALUE	path was `NULL`.
B_ENTRY_NOT_FOUND	The file referenced by path couldn't be found.
B_ERROR	Failed 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

ref	An entry_ref referring to the file to create a BResource object from.
clobber	If `true`, the data of the file are erased.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_BAD_VALUE	ref was `NULL`.
B_ENTRY_NOT_FOUND	The file referenced by ref couldn't be found.
B_ERROR	Failed to initialize the object.

Since: Haiku R1

◆ SetToImage() [1/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

codeOrDataPointer	Pointer to the text or data segment of the image.
clobber	If `true`, the data of the file are erased.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_BAD_VALUE	codeOrDataPointer was `NULL`.
B_ENTRY_NOT_FOUND	The image or the file couldn't be found.
B_ERROR	Failed to initialize the object.

Since: Haiku R1

◆ SetToImage() [2/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

image	ID of a loaded image.
clobber	If `true`, the data of the file are erased.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_ENTRY_NOT_FOUND	The file referenced by image couldn't be found.
B_ERROR	Failed 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_OK	Everything went fine.
B_BAD_FILE	The resource map is empty???
B_FILE_ERROR	A file error occurred.
B_IO_ERROR	An error occurred while writing the resources.
B_NOT_ALLOWED	The 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

type	The type of the resource to write data to.
id	The ID of the resource to write data to.
data	The data to be written.
offset	The byte offset relative to the beginning of the resource at which the data shall be written.
length	The size of the data to be written.

Returns: A status code.

Return values

B_OK	Everything went fine.
B_BAD_VALUE	data was `NULL` or type and id did not identify an existing resource.
B_ERROR	Error writing data.
B_NO_MEMORY	Not 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

file	The file that the resources shall be written to.

Returns: B_OK if everything went fine or an error code otherwise.

Since: BeOS R4

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BResources() [1/4]

◆ BResources() [2/4]

◆ BResources() [3/4]

◆ BResources() [4/4]

◆ ~BResources()

Member Function Documentation

◆ AddResource()

◆ File()

◆ FindResource() [1/2]

◆ FindResource() [2/2]

◆ GetResourceInfo() [1/5]

◆ GetResourceInfo() [2/5]

◆ GetResourceInfo() [3/5]

◆ GetResourceInfo() [4/5]

◆ GetResourceInfo() [5/5]

◆ HasResource() [1/2]

◆ HasResource() [2/2]

◆ InitCheck()

◆ LoadResource() [1/2]

◆ LoadResource() [2/2]

◆ MergeFrom()

◆ PreloadResourceType()

◆ ReadResource()

◆ RemoveResource() [1/2]

◆ RemoveResource() [2/2]

◆ SetTo() [1/3]

◆ SetTo() [2/3]

◆ SetTo() [3/3]

◆ SetToImage() [1/2]

◆ SetToImage() [2/2]

◆ Sync()

◆ Unset()

◆ WriteResource()

◆ WriteTo()