home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 177.lha / DRes_v1.3 / docs / res.doc < prev    next >
Text File  |  1988-04-28  |  13KB  |  325 lines
  1.  
  2.  
  3.                   RESOURCE.DOC
  4.  
  5.            AMIGA RESOURCES AS IMPLEMENTED BY DRES.LIBRARY
  6.  
  7.     The first order of business is to avoid some confusion.  The Amiga
  8.     already has resources .... EXEC resources, which are used mainly to
  9.     arbitrate low level hardware.  The resources I am talking about is an
  10.     object oriented system and has nothing to do with EXEC resources.  All
  11.     references to 'resources' in this document refer to this object
  12.     oriented system.
  13.  
  14.     What is a resources?  A resource is a means of accessing one or more
  15.     objects through a generalized interface with as much flexibility as
  16.     possible.  A specific object in this system has certain capabilities
  17.     and is referenced by a pointer to something.  For instance, an
  18.     intuition Window could be a resource.  Each and every resource in the
  19.     system may be flagged as follows (any combination of flags):
  20.  
  21.     SHARABLE    -   Multiple references to the resource are allowed.  If not
  22.             sharable, duplication of a resource results in two
  23.             distinct resources with different data areas rather
  24.             than two pointers to a shared data area.
  25.  
  26.             Duplication of non-sharable resources via DupRes()
  27.             results in a copy of that resource's data including any
  28.             changes made to that data.    GetRes()ing it results in
  29.             a pristine copy.
  30.  
  31.             Duplication of a shareable resource returns the common
  32.             data area whether you DupRes() it or GetRes() it.
  33.  
  34.     GLOBAL    -   A global resource can be accessed by any task in the
  35.             system.  NOTE:  Private resources can still be
  36.             sharable, but only by a DupRes() call or a GetRes()
  37.             call from a task's private resource list.
  38.  
  39.             Also, any resources tagged as GLOBAL in a task's private
  40.             resource list are immediately accessable to other tasks
  41.             via GetRes().  Searching other task's private lists for
  42.             global resources is always done last.
  43.  
  44.     VIRTUAL    -   A virtual resource is one that has been algorithmically
  45.             generated.    Most resources are virtual resources.  For
  46.             example, an intuition Window would be a virtual resource.
  47.  
  48.             Non virtual resources are the 'raw' resources on disk.
  49.             For instance, a "_List" resource would be a raw resource
  50.             but when you GetRes(name, "List") note that obviously
  51.             some conversion code is required to go from "_List" to
  52.             "List", in this case the code initializes the list
  53.             pointers.
  54.  
  55.             Most of the time, the existance of one or more
  56.             algorithms (subroutines) to generate a resource is
  57.             completely transparent to the routine requesting the
  58.             resource.  Using the above example, the task requesting
  59.             the resource simply asks for a "List" and is oblivious
  60.             to what actually must be performed to give him that
  61.             List.
  62.  
  63.     SWAPABLE    -   While not being referenced (all references fall to 0),
  64.             rather than delete the resource, it should be swapped to
  65.             disk (read: any filesystem device) and then swapped
  66.             back in when accessed.  This does not mean a resource
  67.             is automatically swapped when references fall to 0,
  68.             just that it *might* be swapped.
  69.  
  70.             This only applies to SHARABLE resources, as you cannot
  71.             DupRes() a non-shared resource when the references fall
  72.             to 0 (nothing to dup), and GetRes() returns a pristine
  73.             copy.
  74.  
  75.             SHARABLE resources on the otherhand are assumed to be
  76.             of a more permanent nature.  As in the LOCKED flag
  77.             below, this flag guarentees the resource will not become
  78.             pristine on the next reference after previous usage.
  79.  
  80.     LOCKED    -   While not being referenced, rather than delete or swap
  81.             the resource, it should stay in memory.  This only
  82.             applies to SHARABLE resources.
  83.  
  84.  
  85.             RESOURCE NAMES AND ALGORITHMIC GENERATION
  86.  
  87.     The identification of a resource consists of two parts.  (1) The name
  88.     of the resource, and (2) the structure of the resource.  The name of
  89.     the resource is arbitrary while the structure of the resource is some
  90.     agreed upon standard.  The two parts are stuck together with an
  91.     intervening period like so:
  92.  
  93.         CHArlIE.Window
  94.  
  95.     For the above example, we have a resource named 'CHArlIE' of structure
  96.     'Window'... an intuition window pointer would be the result of
  97.     accessing this particular resource.  However, it is not possible to
  98.     store a Window structure on disk verbatim since there are lots of
  99.     pointers and other dependancies with intuition.  On disk, the resource
  100.     might actually be:
  101.  
  102.         CHArlIE.NewWindow
  103.  
  104.     But we want a Window structure... if the program requests
  105.     CHArlIE.Window there must be some means of algorithmically translating
  106.     a NewWindow to a Window.  These algorithms are provided by yet a
  107.     third resource named:
  108.  
  109.         NewWindow.Window.CODE
  110.  
  111.     The name is 'NewWindow.Window' and the type is 'CODE'.  This resource
  112.     is a procedure which translates a NewWindow to a Window by calling
  113.     OpenWindow().  The translation procedure is recursive, thus allowing
  114.     any manner of 'patching' for reasons given above, for maintaining
  115.     compatibility with older structures, and for convenience.
  116.  
  117.     Finally, a resource is owned by a specific task.  One can pass
  118.     resources around but it must be done with cooperation from the
  119.     library.
  120.  
  121.     CODE resources are discussed later on.  Now that you have an idea how
  122.     resources work, we shall discuss the library calls currently available:
  123.  
  124.  
  125.  
  126.                RESOURCE LIBRARY CALLS
  127.  
  128.     Beginning with the easiest of the calls and ending with the more
  129.     difficult.    NOTE: Resource names are limited to 31 characters,
  130.     Resource types are limited to 31 characters.
  131.  
  132.     resptr= GetRes(resnametype)             char *resnametype;
  133.  
  134.     This function retrieves the requested resource, doing any
  135.     translations required to get the resource into the requested
  136.     type.  NULL is returned if the resource could not be found
  137.     or could not be translated to the requested type.
  138.  
  139.     In-Memory private resources are searched first, then the private
  140.     resource files for the task, then In-Memory system resources, then
  141.     the global resource files for the system.  Openning an already-open
  142.     resource causes one of two actions depending on whether the resource
  143.     is shared or not.  If shared, the reference count is simply
  144.     incremented, otherwise a private copy of the resource is made.
  145.  
  146.     Example:    Win = GetRes("Charlie.Window");
  147.  
  148.     resptr2 = DupRes(resptr1)               APTR resptr1, resptr2;
  149.  
  150.     This call duplicates a resource.  If the resource is shared
  151.     resptr2 will be the same as resptr1 and the reference count will
  152.     be bumped.  Otherwise, a new resource data area is allocated and
  153.     the old copied to the new.
  154.  
  155.     Things like fixing pointers and such within a resource that is
  156.     physically duplicated are handled by the interface code (since
  157.     raw resources do not contain pointers, only VIRTUAL resources
  158.     will contain pointers and all VIRTUAL resources have some
  159.     interface code).
  160.  
  161.     error = FreeRes(resptr)
  162.  
  163.     Free a resource that you retrieved via GetRes().  Only the task
  164.     that owns the resource may free it (though several tasks may own
  165.     a resource through duplication and ownership changes).    1 is
  166.     returned on success, 0 on error.
  167.  
  168.     That is, if task #1 GetRes()'s the resource and duplicates it once,
  169.     then task #2 duplicates it once, task #1 must call FreeRes() twice
  170.     and task #2 must call FreeRes() once.  Ownership is strictly
  171.     tracked.
  172.  
  173.     numres= FreeAllRes(task)
  174.  
  175.     Free all resources associated with the specified task (NULL for
  176.     self).
  177.  
  178.     error = ChownRes(resptr, fromtask, totask)
  179.  
  180.     Change ownership of a resource from the source task to the
  181.     destination task.  The resource must be owned by the source
  182.     task or an error will occur (0 return value).  1 is returned
  183.     on success.  NULL may be specified for either or both tasks
  184.     and means the calling task.
  185.  
  186.     handle= UnLinkAllRes(task)
  187.  
  188.     Unlink all resources associated with the specified task (NULL
  189.     for self) and return a handle representing those resources.
  190.  
  191.     This is useful for shells and such to keep their resources from
  192.     getting removed by commands they run.  Combined with the NUNLINK
  193.     flag one can pass resources to a Command and keep the rest out of
  194.     reach.
  195.  
  196.     (void)  ReLinkAllRes(handle, task)
  197.  
  198.     Link all the resources represented by the handle to the specified
  199.     task (NULL for self).
  200.  
  201.     oldfl = SetResFlags(resptr, newflags, flagsmask)
  202.  
  203.     Modify the flags associated with a resource.  NOTE:  If multiple
  204.     references to a shared resource exist, all are modified.  Some
  205.     modifications may be disallowed by the system.    This call is
  206.     normally used to modify the LOCKED and SWAPABLE flags (note that
  207.     the SWAPABLE flag can be changed back and forth only for resource
  208.     which support it).
  209.  
  210.     error = AddRes(resnametype, flags, ptr, ctlcode);
  211.                             char *resnametype;
  212.                             long flags;
  213.                             APTR ptr;
  214.                             long (*ctlcode)();
  215.  
  216.     Add a resource to the system.  The resource is placed either in
  217.     the task's privately accessable in-memory resource list or
  218.     in the system global accessable in-memory resource list depending
  219.     on the specified flags.  One may now GetRes() the resource.
  220.  
  221.     ONLY VIRTUAL RESOURCES MAY BE ADDED IN THIS WAY.  The VIRTUAL
  222.     and LOCKED flags are automatically set.
  223.  
  224.     If flags specifies a VIRTUAL resource
  225.  
  226.     error = RemRes(resname)
  227.  
  228.     Remove the specified resource.    An error will occur and the resource
  229.     will not be removed (1) if it does not exist in memory, or (2) it
  230.     is currently being referenced.    (Note: the resource is removed even
  231.     if it is swapped or locked).
  232.  
  233.     error = GetResInfo(resname, &flags, &bytes)
  234.  
  235.     Get information on a resource.    Information may not exist for a
  236.     resource if it is not currently in memory and would have to be
  237.     translated to get to the right type.
  238.  
  239.     error = GetResList(wildcard, from, &av, &ac);
  240.  
  241.     from:    mask, bit 0  search private list
  242.               1  search system list
  243.               2  <not used>
  244.               3  search in-memory private list
  245.               4  search in-memory global list
  246.  
  247.     Return an ARGC/ARGV list of resource names.  Note that some names
  248.     might be duplicated if searching multiple lists.  Restricting the
  249.     search to in-memory lists give resources which are already in
  250.     memory (but might be swapped out or removed at any time for those
  251.     with no references)
  252.  
  253.                  RESOURCE FILES
  254.  
  255.     error = GetFileList(wildcard, from, &av, &ac);
  256.  
  257.     from:    mask, bit 0  search private list
  258.               1  search system list
  259.               2  search swap list
  260.  
  261.     Return an ARGC/ARGV list of the files which match the specified
  262.     wildcard from the private list, system list, or system swap dir
  263.     list (in which case you get directory names).  This list has been
  264.     allocated, and can be freed as follows:
  265.  
  266.         Loop through all entries for (i = 0; i < ac; ++i)
  267.                     FreeMem(av[i], strlen(av[i])+1);
  268.         Free the array itself:  FreeMem(av, sizeof(char *) * (ac+1));
  269.  
  270.     num   = AddPrivResFile(filename, pri)
  271.  
  272.     Add a file name to the list of resource files for this task.  These
  273.     are scanned before global files when a resource is requested.  All
  274.     files in the list are write protected (i.e. a shared lock is kept
  275.     for each file).  Thus, such files cannot be updated until removed
  276.     from the list.
  277.  
  278.     Can also be used to modify the priority of an existing file
  279.  
  280.     num   = RemPrivResFiles(wildcard)
  281.  
  282.     Remove zero or more file names from the list of resource files for
  283.     this task.  A wildcard pattern (* and ?) is accepted.
  284.  
  285.     Note for command processors:    commands you run might execute
  286.     this command for *.
  287.  
  288.     num   = AddGlobResFile(filename, pri)
  289.  
  290.     Same as AddPrivResFile() but applies to the system list, which is
  291.     searched last and by any requesting task.  Wildcard file names are
  292.     NOT accepted.  The file need not exist at this time, and references
  293.     to unmounted volumes are allowed.
  294.  
  295.     Can also be used to modify the priority of an existing entry
  296.  
  297.     num   = RemGlobResFiles(wildcard)
  298.  
  299.     Remove zero or more resource files from the global list.  Again,
  300.     a wildcard filename is accepted.
  301.  
  302.     num   = AddResSwapDir(dirname, pri, maxkbytes)      char *dirname;
  303.                             char pri;
  304.                             long maxkbytes
  305.  
  306.     Add a directory to the list of directories the resource system
  307.     can swap to.  The maximum number of KBytes of material allowed
  308.     in the directory should be specified.  You can also use this
  309.     call to modify the priority and maxkbytes for an entry.
  310.  
  311.     The highest priority directories are used before lower priority
  312.     directories.  Not all directories need be mounted, but if a swapin
  313.     occurs from an unmounted directory a requester will appear.
  314.  
  315.     A lock is kept on each specified directory.
  316.  
  317.     num   = RemResSwapDirs(wildcard)
  318.  
  319.     Remove directories associated with the resource swap areas.
  320.  
  321.  
  322.                 RESOURCE FILE IFF FORMAT
  323.  
  324.  
  325.