Handle Suite Callbacks

The following suite of routines is used primarily for cross-platform support. More...

Data Structures
struct	PSHandleSuite1
	The set of routines available in Pica Handle Suite Version 1. More...
struct	PSHandleSuite2
	The set of routines available in Pica Handle Suite Version 2. More...
Defines
#define	kPSHandleSuite   "Photoshop Handle Suite for Plug-ins"
	Unique identifier for the Handle Suite.
#define	kPSHandleSuiteVersion1   1
	Handle suite, version 1.
#define	kPSHandleSuiteVersion2   2
	Handle suite, version 2.
Typedefs
typedef MACPASCAL void(*	SetPIHandleLockProc )(Handle h, Boolean lock, Ptr *address, Boolean *oldLock)
	Locks or unlocks the handle, depending on the value of the lock flag.

---

Detailed Description

The following suite of routines is used primarily for cross-platform support.

Although you can allocate handles directly using the Mac OS Toolbox, these callbacks are recommended, instead. When you use these callbacks, Photoshop accounts for these handles in its virtual memory space calculations.

The use of the Handle structure throughout the API poses a problem under Windows, where a direct equivalent does not exist. To facilitate Windows plug-ins, Photoshop implements a handle model that is very similar to handles under the Mac OS.

In general, the Buffer suite routines are more effective for memory allocation than the Handle suite. The Buffer suite may have access to memory unavailable to the Handle suite. You should use the Handle suite, however, if the data you are managing is a Mac OS handle.

The PICA Handle Suite uses several of the same procedure definitions as the original Photoshop Handle Suite Callbacks (deprecated Standard Suite).

For more information, please see Using Buffer and Handle Suites.

Accessing the Suite

The Handle suite is referred to as:

 #define kPSHandleSuite     "Photoshop Handle Suite for Plug-ins"

There are two versions of the Handle suite:

  #define kPSHandleSuiteVersion1        1
  #define kPSHandleSuiteVersion2        2

The suite is acquired as follows:

  PSHandleSuite2 *sPSHandle;
  // Acquire the most recent version.
  error = sSPBasic->AcquireSuite(kPSHandleSuite,
                                 kPSHandleSuiteVersion2,      
                                 &sPSHandle);
  if (error) goto . . . //handle error

For PICA errors, see SPErrorCodes.h.

---

Define Documentation

#define kPSHandleSuite   "Photoshop Handle Suite for Plug-ins"

Unique identifier for the Handle Suite.

#define kPSHandleSuiteVersion1   1

Handle suite, version 1.

#define kPSHandleSuiteVersion2   2

Handle suite, version 2.

---

Typedef Documentation

typedef MACPASCAL void(* SetPIHandleLockProc)(Handle h, Boolean lock, Ptr *address, Boolean *oldLock)

Locks or unlocks the handle, depending on the value of the lock flag.

Parameters:

h	The handle to lock or unlock.
lock	Indicates whether to lock or unlock the handle.
address	pointer to the handle data
oldLock	status of the old lock