home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 177.lha / DRes_v1.3 / src / res.c < prev    next >
Encoding:
C/C++ Source or Header  |  1988-04-28  |  7.9 KB  |  258 lines
  1.  
  2. /*
  3.  *  RES.C
  4.  *
  5.  *  System Overview:
  6.  *    GetRes()            -
  7.  *    DupRes()            -
  8.  *    FreeRes()           -
  9.  *    FreeAllRes()        -
  10.  *    ChownRes()          -
  11.  *    UnLinkAllRes()      -
  12.  *    ReLinkAllRes()      -
  13.  *    SetResFlags()       -
  14.  *    AddRes()            -
  15.  *    RemRes()            -
  16.  *    GetResInfo()        -
  17.  *    GetResList()        -
  18.  *    GetFileList()       -
  19.  *    AddPrivResFile()    -
  20.  *    RemPrivResFiles()   -
  21.  *    AddGlobResFile()    -
  22.  *    RemGlobResFiles()   -
  23.  *    AddResSwapDir()     -
  24.  *    RemResSwapDirs()    -
  25.  *
  26.  */
  27.  
  28. #include <local/typedefs.h>
  29. #include <local/ipc.h>
  30. #include <local/res.h>
  31. #include "/src/ires.h"
  32.  
  33. static long SysLock[2] = { 0, 0 };
  34.  
  35. extern TML *GetTML();
  36.  
  37. /*
  38.  *  Search order:   Private-mem, Private-disk, System-mem, System-disk,
  39.  *            OtherTaskGlob-mem, OtherTaskGlob-disk
  40.  */
  41.  
  42. APTR
  43. GetRes(name)
  44. char *name;
  45. {
  46.     TML *tml = GetTML();
  47.  
  48.  
  49.  
  50.  
  51.     resptr= GetRes(resnametype)             char *resnametype;
  52.  
  53.     This function retrieves the requested resource, doing any
  54.     translations required to get the resource into the requested
  55.     type.  NULL is returned if the resource could not be found
  56.     or could not be translated to the requested type.
  57.  
  58.     In-Memory private resources are searched first, then the private
  59.     resource files for the task, then In-Memory system resources, then
  60.     the global resource files for the system.  Openning an already-open
  61.     resource causes one of two actions depending on whether the resource
  62.     is shared or not.  If shared, the reference count is simply
  63.     incremented, otherwise a private copy of the resource is made.
  64.  
  65.     Example:    Win = GetRes("Charlie.Window");
  66.  
  67.     resptr2 = DupRes(resptr1)               APTR resptr1, resptr2;
  68.  
  69.     This call duplicates a resource.  If the resource is shared
  70.     resptr2 will be the same as resptr1 and the reference count will
  71.     be bumped.  Otherwise, a new resource data area is allocated and
  72.     the old copied to the new.
  73.  
  74.     Things like fixing pointers and such within a resource that is
  75.     physically duplicated are handled by the interface code (since
  76.     raw resources do not contain pointers, only VIRTUAL resources
  77.     will contain pointers and all VIRTUAL resources have some
  78.     interface code).
  79.  
  80.     error = FreeRes(resptr)
  81.  
  82.     Free a resource that you retrieved via GetRes().  Only the task
  83.     that owns the resource may free it (though several tasks may own
  84.     a resource through duplication and ownership changes).    1 is
  85.     returned on success, 0 on error.
  86.  
  87.     That is, if task #1 GetRes()'s the resource and duplicates it once,
  88.     then task #2 duplicates it once, task #1 must call FreeRes() twice
  89.     and task #2 must call FreeRes() once.  Ownership is strictly
  90.     tracked.
  91.  
  92.     numres= FreeAllRes(task)
  93.  
  94.     Free all resources associated with the specified task (NULL for
  95.     self).
  96.  
  97.     error = ChownRes(resptr, fromtask, totask)
  98.  
  99.     Change ownership of a resource from the source task to the
  100.     destination task.  The resource must be owned by the source
  101.     task or an error will occur (0 return value).  1 is returned
  102.     on success.  NULL may be specified for either or both tasks
  103.     and means the calling task.
  104.  
  105.     handle= UnLinkAllRes(task)
  106.  
  107.     Unlink all resources associated with the specified task (NULL
  108.     for self) and return a handle representing those resources.
  109.  
  110.     This is useful for shells and such to keep their resources from
  111.     getting removed by commands they run.  Combined with the NUNLINK
  112.     flag one can pass resources to a Command and keep the rest out of
  113.     reach.
  114.  
  115.     (void)  ReLinkAllRes(handle, task)
  116.  
  117.     Link all the resources represented by the handle to the specified
  118.     task (NULL for self).
  119.  
  120.     oldfl = SetResFlags(resptr, newflags, flagsmask)
  121.  
  122.     Modify the flags associated with a resource.  NOTE:  If multiple
  123.     references to a shared resource exist, all are modified.  Some
  124.     modifications may be disallowed by the system.    This call is
  125.     normally used to modify the LOCKED and SWAPABLE flags (note that
  126.     the SWAPABLE flag can be changed back and forth only for resource
  127.     which support it).
  128.  
  129.     error = AddRes(resnametype, flags, ptr, ctlcode);
  130.                             char *resnametype;
  131.                             long flags;
  132.                             APTR ptr;
  133.                             long (*ctlcode)();
  134.  
  135.     Add a resource to the system.  The resource is placed either in
  136.     the task's privately accessable in-memory resource list or
  137.     in the system global accessable in-memory resource list depending
  138.     on the specified flags.  One may now GetRes() the resource.
  139.  
  140.     ONLY VIRTUAL RESOURCES MAY BE ADDED IN THIS WAY.  The VIRTUAL
  141.     and LOCKED flags are automatically set.
  142.  
  143.     If flags specifies a VIRTUAL resource
  144.  
  145.     error = RemRes(resname)
  146.  
  147.     Remove the specified resource.    An error will occur and the resource
  148.     will not be removed (1) if it does not exist in memory, or (2) it
  149.     is currently being referenced.    (Note: the resource is removed even
  150.     if it is swapped or locked).
  151.  
  152.     error = GetResInfo(resname, &flags, &bytes)
  153.  
  154.     Get information on a resource.    Information may not exist for a
  155.     resource if it is not currently in memory and would have to be
  156.     translated to get to the right type.
  157.  
  158.     error = GetResList(wildcard, from, &av, &ac);
  159.  
  160.     from:    mask, bit 0  search private list
  161.               1  search system list
  162.               2  <not used>
  163.               3  search in-memory private list
  164.               4  search in-memory global list
  165.  
  166.     Return an ARGC/ARGV list of resource names.  Note that some names
  167.     might be duplicated if searching multiple lists.  Restricting the
  168.     search to in-memory lists give resources which are already in
  169.     memory (but might be swapped out or removed at any time for those
  170.     with no references)
  171.  
  172.                  RESOURCE FILES
  173.  
  174.     error = GetFileList(wildcard, from, &av, &ac);
  175.  
  176.     from:    mask, bit 0  search private list
  177.               1  search system list
  178.               2  search swap list
  179.  
  180.     Return an ARGC/ARGV list of the files which match the specified
  181.     wildcard from the private list, system list, or system swap dir
  182.     list (in which case you get directory names).  This list has been
  183.     allocated, and can be freed as follows:
  184.  
  185.         Loop through all entries for (i = 0; i < ac; ++i)
  186.                     FreeMem(av[i], strlen(av[i])+1);
  187.         Free the array itself:  FreeMem(av, sizeof(char *) * (ac+1));
  188.  
  189.     num   = AddPrivResFile(filename, pri)
  190.  
  191.     Add a file name to the list of resource files for this task.  These
  192.     are scanned before global files when a resource is requested.  All
  193.     files in the list are write protected (i.e. a shared lock is kept
  194.     for each file).  Thus, such files cannot be updated until removed
  195.     from the list.
  196.  
  197.     Can also be used to modify the priority of an existing file
  198.  
  199.     num   = RemPrivResFiles(wildcard)
  200.  
  201.     Remove zero or more file names from the list of resource files for
  202.     this task.  A wildcard pattern (* and ?) is accepted.
  203.  
  204.     Note for command processors:    commands you run might execute
  205.     this command for *.
  206.  
  207.     num   = AddGlobResFile(filename, pri)
  208.  
  209.     Same as AddPrivResFile() but applies to the system list, which is
  210.     searched last and by any requesting task.  Wildcard file names are
  211.     NOT accepted.  The file need not exist at this time, and references
  212.     to unmounted volumes are allowed.
  213.  
  214.     Can also be used to modify the priority of an existing entry
  215.  
  216.     num   = RemGlobResFiles(wildcard)
  217.  
  218.     Remove zero or more resource files from the global list.  Again,
  219.     a wildcard filename is accepted.
  220.  
  221.     num   = AddResSwapDir(dirname, pri, maxkbytes)      char *dirname;
  222.                             char pri;
  223.                             long maxkbytes
  224.  
  225.     Add a directory to the list of directories the resource system
  226.     can swap to.  The maximum number of KBytes of material allowed
  227.     in the directory should be specified.  You can also use this
  228.     call to modify the priority and maxkbytes for an entry.
  229.  
  230.     The highest priority directories are used before lower priority
  231.     directories.  Not all directories need be mounted, but if a swapin
  232.     occurs from an unmounted directory a requester will appear.
  233.  
  234.     A lock is kept on each specified directory.
  235.  
  236.     num   = RemResSwapDirs(wildcard)
  237.  
  238.     Remove directories associated with the resource swap areas.
  239.  
  240.  
  241.                 RESOURCE FILE IFF FORMAT
  242.  
  243.  
  244.  
  245.  
  246. static
  247. TML *
  248. GetTML()
  249. {
  250.     TML *tml = GetTaskData(RESMLNAME, sizeof(TML));
  251.     if (tml && !tml->RFList.mlh_Head) {
  252.     NewList(&tml->RENList);
  253.     NewList(&tml->RFList);
  254.     }
  255.     return(tml);
  256. }
  257.  
  258.