Helper class for reading/writing resources embedded in executables and DLL's.
More...
|
| | Resources (SeekableIO *pcStream) |
| | Construct an os::Resources object from a seekable data stream. More...
|
| |
| | Resources (int nImageID) |
| | Construct a os::Resources from a executable or DLL image ID. More...
|
| |
| | Resources (SeekableIO *pcStream, off_t nResOffset, bool bCreate=false) |
| | Construct a os::Resources object from a seekable data stream. More...
|
| |
| | ~Resources () |
| |
| void | DetachStream () |
| | Detach the data-stream to avoid it being deleted by the constructor. More...
|
| |
| int | GetResourceCount () const |
| | Get the number of resources embedded in this archive. More...
|
| |
| String | GetResourceName (uint nIndex) const |
| | Get the name of a specified resource. More...
|
| |
| String | GetResourceType (uint nIndex) const |
| | Get the mime-type of a specified resource. More...
|
| |
| ssize_t | GetResourceSize (uint nIndex) const |
| | Get the size of a specified resource. More...
|
| |
| ssize_t | ReadResource (const String &cResName, void *pBuffer, String *pzResType, ssize_t nSize) |
| | Read data from a named resource. More...
|
| |
| ResStream * | GetResourceStream (const String &cName) |
| | Get a seekable-data stream referencing a resource's data. More...
|
| |
| ResStream * | GetResourceStream (uint nIndex) |
| | Get a seekable-data stream referencing a resource's data. More...
|
| |
| ResStream * | CreateResource (const String &cName, const String &cType, ssize_t nSize) |
| | Create a new resource. More...
|
| |
| 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. More...
|
| |
- 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 (kurt@.nosp@m.athe.nosp@m.os.cx)
| Enumerator |
|---|
| RES_MAGIC |
|
| RES_VERSION |
|
- 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 (kurt@.nosp@m.athe.nosp@m.os.cx)
References os::StreamableIO::Read().
| 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 (kurt@.nosp@m.athe.nosp@m.os.cx)
| 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 (kurt@.nosp@m.athe.nosp@m.os.cx)
| Resources::~Resources |
( |
| ) |
|
- 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 (kurt@.nosp@m.athe.nosp@m.os.cx)
References os::String::c_str(), ResourceDesc::m_cName, ResourceDesc::m_cType, ResourceDesc::m_nFileOffset, ResourceDesc::m_nHeaderSize, ResourceDesc::m_nSize, and os::String::size().
| 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 (kurt@.nosp@m.athe.nosp@m.os.cx)
| 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 (kurt@.nosp@m.athe.nosp@m.os.cx)
References os::StreamableIO::Read(), os::SeekableIO::ReadPos(), and os::SeekableIO::Seek().
| 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 (kurt@.nosp@m.athe.nosp@m.os.cx)
| String Resources::GetResourceName |
( |
uint |
nIndex | ) |
const |
| ssize_t Resources::GetResourceSize |
( |
uint |
nIndex | ) |
const |
| ResStream * Resources::GetResourceStream |
( |
uint |
nIndex | ) |
|
| String Resources::GetResourceType |
( |
uint |
nIndex | ) |
const |
| 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 (kurt@.nosp@m.athe.nosp@m.os.cx)
References os::ResStream::GetType(), and os::ResStream::Read().
