home *** CD-ROM | disk | FTP | other *** search
/ CLIX - Fazer Clix Custa Nix / CLIX-CD.cdr / mac / lib / Mac / Resources.xs < prev    next >
Text File  |  1998-04-05  |  24KB  |  878 lines
  1. /* $Header: /home/neeri/MacCVS/MacPerl/perl/ext/Mac/Resources/Resources.xs,v 1.2 1997/11/18 00:53:19 neeri Exp $
  2.  *
  3.  *    Copyright (c) 1996 Matthias Neeracher
  4.  *
  5.  *    You may distribute under the terms of the Perl Artistic License,
  6.  *    as specified in the README file.
  7.  *
  8.  * $Log: Resources.xs,v $
  9.  * Revision 1.2  1997/11/18 00:53:19  neeri
  10.  * MacPerl 5.1.5
  11.  *
  12.  * Revision 1.1  1997/04/07 20:50:41  neeri
  13.  * Synchronized with MacPerl 5.1.4a1
  14.  *
  15.  */
  16.  
  17. #define MAC_CONTEXT
  18.  
  19. #include "EXTERN.h"
  20. #include "perl.h"
  21. #include "XSUB.h"
  22. #include <Types.h>
  23. #include <Memory.h>
  24. #include <Resources.h>
  25.  
  26. #define ResErrorReturn  \
  27.     if (gLastMacOSErr = ResError()) {   \
  28.         XSRETURN_UNDEF;                     \
  29.     } else {                            \
  30.         XSRETURN_YES;                       \
  31.     }
  32.  
  33. #define ResErrorCheck                       \
  34.     if (gLastMacOSErr = ResError()) {   \
  35.         XSRETURN_UNDEF;                     \
  36.     } else 0    
  37.  
  38. #define ResErrorCheckRetval             \
  39.     if (RETVAL == -1) {                     \
  40.         gLastMacOSErr = ResError();     \
  41.         XSRETURN_UNDEF;                     \
  42.     } else 0
  43.  
  44. #define ResErrorCheckRetvalNULL         \
  45.     if (!RETVAL) {                              \
  46.         gLastMacOSErr = ResError();     \
  47.         XSRETURN_UNDEF;                     \
  48.     } else 0
  49.  
  50. MODULE = Mac::Resources PACKAGE = Mac::Resources
  51.  
  52. =head2 Functions
  53.  
  54. =over 4
  55.  
  56. =item CloseResFile RFD
  57.  
  58. Given a file reference number for a file whose resource fork is open, the
  59. CloseResFile procedure performs four tasks. First, it updates the file by calling
  60. the &UpdateResFile procedure. Second, it releases the memory occupied by each
  61. resource in the resource fork by calling the &DisposeHandle procedure. Third, it
  62. releases the memory occupied by the resource map. The fourth task is to close the
  63. resource fork.
  64.  
  65. =cut
  66. void
  67. CloseResFile(refNum)
  68.     short   refNum
  69.  
  70. =item CurResFile
  71.  
  72. The CurResFile function returns the file reference number associated with the
  73. current resource file. You can call this function when your application starts up
  74. (before opening the resource fork of any other file) to get the file reference
  75. number of your application's resource fork.
  76.  
  77.     $RFD = CurResFile;
  78.  
  79. =cut
  80. short
  81. CurResFile()
  82.  
  83. =item HomeResFile RESOURCE
  84.  
  85. Given a handle to a resource, the HomeResFile function returns the file reference
  86. number for the resource fork containing the specified resource. If the given
  87. handle isn't a handle to a resource, HomeResFile returns –1, and the &ResError
  88. function returns the result code resNotFound. If HomeResFile returns 0, the
  89. resource is in the System file's resource fork. If HomeResFile returns 1, the
  90. resource is ROM-resident.
  91.  
  92.     $RFD = HomeResFile($Resource);
  93.  
  94. =cut
  95. short
  96. HomeResFile(theResource)
  97.     Handle  theResource
  98.     CLEANUP:
  99.     ResErrorCheckRetval;
  100.  
  101. =item CreateResFile NAME
  102.  
  103. The CreateResFile procedure creates an empty resource file.
  104.  
  105.     if ( CreateResFile("Resource.rsrc")) {
  106.         # error occurred
  107.     } else {
  108.         # proceed
  109.     }
  110.  
  111. =cut
  112. void
  113. CreateResFile(fileName)
  114.     Str255  fileName
  115.     CLEANUP:
  116.     ResErrorReturn;
  117.  
  118. =item OpenResFile NAME
  119.  
  120. The OpenResFile function opens an existing resource file. It also makes this file
  121. the current resource file.
  122.  
  123.     if ( defined($RFD = OpenResFile("Resource.rsrc")) ) {
  124.         # proceed
  125.     } else {
  126.         # error occurred
  127.     }
  128.  
  129. =cut
  130. short
  131. OpenResFile(fileName)
  132.     Str255  fileName
  133.     CLEANUP:
  134.     ResErrorCheckRetval;
  135.  
  136. =item UseResFile RFD
  137.  
  138. The UseResFile procedure searches the list of files whose resource forks have
  139. been opened for the file specified by the RFD parameter. If the specified file
  140. is found, the Resource Manager sets the current resource file to the specified
  141. file. If there's no resource fork open for a file with that reference number,
  142. UseResFile does nothing. To set the current resource file to the System file, use
  143. 0 for the refNum parameter.
  144.  
  145.     if (UseResFile($RFD)) {
  146.         # error occurred
  147.     } else {
  148.         # proceed
  149.     }
  150.  
  151. =cut
  152. void
  153. UseResFile(refNum)
  154.     short   refNum
  155.     CLEANUP:
  156.     ResErrorReturn;
  157.  
  158.  
  159. =item CountTypes
  160.  
  161. =item Count1Types
  162.  
  163. The CountTypes (Count1Types) function reads the resource maps in memory for all resource forks
  164. (the current resource fork) open to your application. It returns an integer representing the 
  165. total number of unique resource types.
  166.  
  167.     $types = Count1Types;
  168.  
  169. =cut
  170. short
  171. CountTypes()
  172.  
  173. short
  174. Count1Types()
  175.  
  176. =item GetIndType INDEX
  177.  
  178. =item Get1IndType INDEX
  179.  
  180. Given an index number from 1 to the number of resource types in all resource
  181. forks (the current resource fork)
  182. open to your application (as returned by CountTypes), the GetIndType
  183. procedure returns a resource type. You can call
  184. GetIndType repeatedly over the entire range of the index to get all the resource
  185. types available in all resource forks open to your application. If the given
  186. index isn't in the range from 1 to the number of resource types as returned by
  187. CountTypes, undef() is returned.
  188.  
  189.     # Load up @resourceTypes with the types from the current file.
  190.     for (1 .. Count1Types) {
  191.         $resourceTypes[$_-1] = Get1IndType($_);
  192.     }
  193.  
  194. =cut
  195. OSType
  196. GetIndType(index)
  197.     short   index
  198.     CODE:
  199.     GetIndType(&RETVAL, index);
  200.     OUTPUT:
  201.     RETVAL
  202.     CLEANUP:
  203.     ResErrorCheckRetvalNULL;
  204.  
  205. OSType
  206. Get1IndType(index)
  207.     short   index
  208.     CODE:
  209.     Get1IndType(&RETVAL, index);
  210.     OUTPUT:
  211.     RETVAL
  212.     CLEANUP:
  213.     ResErrorCheckRetvalNULL;
  214.  
  215. =item SetResLoad BOOL
  216.  
  217. Enable and disable automatic loading of resource data into memory for routines
  218. that return handles to resources.
  219.  
  220. =cut
  221. void
  222. SetResLoad(load)
  223.     Boolean load
  224.  
  225. =item CountResources TYPE
  226.  
  227. =item Count1Resources TYPE
  228.  
  229. Get the total number of available resources of a given type. Count1Resources
  230. looks only at the current resource fork.
  231.  
  232.     $totalDialogsAvailable = CountResources "DITL";
  233.  
  234. =cut
  235. short
  236. CountResources(theType)
  237.     OSType  theType
  238.  
  239. short
  240. Count1Resources(theType)
  241.     OSType  theType
  242.  
  243. =item GetIndResource TYPE, INDEX
  244.  
  245. =item Get1IndResource TYPE, INDEX
  246.  
  247. Given an index ranging from 1 to the number of resources of a given type returned
  248. by &CountResources (&Count1Resources) (that is, the number of resources of that type 
  249. in all resource forks open to your application), the GetIndResource function returns a 
  250. handle to a resource of the given type. If you call GetIndResource repeatedly over the
  251. entire range of the index, it returns handles to all resources of the given type
  252. in all resource forks open to your application.
  253.  
  254.     # Load up handles of this type of resource
  255.     for (1 .. CountResources("DITL")) {
  256.         $dialogs[$_] = GetIndResource("DITL", $_);
  257.     }
  258.  
  259. =cut
  260. Handle
  261. GetIndResource(theType, index)
  262.     OSType  theType
  263.     short   index
  264.     CLEANUP:
  265.     ResErrorCheckRetvalNULL;
  266.  
  267. Handle
  268. Get1IndResource(theType, index)
  269.     OSType  theType
  270.     short   index
  271.     CLEANUP:
  272.     ResErrorCheckRetvalNULL;
  273.  
  274. =item GetResource TYPE, ID
  275.  
  276. =item Get1Resource TYPE, ID
  277.  
  278. Get resource data for a resource specified by resource type and resource ID.
  279.  
  280.     $SFGdialog = GetResource("DITL", 6042);
  281.     if ( defined $SFGdialog ) {
  282.         # proceed
  283.     }
  284.  
  285. =cut
  286. Handle
  287. GetResource(theType, theID)
  288.     OSType  theType
  289.     short   theID
  290.     CLEANUP:
  291.     ResErrorCheckRetvalNULL;
  292.  
  293. Handle
  294. Get1Resource(theType, theID)
  295.     OSType  theType
  296.     short   theID
  297.     CLEANUP:
  298.     ResErrorCheckRetvalNULL;
  299.  
  300. =item GetNamedResource TYPE, NAME
  301.  
  302. =item Get1NamedResource TYPE, NAME
  303.  
  304. The GetNamedResource (Get1NamedResource) function searches the resource maps in memory for the
  305. resource specified by the parameters $TYPE and $NAME.
  306.  
  307.     $SFGdialog = GetNamedResource("DITL", "Standard Get");
  308.     if ( defined $SFGdialog ) {
  309.         # proceed
  310.     }
  311.  
  312. =cut
  313. Handle
  314. GetNamedResource(theType, name)
  315.     OSType  theType
  316.     Str255  name
  317.     CLEANUP:
  318.     ResErrorCheckRetvalNULL;
  319.  
  320. Handle
  321. Get1NamedResource(theType, name)
  322.     OSType  theType
  323.     Str255  name
  324.     CLEANUP:
  325.     ResErrorCheckRetvalNULL;
  326.  
  327. =item LoadResource HANDLE
  328.  
  329. Given a handle to a resource, LoadResource reads the resource data into memory.
  330. If the HANDLE parameter doesn't contain a handle to a resource, then LoadResource
  331. returns undef.
  332.  
  333.     if (LoadResource($HANDLE) ) {
  334.         # proceed
  335.     } else {
  336.         # error occurred
  337.     }
  338.  
  339. =cut
  340. void
  341. LoadResource(theResource)
  342.     Handle  theResource
  343.     CLEANUP:
  344.     ResErrorReturn;
  345.  
  346. =item ReleaseResource HANDLE
  347.  
  348. Given a handle to a resource, ReleaseResource releases the memory occupied by the
  349. resource data, if any, and sets the master pointer of the resource's handle in
  350. the resource map in memory to NIL. If your application previously obtained a
  351. handle to that resource, the handle is no longer valid. If your application
  352. subsequently calls the Resource Manager to get the released resource, the
  353. Resource Manager assigns a new handle. 
  354.  
  355.     if ( ReleaseResource($HANDLE) ) {
  356.         # proceed
  357.     } else {
  358.         # error occurred
  359.     }
  360.  
  361. =cut
  362. void
  363. ReleaseResource(theResource)
  364.     Handle  theResource
  365.     CLEANUP:
  366.     ResErrorReturn;
  367.  
  368. =item DetachResource HANDLE
  369.  
  370. Given a handle to a resource, ReleaseResource releases the memory occupied by the
  371. resource data, if any, and sets the master pointer of the resource's handle in
  372. the resource map in memory to NIL. If your application previously obtained a
  373. handle to that resource, the handle is no longer valid. If your application
  374. subsequently calls the Resource Manager to get the released resource, the
  375. Resource Manager assigns a new handle. 
  376.  
  377.     if ( DetachResource($HANDLE) ) {
  378.         # proceed
  379.     } else {
  380.         # error occurred
  381.     }
  382.  
  383. =cut
  384. void
  385. DetachResource(theResource)
  386.     Handle  theResource
  387.     CLEANUP:
  388.     ResErrorReturn;
  389.  
  390. =item UniqueID TYPE
  391.  
  392. =item Unique1ID TYPE
  393.  
  394. The UniqueID function returns as its function result a resource ID greater than 0
  395. that isn't currently assigned to any resource of the specified type in any open
  396. resource fork. You should use this function before adding a new resource to
  397. ensure that you don't duplicate a resource ID and override an existing resource.
  398. Unique1ID ensures uniqueness within the current resource fork.
  399.  
  400.     $id = Unique1ID("DITL");
  401.  
  402. =cut
  403. short
  404. UniqueID(theType)
  405.     OSType  theType
  406.  
  407. short
  408. Unique1ID(theType)
  409.     OSType  theType
  410.  
  411.  
  412. =item GetResAttrs HANDLE
  413.  
  414. Given a handle to a resource, the GetResAttrs function returns the resource's
  415. attributes as recorded in its entry in the resource map in memory. If the value
  416. of the theResource parameter isn't a handle to a valid resource, undef is returned.
  417.  
  418.     $resAttrs = GetResAttrs($HANDLE);
  419.     if ( defined $resAttrs ) {
  420.         # proceed
  421.     }
  422.  
  423. =cut
  424. short
  425. GetResAttrs(theResource)
  426.     Handle  theResource
  427.     CLEANUP:
  428.     ResErrorCheck;
  429.  
  430. =item GetResInfo HANDLE
  431.  
  432. Given a handle to a resource, the GetResInfo procedure returns the resource's
  433. resource ID, resource type, and resource name. If the handle isn't a valid handle
  434. to a resource, undef is returned.
  435.  
  436.     ($id, $type, $name) = GetResInfo($HANDLE);
  437.     if ( defined $id ) {
  438.         # proceed
  439.     }
  440.  
  441. =cut
  442. void
  443. GetResInfo(theResource)
  444.     Handle  theResource
  445.     PPCODE:
  446.     {
  447.         short       theID;
  448.         OSType  theType;
  449.         Str255  name;
  450.         
  451.         GetResInfo(theResource, &theID, &theType, name);
  452.         ResErrorCheck;
  453.  
  454.         EXTEND(sp, 3);
  455.         XS_PUSH(short, theID);
  456.         XS_PUSH(OSType, theType);
  457.         if (*name)
  458.             XS_PUSH(Str255, name);
  459.     }
  460.  
  461. =item SetResInfo HANDLE, ID, NAME
  462.  
  463. Given a handle to a resource, SetResInfo changes the resource ID and the resource
  464. name of the specified resource to the values given in ID and NAME. If you pass
  465. an empty string for the name parameter, the resource name is not changed.
  466.  
  467. =cut
  468. void
  469. SetResInfo(theResource, theID, name)
  470.     Handle  theResource
  471.     short   theID
  472.     Str255  name
  473.     CLEANUP:
  474.     ResErrorReturn;
  475.  
  476. =item AddResource HANDLE, TYPE, ID, NAME
  477.  
  478. Given a handle to any type of data in memory (but not a handle to an existing
  479. resource), AddResource adds the given handle, resource type, resource ID, and
  480. resource name to the current resource file's resource map in memory. The
  481. AddResource procedure sets the resChanged attribute to 1; it does not set any of
  482. the resource's other attributes—that is, all other attributes are set to 0.
  483.  
  484. =cut
  485. void
  486. AddResource(theData, theType, theID, name)
  487.     Handle  theData
  488.     OSType  theType
  489.     short   theID
  490.     Str255  name
  491.     CLEANUP:
  492.     ResErrorReturn;
  493.  
  494. =item GetResourceSizeOnDisk HANDLE
  495.  
  496. Given a handle to a resource, the GetResourceSizeOnDisk function checks the
  497. resource on disk (not in memory) and returns its exact size, in bytes. If the
  498. handle isn't a handle to a valid resource, undef is returned.
  499.  
  500.     $size = GetResourceSizeOnDisk($HANDLE);
  501.     if ( defined $size ) {
  502.         # proceed
  503.     }
  504.  
  505. =cut
  506. long
  507. GetResourceSizeOnDisk(theResource)
  508.     Handle  theResource
  509.     CLEANUP:
  510.     ResErrorCheckRetval;
  511.  
  512. =item GetMaxResourceSize HANDLE
  513.  
  514. Like &GetResourceSizeOnDisk, GetMaxResourceSize takes a handle and returns the
  515. size of the corresponding resource. However, GetMaxResourceSize does not check
  516. the resource on disk; instead, it either checks the resource size in memory or,
  517. if the resource is not in memory, calculates its size, in bytes, on the basis of
  518. information in the resource map in memory. This gives you an approximate size for
  519. the resource that you can count on as the resource's maximum size. It's possible
  520. that the resource is actually smaller than the offsets in the resource map
  521. indicate because the file has not yet been compacted. If you want the exact size
  522. of a resource on disk, either call &GetResourceSizeOnDisk or call &UpdateResFile
  523. before calling GetMaxResourceSize.
  524.  
  525.     $size = GetMaxResourceSize($HANDLE);
  526.     if ( defined $size ) {
  527.         # proceed
  528.     }
  529.  
  530. =cut
  531. long
  532. GetMaxResourceSize(theResource)
  533.     Handle  theResource
  534.     CLEANUP:
  535.     ResErrorCheckRetval;
  536.  
  537. =item RsrcMapEntry HANDLE
  538.  
  539. Given a handle to a resource, RsrcMapEntry returns the offset of the specified
  540. resource's entry from the beginning of the resource map in memory. If it doesn't
  541. find the resource entry, RsrcMapEntry returns 0, and the ResError function
  542. returns the result code resNotFound. If you pass a handle whose value is NIL,
  543. RsrcMapEntry returns arbitrary data. 
  544.  
  545.     $offset = RsrcMapEntry($HANDLE);
  546.     if ( defined $offset ) {
  547.         # proceed
  548.     }
  549.  
  550. =cut
  551. long
  552. RsrcMapEntry(theResource)
  553.     Handle  theResource
  554.     CLEANUP:
  555.     ResErrorCheckRetvalNULL;
  556.  
  557. =item SetResAttrs HANDLE, ATTRS
  558.  
  559. Given a handle to a resource, SetResAttrs changes the resource attributes of the
  560. resource to those specified in the attrs parameter. The SetResAttrs procedure
  561. changes the information in the resource map in memory, not in the file on disk.
  562. The resProtected attribute changes immediately. Other attribute changes take
  563. effect the next time the specified resource is read into memory but are not made
  564. permanent until the Resource Manager updates the resource fork.
  565.  
  566.     if ( SetResAttrs($HANDLE, $ATTRS) ) {
  567.         # proceed
  568.     } else {
  569.         # error
  570.     }
  571.  
  572. =cut
  573. void
  574. SetResAttrs(theResource, attrs)
  575.     Handle  theResource
  576.     short   attrs
  577.     CLEANUP:
  578.     ResErrorReturn;
  579.  
  580. =item ChangedResource HANDLE
  581.  
  582. Given a handle to a resource, the ChangedResource procedure sets the resChanged
  583. attribute for that resource in the resource map in memory. If the resChanged
  584. attribute for a resource has been set and your application calls &UpdateResFile or
  585. quits, the Resource Manager writes the resource data for that resource (and for
  586. all other resources whose resChanged attribute is set) and the entire resource
  587. map to the resource fork of the corresponding file on disk. If the resChanged
  588. attribute for a resource has been set and your application calls &WriteResource,
  589. the Resource Manager writes only the resource data for that resource to disk.
  590.  
  591.     if ( ChangedResource($HANDLE) ) {
  592.         # proceed
  593.     } else {
  594.         # error
  595.     }
  596.  
  597. =cut
  598. void
  599. ChangedResource(theResource)
  600.     Handle  theResource
  601.     CLEANUP:
  602.     ResErrorReturn;
  603.  
  604. =item RemoveResource HANDLE
  605.  
  606. Given a handle to a resource in the current resource file, RemoveResource removes
  607. the resource entry (resource type, resource ID, resource name, if any, and
  608. resource attributes) from the current resource file's resource map in memory. 
  609.  
  610.     if ( RemoveResource($HANDLE) ) {
  611.         # proceed
  612.     } else {
  613.         # error
  614.     }
  615.  
  616. =cut
  617. void
  618. RemoveResource(theResource)
  619.     Handle  theResource
  620.     CLEANUP:
  621.     ResErrorReturn;
  622.  
  623. =item UpdateResFile RFD
  624.  
  625. Given the reference number of a file whose resource fork is open, UpdateResFile
  626. performs three tasks. The first task is to change, add, or remove resource data
  627. in the file's resource fork to match the resource map in memory. Changed resource
  628. data for each resource is written only if that resource's resChanged bit has been
  629. set by a successful call to &ChangedResource or &AddResource. The UpdateResFile
  630. procedure calls the &WriteResource procedure to write changed or added resources
  631. to the resource fork.
  632.  
  633.     if ( UpdateResFile($RFD) ) {
  634.         # proceed
  635.     } else {
  636.         # error
  637.     }
  638.  
  639. =cut
  640. void
  641. UpdateResFile(refNum)
  642.     short   refNum
  643.     CLEANUP:
  644.     ResErrorReturn;
  645.  
  646. =item WriteResource HANDLE
  647.  
  648. Given a handle to a resource, WriteResource checks the resChanged attribute of
  649. that resource. If the resChanged attribute is set to 1 (after a successful call
  650. to the &ChangedResource or &AddResource procedure), WriteResource writes the
  651. resource data in memory to the resource fork, then clears the resChanged
  652. attribute in the resource's resource map in memory.
  653.  
  654.     if ( WriteResource($HANDLE) ) {
  655.         # proceed
  656.     } else {
  657.         # error
  658.     }
  659.  
  660. =cut
  661. void
  662. WriteResource(theResource)
  663.     Handle  theResource
  664.     CLEANUP:
  665.     ResErrorReturn;
  666.  
  667. =item SetResPurge INSTALL
  668.  
  669. Specify TRUE in the install parameter to make the Memory Manager pass the handle
  670. for a resource to the Resource Manager before purging the resource data to which
  671. the handle points. The Resource Manager determines whether the handle points to a
  672. resource in the application heap. It also checks if the resource's resChanged
  673. attribute is set to 1. If these two conditions are met, the Resource Manager
  674. calls the &WriteResource procedure to write the resource's resource data to the
  675. resource fork before returning control to the Memory Manager.
  676.  
  677. Specify FALSE in the install parameter to restore the normal state, so that the
  678. Memory Manager purges resource data when it needs to without calling the Resource
  679. Manager.
  680.  
  681.     if ( SetResPurge(1) ) {
  682.         # proceed
  683.     } else {
  684.         # error
  685.     }
  686.  
  687. =cut
  688. void
  689. SetResPurge(install)
  690.     Boolean install
  691.     CLEANUP:
  692.     ResErrorReturn;
  693.  
  694. =item GetResFileAttrs RFD
  695.  
  696. Given a file reference number, the GetResFileAttrs function returns the
  697. attributes of the file's resource fork. Specify 0 in $RFD to get
  698. the attributes of the System file's resource fork. If there's no open resource
  699. fork for the given file reference number, undef is returned.
  700.  
  701.     $rfa = GetResFileAttrs($RFD);
  702.     if ( defined $rfa ) {
  703.         # proceed
  704.     }
  705.  
  706. =cut
  707. short
  708. GetResFileAttrs(refNum)
  709.     short   refNum
  710.     CLEANUP:
  711.     ResErrorCheck;
  712.  
  713. =item SetResFileAttrs RFD, ATTRS
  714.  
  715. Given a file reference number, the SetResFileAttrs procedure sets the attributes
  716. of the file's resource fork to those specified in the attrs parameter. If the
  717. refNum parameter is 0, it represents the System file's resource fork. However,
  718. you shouldn't change the attributes of the System file's resource fork. If
  719. there's no resource fork with the given reference number, SetResFileAttrs does
  720. nothing, and the ResError function returns the result code noErr.
  721.  
  722.     if ( SetResFileAttrs($RFD, $ATTRS) ) {
  723.         # proceed
  724.     } else {
  725.         # error
  726.     }
  727.  
  728. =cut
  729. void
  730. SetResFileAttrs(refNum, attrs)
  731.     short   refNum
  732.     short   attrs
  733.     CLEANUP:
  734.     ResErrorReturn;
  735.  
  736. =item RGetResource TYPE, ID
  737.  
  738. The RGetResource function searches the resource maps in memory for the resource
  739. specified by the parameters $TYPE and $ID. The resource maps in memory, which
  740. represent all open resource forks, are arranged as a linked list. The
  741. RGetResource function first uses GetResource to search this list. The GetResource
  742. function starts with the current resource file and progresses through the list in
  743. order (that is, in reverse chronological order in which the resource forks were
  744. opened) until it finds the resource's entry in one of the resource maps. If
  745. GetResource doesn't find the specified resource in its search of the resource
  746. maps of open resource forks (which includes the System file's resource fork),
  747. RGetResource sets the global variable RomMapInsert to TRUE, then calls
  748. GetResource again. In response, GetResource performs the same search, but this
  749. time it looks in the resource map of the ROM-resident resources before searching
  750. the resource map of the System file. 
  751.  
  752.     $handle = RGetResource("DITL", 6042);
  753.     if ( defined $handle ) {
  754.         # proceed
  755.     }
  756.  
  757. =cut
  758. Handle
  759. RGetResource(theType, theID)
  760.     OSType  theType
  761.     short   theID
  762.     CLEANUP:
  763.     ResErrorCheckRetvalNULL;
  764.  
  765. =item FSpOpenResFile SPEC, PERMISSION
  766.  
  767. The FSpOpenResFile function opens the resource fork of the file identified by the
  768. spec parameter. It also makes this file the current resource file.
  769.  
  770.     $sp = FSpOpenResFile($SPEC);
  771.     if ( defined $sp ) {
  772.         # proceed
  773.     }
  774.  
  775. In addition to opening the resource fork for the file with the specified name,
  776. FSpOpenResFile lets you specify in the permission parameter the read/write permission
  777. of the resource fork the first time it is opened. 
  778.  
  779. =cut
  780. short
  781. FSpOpenResFile(spec, permission)
  782.     FSSpec  &spec
  783.     SInt8   permission
  784.     CLEANUP:
  785.     ResErrorCheckRetval;
  786.  
  787. =item FSpCreateResFile SPEC, CREATOR, FILETYPE, SCRIPTTAG
  788.  
  789. The FSpCreateResFile procedure creates an empty resource fork for a file with the
  790. specified $FILETYPE, $CREATOR, and $SCRIPTTAG in the location and with the name
  791. designated by the spec parameter. (An empty resource fork contains no resource
  792. data but does include a resource map.) 
  793.  
  794.     if ( FSpCreateResFile($SPEC, $CREATOR, $FILETYPE, $SCRIPTTAG) ) {
  795.         # proceed
  796.     } else {
  797.         # error
  798.     }
  799.  
  800. =cut
  801. void
  802. FSpCreateResFile(spec, creator, fileType, scriptTag)
  803.     FSSpec      &spec
  804.     OSType      creator
  805.     OSType      fileType
  806.     SInt8           scriptTag
  807.     CLEANUP:
  808.     ResErrorReturn;
  809.  
  810. =item ReadPartialResource HANDLE, OFFSET, BYTECOUNT
  811.  
  812. The ReadPartialResource procedure reads the resource subsection identified by the
  813. theResource, offset, and count parameters.
  814.  
  815.    $data = ReadPartialResource($rsrc, 2000, 256);
  816.  
  817. =cut
  818. SV *
  819. ReadPartialResource(theResource, offset, count)
  820.     Handle  theResource
  821.     long    offset
  822.     long    count
  823.     CODE:
  824.     RETVAL = newSV(count);
  825.     ReadPartialResource(theResource, offset, SvPV(RETVAL, na), count);
  826.     ResErrorCheck;
  827.     OUTPUT:
  828.     RETVAL
  829.  
  830. =item WritePartialResource HANDLE, OFFSET, DATA
  831.  
  832. The WritePartialResource procedure writes the data specified by DATA 
  833. to the resource subsection identified by the HANDLE and OFFSET parameters.
  834.  
  835.     if ( WritePartialResource($HANDLE, $OFFSET, $DATA) ) {
  836.         # proceed
  837.     } else {
  838.         # error
  839.     }
  840.  
  841. =cut
  842. void
  843. WritePartialResource(theResource, offset, data)
  844.     Handle  theResource
  845.     long    offset
  846.     SV *    data
  847.     CODE: 
  848.     {
  849.         STRLEN  count;
  850.         void *  buffer = SvPV(data, count);
  851.         WritePartialResource(theResource, offset, buffer, count);
  852.         ResErrorReturn;
  853.     }
  854.  
  855. =item SetResourceSize HANDLE, SIZE
  856.  
  857. Given a handle to a resource, SetResourceSize sets the size field of the
  858. specified resource on disk without writing the resource data. You can change the
  859. size of any resource, regardless of the amount of memory you have available.
  860.  
  861.     if ( SetResource($HANDLE, $SIZE) ) {
  862.         # proceed
  863.     } else {
  864.         # error
  865.     }
  866.  
  867. =cut
  868. void
  869. SetResourceSize(theResource, newSize)
  870.     Handle  theResource
  871.     long    newSize
  872.     CLEANUP:
  873.     ResErrorReturn;
  874.  
  875. =back
  876.  
  877. =cut
  878.