PA_GetResourceHandle

version 2003

PA_GetResourceHandle (resfile; kind; resID) PA_Handle

Parameter	Type		Description
resfile	short		File reference number of the file to access
kind	unsigned long		Kind (4 Bytes type) of resource to load
resID	short		Unique resource ID
Function result	PA_Handle		Handle to the resource data. 0 if resource not found

The routine PA_GetResourceHandle returns a handle to the resource of type kind and the ID resID in the file resFile.

Pass in resFile the file reference number of the file that holds the resource.

Pass in kind the 4-Bytes type code of the resource (such as 'PICT', 'TEXT', or anything you need) and in resID its unique ID in the file.

The handle belongs to 4th Dimension. Never modify it until you call PA_DetachResource (which makes the resource a standard PA_Handle that belongs to the plug-in).

Using PA_GetResourceHandle instead of PA_GetResource permits the plug-in to use less memory, especially for large resources and/or if the plug-in need to read-only the resource.

If the resource does not exist or if resFile is an invalid file reference number, the routine returns 0L, and PA_GetLastError returns -5 ("Resource not found").

Loading and reading a preference resource.

   typedef struct
   {
      short   defaultFontSize;
      short   defaultFontFace;
      long   defaultColor;
      unsigned long   lastCount;
   } Plug_Prefs, *Plug_PrefsPtr, **Plug_PrefsHdle;

   #define kPLUGIN_PREFS   'pipf'
         #define kPREFS_ID   0;

   // To read the preference, use:
   Plug_Prefs   prefs;
   /* . . . */
   prefs =(Plug_PrefsHdle) PA_GetResourceHandle(resFile, kPLUGIN_PREFS, kPREFS_ID);
   if(prefs)
   {
   /* do something with (*prefs)->defaultXXX . . . */
   // NEVER DISPOSE THIS HANDLE UNLESS YOU CALL DETACH RESOURCE
   }

PA_DetachResource, PA_GetIndexedResource, PA_GetResource.

Use PA_GetLastError to see if an error occurred