PA_GetResource

version 2003

PA_GetResource (resfile; kind; resID; resData) → long

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
resData	char*	←	Data of the resource
Function result	long	←	Size of the received data in bytes

Description

The routine PA_GetResource loads the internal resource of type kind and ID resID (in the file referenced by resFile ), and fills the buffer pointed to by resData with its content. It then returns the size of the data in bytes.

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

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

In resData , pass a pointer to the block of memory that will be filled with the resource content.

The data pointed to by resData must be large enough to receive the resource content. The plug-in can get this size by calling the routine passing 0L in the resData parameter, or, more simply, it can call the PA_GetResourceSize routine.

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

NOTE


   
    resData

contains a copy of the resource; you can use it or dispose of it as you like. To get a handle to the resource, use


   
    PA_GetResourceHandle

. You can use less memory if you only want to read the resource.
Examples

(1) Wrapper of PA_GetResource.

   char * MyGetResource(short resFile, unsigned long kind, short ID)
   {
      char   *resData:
      long   size;
 
      resData = 0L;
      size = PA_GetResourceSize(resFile, kind, ID);
      if( size && !PA_GetLastError())
      {
         resData = malloc(size);
         if(resdata)
            size = PA_GetResource(resFile, kind, ID, resData);
      }
 
      return resData;
   }

(2) Get a resource that is built from a private structure with preferences.

   typedef struct
   {
      short   defaultFontSize;
      short   defaultFontFace;
      long   defaultColor;
      unsigned long   lastCount;
   } Plug_Prefs;
 
   #define kPLUGIN_PREFS   'pipf'
         #define kPREFS_ID   0;
 
   void LoadThePrefs(short resFile, Plug_Prefs *prefs)
   {
      long   size;
      size = PA_GetResource(resFile, kPLUGIN_PREFS, kPREFS_ID, prefs);
   // If the resource did not exist, create it with default values
      if(PA_GetLastError() == -5)
      {
         prefs->defaultFontSize = prefs->defaultFontFace = prefs->defaultColor = prefs->lastCount = -1;
         PA_CreateResource(resFile, kPLUGIN_PREFS, kPREFS_ID, prefs, sizeof(Plug_Prefs));
      }
   }

Error Handling

Use PA_GetLastError to see if an error occurred