Index

Package: Resources

Description

package Resources is

Classes

Resource_File

type Resource_File is tagged limited private;

Primitive operations:

Get_Filename
Get_Packfile
Reference
Unreference
A Resource_File represents a resource file loaded in memory. The contents of the file can be accessed via various methods. Once a Resource_File is closed, its backing data should no longer be relied upon. If the file data is required after the Resource_File must be closed, a copy of the contents should be made. Resource files are cached to avoid the cost of searching and reading from disk each time file is needed but the details of the cache and how/when it is purged are private.

Tasks & Protected

Async_Operation (protected type)

Protected state object useful for asynchronously loading resources.

Types

A_Async_Operation

type A_Async_Operation is access all Async_Operation;

A_Resource_File

type A_Resource_File is access all Resource_File'Class;

Constants & Global variables

RESOURCE_ERROR

RESOURCE_ERROR,
    RESOURCE_FORMAT_ERROR : exception;

RESOURCE_FORMAT_ERROR

RESOURCE_FORMAT_ERROR : exception;

Subprograms & Entries

Async_Operation. Complete

procedure Complete;
Notifies the object that the operation is complete. This will free up all threads blocking on the Wait entry.

Async_Operation. Is_Complete

function Is_Complete return Boolean;
Checks the state of the operation without waiting for completion.

Async_Operation. Wait (abstract)

entry Wait;
Blocks the caller until the operation is complete.

Delete

procedure Delete
( op: in out A_Async_Operation );

Loading_Begins

procedure Loading_Begins;

Loading_Ends

procedure Loading_Ends;

Get_Address

function Get_Address
( this: access Resource_File ) return Address;
Returns the address of the resource file's data. The length of the data can be determined by calling Size.

Get_Filename

function Get_Filename
( this: access Resource_File ) return String;
Returns the filename of the resource.

Get_Id

function Get_Id
( this: access Resource_File ) return String;
Returns an identifying string comprised of the original filepath and group name used to find the resource.

Get_Packfile

function Get_Packfile
( this: access Resource_File ) return A_Packfile;
Returns a packfile reference to the resource. Be sure to close the packfile before unloading the resource.

Get_Stream

procedure Get_Stream
( this: access Resource_File;
strm: out A_Buffer_Stream );
Returns a new read-only stream backed by the resource contents. Be sure to close the stream before unloading the resource.

Size

function Size
( this: access Resource_File ) return Unsigned_32;
Returns the size of the file in bytes;

Load_Resource

function Load_Resource
( filepath: String;
group: String ) return A_Resource_File;
Searches for and loads a resource file, returning a reference to it. The search order for resources files is as follows: 1. filepath (If filepath is an absolute file path) 2. working_dir/filename 3. working_dir/group.zip/filename 4. media_dir/filename 5. media_dir/group.zip/filename (Where 'filename' is the filename taken from 'filepath'.) NULL will be returned if the file is not found or can't otherwise be accessed. Resource files are reference counted, so you must call Unload_Resource when finished with the Resource_File.

Unload_Resource

procedure Unload_Resource
( resource: in out A_Resource_File );
Unloads a resource file. Resource files are reference counted so be sure to call this when finished with a Resource_File.

Write_Path

function Write_Path
( filepath: String;
group: String ) return String;
Returns the location where a file can be written to overwrite an existing resource if possible or override an existing resource that is in an archive. The specified file will searched for with the same algorithm as Load_Resource. If the resource file is found and it's not in an archive, its absolute path will be returned. If the file was found in an archive or couldn't be found at all, then the returned path will point to a file of the same name in the executable directory.