home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Frozen Fish 1: Amiga
/
FrozenFish-Apr94.iso
/
bbs
/
alib
/
d1xx
/
d168
/
dillonstuff.lha
/
doc
/
dres
/
res.doc
< prev
next >
Wrap
Text File
|
1988-11-22
|
13KB
|
325 lines
RESOURCE.DOC
AMIGA RESOURCES AS IMPLEMENTED BY DRES.LIBRARY
The first order of business is to avoid some confusion. The Amiga
already has resources .... EXEC resources, which are used mainly to
arbitrate low level hardware. The resources I am talking about is an
object oriented system and has nothing to do with EXEC resources. All
references to 'resources' in this document refer to this object
oriented system.
What is a resources? A resource is a means of accessing one or more
objects through a generalized interface with as much flexibility as
possible. A specific object in this system has certain capabilities
and is referenced by a pointer to something. For instance, an
intuition Window could be a resource. Each and every resource in the
system may be flagged as follows (any combination of flags):
SHARABLE - Multiple references to the resource are allowed. If not
sharable, duplication of a resource results in two
distinct resources with different data areas rather
than two pointers to a shared data area.
Duplication of non-sharable resources via DupRes()
results in a copy of that resource's data including any
changes made to that data. GetRes()ing it results in
a pristine copy.
Duplication of a shareable resource returns the common
data area whether you DupRes() it or GetRes() it.
GLOBAL - A global resource can be accessed by any task in the
system. NOTE: Private resources can still be
sharable, but only by a DupRes() call or a GetRes()
call from a task's private resource list.
Also, any resources tagged as GLOBAL in a task's private
resource list are immediately accessable to other tasks
via GetRes(). Searching other task's private lists for
global resources is always done last.
VIRTUAL - A virtual resource is one that has been algorithmically
generated. Most resources are virtual resources. For
example, an intuition Window would be a virtual resource.
Non virtual resources are the 'raw' resources on disk.
For instance, a "_List" resource would be a raw resource
but when you GetRes(name, "List") note that obviously
some conversion code is required to go from "_List" to
"List", in this case the code initializes the list
pointers.
Most of the time, the existance of one or more
algorithms (subroutines) to generate a resource is
completely transparent to the routine requesting the
resource. Using the above example, the task requesting
the resource simply asks for a "List" and is oblivious
to what actually must be performed to give him that
List.
SWAPABLE - While not being referenced (all references fall to 0),
rather than delete the resource, it should be swapped to
disk (read: any filesystem device) and then swapped
back in when accessed. This does not mean a resource
is automatically swapped when references fall to 0,
just that it *might* be swapped.
This only applies to SHARABLE resources, as you cannot
DupRes() a non-shared resource when the references fall
to 0 (nothing to dup), and GetRes() returns a pristine
copy.
SHARABLE resources on the otherhand are assumed to be
of a more permanent nature. As in the LOCKED flag
below, this flag guarentees the resource will not become
pristine on the next reference after previous usage.
LOCKED - While not being referenced, rather than delete or swap
the resource, it should stay in memory. This only
applies to SHARABLE resources.
RESOURCE NAMES AND ALGORITHMIC GENERATION
The identification of a resource consists of two parts. (1) The name
of the resource, and (2) the structure of the resource. The name of
the resource is arbitrary while the structure of the resource is some
agreed upon standard. The two parts are stuck together with an
intervening period like so:
CHArlIE.Window
For the above example, we have a resource named 'CHArlIE' of structure
'Window'... an intuition window pointer would be the result of
accessing this particular resource. However, it is not possible to
store a Window structure on disk verbatim since there are lots of
pointers and other dependancies with intuition. On disk, the resource
might actually be:
CHArlIE.NewWindow
But we want a Window structure... if the program requests
CHArlIE.Window there must be some means of algorithmically translating
a NewWindow to a Window. These algorithms are provided by yet a
third resource named:
NewWindow.Window.CODE
The name is 'NewWindow.Window' and the type is 'CODE'. This resource
is a procedure which translates a NewWindow to a Window by calling
OpenWindow(). The translation procedure is recursive, thus allowing
any manner of 'patching' for reasons given above, for maintaining
compatibility with older structures, and for convenience.
Finally, a resource is owned by a specific task. One can pass
resources around but it must be done with cooperation from the
library.
CODE resources are discussed later on. Now that you have an idea how
resources work, we shall discuss the library calls currently available:
RESOURCE LIBRARY CALLS
Beginning with the easiest of the calls and ending with the more
difficult. NOTE: Resource names are limited to 31 characters,
Resource types are limited to 31 characters.
resptr= GetRes(resnametype) char *resnametype;
This function retrieves the requested resource, doing any
translations required to get the resource into the requested
type. NULL is returned if the resource could not be found
or could not be translated to the requested type.
In-Memory private resources are searched first, then the private
resource files for the task, then In-Memory system resources, then
the global resource files for the system. Openning an already-open
resource causes one of two actions depending on whether the resource
is shared or not. If shared, the reference count is simply
incremented, otherwise a private copy of the resource is made.
Example: Win = GetRes("Charlie.Window");
resptr2 = DupRes(resptr1) APTR resptr1, resptr2;
This call duplicates a resource. If the resource is shared
resptr2 will be the same as resptr1 and the reference count will
be bumped. Otherwise, a new resource data area is allocated and
the old copied to the new.
Things like fixing pointers and such within a resource that is
physically duplicated are handled by the interface code (since
raw resources do not contain pointers, only VIRTUAL resources
will contain pointers and all VIRTUAL resources have some
interface code).
error = FreeRes(resptr)
Free a resource that you retrieved via GetRes(). Only the task
that owns the resource may free it (though several tasks may own
a resource through duplication and ownership changes). 1 is
returned on success, 0 on error.
That is, if task #1 GetRes()'s the resource and duplicates it once,
then task #2 duplicates it once, task #1 must call FreeRes() twice
and task #2 must call FreeRes() once. Ownership is strictly
tracked.
numres= FreeAllRes(task)
Free all resources associated with the specified task (NULL for
self).
error = ChownRes(resptr, fromtask, totask)
Change ownership of a resource from the source task to the
destination task. The resource must be owned by the source
task or an error will occur (0 return value). 1 is returned
on success. NULL may be specified for either or both tasks
and means the calling task.
handle= UnLinkAllRes(task)
Unlink all resources associated with the specified task (NULL
for self) and return a handle representing those resources.
This is useful for shells and such to keep their resources from
getting removed by commands they run. Combined with the NUNLINK
flag one can pass resources to a Command and keep the rest out of
reach.
(void) ReLinkAllRes(handle, task)
Link all the resources represented by the handle to the specified
task (NULL for self).
oldfl = SetResFlags(resptr, newflags, flagsmask)
Modify the flags associated with a resource. NOTE: If multiple
references to a shared resource exist, all are modified. Some
modifications may be disallowed by the system. This call is
normally used to modify the LOCKED and SWAPABLE flags (note that
the SWAPABLE flag can be changed back and forth only for resource
which support it).
error = AddRes(resnametype, flags, ptr, ctlcode);
char *resnametype;
long flags;
APTR ptr;
long (*ctlcode)();
Add a resource to the system. The resource is placed either in
the task's privately accessable in-memory resource list or
in the system global accessable in-memory resource list depending
on the specified flags. One may now GetRes() the resource.
ONLY VIRTUAL RESOURCES MAY BE ADDED IN THIS WAY. The VIRTUAL
and LOCKED flags are automatically set.
If flags specifies a VIRTUAL resource
error = RemRes(resname)
Remove the specified resource. An error will occur and the resource
will not be removed (1) if it does not exist in memory, or (2) it
is currently being referenced. (Note: the resource is removed even
if it is swapped or locked).
error = GetResInfo(resname, &flags, &bytes)
Get information on a resource. Information may not exist for a
resource if it is not currently in memory and would have to be
translated to get to the right type.
error = GetResList(wildcard, from, &av, &ac);
from: mask, bit 0 search private list
1 search system list
2 <not used>
3 search in-memory private list
4 search in-memory global list
Return an ARGC/ARGV list of resource names. Note that some names
might be duplicated if searching multiple lists. Restricting the
search to in-memory lists give resources which are already in
memory (but might be swapped out or removed at any time for those
with no references)
RESOURCE FILES
error = GetFileList(wildcard, from, &av, &ac);
from: mask, bit 0 search private list
1 search system list
2 search swap list
Return an ARGC/ARGV list of the files which match the specified
wildcard from the private list, system list, or system swap dir
list (in which case you get directory names). This list has been
allocated, and can be freed as follows:
Loop through all entries for (i = 0; i < ac; ++i)
FreeMem(av[i], strlen(av[i])+1);
Free the array itself: FreeMem(av, sizeof(char *) * (ac+1));
num = AddPrivResFile(filename, pri)
Add a file name to the list of resource files for this task. These
are scanned before global files when a resource is requested. All
files in the list are write protected (i.e. a shared lock is kept
for each file). Thus, such files cannot be updated until removed
from the list.
Can also be used to modify the priority of an existing file
num = RemPrivResFiles(wildcard)
Remove zero or more file names from the list of resource files for
this task. A wildcard pattern (* and ?) is accepted.
Note for command processors: commands you run might execute
this command for *.
num = AddGlobResFile(filename, pri)
Same as AddPrivResFile() but applies to the system list, which is
searched last and by any requesting task. Wildcard file names are
NOT accepted. The file need not exist at this time, and references
to unmounted volumes are allowed.
Can also be used to modify the priority of an existing entry
num = RemGlobResFiles(wildcard)
Remove zero or more resource files from the global list. Again,
a wildcard filename is accepted.
num = AddResSwapDir(dirname, pri, maxkbytes) char *dirname;
char pri;
long maxkbytes
Add a directory to the list of directories the resource system
can swap to. The maximum number of KBytes of material allowed
in the directory should be specified. You can also use this
call to modify the priority and maxkbytes for an entry.
The highest priority directories are used before lower priority
directories. Not all directories need be mounted, but if a swapin
occurs from an unmounted directory a requester will appear.
A lock is kept on each specified directory.
num = RemResSwapDirs(wildcard)
Remove directories associated with the resource swap areas.
RESOURCE FILE IFF FORMAT