os::Resources Class Reference
[Various utillity classes.]

Helper class for reading/writing resources embedded in executables and DLL's. More...

List of all members.

Public Types
enum	{   RES_MAGIC = 0x3020c49b,   RES_VERSION = 1 }
Public Member Functions
	Resources (SeekableIO *pcStream)
	Construct an os::Resources object from a seekable data stream.
	Resources (int nImageID)
	Construct a os::Resources from a executable or DLL image ID.
	Resources (SeekableIO *pcStream, off_t nResOffset, bool bCreate=false)
	Construct a os::Resources object from a seekable data stream.
	~Resources ()
void	DetachStream ()
	Detach the data-stream to avoid it being deleted by the constructor.
int	GetResourceCount () const
	Get the number of resources embedded in this archive.
String	GetResourceName (uint nIndex) const
	Get the name of a specified resource.
String	GetResourceType (uint nIndex) const
	Get the mime-type of a specified resource.
ssize_t	GetResourceSize (uint nIndex) const
	Get the size of a specified resource.
ssize_t	ReadResource (const String &cResName, void *pBuffer, String *pzResType, ssize_t nSize)
	Read data from a named resource.
ResStream *	GetResourceStream (const String &cName)
	Get a seekable-data stream referencing a resource's data.
ResStream *	GetResourceStream (uint nIndex)
	Get a seekable-data stream referencing a resource's data.
ResStream *	CreateResource (const String &cName, const String &cType, ssize_t nSize)
	Create a new resource.
status_t	FindExecutableResource (SeekableIO *pcStream, off_t *pnOffset, ssize_t *pnSize, const char *pzSectionName=NULL)
	Locate the resource section in an AtheOS executable or DLL.
Classes
class	Private

---

Detailed Description

Description:

Many applications will need external resources like bitmaps, icons, text, or other data that is not includeded in the executable by the compiler or linker. Such resources can be stored in separate files inside the application directory but it is often convinient to collect them inside the application executable iteself to avoid having a large amount of small files floating around. Also if a DLL need external resources it can be hard for the DLL to locate external resource files.

It is therefor often more convinient to add the resources to the executable or DLL with the "rescopy" utility and then use this class to load them at runtime. A os::Resources object can be initialized from a regular data-stream or from a image-ID. The executable and all the DLL's loaded by a process is assigned individual image-ID's. This ID's can be obtained by a global function named get_image_id(). The get_image_id() function will return different ID's depending on what DLL or executable the calling function lives in and can therefor be used by a DLL or executable to learn what image it should use when loading it's resources.

The os::Resources class can be used to read resources directly from the resource section of an executable or from a dedicated resource archive. It can also be used to write resources into a resource archive but it can not embed the archive into an executable.

Resources within a archive is identified by uniqueue names and each resource have a mime-type that can be used by to specify what kind of data is contained by the resource. The mime-type is not used by os::Resources itself but can be useful when manipulating the resources with external applications.

Since:

0.3.7

See also:

ResStream

Author:

Kurt Skauen ([email protected])

---

Member Enumeration Documentation

anonymous enum

Enumerator:

RES_MAGIC
RES_VERSION

---

Constructor & Destructor Documentation

Resources::Resources

(

SeekableIO *

pcFile

)

Description:

This constructor will initialize a read-only reasorce archive from the given data-stream. The stream must point to a plain resource file or an AtheOS executable/DLL image containing a resource section.

If any errors including invalid file-format/missing resource section an os::errno_exception will be thrown.

Note:

The pcFile object will be deleted by the os::Resources when the os::Resources object is deleted unless it is manually detached by calling the DetachStream() member.

Parameters:

pcFile

A readable stream referencing a valid resource archive or a valid AtheOS executable/DLL with a resource section.This stream will be deleted by the archive unless an exception is thrown from this constructor or it is detached from the archive with DetachStream().

Author:

Kurt Skauen ([email protected])

Resources::Resources

(

int

nImageID

)

Description:

This is normally the most convenient constructor to use when loading resources from the application's executable or from one of it's loaded DLL's. The constructor will obtain a file descriptor to the specified executable image using the open_image_file() syscall and then initiate the archive from this.

The ID to pass as nImageID can be obtained with the get_image_id() syscall. get_image_id() will return the image ID of the DLL or executable in which the calling function live.

If anything goes wrong an os::errno_exception exception will be thrown.

Parameters:

nImageID

A valid handle to a DLL or executable loaded by this process.

See also:

get_image_id(), open_image_file()

Author:

Kurt Skauen ([email protected])

Resources::Resources	(	SeekableIO *	pcFile,
		off_t	nResOffset,
		bool	bCreate = false
	)

Description:

This is the most flexible but least used constructor. It allow you to specify what position within the stream the resource archive lives and it can also initiate the archive for writing.

If the bCreate parameter is true a resource archive header will be written to the file and you can add resources to it with the CreateResource() member. All old resources will be deleted when creating an archive.

If anything goes wrong an os::errno_exception exception will be thrown.

Note:

The pcFile object will be deleted by the os::Resources when the os::Resources object is deleted unless it is manually detached by calling the DetachStream() member.

Parameters:

	pcFile	The stream to operate on. This can be an empty file if the bCreate argument is true. This stream will be deleted by the archive unless an exception is thrown from this constructor or it is detached from the archive with DetachStream().
	nResOffset	The file-position where the resource archive lives or where a new resource archive should be written.
	bCreate	If true a new archive header will be written at nResOffset and new resources can be added with CreateResource().

Author:

Kurt Skauen ([email protected])

Resources::~Resources

(

)

---

Member Function Documentation

void Resources::DetachStream

(

)

Description:

Normally the os::Resources object will delete the os::SeekableIO object passed in to any of the constructors when the object is deleted. If you don't want this to happen (for example because the stream-object is allocated on the stack) you must call DetachStream() before deleting the os::Resources object.

Note:

Calling any members on the os::Resources object or any of the os::ResStream objects spawned from it might still use the passed in data-stream so it is very important that you don't delete the stream yourself before you are done using the os::Resources object or any of it childrens even if you have detached the stream.

It is however safe to delete the os::Resources object after the stream so no precautions are needed to assure that the os::Resources object goes away after the os::SeekableIO in case they are both allocated on the stack. Just make sure to not call any other members after the stream is gone.

Author:

Kurt Skauen ([email protected])

int Resources::GetResourceCount

(

)

const

Description:

Get the number of resources embedded in this archive.

Returns:

Number of resources embedded in the archive.

Author:

Kurt Skauen ([email protected])

String Resources::GetResourceName

(

uint

nIndex

)

const

Description:

Get the name of a specified resource.

Parameters:

nIndex

Which resource to query.

Returns:

The name of the specified resource.

See also:

GetResourceType(), GetResourceSize(), GetResourceStream(), GetResourceCount()

Author:

Kurt Skauen ([email protected])

String Resources::GetResourceType

(

uint

nIndex

)

const

Description:

Get the mime-type of a specified resource.

Parameters:

nIndex

Which resource to query.

Returns:

The mime-type of the specified resource.

See also:

GetResourceName(), GetResourceSize(), GetResourceStream(), GetResourceCount()

Author:

Kurt Skauen ([email protected])

ssize_t Resources::GetResourceSize

(

uint

nIndex

)

const

Description:

Get the size of a specified resource.

Parameters:

nIndex

Which resource to query.

Returns:

The size in bytes of the specified resource.

See also:

GetResourceName(), GetResourceType(), GetResourceStream(), GetResourceCount()

Author:

Kurt Skauen ([email protected])

ssize_t Resources::ReadResource	(	const String &	cResName,
		void *	pBuffer,
		String *	pcResType,
		ssize_t	nSize
	)

Description:

Read date from a named resource. This is shortcut for calling GetResourceStream()/read from the stream/delete the stream. This can be convinient when the resource should be read only once and when the entire resource should be loaded in one read operation.

Note:

ReadResource() will always start at offset 0 in the stream so multiple reads will return the same data.

Parameters:

	cResName	The name of the resource to read.
	pBuffer	Pointer to a buffer that will receive at most nSize bytes of data. If only the mime-type is interresting this can be a NULL pointer.
	pcResType	Pointer to a STL string that will receive the mime-type of the resource or NULL if you don't want to receive the mime-type.
	nSize	The maximum number of bytes to read from the stream.

Returns:

The number of bytes actually read or -1 if an error occure. In the case of failure an error code will be written to the global variable errno.

See also:

GetResourceStream()

Author:

Kurt Skauen ([email protected])

ResStream * Resources::GetResourceStream

(

const String &

cName

)

Description:

Get a seekable data stream referencing the specified resource. The returned stream inherit from os::SeekableIO and can be used to read data from the resource.

Note:

It is your responsibility to delete the returned stream object when you are done using it. The returned stream will also reference it's parent os::Resources object so it is important that you don't use the stream after the os::Resources object that spawned it has been deleted.

Parameters:

cName

The name of the resource to lookup.

Returns:

A pointer to a os::ResStream object that can be used to read data from the resource and to obtain various other info like mime-type and size of the resource. If there was no resource with the given name or if something went wrong during creation of the stream object NULL will be returned and an error code will be written to the global variable errno.

See also:

GetResourceStream(uint), CreateResource(), ReadResource()

Author:

Kurt Skauen ([email protected])

ResStream * Resources::GetResourceStream

(

uint

nIndex

)

Description:

GetResourceStream(uint) have the same functionality as GetResourceStream(const String&) except that the resource is identified by an index instead of the resource name. This can be useful when for example iterating over all the resources in an archive. Look at GetResourceStream(const String&) for a more detailed description of the functionality.

Note:

It is your responsibility to delete the returned stream object when you are done using it. The returned stream will also reference it's parent os::Resources object so it is important that you don't use the stream after the os::Resources object that spawned it has been deleted.

Parameters:

nIndex

The index (between 0 and GetResourceCount() - 1) of the resource to obtain.

Returns:

Pointer to a os::ResStream object or NULL if the index was out of range or if something whent wrong during creation of the stream object.

See also:

GetResourceStream(const String&)

Author:

Kurt Skauen ([email protected])

ResStream * Resources::CreateResource	(	const String &	cName,
		const String &	cType,
		ssize_t	nSize
	)

Description:

Create a new resource and return a writable stream object referencing it. The name, size, and type must be specified and can not be changed later. Neither can the resource be deleted again without recreating the archive from scratch.

Note:

It is your responsibility to delete the returned stream object when you are done using it. The returned stream will also reference it's parent os::Resources object so it is important that you don't use the stream after the os::Resources object that spawned it has been deleted.

Parameters:

	cName	The name of the new resource. The name must be unique and can be at most 255 bytes long.
	cType	The mime-type of the stream. This is used to identify the data type that will be written to the stream. If the data don't have a mime-typed defined for it you should normally use "application/octet-stream". The mime-type must be at most 255 bytes long.
	nSize	The number of bytes that should be allocated for this resource.

Returns:

Pointer to a writable ResStream object if the resource was successfully created or NULL if something went wrong. In the case of failure an error code will be written to the global variable errno.

See also:

GetResourceStream()

Author:

Kurt Skauen ([email protected])

status_t Resources::FindExecutableResource	(	SeekableIO *	pcStream,
		off_t *	pnOffset,
		ssize_t *	pnSize,
		const char *	pzSectionName = NULL
	)

Description:

Locate the resource section in an AtheOS executable or DLL.

Note:

This member is normally only used internally by the os::Resources class itself but it is made public so you can call it if you should ever need it.

Parameters:

	pcStream	A seekable stream referencing an AtheOS executable or DLL.
	pnOffset	Pointer to an off_t variable that will receive the position of the first byte of the resource section within the executable. Can safely be passed as NULL if the offset is not interresting.
	pnSize	Pointer to an ssize_t variable that will receive the size of the resource section. Can safely be passed as NULL if the size is not interresting.
	pzSectionName	Should normally be passed as NULL (the default) but can optionally be used to specify the name of the section to be searched for.

Returns:

On success 0 is returned. On failure -1 is returned and an error code is written to the global variable errno.

Author:

Kurt Skauen ([email protected])

---